234 lines
7.7 KiB
Markdown
234 lines
7.7 KiB
Markdown
|
# CLARA
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
**Log de entrada DECK - Sistema TZZR**
|
||
|
|
|
||
|
|
## Rol
|
||
|
|
|
||
|
|
Secretaria de entrada para DECK (servidor personal). Log inmutable que recibe información sin procesarla.
|
||
|
|
|
||
|
|
## Posición en el Flujo
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
|
|
│ PACKET (App móvil) │
|
||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
┌────────────────────────────┼────────────────────────────┐
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
|
|
│ CLARA │ │ MARGARET │ │ ALFRED/JARED │
|
||
|
|
│ (DECK log) │ │ (CORP log) │ │(flujo predefinido)│
|
||
|
|
│ inmutable │ │ inmutable │ │ │
|
||
|
|
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
||
|
|
│ │ │
|
||
|
|
└──────────────────────────┴──────────────────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────┐
|
||
|
|
│ MASON │
|
||
|
|
│(enriquecer) │
|
||
|
|
└──────┬──────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────┐
|
||
|
|
│ FELDMAN │
|
||
|
|
│(consolidar) │
|
||
|
|
└─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Función
|
||
|
|
|
||
|
|
1. Recibe contenedor de PACKET
|
||
|
|
2. Envía archivos a R2
|
||
|
|
3. Registra en PostgreSQL:
|
||
|
|
- Metadata del contenedor
|
||
|
|
- Ubicación de archivos en R2
|
||
|
|
4. **NO añade información**
|
||
|
|
5. **NO procesa**
|
||
|
|
6. **NO modifica**
|
||
|
|
|
||
|
|
## Comparación
|
||
|
|
|
||
|
|
| Componente | Servidor | Tipo | Función |
|
||
|
|
|------------|----------|------|---------|
|
||
|
|
| **CLARA** | DECK | Input suelto | Log de entrada personal |
|
||
|
|
| MARGARET | CORP | Input suelto | Log de entrada empresarial |
|
||
|
|
| ALFRED | DECK | Flujo predefinido | Cadenas de pasos conocidos |
|
||
|
|
| JARED | CORP | Flujo predefinido | Cadenas de pasos + NOTARIO |
|
||
|
|
|
||
|
|
## Identificador
|
||
|
|
|
||
|
|
```
|
||
|
|
h_instancia = SHA-256(seed único de DECK)
|
||
|
|
```
|
||
|
|
|
||
|
|
Mismo hash para:
|
||
|
|
- Autenticación: `X-Auth-Key: {h_instancia}`
|
||
|
|
- Biblioteca privada: `h_biblioteca = h_instancia`
|
||
|
|
- Prefijo R2: `{endpoint}/{h_instancia}/...`
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
### Recepción
|
||
|
|
```http
|
||
|
|
POST /ingest
|
||
|
|
X-Auth-Key: {h_instancia}
|
||
|
|
Content-Type: application/json
|
||
|
|
|
||
|
|
{
|
||
|
|
"hash": "fc2fae65...",
|
||
|
|
"titulo": "opcional",
|
||
|
|
"descripcion": "opcional",
|
||
|
|
"etiquetas": ["h_maestro1", "h_maestro2"],
|
||
|
|
"gps": {"lat": 43.36, "long": -8.41},
|
||
|
|
"archivos": [...]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Respuestas
|
||
|
|
- `200`: `{"ok": true, "id": 1001}`
|
||
|
|
- `409`: `{"error": "hash_exists"}`
|
||
|
|
- `401`: `{"error": "unauthorized"}`
|
||
|
|
|
||
|
|
## Estructura de Datos
|
||
|
|
|
||
|
|
CLARA registra contenedores con la siguiente estructura (ver [esquema completo](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/06-contenedor-schema.md)):
|
||
|
|
|
||
|
|
```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.38, "lon": 2.17, "precision_m": 10}
|
||
|
|
},
|
||
|
|
|
||
|
|
"archivo": {
|
||
|
|
"tipo": "image/jpeg",
|
||
|
|
"categoria": "imagen",
|
||
|
|
"size_bytes": 2048576,
|
||
|
|
"dimensiones": {"ancho": 1920, "alto": 1080}
|
||
|
|
},
|
||
|
|
|
||
|
|
"tags": [
|
||
|
|
{"h_maestro": "sha256", "grupo": "hst", "nombre": "Factura", "confianza": 1.0}
|
||
|
|
],
|
||
|
|
|
||
|
|
"estado": {
|
||
|
|
"actual": "en_clara",
|
||
|
|
"historial": [{"paso": "clara", "entrada": "...", "procesado_por": "clara-service"}]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Secciones que CLARA recibe de PACKET**:
|
||
|
|
- `identificacion`: id, h_instancia, archivo_hash
|
||
|
|
- `origen`: dispositivo, app_version, timestamp, geolocalizacion
|
||
|
|
- `archivo`: metadata tecnica
|
||
|
|
- `tags`: etiquetas iniciales
|
||
|
|
|
||
|
|
**Secciones que CLARA NO toca**:
|
||
|
|
- `extraccion`: la anade servicio externo despues
|
||
|
|
- `enriquecimiento`: la anade usuario en MASON
|
||
|
|
- `bloque`: la anade FELDMAN al consolidar
|
||
|
|
|
||
|
|
## Tabla PostgreSQL
|
||
|
|
|
||
|
|
```sql
|
||
|
|
CREATE TABLE clara_log (
|
||
|
|
id BIGSERIAL PRIMARY KEY,
|
||
|
|
h_instancia VARCHAR(64) NOT NULL,
|
||
|
|
h_entrada VARCHAR(64) NOT NULL,
|
||
|
|
contenedor JSONB NOT NULL,
|
||
|
|
r2_paths JSONB,
|
||
|
|
created_at TIMESTAMP DEFAULT NOW()
|
||
|
|
);
|
||
|
|
|
||
|
|
-- Inmutable: sin updated_at
|
||
|
|
CREATE INDEX idx_clara_instancia ON clara_log(h_instancia);
|
||
|
|
CREATE INDEX idx_clara_entrada ON clara_log(h_entrada);
|
||
|
|
CREATE INDEX idx_clara_estado ON clara_log((contenedor->>'estado'->>'actual'));
|
||
|
|
```
|
||
|
|
|
||
|
|
## Inmutabilidad
|
||
|
|
|
||
|
|
- Registros NUNCA se modifican
|
||
|
|
- Archivos en R2 NUNCA se mueven
|
||
|
|
- Las correcciones se hacen en MASON
|
||
|
|
|
||
|
|
## Arquitectura Completa
|
||
|
|
|
||
|
|
Ver documentación en [contratos-comunes/architecture](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/01-clara-margaret.md)
|
||
|
|
|
||
|
|
## Repositorios Relacionados
|
||
|
|
|
||
|
|
| Repo | Rol |
|
||
|
|
|------|-----|
|
||
|
|
| [margaret](https://git.tzzr.me/tzzr/margaret) | Equivalente para CORP |
|
||
|
|
| [alfred](https://git.tzzr.me/tzzr/alfred) | Flujos predefinidos DECK |
|
||
|
|
| [mason](https://git.tzzr.me/tzzr/mason) | Enriquecimiento |
|
||
|
|
| [feldman](https://git.tzzr.me/tzzr/feldman) | Consolidación |
|
||
|
|
| [sentinel](https://git.tzzr.me/tzzr/sentinel) | Auditoría |
|
||
|
|
| [packet](https://git.tzzr.me/tzzr/packet) | App móvil |
|
||
|
|
|
||
|
|
## Implementación
|
||
|
|
|
||
|
|
Este repositorio contiene la implementación completa del servicio CLARA:
|
||
|
|
|
||
|
|
### Archivos principales
|
||
|
|
|
||
|
|
- **`app.py`**: Servicio Flask con API REST
|
||
|
|
- **`Dockerfile`**: Imagen Docker del servicio
|
||
|
|
- **`docker-compose.yml`**: Orquestación con PostgreSQL
|
||
|
|
- **`init.sql`**: Schema de base de datos
|
||
|
|
- **`requirements.txt`**: Dependencias Python
|
||
|
|
- **`test_clara.sh`**: Suite de tests automatizados
|
||
|
|
- **`DEPLOYMENT.md`**: Guía de despliegue completa
|
||
|
|
|
||
|
|
### Tecnologías
|
||
|
|
|
||
|
|
- **Backend**: Flask + Gunicorn
|
||
|
|
- **Base de datos**: PostgreSQL 15 con JSONB
|
||
|
|
- **Storage**: Cloudflare R2 (compatible S3)
|
||
|
|
- **Contenedores**: Docker + Docker Compose
|
||
|
|
- **Testing**: Bash + curl + jq
|
||
|
|
|
||
|
|
### Inicio rápido
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. Configurar credenciales
|
||
|
|
cp .env.example .env
|
||
|
|
nano .env
|
||
|
|
|
||
|
|
# 2. Iniciar servicios
|
||
|
|
docker-compose up -d
|
||
|
|
|
||
|
|
# 3. Verificar
|
||
|
|
curl http://localhost:5051/health
|
||
|
|
|
||
|
|
# 4. Ejecutar tests
|
||
|
|
./test_clara.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Ver [`DEPLOYMENT.md`](./DEPLOYMENT.md) para instrucciones completas.
|
||
|
|
|
||
|
|
### Estado del servicio
|
||
|
|
|
||
|
|
- ✅ Implementación completa
|
||
|
|
- ✅ Tests automatizados
|
||
|
|
- ✅ Docker ready
|
||
|
|
- ⏳ Pendiente despliegue a DECK (72.62.1.113)
|
||
|
|
- ⏳ Pendiente integración con PACKET
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*Componente del sistema TZZR - Actualizado 2025-12-23*
|