alla-allaos-fullstack/docs/setup/integration-scenarios.md

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:

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.