# 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.