223 lines
6.7 KiB
Markdown
223 lines
6.7 KiB
Markdown
# Task D.7.2 - Setup Readiness and Verification APIs
|
|
|
|
## Objective
|
|
|
|
Implement the first non-destructive setup API slice for ALLA OS Initial Setup: readiness checks, verification checks, and report contracts. This slice must not run destructive reset logic or commit seed/import data.
|
|
|
|
## Files To Review
|
|
|
|
- `AGENTS.md`
|
|
- `plans/task-d.7.md`
|
|
- `plans/task-d.7.1.md`
|
|
- `docs/implementation/task-d7-initial-system-setup-audit.md`
|
|
- `docs/setup/seed-matrix.md`
|
|
- `docs/setup/setup-wizard-blueprint.md`
|
|
- `docs/setup/setup-state-machine.md`
|
|
- `docs/setup/verification-matrix.md`
|
|
- `docs/setup/reset-reseed-matrix.md`
|
|
- `src/db/schema.ts`
|
|
- `src/features/foundation/storage/**`
|
|
- `src/features/foundation/document-sequence/**`
|
|
- `src/features/foundation/document-template/**`
|
|
- `src/features/foundation/pdf-generator/**`
|
|
- `src/features/foundation/approval/**`
|
|
- `src/features/foundation/master-options/**`
|
|
- `src/features/crm/reports/**`
|
|
- `src/lib/auth/session.ts`
|
|
- `src/lib/auth/crm-access.ts`
|
|
|
|
## Implementation Scope
|
|
|
|
- Create setup feature API contracts:
|
|
- `src/features/setup/api/types.ts`
|
|
- `src/features/setup/api/service.ts`
|
|
- `src/features/setup/api/queries.ts`
|
|
- Create read-only setup server services:
|
|
- `src/features/setup/server/readiness.service.ts`
|
|
- `src/features/setup/server/verification.service.ts`
|
|
- Create thin route handlers:
|
|
- `src/app/api/setup/readiness/route.ts`
|
|
- `src/app/api/setup/verify/route.ts`
|
|
- Implement structured check result types:
|
|
- `PASS`
|
|
- `WARNING`
|
|
- `FAIL`
|
|
- Implement checks from `docs/setup/verification-matrix.md` that can safely run without mutating production data.
|
|
- For storage smoke test, either use an explicitly temporary setup key and cleanup immediately or mark as warning when provider does not support safe smoke test yet.
|
|
- Return actionable `suggestedFix` values without leaking secrets or raw SQL errors.
|
|
|
|
## Out Of Scope
|
|
|
|
- Final Setup Wizard UI.
|
|
- CSV template generator.
|
|
- CSV preview/import commit engine.
|
|
- Seed execution.
|
|
- Destructive reset/reseed APIs.
|
|
- Setup state persistence tables.
|
|
- Migrations for `setup_runs` or `seed_manifests`.
|
|
- Changing existing production CRM behavior.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `GET /api/setup/readiness` returns readiness report with environment, database, migration, storage, PDF, and optional email checks.
|
|
- `POST /api/setup/verify` returns verification report for a selected organization or current active organization.
|
|
- Route handlers are thin and call setup server services.
|
|
- All checks return consistent structured result objects.
|
|
- Checks use existing foundation services where available.
|
|
- No production data is created, updated, or deleted except safe temporary storage smoke-test object if explicitly implemented.
|
|
- Unauthorized users cannot access setup reports.
|
|
- Relevant lint/typecheck passes or failures are documented.
|
|
|
|
## Risk Notes
|
|
|
|
- Migration status detection may need a conservative fallback if Drizzle metadata table differs by environment.
|
|
- Storage smoke testing is partly non-transactional; if cleanup fails, the API must report a warning with the storage key.
|
|
- PDF/template checks should inspect existing template rows and mappings, not render or persist PDFs in this slice.
|
|
- Email checks should remain optional unless a first-class provider configuration is added.
|
|
|
|
---
|
|
|
|
# Future Slices
|
|
|
|
---
|
|
|
|
# Implementation Log
|
|
|
|
## 2026-07-02 - Readiness and verification APIs implemented
|
|
|
|
- Added setup API contracts under `src/features/setup/api/`.
|
|
- Added read-only setup services under `src/features/setup/server/`.
|
|
- Added protected route handlers:
|
|
- `GET /api/setup/readiness`
|
|
- `POST /api/setup/verify`
|
|
- Verification:
|
|
- `npm run typecheck` passed.
|
|
- `npx oxlint src/features/setup src/app/api/setup` passed.
|
|
- `npm run lint` still fails on pre-existing unrelated repo lint issues outside this task.
|
|
- Implementation note: `docs/implementation/task-d72-setup-readiness-verification-apis.md`
|
|
|
|
## Task D.7.3 - CSV Template Generator Static Template Pack
|
|
|
|
Objective: create checked-in `setup/templates/*.csv` files and optional route to download them.
|
|
|
|
Scope:
|
|
|
|
- Generate templates from `docs/setup/csv-template-spec.md`.
|
|
- Include headers and sample rows.
|
|
- Mark unsupported templates in docs only, not importable packs.
|
|
|
|
Out scope:
|
|
|
|
- CSV parser.
|
|
- CSV commit import.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Supported templates exist under `setup/templates/`.
|
|
- Each template has required headers and one safe sample row.
|
|
- Template docs match checked-in files.
|
|
|
|
## Task D.7.4 - CSV Preview Validation Engine
|
|
|
|
Objective: implement reusable CSV parser, validation, relationship resolution, duplicate detection, and preview report.
|
|
|
|
Scope:
|
|
|
|
- `src/features/setup/server/csv-import.service.ts`
|
|
- preview-only API route
|
|
- validation from `docs/setup/import-mapping.md`
|
|
|
|
Out scope:
|
|
|
|
- DB commit writes.
|
|
- rollback.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Preview classifies imported/updated/skipped/error candidates.
|
|
- Unsupported templates are blocked with clear reason.
|
|
|
|
## Task D.7.5 - CSV Commit Import Engine
|
|
|
|
Objective: commit validated CSV imports transactionally where safe.
|
|
|
|
Scope:
|
|
|
|
- commit API
|
|
- transaction support
|
|
- upsert support
|
|
- import report
|
|
|
|
Out scope:
|
|
|
|
- UI.
|
|
- arbitrary rollback beyond failed transaction.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Commit requires matching preview hash.
|
|
- DB-only imports rollback on error.
|
|
- Related feature/foundation services are reused where practical.
|
|
|
|
## Task D.7.6 - Dashboard Setup Wizard UI
|
|
|
|
Objective: build dashboard-native setup wizard using existing app shell.
|
|
|
|
Scope:
|
|
|
|
- `src/app/dashboard/administration/setup/page.tsx`
|
|
- setup wizard components under `src/features/setup/components/`
|
|
- readiness, verification, CSV preview integration
|
|
|
|
Out scope:
|
|
|
|
- destructive reset UI.
|
|
- migrations for setup state persistence unless D.7.8 completed first.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Uses `PageContainer`.
|
|
- Responsive, accessible, dark-mode compatible.
|
|
- Shows progress, preview tables, validation badges, and summary report.
|
|
|
|
## Task D.7.7 - Scoped Reset and Reseed Engine
|
|
|
|
Objective: implement non-production scoped reset/reseed service.
|
|
|
|
Scope:
|
|
|
|
- reset scopes from `docs/setup/reset-reseed-matrix.md`
|
|
- safety guards
|
|
- confirmation tokens
|
|
- reports
|
|
|
|
Out scope:
|
|
|
|
- production reset workflow.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Production destructive reset blocked.
|
|
- Scope reset is organization-aware.
|
|
- Storage cleanup is reported.
|
|
|
|
## Task D.7.8 - Seed Manifest and Setup State Persistence
|
|
|
|
Objective: add persistent setup run and seed manifest tracking.
|
|
|
|
Scope:
|
|
|
|
- schema/migrations for `setup_runs`, `setup_run_steps`, `seed_manifests`, `seed_manifest_items`
|
|
- state transitions from `docs/setup/setup-state-machine.md`
|
|
- manifest behavior from `docs/setup/seed-version-manifest.md`
|
|
|
|
Out scope:
|
|
|
|
- new business seed behavior.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Setup can resume.
|
|
- Seed packages are versioned and checksummed.
|
|
- Completion report is persisted.
|