156 lines
4.0 KiB
Markdown
156 lines
4.0 KiB
Markdown
# 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.
|