system-docs/03_MODELO_DATOS/contenedor-schema.md

Estructura CONTENEDOR

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

Esquema 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

{
  "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:

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

Audio:

{
  "transcripcion": "...",
  "idioma_detectado": "es",
  "hablantes": 2
}

Video:

{
  "transcripcion": "...",
  "escenas": [...]
}

Documento (PDF):

{
  "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