Una màquina d'estats converteix un simple camp d'estat en un flux de treball guiat: una instància només es pot moure entre estats seguint les transicions que defineixes, i cada moviment pot executar comprovacions o passos posteriors abans de confirmar-se. Aquest tutorial construeix un exemple complet — un informe de despeses (ExpenseReport) que va d'Esborrany → Enviat → Aprovat o Rebutjat → Pagat — perquè vegis com encaixa cada peça.

Combinaràs blocs que Yellow ja ofereix:

  • una enumeració els ítems de la qual són els estats,
  • una restricció de màquina d'estats que diu "l'estat d'aquest model viu en aquesta propietat i fa servir aquesta enumeració",
  • registres de transició que defineixen els moviments permesos, i
  • una restricció de referència perquè el camp d'estat es mostri com un desplegable.

Què construiràs

Peça Funció
Model ExpenseReport L'element que té un flux de treball — Title, Amount, Submitter i una propietat State.
Enumeració ExpenseReportStatus El conjunt d'estats: Draft, Submitted, Approved, Rejected, Paid.
Restricció de màquina d'estats Vincula la propietat State d'ExpenseReport amb l'enumeració ExpenseReportStatus.
Transicions Els moviments permesos entre estats.
Model RejectionInfo Dades addicionals que es capturen quan es rebutja un informe.

Pas 1 — Crea l'enumeració d'estats

Crea una enumeració anomenada ExpenseReportStatus i afegeix-hi un ítem per estat. Dona a cada ítem un Name (el que veuen els usuaris) i un Id (un número que tries, que serveix per ordenar):

Ítem Id
Draft 1
Submitted 2
Approved 3
Rejected 4
Paid 5

Resultat: una enumeració amb cinc ítems, ordenats per Id.

Pas 2 — Crea el model ExpenseReport

Crea un model anomenat ExpenseReport amb aquestes propietats:

Propietat Tipus Què fa
Title Text Un títol breu de l'informe.
Amount Número L'import total.
Submitter Text Qui l'ha enviat.
State Referència Conté l'estat actual — apunta a un ítem d'ExpenseReportStatus.

La propietat State és la que mou el flux de treball; les altres tres són camps normals.

Pas 3 — Fes que State sigui un desplegable

Afegeix una restricció de referència a la propietat State perquè només accepti els estats:

  • Model objectiu: EnumerationItem
  • Enumeració: ExpenseReportStatus
  • Obligatori: sí

Resultat: quan edites un informe de despeses, State es mostra com un desplegable amb els cinc estats, en lloc d'un selector de referència lliure.

Pas 4 — Declara la màquina d'estats

Afegeix una restricció de màquina d'estats amb:

  • Model: ExpenseReport
  • Propietat: State
  • Màquina d'estats: ExpenseReportStatus

Això indica a Yellow que ExpenseReport té un flux de treball i quina propietat conté el seu estat.

Pas 5 — Defineix les transicions

Crea una transició per cada moviment permès. Cada transició indica la màquina d'estats, un estat inicial, un estat final i una opció Direct. Algunes també apunten a un model d'Additional Info per a dades addicionals.

De A Direct Additional Info
Draft Submitted Sí —
Submitted Approved No —
Submitted Rejected No RejectionInfo
Approved Paid No —

Per a la transició de rebuig, crea primer un model petit RejectionInfo amb Reason (Text) i Rejected By (Text). Qui rebutgi un informe els emplenarà.

Moviments directes i no directes

L'opció Direct decideix com s'aplica un moviment:

  • Direct = Sí — el moviment passa immediatament en desar. Draft → Submitted és directe: enviar sempre està permès, així que l'estat canvia a l'instant.
  • Direct = No — el moviment es registra com una sol·licitud i s'aplica després, un cop Yellow ha executat les validacions del model i els passos posteriors. Submitted → Approved no és directe: l'aprovació pot dependre de regles, per això es comprova abans de canviar l'estat.

Un moviment no directe que no es pot completar torna amb el motiu, i l'estat es queda on era.

Com fer-lo servir

Obre un informe de despeses en estat Draft i busca el menú Save & transition al costat de Save. Només llista els estats als quals pots arribar des de l'actual — des de Draft veuràs Submitted.

  1. Tria Submitted. Com que aquest moviment és directe, l'informe passa a Submitted tan bon punt es desa.
  2. Des de Submitted, tria Approved o Rejected. Aquests no són directes: Yellow registra la sol·licitud i la resol, i després actualitza l'estat si es compleixen les regles.
  3. Si tries Rejected, primer s'obre un formulari petit — els camps de RejectionInfo — perquè anotis el motiu. Emplena'l i confirma.

El camp State és de només lectura a l'editor expressament: l'única manera de canviar-lo és mitjançant una transició, cosa que manté vigents les regles del flux de treball.

On trobar-ho

L'enumeració d'estats i els seus ítems són a l'àrea d'Enumeracions. El model, la seva propietat State i les dues restriccions s'editen a l'editor de models. Les transicions són instàncies normals del model StateMachineTransition, de manera que les crees i edites com qualsevol altra dada.

Relacionat

  • Enumeracions — els estats són els ítems d'una enumeració.
  • Restriccions — les restriccions de referència i de màquina d'estats que s'hi fan servir.
  • Tipus de propietat — referències i altres tipus de propietat.