task-d.7.10

2026-07-03 11:23:24 +07:00
parent ccfd7c6cd7
commit 503f34e22f
37 changed files with 1511 additions and 0 deletions
--- a/docs/implementation/task-d710-setup-integration-test-golden-dataset.md
+++ b/docs/implementation/task-d710-setup-integration-test-golden-dataset.md
@@ -0,0 +1,77 @@
+# Task D.7.10 Setup Integration Test & Golden Dataset
+
+Date: 2026-07-03
+Status: implemented
+
+## Scope Delivered
+
+Added official setup golden dataset:
+
+- `setup/golden-dataset/README.md`
+- `setup/golden-dataset/dataset.json`
+- 22 setup CSV files matching `setup/templates/templates.json`
+
+Dataset coverage:
+
+- Organizations: `ALLA`, `ONVALLA`
+- Users: IT/admin, marketing, sales, sales manager, CEO
+- Customers: 10
+- Contacts: 20
+- Leads: 20
+- Opportunities: 15
+- Quotations: 20
+- Multiple branches and product types
+- Quotation statuses: draft, pending approval, approved, rejected, revision
+
+Added setup integration documentation:
+
+- `docs/setup/integration-scenarios.md`
+- `docs/setup/setup-performance-report.md`
+
+Added automated setup contract tests:
+
+- `src/tests/setup/helpers.ts`
+- `src/tests/setup/golden-dataset.test.ts`
+- `src/tests/setup/setup-install.test.ts`
+- `src/tests/setup/setup-preview.test.ts`
+- `src/tests/setup/setup-commit.test.ts`
+- `src/tests/setup/setup-verification.test.ts`
+- `src/tests/setup/setup-resume.test.ts`
+- `src/tests/setup/setup-reset.test.ts`
+
+Added script:
+
+- `npm run test:setup`
+
+## Test Coverage
+
+The setup test suite validates:
+
+- Golden dataset files exist.
+- Golden dataset headers match official setup templates.
+- Required row counts are present.
+- Quotation statuses cover approval and revision scenarios.
+- Golden dataset includes every supported setup template.
+- Dataset import order follows template registry ordering.
+- Preview hash semantics change when CSV content changes.
+- Commit API and seed manifest integration exist.
+- Commit engine preserves preview hash validation contract.
+- Setup readiness and verification APIs exist.
+- Setup run resume APIs exist.
+- Setup wizard persists core step outputs.
+- Reset and reseed APIs exist.
+- Reset guard source blocks production and requires preview token semantics.
+- Unsafe reset scopes are intentionally blocked.
+- Integration scenarios document operational readiness checks.
+
+## Validation
+
+- `npm run test:setup` passed: 17 tests.
+- `npm run typecheck -- --pretty false` passed.
+- `npx oxlint src/tests/setup` passed.
+
+## Residual Notes
+
+- This task adds runnable setup contract tests using Node's built-in test runner to avoid introducing a new test framework.
+- Full empty-database E2E execution is documented in `docs/setup/integration-scenarios.md` but not automated because this repository does not yet have an isolated CI test database harness.
+- Performance targets are documented in `docs/setup/setup-performance-report.md`; measured preview/commit/verification timings require the future isolated database harness.
--- a/docs/setup/integration-scenarios.md
+++ b/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.
--- a/docs/setup/setup-performance-report.md
+++ b/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.