Archive: System v4 - Estado al 2024-12-24
This commit is contained in:
ARCHITECT
233
v4-archive/clara/README.md
Normal file
233
v4-archive/clara/README.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user