Blueprint Incarichi Tecnici - Release 1

Obiettivo

Release 1 introduce un layer operativo centrale per governare gli incarichi tecnici senza sostituire i verticali esistenti.

Il modulo deve permettere di:

• creare un incarico tecnico manuale;
• assegnare un tecnico;
• distinguere chi gestisce l'incarico da chi lo esegue;
• controllare lo stato con transizioni esplicite;
• tracciare ogni variazione rilevante;
• filtrare gli incarichi per tenant, stato, tecnico, gestore e scadenza.

In Release 1 il calendario viene solo predisposto a livello schema. La sincronizzazione automatica calendario/incarico resta fuori scope.

Perimetro

Incluso:

• modelli SQLAlchemy;
• migrazione Alembic;
• service layer transazionale;
• view FAB iniziale;
• menu Operativo -> Incarichi Tecnici;
• permessi base;
• audit log;
• filtri operativi principali.

Fuori scope Release 1:

• automazioni calendario;
• collegamento automatico da ticket/RAS/DVR/checklist;
• rapportini legati direttamente all'incarico;
• kanban;
• dashboard carico tecnici;
• notifiche email.

Tabelle

technical_assignment

Contenitore principale dell'incarico.

Campi:

• id integer primary key
• tenant_key string(64), not null, index
• code string(40), not null
• tipo_incarico string(40), not null
• source_type string(80), nullable
• source_id integer, nullable
• cliente_id integer, nullable
• condominio_id integer, nullable
• title string(255), not null
• description text, nullable
• stato string(40), not null, default da_assegnare
• priorita string(24), not null, default media
• manager_user_id integer, nullable, FK ab_user.id
• assigned_user_id integer, nullable, FK ab_user.id
• created_by_id integer, nullable, FK ab_user.id
• closed_by_id integer, nullable, FK ab_user.id
• planned_start datetime, nullable
• planned_end datetime, nullable
• due_date date, nullable
• opened_at datetime, nullable
• assigned_at datetime, nullable
• started_at datetime, nullable
• completed_at datetime, nullable
• cancelled_at datetime, nullable
• notes_internal text, nullable
• closure_note text, nullable
• created_at datetime, not null
• updated_at datetime, not null

Vincoli e indici:

• unique (tenant_key, code)
• index (tenant_key, stato)
• index (tenant_key, assigned_user_id, stato)
• index (tenant_key, manager_user_id, stato)
• index (tenant_key, due_date)
• index (tenant_key, tipo_incarico)
• index (tenant_key, source_type, source_id)

technical_assignment_log

Storico operativo dell'incarico.

Campi:

• id integer primary key
• tenant_key string(64), not null, index
• assignment_id integer, not null, FK technical_assignment.id
• event_type string(60), not null
• old_value text, nullable
• new_value text, nullable
• note text, nullable
• created_by_id integer, nullable, FK ab_user.id
• created_at datetime, not null

Indici:

• index (tenant_key, assignment_id)
• index (tenant_key, event_type)
• index (tenant_key, created_at)

Eventi minimi:

• created
• status_changed
• assigned_user_changed
• manager_changed
• priority_changed
• planning_changed
• closed
• cancelled

technical_assignment_event

Ponte futuro tra incarico ed eventi calendario.

Campi:

• id integer primary key
• tenant_key string(64), not null, index
• assignment_id integer, not null, FK technical_assignment.id
• calendar_event_id integer, nullable
• event_type string(40), nullable
• starts_at datetime, nullable
• ends_at datetime, nullable
• status string(40), not null, default planned
• created_at datetime, not null
• updated_at datetime, not null

Indici:

• index (tenant_key, assignment_id)
• index (tenant_key, calendar_event_id)
• index (tenant_key, starts_at)

Enumerazioni

Tipi Incarico

Costanti iniziali:

• intervento
• ras
• dvr
• checklist
• sopralluogo
• formazione
• altro

Stati

Costanti iniziali:

• draft
• da_assegnare
• assegnato
• da_pianificare
• programmato
• in_lavorazione
• in_attesa
• sospeso
• completato
• annullato

Priorita

Costanti iniziali:

• bassa
• media
• alta
• urgente

Stato Macchina

Transizioni ammesse:

draft -> da_assegnare
da_assegnare -> assegnato
assegnato -> da_pianificare
assegnato -> programmato
da_pianificare -> programmato
programmato -> in_lavorazione
in_lavorazione -> in_attesa
in_lavorazione -> sospeso
in_lavorazione -> completato
in_attesa -> programmato
in_attesa -> in_lavorazione
in_attesa -> annullato
sospeso -> da_pianificare
sospeso -> annullato

Stati terminali:

• completato
• annullato

Vincoli:

• assegnato richiede assigned_user_id;
• programmato richiede assigned_user_id e planned_start;
• completato richiede closure_note o outcome minimo;
• annullato richiede nota;
• ogni transizione deve generare log.

Moduli e File Proposti

Percorso modulo:

app/modules/technical_assignments/

File:

app/modules/technical_assignments/__init__.py
app/modules/technical_assignments/models.py
app/modules/technical_assignments/services.py
app/modules/technical_assignments/views.py
app/templates/appbuilder/custom/technical_assignment_show.html

Migrazione:

migrations/versions/<revision>_add_technical_assignments.py

Classi SQLAlchemy

Classi:

• TechnicalAssignment
• TechnicalAssignmentLog
• TechnicalAssignmentEvent

Relazioni minime:

• TechnicalAssignment.logs
• TechnicalAssignment.events
• TechnicalAssignment.manager
• TechnicalAssignment.assigned_user
• TechnicalAssignment.created_by
• TechnicalAssignment.closed_by

Service Layer

Il service layer e obbligatorio. Le view non devono modificare direttamente stato, assegnazioni o pianificazione senza passare dai servizi.

Funzioni iniziali:

create_assignment(...)
assign_technician(...)
change_status(...)
reschedule_assignment(...)
change_manager(...)
change_priority(...)
close_assignment(...)
cancel_assignment(...)
log_assignment_event(...)

Responsabilita:

• validare tenant;
• validare transizioni;
• aggiornare timestamp di processo;
• creare log;
• mantenere atomica ogni operazione.

Regole Service

create_assignment

Input minimo:

• tenant_key
• title
• tipo_incarico
• manager_user_id opzionale
• assigned_user_id opzionale
• created_by_id

Comportamento:

• genera code;
• imposta opened_at;
• stato iniziale:
• assegnato se assigned_user_id valorizzato;
• altrimenti da_assegnare;
• crea log created;
• crea log assigned_user_changed se tecnico gia presente.

assign_technician

Vincoli:

• tecnico deve essere utente attivo del tenant;
• stati terminali non modificabili.

Comportamento:

• aggiorna assigned_user_id;
• imposta assigned_at se vuoto;
• se stato da_assegnare, passa a assegnato;
• logga cambio tecnico e cambio stato se avviene.

change_status

Vincoli:

• transizione presente nella matrice;
• vincoli stato rispettati;
• stati terminali non modificabili.

Comportamento:

• aggiorna stato;
• aggiorna timestamp collegato:
• started_at per in_lavorazione;
• completed_at e closed_by_id per completato;
• cancelled_at per annullato;
• logga status_changed.

reschedule_assignment

Vincoli:

• planned_end deve essere maggiore di planned_start, se presente;
• stati terminali non modificabili.

Comportamento:

• aggiorna pianificazione;
• se stato assegnato, puo passare a programmato quando esistono tecnico e planned_start;
• logga planning_changed.

Permessi

Profili:

• admin tenant;
• gestore incarichi;
• tecnico.

Ruoli consigliati:

• ROLE_PROFILE_ADMIN_TENANT
• ROLE_PROFILE_GESTORE_INCARICHI
• profili tecnici esistenti o ruolo tecnico tenant.

Regole:

• admin tenant: piena visibilita tenant;
• gestore incarichi: piena visibilita tenant e gestione operativa;
• tecnico: vede solo assigned_user_id == current_user.id;
• tutti i query scope filtrano sempre tenant_key.

View FAB

Classe:

TechnicalAssignmentView(ModelView)

Route:

/technical-assignments

Menu:

Operativo -> Incarichi Tecnici

Colonne lista:

• code
• tipo_incarico
• title
• cliente_id
• stato
• priorita
• manager_user_id
• assigned_user_id
• planned_start
• due_date
• updated_at

Filtri:

• stato
• tipo_incarico
• priorita
• manager_user_id
• assigned_user_id
• cliente_id
• due_date

Filtri custom da aggiungere:

• senza tecnico;
• da pianificare;
• in ritardo.

Azioni iniziali:

• crea incarico;
• assegna tecnico;
• cambia stato;
• modifica pianificazione;
• chiudi;
• annulla.

Show View

La vista dettaglio deve mostrare:

• dati principali;
• responsabilita;
• pianificazione;
• origine;
• note interne;
• chiusura;
• storico log ordinato per data discendente.

Registrazione App

In app/__init__.py:

• import TechnicalAssignmentView;
• appbuilder.add_view(...);
• categoria Operativo;
• menu label Incarichi Tecnici;
• condizione modulo interventi o modulo dedicato technical_assignments.

Per Release 1 si puo agganciare alla condizione menu_interventi_enabled_current_tenant, poi separare in feature dedicata.

In app/modules/iam/menu_runtime.py:

• aggiungere incarichi tecnici alle voci operative forzate per tenant abilitati.

Migrazione Alembic

La migrazione deve:

• creare le tre tabelle;
• creare indici;
• creare FK verso ab_user;
• usare tenant_key coerente con il resto SafeOps;
• essere idempotente dove ragionevole, seguendo lo stile delle migrazioni recenti.

Test Smoke Release 1

Test minimi:

1. crea incarico manuale;
2. verifica code generato;
3. verifica log created;
4. assegna tecnico;
5. verifica stato assegnato;
6. verifica log tecnico;
7. prova passaggio a programmato senza planned_start, deve fallire;
8. imposta pianificazione;
9. passa a programmato;
10. passa a in_lavorazione;
11. prova completamento senza nota finale, deve fallire;
12. completa con nota;
13. verifica stato terminale;
14. prova modifica stato terminale, deve fallire;
15. tecnico vede solo i propri incarichi;
16. admin/gestore vede tutto il tenant.

Criteri di Accettazione

Release 1 e accettata quando:

• un incarico puo essere creato manualmente;
• ogni incarico e isolato per tenant_key;
• admin e gestore vedono tutto il tenant;
• tecnico vede solo i propri incarichi;
• assegnazione tecnico funziona;
• cambio stato e controllato;
• ogni cambio stato e assegnazione genera log;
• filtri senza tecnico, da pianificare e in ritardo funzionano;
• menu operativo e disponibile;
• nessuna automazione calendario e necessaria per completare il rilascio.

Note di Implementazione

• Evitare logica di workflow nelle view.
• Evitare automazioni sui verticali in Release 1.
• Non migrare dati ticket/interventi/RAS nella prima release.
• Tenere source_type e source_id nullable per supportare incarichi manuali.
• Usare label italiane in UI, valori macchina stabili in DB.