Definition of Done — feature Akira

Owner: Massimo Bagnoli Riferimento: estende le CONVENTIONS Toolbox A.Sheep Stato: bozza per ratifica nel branch main di akira/ Data: 2026-05-13

Questo documento definisce la Definition of Done a livello feature per il progetto Akira. Una PR non può essere mergiata su main se anche un solo item della checklist è insoddisfatto, salvo eccezioni esplicitamente documentate nel body della PR e firmate dall'owner (Massimo).

La DoD si applica a ogni feature funzionale (es. "Companies CRUD", "Pattern Analyzer UI") e non sostituisce ma estende le convenzioni Toolbox A.Sheep (CONVENTIONS.md copiato nel workspace).

---

1. Filosofia

Una feature è "done" quando:

1. Funziona (test, deploy staging verde).
2. È mantenibile (lint, type, docs).
3. È osservabile (log, metric, errori).
4. È sicura (no secret, no SQL injection, audit log).
5. È stata vista da occhi diversi da chi l'ha scritta (manual smoke).

"Funziona sul mio laptop" non è done. "Test passa in CI" non basta da solo.

---

2. Checklist DoD obbligatoria (PR template)

Da incollare nel body della PR e spuntare prima del merge. La CI fa enforcement automatico dove possibile; gli item con [manuale] richiedono revisione umana.

Tests

• pytest backend green — unit + integration (pytest tests/)
• Vitest frontend smoke green — almeno smoke test del componente principale (pnpm test)
• Playwright E2E almeno 1 happy path per la feature (pnpm test:e2e)

Coverage

• Delta coverage non sotto target modulo — pyproject.toml [tool.coverage] enforced in CI (fail se coverage del modulo touched < soglia configurata, default 70 %, 85 % per moduli billing/auth)

Lint / Type

• Backend: ruff check clean + ruff format --check clean
• Backend: mypy --strict clean (nessun # type: ignore non motivato)
• Frontend: tsc --noEmit clean
• Frontend: eslint clean

Database / Migration

• Migration Alembic applicabile e reversibile: alembic upgrade head + alembic downgrade -1 non rompono lo schema e mantengono i dati di seed coerenti
• Nessun DROP TABLE o ALTER distruttivo senza nota esplicita nel body della PR + sign-off Massimo

API contract

• OpenAPI snapshot aggiornato — python scripts/dump_openapi.py > docs/api/openapi-snapshot.json
• api-types/ rigenerato lato frontend (tipi TS allineati al backend)
• Breaking change API → bump versione + changelog docs/api/CHANGELOG.md

Documentation

• README modulo aggiornato se contratto pubblico è cambiato (backend/akira/modules/<feature>/README.md)
• ADR scritto se è stata presa una decisione architetturale (template docs/adr/_template.md)
• Inline docstring presenti su funzioni pubbliche con typing non banale

Deploy

• Deployato su staging via Ansible — ansible-playbook -i inventories/staging deploy.yml --tags <feature>
• Smoke test pipeline verde post-deploy staging (script scripts/smoke-staging.sh <feature>)
• Migration applicata su staging senza errori

Observability

• Log strutturato con correlation_id — vedi docs/conventions/error-handling-and-correlation-id.md
• Almeno 1 metrica Prometheus chiave esposta per la feature (counter/histogram, naming akira_<dominio>_<azione>_<unit>)
• Errori tracciati su Sentry con tag feature=<name>
• Dashboard Grafana aggiornata se metric nuova (link in PR body)

Security

• Nessun secret in repo — gitleaks pre-commit + CI verificano
• No raw SQL su input utente — solo SQLAlchemy ORM o text() con bindparams; nessun f-string in query
• Audit log per azioni sensibili — tutte le modifiche su Companies/Tariffs/Routing/Devices loggate su audit_log con user_id, action, before, after
• Nessun PII in log (mascheramento email/phone applicato)
• gitleaks scan verde sull'intera PR

Performance

• p95 API CRUD < 200 ms — verificato con k6 sullo staging post-deploy
• p95 API reports/aggregates < 500 ms — verificato con k6 su dataset di staging (≥ 1M CDR seed)
• Query lente loggate con EXPLAIN allegato nel body PR

Manual smoke

• Massimo verifica flusso end-to-end su staging (o Francesco per flussi UX-heavy) — checklist breve nel body PR con esito

CONVENTIONS Toolbox A.Sheep

• No push diretto su main — solo via PR
• Frontmatter task presente nei file notes/ se PR generata da run notturna Toolbox (formato yaml task_id, started_at, duration_min)
• ≤ 30 min/task rispettato per task atomici (se sforato, split in sotto-task)
• Commit message segue convenzione <scope>: <verbo imperativo> (es. companies: aggiungi endpoint POST /companies)

---

3. Tabella sintetica enforcement

Item	Enforcement	Strumento	Bloccante CI
pytest	auto	GitHub Actions	sì
Vitest	auto	GitHub Actions	sì
Playwright E2E	auto	GitHub Actions	sì
Coverage delta	auto	coverage report --fail-under	sì
ruff check/format	auto	pre-commit + CI	sì
mypy --strict	auto	CI	sì
tsc	auto	CI	sì
eslint	auto	CI	sì
Alembic up/down	auto	CI job migration-test	sì
OpenAPI snapshot	auto	CI diff check	sì
README modulo	manuale	code review	no (warn)
ADR	manuale	code review	no (warn)
Deploy staging	manuale	Ansible run	sì (prerequisito merge)
Smoke staging	auto	smoke-staging.sh	sì
Log + correlation_id	misto	grep CI + review	sì (grep) + manuale
Metrica Prometheus	manuale	code review	no (warn)
Sentry tag	manuale	code review	no (warn)
gitleaks	auto	pre-commit + CI	sì
No raw SQL	misto	bandit + review	sì (bandit)
Audit log	manuale	code review	no (warn)
k6 p95	auto/manuale	k6 run post-deploy	sì (per moduli critici)
Manual smoke	manuale	checklist PR body	sì
Frontmatter task	auto	script check-frontmatter.py	sì (per PR Toolbox)

---

4. Eccezioni e deroghe

Una deroga deve:

1. Essere scritta esplicitamente nel body della PR sotto sezione ## Deroghe DoD.
2. Indicare quale item è derogato.
3. Indicare motivazione tecnica (non "tempo che stringe").
4. Indicare issue di follow-up con scadenza (max 1 sprint).
5. Avere firma esplicita Massimo nel commento PR (approved-deroga: massimo).

Item non derogabili (mai):

• gitleaks
• mypy --strict sui moduli auth/billing
• audit log su azioni sensibili
• migration reversibilità (no DROP irreversibili)
• manual smoke Massimo

---

5. PR template (.github/pull_request_template.md)

## Cosa fa questa PR

<one-liner>

## Why

<contesto, link a issue/spec>

## Come testarla

```bash
# comandi per riprodurre/verificare

DoD checklist

Tests

• pytest backend green
• Vitest frontend smoke
• Playwright E2E happy path

Quality

• Coverage delta OK
• ruff + mypy --strict clean
• tsc + eslint clean

Database

• Alembic up + down testati

API

• OpenAPI snapshot aggiornato
• api-types/ rigenerato

Docs

• README modulo aggiornato (o N/A)
• ADR scritto (o N/A)

Deploy

• Deployato su staging
• Smoke staging verde

Observability

• Log + correlation_id
• Metrica Prometheus
• Sentry tag

Security

• gitleaks verde
• No raw SQL
• Audit log su azioni sensibili (o N/A)

Performance

• k6 p95 < target

Manual

• Smoke E2E verificato da Massimo (o Francesco per UX)

Toolbox conventions

• No push diretto main
• Frontmatter task (se Toolbox-generated)
• ≤ 30 min/task rispettato

Deroghe DoD

<nessuna oppure elenco con motivazione + issue follow-up>

---

## 6. Riferimenti

- `docs/conventions/error-handling-and-correlation-id.md`
- `docs/conventions/branch-strategy.md`
- `docs/architecture/roadmap-v5.16.md`
- `docs/architecture/pilot-gating-kpi.md`
- CONVENTIONS Toolbox A.Sheep (copia in workspace)
- ADR-0001 stack tecnologico