task-d.7.2

docs/setup/setup-state-machine.md

@@ -0,0 +1,155 @@
+# Setup State Machine
+
+D.7.1 does not implement persistence. This document proposes the model and transitions for D.7.8.
+
+## States
+
+```text
+not_started
+readiness_checked
+foundation_installed
+organization_created
+administrator_created
+scope_configured
+sequences_configured
+approval_configured
+csv_validated
+csv_imported
+verified
+completed
+failed
+cancelled
+```
+
+## Events
+
+```text
+CHECK_READINESS
+INSTALL_FOUNDATION
+CREATE_ORGANIZATION
+CREATE_ADMIN
+CONFIGURE_SCOPE
+CONFIGURE_SEQUENCES
+CONFIGURE_APPROVAL
+VALIDATE_CSV
+IMPORT_CSV
+RUN_VERIFICATION
+COMPLETE_SETUP
+FAIL_STEP
+CANCEL_SETUP
+RESUME_SETUP
+RESET_STEP
+```
+
+## Transition Rules
+
+| From | Event | To | Guard |
+| --- | --- | --- | --- |
+| `not_started` | `CHECK_READINESS` | `readiness_checked` | Required readiness checks pass or warnings are acknowledged. |
+| `readiness_checked` | `INSTALL_FOUNDATION` | `foundation_installed` | Migrations valid and seed transaction succeeds. |
+| `foundation_installed` | `CREATE_ORGANIZATION` | `organization_created` | Organization is created or resolved. |
+| `organization_created` | `CREATE_ADMIN` | `administrator_created` | User, membership, and CRM role assignment resolve. |
+| `administrator_created` | `CONFIGURE_SCOPE` | `scope_configured` | At least one branch and product type exists. |
+| `scope_configured` | `CONFIGURE_SEQUENCES` | `sequences_configured` | Required sequence previews succeed. |
+| `sequences_configured` | `CONFIGURE_APPROVAL` | `approval_configured` | Quotation workflow, steps, and matrix resolve. |
+| `approval_configured` | `VALIDATE_CSV` | `csv_validated` | Preview has no blocking errors, or no CSV files were selected. |
+| `csv_validated` | `IMPORT_CSV` | `csv_imported` | Commit succeeds or CSV import skipped. |
+| `csv_imported` | `RUN_VERIFICATION` | `verified` | Required verification checks pass. |
+| `verified` | `COMPLETE_SETUP` | `completed` | No blocking failures remain. |
+| any non-completed state | `FAIL_STEP` | `failed` | Step returns blocking error. |
+| any non-completed state | `CANCEL_SETUP` | `cancelled` | User confirms cancellation. |
+| `failed` | `RESUME_SETUP` | prior recoverable state | Failure source still recoverable. |
+| completed step state | `RESET_STEP` | earliest affected state | Explicit confirmation and reset scope guard pass. |
+
+## Proposed Persistence
+
+### `setup_runs`
+
+Purpose: one row per setup attempt.
+
+Fields:
+
+- `id`
+- `status`
+- `mode`: `production | demo_uat | dry_run`
+- `target_organization_id`
+- `started_by`
+- `completed_by`
+- `started_at`
+- `completed_at`
+- `last_error`
+- `metadata`
+- timestamps
+
+### `setup_run_steps`
+
+Purpose: step-level status, resume, and report storage.
+
+Fields:
+
+- `id`
+- `setup_run_id`
+- `step_key`
+- `status`
+- `input_hash`
+- `output_json`
+- `errors_json`
+- `warnings_json`
+- `started_at`
+- `completed_at`
+- timestamps
+
+### `seed_manifests`
+
+Purpose: seed package lifecycle tracking.
+
+Fields:
+
+- `id`
+- `setup_run_id`
+- `organization_id`
+- `name`
+- `version`
+- `type`
+- `checksum`
+- `status`
+- `applied_by`
+- `applied_at`
+- `report_json`
+- timestamps
+
+### `seed_manifest_items`
+
+Purpose: item-level seed/import report and checksum tracking.
+
+Fields:
+
+- `id`
+- `seed_manifest_id`
+- `item_key`
+- `source_file`
+- `checksum`
+- `status`
+- `imported_count`
+- `updated_count`
+- `skipped_count`
+- `error_count`
+- `warning_count`
+- `report_json`
+- timestamps
+
+## Staleness Rules
+
+- Changing organization setup makes administrator, scope, sequence, approval, CSV, and verification stale.
+- Changing administrator makes verification stale.
+- Changing scope makes sequences, approval, CSV, and verification stale.
+- Changing sequences makes verification stale.
+- Changing approval makes CSV quotations and verification stale.
+- Changing CSV preview invalidates committed import unless the source file checksum is unchanged.
+- Any committed import makes verification stale.
+
+## Cancellation Rules
+
+- `cancelled` keeps report history.
+- Cancellation does not rollback already committed successful steps.
+- A cancelled setup can resume only through `RESUME_SETUP` with explicit acknowledgement of committed state.