[DOCS] Standard cross-suite AgileHub + governance CLAUDE.md + registri agent

- CLAUDE.md: TZ, SSO, vault-steward, versioning, persona v2.0, multitenant, KB RAG - docs/standards: persona-conversational-rules v2.0 - docs/STANDARD_*: installer-integration, email-relay, AI-prodotto, marketing-tenant, multitenant - AGENT_CHANGES.md + OPEN_TICKETS.md (registri agent automatico) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-29 15:41:54 +02:00
parent 1d13166d7a
commit c0bf7b6c15
9 changed files with 3920 additions and 1 deletions
@@ -0,0 +1,160 @@
+# STANDARD AgileHub: multitenant-architecture v1.0
+
+> **Codename progetto**: NAVIGAI (Navigare nell'AI)
+> **Status**: `proposed`
+> **Applies to**: `*` (tutta la suite — 11 prodotti)
+> **Owner**: REGENT (coordinamento) + TITAN (backend) + VIGILE (audit) + Agile AI (KB master) + PRISMA (UI master/tenant)
+> **Date**: 2026-05-17
+> **Public facing**: AgileHub (NAVIGAI è il codename interno, invisibile al cliente)
+
+---
+
+## 1. Scopo
+
+Definire l'architettura multitenant esplicita di AgileHub con un livello master condiviso, tenant client isolati, catalogo cross-tenant condivisibile, billing per-tenant e governance centralizzata.
+
+## 2. Tassonomia tenant
+
+| Tipo | Esempio | id | is_master | tier | parent_tenant_id |
+|---|---|---|---|---|---|
+| **Master** | AgileHub | 1 | TRUE | `master` | NULL |
+| Client enterprise | Work Group s.r.l. | N | FALSE | `enterprise` | 1 |
+| Client professional | Studio Tremolada | N | FALSE | `professional` | 1 |
+| Client trial | sandbox | N | FALSE | `trial` | 1 |
+| Sandbox interno | Agile Technology test | N | FALSE | `trial` | 1 |
+
+## 3. Visibility ENUM cross-tabella
+
+Ogni record sensibile (KB articles, personas, workflow templates, routing rules, RAG repositories) ha colonna `visibility ENUM('global','shared','tenant','team','private')`.
+
+| Valore | Significato | Lettura da |
+|---|---|---|
+| `global` | Master AgileHub catalog, riusabile read-only da tutti i tenant | tutti |
+| `shared` | Visibile a tenant + i suoi sotto-tenant | tenant + figli |
+| `tenant` | Solo tenant proprietario | tenant |
+| `team` | Team specifico dentro un tenant | team members |
+| `private` | Singolo utente | owner_user_id |
+
+## 4. Opt-out granulare
+
+Tabella `nexus_tenant_db.tenant_global_exclusions(tenant_id, resource_type, resource_id, exclusion_reason)` permette al client di dichiarare "non voglio usare quell'articolo KB master/quella persona master/quella regola routing master".
+
+## 5. JWT additivi (no breaking)
+
+Claims aggiunti (additive, retro-compat):
+- `tenant_id BIGINT`
+- `tenant_slug VARCHAR(64)`
+- `is_master TINYINT(1)`
+- `permitted_tenant_ids INT[]` (per is_master users che possono switchare contesto)
+
+Vecchi JWT senza nuovi claim restano validi → tenant_id desunto via fallback `tenants.email → user → tenant_membership`.
+
+## 6. Shared library
+
+Pacchetto npm interno `@agile/tenant-auth` (Node) + `agile_tenant_auth` (Python) fornisce:
+- `extractTenantContext(req)` → `{ tenant_id, tenant_slug, is_master, user_id }`
+- `requireSameTenant(req, resourceTenantId)` → throws 403 se mismatch
+- `requireMaster(req)` → throws 403 se !is_master
+- `withTenantFilter(query)` → injects `WHERE (tenant_id = X OR visibility = 'global')`
+
+## 7. Vault namespace tenant-aware
+
+Pattern: `tier1__<ms>__<tenant_slug>__<feature>`
+
+Esempi:
+- `tier1__nexus-marketing-ms__work_group_001__mailgun_api_key`
+- `tier1__nexus-presenter-ms__agilehub_master__tavus_api_key`
+
+Compatibility: namespace senza `<tenant_slug>` restano validi per master.
+
+## 8. Audit log HMAC chain
+
+JSONL append-only in `docs/multitenant-audit/YYYY-MM-WNN.jsonl` con catena HMAC-SHA256 (ogni entry contiene SHA del precedente). Genesis entry firmata da TITAN al kickoff SG-0.
+
+## 9. Distributed tracing
+
+Header `X-Trace-Id` propagato cross-MS in tutti i call HTTP/Redis Streams. Generato in API gateway Apache se assente. Pino structured log + Loki backend.
+
+## 10. Status page tenant-aware
+
+`/status` Next.js mostra SLA + uptime + latency p99 **per-tenant** (con auth). SLA differenziato per tier:
+- master: 99.99%
+- enterprise: 99.95%
+- professional: 99.9%
+- trial: 99%
+
+## 11. Canary deploy
+
+Apache `mod_proxy_balancer` rolling 5% → 50% → 100% con auto-rollback se error rate > 2% per 5 min.
+
+## 12. Billing per-tenant
+
+Tabella `nexus_hub.hub_cost_events(tenant_id, ms, event_type, cost_eur_micros, ts)` con 8 hook nei MS:
+- nexus-ai-ms (tokens LLM Anthropic + Voyage embedding)
+- nexus-marketing-ms (email sends via Mailgun)
+- nexus-call-ms (Twilio minutes)
+- nexus-presenter-ms (Tavus session-minutes + LiveKit)
+- nexus-voice-ms (Deepgram STT + ElevenLabs TTS)
+- nexus-rag-ms (Voyage embed/rerank + storage GB)
+- nexus-hub-ms (server time)
+- agilehub-workflow-engine (Haiku suggester tokens)
+
+Export mensile CSV/PDF (showback) per cliente.
+
+## 13. Compliance
+
+- **GDPR Art.32**: encryption at rest+transit, access controls, audit trail, business continuity, periodic testing — tutti documentati in `docs/COMPLIANCE_GDPR_ART32.md`
+- **ISO A.18.1.5** readiness: gap analysis NON certificazione formale
+- **Retention fiscale IT**: 10 anni per `hub_cost_events` (NON 7)
+- **GDPR Art.17 erasure**: cascade già implementato in nexus-rag-ms (estendere ai 13 MS)
+
+## 14. Pen test esterno
+
+STRIDE 13×6 matrix (13 MS × 6 categorie) eseguita da vendor EU certificato durante SG-5. Budget €15K una tantum. Vendor RFP da VIGILE.
+
+## 15. Roadmap distribution
+
+| Wave | Prodotti | Trigger |
+|---|---|---|
+| **Reference** | AGILEHUB | SG-0 in progress |
+| **Wave 1 (P1)** | TRPG, SUSTAINAI, NIS2, DFM | SG-4 GREEN |
+| **Wave 2 (P2)** | TAXAI, LG231, MKTG, ALLRISK, WMS, MADEBYCLOUD, CERTISOURCE | post smoke Wave 1 |
+
+Distribution via INSTALLATORE pattern: docs_file scp + claude_md append + claude memory write nei 11 container DevEnv prodotto + `hub_standards_adoption` row per ogni prodotto (status `pending → acknowledged → implemented`).
+
+## 16. NESSUN out-of-scope (v1.0)
+
+Documentato esplicitamente FUORI da v1.0:
+- Multi-region failover (Hetzner Helsinki + EU secondary)
+- Self-service tenant signup pubblico con CC payment
+- Multi-currency (solo EUR)
+- SAML/OIDC federation
+- Tenant white-label dominio custom (solo subdomain `{slug}.agilehub.it`)
+- Audit log immutabile blockchain
+- ISO 27001 / SOC 2 certification formale
+
+---
+
+## Adoption tracker (status iniziale)
+
+| Prodotto | docs_file | claude_md | claude_memory | adoption_status |
+|---|---|---|---|---|
+| AGILEHUB | ✓ pending SG-0 | pending | pending | `proposed` |
+| TRPG | pending | pending | pending | `pending` |
+| SUSTAINAI | pending | pending | pending | `pending` |
+| NIS2 | pending | pending | pending | `pending` |
+| TAXAI | pending | pending | pending | `pending` |
+| LG231 | pending | pending | pending | `pending` |
+| DFM | pending | pending | pending | `pending` |
+| MKTG | pending | pending | pending | `pending` |
+| ALLRISK | pending | pending | pending | `pending` |
+| WMS | pending | pending | pending | `pending` |
+| MADEBYCLOUD | pending | pending | pending | `pending` |
+| CERTISOURCE | pending | pending | pending | `pending` |
+
+## Riferimenti
+
+- [NAVIGAI_EXECUTIVE_BRIEF.md](NAVIGAI_EXECUTIVE_BRIEF.md)
+- [NAVIGAI_ARCHITETTURA_TECNICA.md](NAVIGAI_ARCHITETTURA_TECNICA.md)
+- [NAVIGAI_ROADMAP_OPERATIVA.md](NAVIGAI_ROADMAP_OPERATIVA.md)
+- [PLAN_MULTITENANT_MASTER_REFACTOR_V11.md](PLAN_MULTITENANT_MASTER_REFACTOR_V11.md) (920 righe production-ready)