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.

docs/setup/setup-performance-report.md

@@ -0,0 +1,27 @@
+# Setup Performance Report
+
+Date: 2026-07-03
+
+## Targets
+
+- Preview 1000 rows: under 5 seconds.
+- Commit 1000 rows: under 10 seconds.
+- Verification: under 3 seconds.
+- Setup Wizard load: under 2 seconds.
+
+## D.7.10 Status
+
+D.7.10 adds the golden dataset and runnable setup contract tests. A dedicated isolated performance database harness is not yet present in this repository, so this report records targets and the contract coverage that protects future performance testing.
+
+## Current Automated Coverage
+
+- Golden dataset row counts and CSV headers.
+- Template registry compatibility.
+- Import order compatibility.
+- Preview hash mutation semantics.
+- Seed manifest and resume API surface existence.
+- Reset/reseed safety API surface existence.
+
+## Follow-Up
+
+Add a CI-only isolated database harness that can safely run the full fresh database workflow and record elapsed times for preview, commit, verification, and wizard load.