if (status.equals("APPROVED")) {
    status = "POSTED";
}

public enum PurchaseOrderStatus {
    DRAFT,
    SUBMITTED,
    APPROVED,
    CANCELLED,
    CLOSED
}

current state
+ event
+ actor/context
+ guard
+ action
+ next state
+ evidence

Transition = f(currentState, event, context) -> nextState + actions
only if guards(context) are true

DRAFT + SUBMIT
  guard: has at least one line, vendor active, total > 0, period open
  action: create approval workflow
  next: SUBMITTED

status = SENT

document_state = APPROVED
approval_state = COMPLETED
posting_state = NOT_POSTED
integration_state = PENDING_EXPORT

@ParameterizedTest
@MethodSource("illegalTransitions")
void illegalTransitionsMustFail(DocumentState current, DocumentEvent event) {
    var po = PurchaseOrderFixture.inState(current);
    assertThrows(IllegalTransitionException.class,
            () -> stateMachine.apply(po, event, context));
}

public interface TransitionGuard<D, C> {
    GuardDecision evaluate(D document, C context);
}

public record GuardDecision(
        boolean allowed,
        String code,
        List<String> reasons,
        Map<String, Object> evidence
) {
    public static GuardDecision allow(String code) {
        return new GuardDecision(true, code, List.of(), Map.of());
    }

    public static GuardDecision deny(String code, String reason) {
        return new GuardDecision(false, code, List.of(reason), Map.of());
    }
}

public final class PurchaseOrderSubmitGuard
        implements TransitionGuard<PurchaseOrder, TransitionContext> {

    @Override
    public GuardDecision evaluate(PurchaseOrder po, TransitionContext ctx) {
        if (po.lines().isEmpty()) {
            return GuardDecision.deny("PO_SUBMIT", "PO must have at least one line");
        }
        if (!po.vendorSnapshot().active()) {
            return GuardDecision.deny("PO_SUBMIT", "Vendor is inactive");
        }
        if (po.total().isZeroOrNegative()) {
            return GuardDecision.deny("PO_SUBMIT", "PO total must be positive");
        }
        if (ctx.periodService().isLocked(po.documentDate(), po.legalEntityId())) {
            return GuardDecision.deny("PO_SUBMIT", "Accounting period is locked");
        }
        return GuardDecision.allow("PO_SUBMIT");
    }
}

state update
+ transition log
+ domain event
+ outbox message
commit together

@Transactional
public TransitionResult transition(TransitionCommand command) {
    Document doc = repository.getForUpdate(command.documentId());
    TransitionPlan plan = stateMachine.plan(doc, command.event(), command.context());

    plan.assertAllowed();
    doc.apply(plan);

    repository.save(doc);
    transitionLogRepository.append(TransitionLog.from(plan));
    outboxRepository.saveAll(plan.outboxEvents());

    return TransitionResult.success(doc.id(), doc.state(), doc.revision());
}

create table erp_document (
    id uuid primary key,
    document_type varchar(80) not null,
    document_number varchar(120) not null,
    legal_entity_id uuid not null,
    branch_id uuid,
    document_state varchar(60) not null,
    approval_state varchar(60) not null,
    posting_state varchar(60) not null,
    integration_state varchar(60) not null,
    revision integer not null,
    version integer not null,
    created_at timestamptz not null,
    updated_at timestamptz not null,
    unique (document_type, document_number)
);

create table document_transition_log (
    id uuid primary key,
    document_id uuid not null,
    document_type varchar(80) not null,
    from_state varchar(60) not null,
    to_state varchar(60) not null,
    event varchar(80) not null,
    actor_id uuid,
    transition_time timestamptz not null,
    revision integer not null,
    command_id varchar(160) not null,
    guard_evidence jsonb not null,
    action_evidence jsonb not null,
    reason_code varchar(120),
    comment text,
    hash varchar(128) not null,
    previous_hash varchar(128),
    unique (document_id, command_id)
);

who moved this document from state A to state B,
when,
why,
under which guard decision,
for which revision,
with what command id.

revision = 4 means business content revision 4
version = 23 means row has been updated 23 times

DRAFT -> APPROVED -> POSTED -> PAID -> CLOSED
POSTED -> CREDITED -> CLOSED
POSTED -> REVERSED -> CLOSED

update invoice set amount = 0 where id = :id;

create credit note or reversal journal linked to original invoice

public final class StateMachine<S extends Enum<S>, E extends Enum<E>, D> {
    private final Map<Key<S, E>, Transition<S, E, D>> transitions;

    public TransitionPlan<S> plan(D document, S current, E event, TransitionContext context) {
        Transition<S, E, D> transition = transitions.get(new Key<>(current, event));
        if (transition == null) {
            throw new IllegalTransitionException(current, event);
        }

        GuardDecision guard = transition.guard().evaluate(document, context);
        if (!guard.allowed()) {
            return TransitionPlan.denied(current, event, guard);
        }

        return TransitionPlan.allowed(
                current,
                transition.to(),
                event,
                guard,
                transition.actions()
        );
    }
}

new Transition<>(
    PurchaseOrderState.DRAFT,
    PurchaseOrderEvent.SUBMIT,
    PurchaseOrderState.SUBMITTED,
    new PurchaseOrderSubmitGuard(),
    List.of(new CreateApprovalWorkflowAction())
)

public interface PurchaseOrderLifecycleState {
    PurchaseOrderState state();
    TransitionPlan submit(PurchaseOrder po, TransitionContext ctx);
    TransitionPlan approve(PurchaseOrder po, TransitionContext ctx);
    TransitionPlan cancel(PurchaseOrder po, TransitionContext ctx);
}

OPEN
  - DRAFT
  - SUBMITTED
  - APPROVED
FULFILLMENT
  - ALLOCATING
  - PICKING
  - SHIPPED_PARTIAL
  - SHIPPED_FULL
BILLING
  - INVOICED_PARTIAL
  - INVOICED_FULL
CLOSED
  - CLOSED_NORMAL
  - CLOSED_CANCELLED
  - CLOSED_REVERSED

approval_state: PENDING / APPROVED / REJECTED
fulfillment_state: NOT_RELEASED / RELEASED / PARTIAL / COMPLETE
billing_state: NOT_BILLED / PARTIAL / COMPLETE
payment_state: UNPAID / PARTIAL / PAID

billing_state cannot be COMPLETE if fulfillment_state is NOT_RELEASED
payment_state cannot be PAID if billing_state is NOT_BILLED
fulfillment_state cannot be RELEASED if approval_state != APPROVED

public final class SalesOrderLifecycleInvariant {
    public void validate(SalesOrder order) {
        if (order.fulfillmentState().isReleasedOrBeyond()
                && order.approvalState() != ApprovalState.APPROVED) {
            throw new LifecycleInvariantViolation("Cannot fulfill unapproved order");
        }

        if (order.paymentState() == PaymentState.PAID
                && order.billingState() == BillingState.NOT_BILLED) {
            throw new LifecycleInvariantViolation("Cannot pay unbilled order");
        }
    }
}

update purchase_order
set state = :nextState,
    version = version + 1
where id = :id
  and state = :expectedState
  and version = :expectedVersion;

select *
from purchase_order
where id = :id
for update;

POST /purchase-orders/{id}/approve
Idempotency-Key: actor-task-approval-uuid

unique (document_id, command_id)

{
  "documentId": "...",
  "documentType": "PURCHASE_ORDER",
  "fromState": "IN_REVIEW",
  "event": "APPROVE",
  "toState": "APPROVED",
  "actorId": "...",
  "revision": 4,
  "guardEvidence": {
    "approvalComplete": true,
    "budgetStillAvailable": true,
    "periodOpen": true
  },
  "actionEvidence": {
    "approvalSnapshotId": "...",
    "outboxEventId": "..."
  },
  "transitionTime": "2026-06-30T10:15:30Z",
  "commandId": "..."
}

public record PurchaseOrderApproved(
        UUID purchaseOrderId,
        String documentNumber,
        int revision,
        UUID legalEntityId,
        Money total,
        Instant approvedAt
) implements DomainEvent {}

public final class PostingGuard implements TransitionGuard<FinancialDocument, TransitionContext> {
    @Override
    public GuardDecision evaluate(FinancialDocument doc, TransitionContext ctx) {
        if (doc.approvalState() != ApprovalState.APPROVED) {
            return GuardDecision.deny("POSTING_GUARD", "Document is not approved");
        }
        if (doc.postingState() != PostingState.NOT_POSTED) {
            return GuardDecision.deny("POSTING_GUARD", "Document already posted or reversed");
        }
        if (ctx.periodService().isLocked(doc.accountingDate(), doc.legalEntityId())) {
            return GuardDecision.deny("POSTING_GUARD", "Accounting period is locked");
        }
        if (!doc.isBalancedIfFinancial()) {
            return GuardDecision.deny("POSTING_GUARD", "Journal is not balanced");
        }
        return GuardDecision.allow("POSTING_GUARD");
    }
}

DRAFT -> APPROVED -> POSTED

DRAFT -> SUBMITTED -> IN_REVIEW -> APPROVED -> RELEASED -> POSTED

insert into document_transition_log (
    id, document_id, from_state, to_state, event,
    actor_id, transition_time, revision,
    guard_evidence, action_evidence, command_id
) values (
    gen_random_uuid(), :docId, :oldState, :newState, 'LIFECYCLE_MIGRATION',
    :migrationActor, now(), :revision,
    :evidence, :actionEvidence, :migrationCommandId
);

@Test
void draftCanBeSubmittedWhenValid() {
    PurchaseOrder po = fixtures.validDraftPo();
    TransitionResult result = lifecycle.transition(po, PurchaseOrderEvent.SUBMIT, context);
    assertThat(result.nextState()).isEqualTo(PurchaseOrderState.SUBMITTED);
}

@Test
void closedPoCannotBeEdited() {
    PurchaseOrder po = fixtures.closedPo();
    assertThrows(IllegalTransitionException.class,
        () -> lifecycle.transition(po, PurchaseOrderEvent.EDIT, context));
}

@Test
void cannotPostWhenPeriodLocked() {
    var po = fixtures.approvedPo();
    var ctx = context.withLockedPeriod(true);

    GuardDeniedException ex = assertThrows(GuardDeniedException.class,
        () -> lifecycle.transition(po, PurchaseOrderEvent.POST, ctx));

    assertThat(ex.reasonCode()).isEqualTo("POSTING_GUARD");
}

No document can move out of CLOSED.
No posted document can be edited directly.
No document can be POSTED twice.
No approval decision applies to a different revision.
No transition can skip required approval.

document_transition_total{document_type,event,from_state,to_state,outcome}
illegal_transition_rejected_total{document_type,event,current_state,reason}
transition_guard_denied_total{guard,reason}
document_state_age_seconds{document_type,state}
posted_document_reversal_total{document_type,reason}
stale_revision_transition_rejected_total{document_type}

{
  "documentId": "...",
  "state": "IN_REVIEW",
  "revision": 4,
  "allowedActions": [
    {
      "action": "APPROVE",
      "enabled": true,
      "reason": null
    },
    {
      "action": "CANCEL",
      "enabled": false,
      "reason": "Only requester can cancel during review"
    }
  ]
}

{
  "event": "APPROVE",
  "expectedState": "IN_REVIEW",
  "expectedRevision": 4,
  "expectedVersion": 23,
  "reasonCode": "OK",
  "comment": "Budget verified"
}

APPROVED_PARTIALLY_SHIPPED_PARTIALLY_INVOICED_PAYMENT_PENDING_EXPORT_FAILED

DRAFT can be edited.
SUBMITTED cannot change approval-relevant fields without returning to DRAFT.
APPROVED is valid only for revision N.
RELEASED means supplier-facing commitment exists.
RECEIVED implies at least one goods receipt exists.
CLOSED means no further receiving is allowed.
CANCELLED before receipt has no stock effect.
Cancellation after receipt requires return/reversal/credit flow, not simple cancel.

public enum PurchaseOrderEvent {
    SUBMIT,
    START_APPROVAL,
    REQUEST_CHANGE,
    RESUBMIT,
    APPROVE_ALL,
    REJECT,
    RELEASE_TO_SUPPLIER,
    RECEIVE_PARTIAL,
    RECEIVE_COMPLETE,
    CANCEL,
    CLOSE,
    CLOSE_SHORT
}

registry.register(DRAFT, SUBMIT, SUBMITTED, submitGuard, createApprovalWorkflow);
registry.register(SUBMITTED, START_APPROVAL, IN_REVIEW, workflowGuard, openApprovalTasks);
registry.register(IN_REVIEW, REQUEST_CHANGE, RETURNED, reviewGuard, notifyRequester);
registry.register(RETURNED, RESUBMIT, SUBMITTED, submitGuard, rerouteApproval);
registry.register(IN_REVIEW, APPROVE_ALL, APPROVED, approvalCompleteGuard, snapshotApproval);
registry.register(IN_REVIEW, REJECT, REJECTED, reviewGuard, closeWorkflow);
registry.register(APPROVED, RELEASE_TO_SUPPLIER, RELEASED, releaseGuard, publishSupplierOrder);
registry.register(RELEASED, RECEIVE_PARTIAL, PARTIALLY_RECEIVED, receivingGuard, createStockLedgerEvent);
registry.register(PARTIALLY_RECEIVED, RECEIVE_COMPLETE, FULLY_RECEIVED, receivingGuard, createStockLedgerEvent);
registry.register(FULLY_RECEIVED, CLOSE, CLOSED, closeGuard, closeOpenCommitments);

Can this lifecycle survive audit, concurrency, integration retry, and user correction?