# Estructura CONTENEDOR

Esquema de datos completo para un registro en el sistema TZZR.

## Esquema JSON

```json
{
  "id": "uuid-contenedor",
  "h_instancia": "sha256-instancia",
  "archivo_hash": "sha256-archivo",

  "origen": {
    "dispositivo": "uuid-dispositivo",
    "app_version": "1.0.0",
    "timestamp_captura": "2025-01-15T10:30:00Z",
    "geolocalizacion": {
      "lat": 41.3851,
      "lon": 2.1734,
      "precision_m": 10
    }
  },

  "archivo": {
    "tipo": "image/jpeg",
    "categoria": "imagen",
    "size_bytes": 2048576,
    "nombre_original": "IMG_2024.jpg",
    "dimensiones": {
      "ancho": 1920,
      "alto": 1080
    },
    "duracion_seg": null
  },

  "tags": [
    {
      "h_maestro": "sha256-tag",
      "grupo": "hst",
      "nombre": "Factura",
      "confianza": 1.0
    }
  ],

  "extraccion": {
    "servicio": "openai-vision",
    "version": "gpt-4o",
    "timestamp": "2025-01-15T10:30:05Z",
    "coste_cents": 2,
    "texto": "FACTURA N 2024-001...",
    "resumen": "Factura de servicios por 1.500EUR",
    "entidades": {
      "fechas": ["2025-01-15"],
      "importes": [{"valor": 1500.00, "moneda": "EUR"}],
      "personas": [],
      "organizaciones": ["Acme Corp"],
      "ubicaciones": [],
      "documentos": [{"tipo": "factura", "numero": "2024-001"}]
    },
    "clasificacion": {
      "categoria": "finanzas",
      "subcategoria": "factura_recibida",
      "confianza": 0.95
    },
    "tags_sugeridos": [
      {"h_maestro": "sha256", "nombre": "Factura", "confianza": 0.95}
    ],
    "especifico": {}
  },

  "enriquecimiento": {
    "notas": "Pendiente de pago",
    "campos_personalizados": {
      "proyecto": "Proyecto Alpha",
      "responsable": "Juan Garcia"
    },
    "tags_confirmados": ["sha256-tag1", "sha256-tag2"],
    "tags_rechazados": ["sha256-tag3"],
    "correcciones": {
      "texto": null,
      "entidades": null
    },
    "editado_por": "usuario-id",
    "editado_at": "2025-01-15T11:00:00Z"
  },

  "estado": {
    "actual": "en_feldman_cola",
    "historial": [
      {"paso": "clara", "entrada": "...", "salida": "...", "procesado_por": "clara-service"},
      {"paso": "mason", "entrada": "...", "salida": "...", "procesado_por": "usuario-id"},
      {"paso": "feldman_cola", "entrada": "...", "procesado_por": "feldman-service"}
    ]
  },

  "bloque": {
    "id": "sha256-bloque",
    "numero": 42,
    "registro_hash": "sha256-este-registro",
    "merkle_proof": ["sha256-1", "sha256-2", "sha256-3"]
  }
}
```

---

## Secciones

### IDENTIFICACION

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `id` | UUID | Identificador unico del contenedor, generado por PACKET |
| `h_instancia` | SHA-256 | Identifica servidor DECK/CORP de origen |
| `archivo_hash` | SHA-256 | Hash del archivo, sirve como ruta en R2 |

**Ruta R2**: `{endpoint}/{archivo_hash}`

---

### ORIGEN

Informacion del momento de captura. Generada automaticamente por PACKET.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `dispositivo` | UUID | ID del dispositivo que capturo |
| `app_version` | String | Version de PACKET |
| `timestamp_captura` | ISO 8601 | Momento exacto de captura |
| `geolocalizacion` | Object | Ubicacion GPS (opcional) |
| `geolocalizacion.lat` | Float | Latitud |
| `geolocalizacion.lon` | Float | Longitud |
| `geolocalizacion.precision_m` | Int | Precision en metros |

**Inmutable**: Esta seccion nunca se modifica despues de la captura.

---

### ARCHIVO

Metadata tecnica del archivo capturado.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `tipo` | String | MIME type (image/jpeg, audio/mp3, etc.) |
| `categoria` | Enum | imagen, audio, video, documento |
| `size_bytes` | Int | Tamano en bytes |
| `nombre_original` | String | Nombre original del archivo (opcional) |
| `dimensiones.ancho` | Int | Ancho en pixels (imagen/video) |
| `dimensiones.alto` | Int | Alto en pixels (imagen/video) |
| `duracion_seg` | Float | Duracion en segundos (audio/video) |

**Inmutable**: Esta seccion nunca se modifica.

---

### TAGS

Etiquetas aplicadas por el usuario en PACKET al momento de captura.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `h_maestro` | SHA-256 | Referencia a la biblioteca de tags |
| `grupo` | Enum | hst, emp, hsu, pjt, sys |
| `nombre` | String | Nombre visible del tag |
| `confianza` | Float | 1.0 = usuario, <1.0 = sugerido por IA |

**Grupos de tags**:
- `hst`: Biblioteca publica HST
- `emp`: Biblioteca de empresa
- `hsu`: Biblioteca personal de usuario
- `pjt`: Biblioteca de proyecto
- `sys`: Tags de sistema (automaticos)

**Mutable**: Se pueden anadir tags en MASON.

---

### EXTRACCION

Resultado del servicio de extraccion (OCR, transcripcion, analisis IA).

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `servicio` | String | Identificador del servicio usado |
| `version` | String | Version del modelo/servicio |
| `timestamp` | ISO 8601 | Momento de la extraccion |
| `coste_cents` | Int | Coste en centavos (obligatorio para auditoria) |
| `texto` | String | Contenido textual extraido |
| `resumen` | String | Resumen generado por IA |
| `entidades` | Object | Datos estructurados detectados |
| `clasificacion` | Object | Categoria sugerida automaticamente |
| `tags_sugeridos` | Array | Tags de biblioteca que podrian aplicar |
| `especifico` | Object | Campos segun tipo de archivo |

#### Entidades detectadas

```json
{
  "fechas": ["2025-01-15"],
  "importes": [{"valor": 1500.00, "moneda": "EUR"}],
  "personas": ["Juan Garcia"],
  "organizaciones": ["Acme Corp"],
  "ubicaciones": ["Barcelona"],
  "documentos": [{"tipo": "factura", "numero": "2024-001"}]
}
```

#### Campos especificos por tipo

**Imagen**:
```json
{
  "descripcion_visual": "Documento escaneado...",
  "objetos_detectados": ["documento", "texto", "logo"],
  "texto_ocr_bruto": "..."
}
```

**Audio**:
```json
{
  "transcripcion": "...",
  "idioma_detectado": "es",
  "hablantes": 2
}
```

**Video**:
```json
{
  "transcripcion": "...",
  "escenas": [...]
}
```

**Documento (PDF)**:
```json
{
  "paginas": 3,
  "texto_por_pagina": ["...", "...", "..."]
}
```

**Inmutable**: Esta seccion no se modifica una vez generada.

---

### ENRIQUECIMIENTO

Lo que el usuario anade o modifica en MASON.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `notas` | String | Texto libre del usuario |
| `campos_personalizados` | Object | Campos key-value definidos por usuario |
| `tags_confirmados` | Array | h_maestro de tags sugeridos aceptados |
| `tags_rechazados` | Array | h_maestro de tags sugeridos descartados |
| `correcciones.texto` | String | Texto corregido si OCR fallo |
| `correcciones.entidades` | Object | Entidades corregidas |
| `editado_por` | String | ID del usuario que edito |
| `editado_at` | ISO 8601 | Ultima edicion |

**Mutable**: Hasta que se consolida en FELDMAN.

---

### ESTADO

Trazabilidad del registro a traves del sistema.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `actual` | String | Ubicacion actual del registro |
| `historial` | Array | Pasos por los que ha pasado |
| `historial[].paso` | String | Nombre del paso (clara, mason, feldman_cola, feldman_bloque) |
| `historial[].entrada` | ISO 8601 | Cuando entro |
| `historial[].salida` | ISO 8601 | Cuando salio |
| `historial[].procesado_por` | String | Servicio o usuario que proceso |

**Estados posibles**:
- `en_clara` / `en_margaret`: Recien capturado
- `en_mason`: En enriquecimiento
- `en_feldman_cola`: Esperando consolidacion
- `en_feldman_bloque`: Consolidado (inmutable)

---

### BLOQUE

Solo se rellena cuando FELDMAN consolida el registro.

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `id` | SHA-256 | Hash del bloque |
| `numero` | Int | Numero secuencial del bloque |
| `registro_hash` | SHA-256 | Hash de este registro |
| `merkle_proof` | Array | Prueba de inclusion en el arbol Merkle |

**Inmutable**: Una vez consolidado, nunca cambia.

---

## Mutabilidad por Seccion

| Seccion | Quien escribe | Inmutable |
|---------|---------------|-----------|
| identificacion | PACKET | Si |
| origen | PACKET | Si |
| archivo | PACKET | Si |
| tags | PACKET (usuario) | No (se puede anadir) |
| extraccion | Servicio externo | Si |
| enriquecimiento | Usuario en MASON | No (hasta consolidar) |
| estado | Sistema | Se acumula |
| bloque | FELDMAN | Si (al consolidar) |

---

## Flujo de datos

```
PACKET genera:
  - identificacion
  - origen
  - archivo
  - tags (iniciales)

CLARA/MARGARET registra:
  - estado.historial += {paso: "clara/margaret"}

Servicio extraccion anade:
  - extraccion (completa)

MASON permite editar:
  - enriquecimiento
  - tags (anadir)
  - estado.historial += {paso: "mason"}

FELDMAN consolida:
  - bloque (completo)
  - estado.actual = "en_feldman_bloque"
  - estado.historial += {paso: "feldman_bloque"}
```

---

*Actualizado: 2025-12-22*