Bacheche

Una bacheca appartiene a un team e contiene gli stati (le colonne del Kanban), le task, le viste, i filtri salvati, le etichette proprie, i link pubblici e i webhook.

Modelli

Modello	Tabella	Cosa rappresenta
Board	boards	La bacheca: team_id, title, board_key (sigla), task_counter, color_code, archived_at.
BoardTemplate	board_templates	Un modello di bacheca: owner_id, team_id, visibility (system, private, team, public) e la struttura in JSON.
BoardList	board_lists	Uno stato/colonna: position, color_code, is_done, is_default_done, excluded_from_progress, counts_time.
BoardView	board_views	Una vista salvata: view_kind fra list, kanban, table, gantt, calendar, con filtro e raggruppamento in JSON.
SavedFilter	saved_filters	Un filtro personale (owner_id) su una bacheca.
LinkShare	link_shares	Un link pubblico, in lettura o scrittura.
Webhook, WebhookDelivery	webhooks, webhook_deliveries	Vedi Webhook.
Favorite	favorites	Preferiti dell'utente, per bacheche e task.
—	board_user_positions	Ordine personalizzato delle bacheche, per utente (user_id, board_id, position).
Tag	tags	Etichetta: globale se board_id è NULL, altrimenti della bacheca.

Bacheche, stati, viste, filtri, link e webhook vanno nel cestino invece di essere eliminati (vedi Cestino).

Sigla e numerazione

• board_key è di massimo 6 caratteri maiuscoli o cifre, unica. Alla creazione BoardKeyService la propone dal titolo (le iniziali di un titolo di più parole, le prime quattro lettere di una parola sola, altrimenti BOARD) e aggiunge un numero se è già presa.
• Ogni task riceve un numero progressivo dal contatore della bacheca (task_counter, incrementato in modo atomico da TaskNumberBehavior). Sigla e numero formano la chiave della task, ad esempio OPS-142. Una volta assegnato, il numero non cambia più.

Stati

• Colonna d'ingresso. Non c'è un flag: TaskWorkflow::entryList() usa lo stato che si chiama "Da fare", altrimenti il primo non concluso, altrimenti il primo.
• Stati conclusivi. Uno stato con is_done conclude le task che ci entrano. Fra gli stati conclusivi, quello con is_default_done è dove va una task completata con il comando "Completa".
• Avanzamento. La percentuale di una task dipende dalla posizione del suo stato (vedi Task). excluded_from_progress toglie uno stato dal calcolo.
• Conteggio ore. Uno stato con counts_time conteggia le ore delle task che contiene (vedi Task); non è ammesso insieme a is_done.

BoardListService crea gli stati predefiniti (Da fare, In corso, In revisione, Completato, l'ultimo conclusivo) e ne gestisce le modifiche:

• segnare o togliere is_done aggiorna in blocco le task dello stato a completate o aperte, con updateAll (senza storia né webhook);
• uno stato con task non si elimina;
• ogni modifica ricalcola l'avanzamento della bacheca.

Creazione

BoardFactory::create crea la bacheca dal modello di sistema; solo se quello manca usa gli stati predefiniti scritti nel codice, una vista Kanban e il filtro preferito "Tutte le task". Dal frontend e dall'API la creazione passa da BoardSettings::createBoard, che senza un modello scelto usa il predefinito dell'utente. BoardSettings raccoglie le altre operazioni di configurazione: nome, archivio, colore, sigla, preferiti, ordine degli stati, viste, filtri, webhook, link.

Modelli di bacheca

Un modello è un'istantanea della struttura di una bacheca, salvata in board_templates.structure (JSON) e slegata dal team di origine: stati con i loro flag, etichette della bacheca, viste, filtri e, a scelta, le task iniziali (titolo, descrizione, priorità, stima, checklist, etichette, gerarchia). Nella struttura i riferimenti interni sono posizioni negli elenchi, non id.

Visibilità (visibility):

Valore	Chi lo vede e lo usa
system	tutti; è uno solo, si modifica solo dal pannello e non si elimina
private	solo il proprietario
team	i membri di team_id; lo modifica anche chi ha board.manage sul team
public	tutti gli utenti

BoardTemplateService:

• snapshot / saveFromBoard leggono una bacheca e ne fanno un modello (serve board.manage sulla bacheca);
• createFrom crea una bacheca dal modello: stati, etichette, viste, filtri (che passano a chi crea la bacheca) e, a richiesta, le task, tutte riaperte, con le checklist da spuntare e chi crea la bacheca come autore;
• visibleTo, findUsable, canEdit applicano la visibilità;
• defaultFor restituisce il predefinito dell'utente (user.default_board_template_id) se lo vede ancora, altrimenti quello di sistema;
• update applica l'editor (titolo, descrizione, visibilità, stati ed etichette) spostando le task con le loro colonne.

Le bacheche che fino alla 3.2 erano modelli (boards.is_template) sono state convertite in modelli team dalla migrazione m261014_120000, e restano bacheche normali.

Ordinamento nell'elenco

Nell'elenco bacheche ogni membro sceglie, team per team, come ordinarle: alfabetico, per numero di task (crescente o decrescente) o personalizzato. La scelta sta in team_members.board_sort (title, tasks_asc, tasks_desc, custom) e si salva con board-preference/set-sort. L'ordine personalizzato si trascina e si salva con board-preference/reorder in board_user_positions: è personale, e le bacheche senza posizione vanno in coda. Basta il permesso board.view. Le preferite restano in ordine alfabetico. Le due azioni passano da BoardSettings::orderBoards(), come PUT /v1/teams/{uuid}/board-order.

Il server consegna le bacheche in ordine di titolo con i dati per ordinarle (data-sort-title, data-sort-tasks, data-sort-position); l'ordine lo applica board-index.js, che gestisce anche il menu e il trascinamento.

Spazio personale

Ogni utente ha uno spazio personale: un team "Personale" con lui solo e una bacheca "La mia bacheca". Vedi Team e ruoli.

Filtri e query

• TaskFilterConfigBuilder::build() trasforma i campi del modulo filtri nella configurazione salvata: stato, priorità, assegnatario, autore, etichette (tags, id) e intervalli di date (creazione, completamento, scadenza), accettando gg/mm/aaaa o AAAA-MM-GG.
• BoardTaskQuery::applyFilter() la applica. L'assegnatario corrisponde sia al vecchio campo assigned_to sia alla tabella task_assignees; fra più etichette basta averne una.
• Filtro rapido per etichetta: ?tag=uuid sulla pagina della bacheca (è il clic su un'etichetta di una card, della tabella o della lista) si aggiunge a vista e filtro salvato senza essere salvato (BoardBaseController::effectiveFilter()). Un'etichetta che non è globale né della bacheca non filtra niente.
• Le colonne Kanban si caricano a pagine da 50, le viste a elenco da 100, la timeline fino a 1000 task.

Etichette

• Globali (board_id NULL, permesso tag.global) o della bacheca (tag.manage sul team). Il nome è unico nel suo ambito, senza distinguere maiuscole.
• Nel titolo. Alla creazione (TaskWorkflow::create(), quindi dal modale e dall'API) TitleTags riconosce #nome quando corrisponde per intero a un'etichetta disponibile: la applica e la toglie dal titolo. Il resto resta testo, quindi #123 o un nome inesistente non cambiano e non creano niente; a parità di nome vince l'etichetta della bacheca. Il modale mostra le etichette disponibili, e un clic aggiunge #nome al titolo.
• Nella scheda. Il campo di ricerca filtra le etichette; Invio applica quella trovata o, a chi ha tag.manage, crea l'etichetta della bacheca con un colore a turno e la applica (TaskTagController::actionCreate(); un nome già esistente riusa quella).
• Si vedono su card, tabella, lista e «Le mie task», con il loro colore; il clic filtra.

Importazione ed esportazione CSV

BoardCsv (azioni in BoardDataController e nell'API):

• separatore ;, BOM UTF-8, date gg/mm/aaaa;
• colonne: uuid, chiave, titolo, descrizione, stato, priorita, assegnatario, inizio, fine, avanzamento, stima_minuti, registrato_minuti, tag, creata_il;
• ogni cella passa da CsvSafety, contro l'iniezione di formule nei fogli di calcolo;
• l'importazione richiede la colonna titolo, riconosce stato, priorità e assegnatario per nome, salta le righe non valide e le elenca;
• l'importazione non invia notifiche né webhook per le task create;
• ogni esportazione finisce nel registro operazioni.

Link pubblici

LinkShareController crea i link, ShareController apre la pagina pubblica share/<token>:

• il token nel percorso è la credenziale; può avere una password (chiesta una volta per sessione) e una scadenza (fine del giorno scelto);
• un link in scrittura permette di creare task (nello stato d'ingresso, con autore chi ha condiviso) e di spostarle;
• le scritture sono limitate a 30 l'ora per link e per indirizzo IP.

Note

ShareController salva le task direttamente invece di passare da TaskWorkflow: i behavior (numero, stato, storia, webhook) girano, ma non partono notifiche.

Ricerca

TaskSearch cerca in titolo e descrizione delle task e nei commenti, con indici full-text, solo nei team dell'utente. Il nome intero di un'etichetta (anche come #bug) trova le task che la portano. Servono almeno 2 caratteri; una chiave come OPS-142 porta per prima la task esatta.