docs(persistencia): afegir especificació completa de la capa de persistència
Disseny validat durant sessió de brainstorming. Cobreix: - Model de dades SQLAlchemy 2.x (User, Project, Ontology, Graph, Simulation, Report, Task, SystemConfig) - StorageService amb adaptadors LocalFS / Azure Blob (S3 preparat però diferit) - Autenticació JWT + RBAC (user/admin) amb flux d'invitació - SystemConfig per a configuració dinàmica (LLM keys, límits, features) - 4 fases d'implementació amb criteris de verificació Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Ubuntu
parent
49f4da51b1
commit
36107c2c69
|
|
@ -0,0 +1,450 @@
|
||||||
|
# Disseny: Capa de Persistència MiroFish
|
||||||
|
|
||||||
|
## 1. Context i motivació
|
||||||
|
|
||||||
|
MiroFish es desplega com a contenidor Docker. Sense volums muntats, tot el que es guarda al filesystem del contenidor (`backend/uploads/`) es perd en cada reinici o redeploy. A més:
|
||||||
|
|
||||||
|
- `TaskManager` és 100% in-memory: cada reinici invalida les tasques en curs, impedint recovery de l'usuari
|
||||||
|
- `ProjectManager` persisteix via JSON a disc: funcional en dev però no en contenidors efímers ni en multi-instància
|
||||||
|
- No hi ha gestió d'usuaris: tots els projectes són globals i sense propietari
|
||||||
|
- No hi ha configuració dinàmica: tots els paràmetres d'LLM, límits i features van hard-coded a variables d'entorn
|
||||||
|
|
||||||
|
Aquest disseny estableix la capa de persistència completa que farà l'aplicació viable en producció.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Principis de disseny
|
||||||
|
|
||||||
|
1. **Abstracció total del backend** — les capes de negoci mai toquen SQL ni fitxers directament; ho fan a través de `StorageService` i sessions SQLAlchemy
|
||||||
|
2. **Un URL, dos entorns** — `DATABASE_URL` i `STORAGE_TYPE` seleccionen el backend; el codi de negoci no canvia
|
||||||
|
3. **Paths estables** — els `storage_path` guardats a la BD no depenen del backend de storage; l'adaptador els resol
|
||||||
|
4. **Dades de simulació OASIS separades** — els fitxers `.db` SQLite del motor OASIS es tracten com a artefactes i es guarden a storage, no a la BD de l'app
|
||||||
|
5. **Configuració dinàmica per admins** — paràmetres modificables en runtime van a `SystemConfig` a la BD, no a variables d'entorn
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Arquitectura general
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────┐
|
||||||
|
│ Flask Routes │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ Services (ProjectService, AuthService, │
|
||||||
|
│ SimulationService, ReportService...) │
|
||||||
|
│ → usen StorageService + DB Session │
|
||||||
|
├──────────────────┬──────────────────────┤
|
||||||
|
│ StorageService │ SQLAlchemy 2.x │
|
||||||
|
│ (Protocol) │ Session Factory │
|
||||||
|
├────────┬─────────┼──────────────────────┤
|
||||||
|
│LocalFS │AzureBlob│ SQLite (dev) │
|
||||||
|
│ │ (S3*) │ PostgreSQL (prod) │
|
||||||
|
└────────┴─────────┴──────────────────────┘
|
||||||
|
|
||||||
|
* S3: interfície dissenyada, implementació diferida
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Model de dades (SQLAlchemy 2.x)
|
||||||
|
|
||||||
|
### User
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| email | text unique | |
|
||||||
|
| name | text | |
|
||||||
|
| password_hash | text | bcrypt |
|
||||||
|
| role | enum: user\|admin | |
|
||||||
|
| status | enum: pending\|active\|disabled | |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### Project
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| user_id | FK → User | CASCADE delete |
|
||||||
|
| name | text | |
|
||||||
|
| status | text | created\|ontology_generated\|graph_building\|graph_completed\|failed |
|
||||||
|
| analysis_summary | text nullable | resum LLM del document |
|
||||||
|
| simulation_requirement | text nullable | pregunta de simulació |
|
||||||
|
| chunk_size | int | default 500 |
|
||||||
|
| chunk_overlap | int | default 50 |
|
||||||
|
| active_task_id | FK → Task nullable | ON DELETE SET NULL |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### ProjectFile
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| project_id | FK → Project | CASCADE delete |
|
||||||
|
| original_name | text | nom original del fitxer |
|
||||||
|
| storage_path | text | path relatiu a StorageService |
|
||||||
|
| size | int | bytes |
|
||||||
|
| mime_type | text | |
|
||||||
|
| file_type | enum: upload\|extracted_text | |
|
||||||
|
| created_at | datetime | |
|
||||||
|
|
||||||
|
### Ontology
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| project_id | FK → Project | CASCADE delete |
|
||||||
|
| version | int | default 1, incrementa en re-generació |
|
||||||
|
| entity_types | JSON | llista de {name, description, attributes, examples} |
|
||||||
|
| edge_types | JSON | llista de {name, source_targets, attributes} |
|
||||||
|
| created_at | datetime | |
|
||||||
|
|
||||||
|
### Graph
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| project_id | FK → Project | CASCADE delete |
|
||||||
|
| ontology_id | FK → Ontology | quin esquema va usar |
|
||||||
|
| backend | enum: zep\|graphiti | |
|
||||||
|
| external_id | text | ID a Zep Cloud o nom del graf Neo4j |
|
||||||
|
| status | enum: building\|ready\|failed | |
|
||||||
|
| node_count | int nullable | stats post-build |
|
||||||
|
| edge_count | int nullable | stats post-build |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### Simulation
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| project_id | FK → Project | CASCADE delete |
|
||||||
|
| graph_id | FK → Graph | quin graf usa |
|
||||||
|
| status | text | prepared\|running\|completed\|failed |
|
||||||
|
| platform | enum: twitter\|reddit\|both | |
|
||||||
|
| config | JSON | time steps, events, agent params |
|
||||||
|
| profiles_path | text nullable | storage_path al JSON/CSV perfils |
|
||||||
|
| db_path | text nullable | storage_path al fitxer .db OASIS |
|
||||||
|
| actions_path | text nullable | storage_path al JSONL accions |
|
||||||
|
| rounds_total | int nullable | |
|
||||||
|
| rounds_completed | int | default 0 |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### Report
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| project_id | FK → Project | CASCADE delete |
|
||||||
|
| simulation_id | FK → Simulation | |
|
||||||
|
| graph_id | FK → Graph | per fer queries Zep durant generació |
|
||||||
|
| status | text | generating\|completed\|failed |
|
||||||
|
| outline | JSON nullable | estructura de seccions |
|
||||||
|
| storage_prefix | text | prefix del directori a storage |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### Task
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| id | UUID PK | |
|
||||||
|
| task_type | text | ontology_generate\|graph_build\|simulation_prepare\|etc. |
|
||||||
|
| entity_type | text | project\|simulation\|report |
|
||||||
|
| entity_id | text | UUID de l'entitat relacionada |
|
||||||
|
| status | enum: pending\|processing\|completed\|failed | |
|
||||||
|
| progress | int | 0–100 |
|
||||||
|
| message | text nullable | missatge de progrés |
|
||||||
|
| result | JSON nullable | resultat final |
|
||||||
|
| error | text nullable | error si failed |
|
||||||
|
| created_at | datetime | |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
|
||||||
|
### SystemConfig
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| key | text PK | p.ex. `llm.api_key` |
|
||||||
|
| value | text | valor serialitzat |
|
||||||
|
| value_type | enum: string\|int\|float\|bool\|json | per deserialitzar |
|
||||||
|
| group | enum: llm\|limits\|email\|graph\|features | agrupació UI |
|
||||||
|
| label | text | text llegible |
|
||||||
|
| description | text | |
|
||||||
|
| is_secret | bool | emmascara el valor a la UI |
|
||||||
|
| updated_at | datetime | |
|
||||||
|
| updated_by | FK → User nullable | qui va fer el canvi |
|
||||||
|
|
||||||
|
#### Claus predefinides per grup
|
||||||
|
|
||||||
|
| group | key | secret |
|
||||||
|
|-------|-----|--------|
|
||||||
|
| llm | llm.api_key | sí |
|
||||||
|
| llm | llm.base_url | no |
|
||||||
|
| llm | llm.model_name | no |
|
||||||
|
| llm | llm.boost_model_name | no |
|
||||||
|
| graph | graph.backend | no |
|
||||||
|
| graph | graph.zep_api_key | sí |
|
||||||
|
| limits | limits.max_projects_per_user | no |
|
||||||
|
| limits | limits.max_file_size_mb | no |
|
||||||
|
| limits | limits.max_simulation_agents | no |
|
||||||
|
| email | email.sender_address | no |
|
||||||
|
| email | email.acs_endpoint | no |
|
||||||
|
| email | email.acs_key | sí |
|
||||||
|
| features | features.registration_open | no |
|
||||||
|
|
||||||
|
### InvitationToken
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| token | text PK | UUID o token segur |
|
||||||
|
| user_id | FK → User | CASCADE delete |
|
||||||
|
| expires_at | datetime | TTL 48h |
|
||||||
|
| used_at | datetime nullable | null = no usat |
|
||||||
|
|
||||||
|
### PasswordResetToken
|
||||||
|
|
||||||
|
| camp | tipus | notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| token | text PK | |
|
||||||
|
| user_id | FK → User | CASCADE delete |
|
||||||
|
| expires_at | datetime | TTL 1h |
|
||||||
|
| used_at | datetime nullable | |
|
||||||
|
|
||||||
|
### Relacions clau
|
||||||
|
|
||||||
|
```
|
||||||
|
User ──1:N──► Project ──1:N──► ProjectFile
|
||||||
|
──1:N──► Ontology ──1:N──► Graph ──1:N──► Simulation ──1:N──► Report
|
||||||
|
──1:N──► Task (via entity_id)
|
||||||
|
```
|
||||||
|
|
||||||
|
- `Project.active_task_id` → FK → Task amb `ON DELETE SET NULL`
|
||||||
|
- Eliminació User → CASCADE elimina tots els seus Projects i descendents
|
||||||
|
- Eliminació Project → CASCADE elimina Files, Ontologies, Graphs, Simulations, Reports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. StorageService (abstracció de fitxers)
|
||||||
|
|
||||||
|
### Interfície Protocol (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from typing import IO, Protocol
|
||||||
|
|
||||||
|
class StorageService(Protocol):
|
||||||
|
def upload(self, path: str, data: bytes | IO, content_type: str) -> None: ...
|
||||||
|
def download(self, path: str) -> bytes: ...
|
||||||
|
def download_stream(self, path: str) -> IO: ...
|
||||||
|
def delete(self, path: str) -> None: ...
|
||||||
|
def delete_prefix(self, prefix: str) -> None: ...
|
||||||
|
def exists(self, path: str) -> bool: ...
|
||||||
|
def list(self, prefix: str) -> list[str]: ...
|
||||||
|
def public_url(self, path: str) -> str | None: ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementacions
|
||||||
|
|
||||||
|
| `STORAGE_TYPE` | Classe | Dependència |
|
||||||
|
|---|---|---|
|
||||||
|
| `local` | `LocalFSStorage` | stdlib `pathlib` |
|
||||||
|
| `azure` | `AzureBlobStorage` | `azure-storage-blob` |
|
||||||
|
| `s3` *(disseny llest, no implementat)* | `S3Storage` | `boto3` |
|
||||||
|
|
||||||
|
La selecció es fa a l'inici de l'app via `STORAGE_TYPE`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def create_storage_service() -> StorageService:
|
||||||
|
match os.environ.get("STORAGE_TYPE", "local"):
|
||||||
|
case "azure": return AzureBlobStorage(...)
|
||||||
|
case "s3": return S3Storage(...) # futur
|
||||||
|
case _: return LocalFSStorage(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Convenció de paths
|
||||||
|
|
||||||
|
Els paths guardats a la BD són relatius i independents del backend:
|
||||||
|
|
||||||
|
```
|
||||||
|
projects/{project_id}/files/{filename}
|
||||||
|
projects/{project_id}/extracted_text.txt
|
||||||
|
simulations/{sim_id}/{platform}_simulation.db
|
||||||
|
simulations/{sim_id}/profiles.json
|
||||||
|
simulations/{sim_id}/twitter_profiles.csv
|
||||||
|
simulations/{sim_id}/actions.jsonl
|
||||||
|
reports/{report_id}/full_report.md
|
||||||
|
reports/{report_id}/section_{nn}.md
|
||||||
|
reports/{report_id}/agent_log.jsonl
|
||||||
|
reports/{report_id}/console_log.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
En canviar de `local` a `azure` (o `s3`), els paths a la BD no canvien — només l'adaptador que els resol.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Autenticació i RBAC
|
||||||
|
|
||||||
|
### Mecanisme
|
||||||
|
|
||||||
|
- **JWT** via `flask-jwt-extended`
|
||||||
|
- Access token: 8h, en cookie HTTP-only
|
||||||
|
- Refresh token: 7 dies, en cookie HTTP-only
|
||||||
|
- Cap token en `localStorage` (evita XSS)
|
||||||
|
|
||||||
|
### Rols i accés
|
||||||
|
|
||||||
|
| Rol | Accés |
|
||||||
|
|-----|-------|
|
||||||
|
| `user` | Veu i gestiona els seus propis projectes |
|
||||||
|
| `admin` | Veu tots els projectes + gestió d'usuaris + SystemConfig |
|
||||||
|
|
||||||
|
Decoradors Flask:
|
||||||
|
|
||||||
|
```python
|
||||||
|
@require_auth # qualsevol usuari autenticat
|
||||||
|
@require_admin # només admins
|
||||||
|
@require_project_owner # propietari del projecte o admin
|
||||||
|
```
|
||||||
|
|
||||||
|
### Flux d'invitació
|
||||||
|
|
||||||
|
```
|
||||||
|
Admin crea usuari (status: pending)
|
||||||
|
→ email amb InvitationToken (TTL 48h)
|
||||||
|
→ usuari clica l'enllaç, defineix contrasenya
|
||||||
|
→ status: active
|
||||||
|
```
|
||||||
|
|
||||||
|
### Endpoints d'autenticació
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/auth/login
|
||||||
|
POST /api/auth/refresh
|
||||||
|
POST /api/auth/logout
|
||||||
|
POST /api/auth/set-password (invitació + primer login)
|
||||||
|
POST /api/auth/forgot-password
|
||||||
|
POST /api/auth/reset-password
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. SystemConfig: resolució de valors
|
||||||
|
|
||||||
|
Prioritat descendent (el primer que es trobi guanya):
|
||||||
|
|
||||||
|
1. **Variable d'entorn** — sobreescriu tot; útil per secrets en CI/CD
|
||||||
|
2. **`SystemConfig` a la BD** — configurable per admins via UI en runtime
|
||||||
|
3. **Valor per defecte al codi** — fallback si no hi ha cap dels anteriors
|
||||||
|
|
||||||
|
```python
|
||||||
|
def get_config(key: str, default=None):
|
||||||
|
env_key = key.replace(".", "_").upper() # llm.api_key → LLM_API_KEY
|
||||||
|
if val := os.environ.get(env_key):
|
||||||
|
return val
|
||||||
|
if row := db.query(SystemConfig).get(key):
|
||||||
|
return row.typed_value
|
||||||
|
return default
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Variables d'entorn (infraestructura)
|
||||||
|
|
||||||
|
Les variables d'entorn cobreixen exclusivament la infraestructura (no modificables en runtime):
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Base de dades
|
||||||
|
DATABASE_URL=sqlite:///dev.db
|
||||||
|
# DATABASE_URL=postgresql://user:pass@host:5432/mirofish
|
||||||
|
|
||||||
|
# Storage
|
||||||
|
STORAGE_TYPE=local
|
||||||
|
STORAGE_LOCAL_PATH=./uploads
|
||||||
|
# STORAGE_TYPE=azure
|
||||||
|
AZURE_STORAGE_CONNECTION_STRING=...
|
||||||
|
AZURE_STORAGE_CONTAINER=mirofish
|
||||||
|
|
||||||
|
# Autenticació
|
||||||
|
JWT_SECRET=...
|
||||||
|
JWT_REFRESH_SECRET=...
|
||||||
|
|
||||||
|
# Entorn
|
||||||
|
ENVIRONMENT=development
|
||||||
|
# ENVIRONMENT=production
|
||||||
|
```
|
||||||
|
|
||||||
|
Paràmetres com `LLM_API_KEY`, `LLM_MODEL_NAME`, `ZEP_API_KEY`, límits i features van a `SystemConfig` (amb fallback a variable d'entorn per compatibilitat).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Fases d'implementació
|
||||||
|
|
||||||
|
### Fase 1 — Infraestructura base
|
||||||
|
|
||||||
|
**Objectiu:** BD + storage funcionals, `ProjectManager` i `TaskManager` migrats.
|
||||||
|
|
||||||
|
- Configurar SQLAlchemy 2.x + Alembic (migració inicial)
|
||||||
|
- Crear tots els models SQLAlchemy
|
||||||
|
- Implementar `StorageService` + `LocalFSStorage` + `AzureBlobStorage`
|
||||||
|
- Migrar `ProjectManager` (JSON → BD)
|
||||||
|
- Migrar `TaskManager` (memòria → BD)
|
||||||
|
- Injectar `StorageService` i sessió DB a Flask via app factory
|
||||||
|
|
||||||
|
**Verificació:** crear projecte, pujar fitxer, crear task → reiniciar servidor → verificar que tot sobreviu
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 2 — Autenticació i multi-usuari
|
||||||
|
|
||||||
|
**Objectiu:** login, RBAC i aïllament de dades per usuari.
|
||||||
|
|
||||||
|
- Models `User`, `InvitationToken`, `PasswordResetToken`
|
||||||
|
- JWT via `flask-jwt-extended` (cookies HTTP-only)
|
||||||
|
- Decoradors `@require_auth`, `@require_admin`, `@require_project_owner`
|
||||||
|
- Flux invitació + reset contrasenya
|
||||||
|
- Totes les rutes de `Project` filtrades per `user_id`
|
||||||
|
|
||||||
|
**Verificació:** login, accés projecte propi, bloqueig projecte d'altri, flux invitació complet
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 3 — Migració pipeline complet
|
||||||
|
|
||||||
|
**Objectiu:** les 5 etapes del pipeline usen BD + storage.
|
||||||
|
|
||||||
|
- `GraphBuilder` → desa `Ontology` + `Graph` a BD
|
||||||
|
- `SimulationRunner` → desa `.db` OASIS a `StorageService`, metadades a `Simulation`
|
||||||
|
- `ReportAgent` → desa seccions a `StorageService`, metadades a `Report`
|
||||||
|
- `SystemConfig` operatiu (LLM keys, Zep key, límits via BD)
|
||||||
|
|
||||||
|
**Verificació:** pipeline end-to-end (upload → ontologia → graf → simulació → report) amb BD + storage
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 4 — Hardening producció
|
||||||
|
|
||||||
|
**Objectiu:** desplegament estable en contenidor amb PostgreSQL + Azure Blob.
|
||||||
|
|
||||||
|
- Configurar PostgreSQL + connection pool (SQLAlchemy `pool_size`, `max_overflow`)
|
||||||
|
- Configurar Azure Blob Storage
|
||||||
|
- `.env.dev` i `.env.prod` per entorn
|
||||||
|
- Health check endpoint (`GET /api/health`) que verifica BD + storage
|
||||||
|
- Smoke tests en contenidor Docker
|
||||||
|
|
||||||
|
**Verificació:** `docker build` + `docker run` sense volums → pipeline complet → reinici contenidor → dades persistides
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Verificació end-to-end
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Arrancar en mode dev (SQLite + LocalFS)
|
||||||
|
2. Crear projecte → verificar fila a BD + fitxer a uploads/
|
||||||
|
3. Executar pipeline complet → verificar Ontology, Graph, Simulation, Report a BD
|
||||||
|
4. Reiniciar servidor → verificar que projecte, tasks i fitxers sobreviuen
|
||||||
|
5. Canviar STORAGE_TYPE=azure → verificar que paths a BD no canvien
|
||||||
|
6. Canviar DATABASE_URL=postgresql://... + alembic upgrade head → verificar sense errors
|
||||||
|
7. Reiniciar contenidor sense volum → verificar dades persistides a BD + Azure Blob
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue