task-d.7.10

docs/setup/integration-scenarios.md

@@ -0,0 +1,81 @@
+# Setup Integration Scenarios
+
+This document defines the D.7.10 setup integration workflow and the golden dataset validation contract.
+
+## Golden Dataset
+
+Source: `setup/golden-dataset/`
+
+The dataset must remain compatible with `setup/templates/templates.json` and must not introduce business behavior beyond existing setup/import contracts.
+
+## Scenario 1: Fresh Install Smoke
+
+1. Start from an empty local or CI database.
+2. Run migrations.
+3. Run setup readiness.
+4. Start a setup run.
+5. Preview every CSV in `setup/golden-dataset/`.
+6. Commit with the returned `previewHash`.
+7. Run verification.
+8. Complete setup.
+9. Confirm seed manifests and setup run report exist.
+
+Expected result: setup completes without manual SQL.
+
+## Scenario 2: Idempotent Import
+
+1. Preview and commit the full golden dataset.
+2. Preview and commit the same files again.
+3. Preview and commit the same files a third time.
+
+Expected result: repeated imports produce update/skip behavior and do not create duplicate business-key records.
+
+## Scenario 3: Preview Hash Rejection
+
+1. Preview the golden dataset.
+2. Modify one CSV row.
+3. Attempt commit using the old `previewHash`.
+
+Expected result: commit is rejected and requires re-preview.
+
+## Scenario 4: Resume
+
+1. Start setup run.
+2. Save readiness and CSV preview steps.
+3. Refresh browser or call `GET /api/setup/run/current`.
+
+Expected result: persisted setup run and step statuses are returned without raw CSV contents.
+
+## Scenario 5: Reset Safety
+
+1. Preview `business_reset` with a target organization.
+2. Execute only after matching preview hash, token, and typed phrase.
+3. Preview `setup_run_reset`.
+4. Confirm blocked reports for `foundation_reset`, `organization_reset`, `demo_uat_reset`, `full_reset`, and `csv_import_rollback`.
+
+Expected result: only explicitly supported safe reset paths execute; unsupported reset paths return blocking reports.
+
+## Scenario 6: Operational Readiness
+
+After setup completes, verify these domains are ready:
+
+- login
+- CRM dashboard
+- customer list and detail
+- lead list and detail
+- opportunity list and detail
+- quotation list and detail
+- quotation approval routing
+- document sequence previews
+- PDF/document template readiness
+- setup report and seed manifest report
+
+## Automated Contract Tests
+
+Run:
+
+```bash
+npm run test:setup
+```
+
+These tests validate golden dataset headers, counts, import ordering, reset/reseed API surfaces, setup state surfaces, and non-destructive reset policy contracts.