tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e2c308eb6ff0c57f76f77a4428217611a1dd3b65
system-docs/03_MODELO_DATOS/contenedor-schema.md
ARCHITECT 6ea70bd34f 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

348 lines
8.7 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink