# CLARA

![Estado](https://img.shields.io/badge/Estado-IMPLEMENTADO-brightgreen)


**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*