Update to Skynet v7 - Complete documentation restructure

- Nueva estructura de carpetas según Skynet v7 - Añadidos schemas SQL completos - Documentación de entidades, componentes e integraciones - Modelo de seguridad actualizado - Infraestructura y operaciones reorganizadas
2025-12-29 18:23:41 +00:00
parent ac481fe266
commit 6ea70bd34f
76 changed files with 13029 additions and 4340 deletions
--- a/03_MODELO_DATOS/contenedor-schema.md
+++ b/03_MODELO_DATOS/contenedor-schema.md
@@ -0,0 +1,347 @@
+# 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*