task-d.7.8
This commit is contained in:
phaichayon
681
plans/task-d.7.8.md
Normal file
681
plans/task-d.7.8.md
Normal file
@@ -0,0 +1,681 @@
|
||||
# Task D.7.8 – Seed Manifest and Setup State Persistence
|
||||
|
||||
## Objective
|
||||
|
||||
Add persistent setup run tracking and seed manifest lifecycle tracking for ALLA OS Initial Setup.
|
||||
|
||||
This task must make the Setup Wizard resumable, auditable, and able to persist setup reports across browser refreshes and future setup sessions.
|
||||
|
||||
D.7.8 should build on:
|
||||
|
||||
- D.7.2 Readiness and Verification APIs
|
||||
- D.7.3 CSV Template Pack
|
||||
- D.7.4 CSV Preview Validation Engine
|
||||
- D.7.5 CSV Commit Import Engine
|
||||
- D.7.6 Dashboard Setup Wizard UI
|
||||
|
||||
This task must not implement destructive reset/reseed behavior. Reset remains D.7.7.
|
||||
|
||||
---
|
||||
|
||||
## Review Before Implementation
|
||||
|
||||
Review:
|
||||
|
||||
- AGENTS.md
|
||||
- plans/task-d.7.md
|
||||
- plans/task-d.7.1.md
|
||||
- plans/task-d.7.2.md
|
||||
- plans/task-d.7.3.md
|
||||
- plans/task-d.7.4.md
|
||||
- plans/task-d.7.5.md
|
||||
- plans/task-d.7.6.md
|
||||
- docs/setup/setup-state-machine.md
|
||||
- docs/setup/seed-version-manifest.md
|
||||
- docs/setup/setup-wizard-blueprint.md
|
||||
- docs/setup/verification-matrix.md
|
||||
- docs/setup/reset-reseed-matrix.md
|
||||
- docs/setup/setup-plugin-architecture.md
|
||||
- src/db/schema.ts
|
||||
- src/features/setup/**
|
||||
- src/app/dashboard/administration/setup/page.tsx
|
||||
- src/app/api/setup/**
|
||||
- existing migration conventions under drizzle/
|
||||
|
||||
---
|
||||
|
||||
## Implementation Scope
|
||||
|
||||
Add setup persistence tables:
|
||||
|
||||
- setup_runs
|
||||
- setup_run_steps
|
||||
- seed_manifests
|
||||
- seed_manifest_items
|
||||
|
||||
Add migration through existing Drizzle workflow.
|
||||
|
||||
Add schema definitions to:
|
||||
|
||||
src/db/schema.ts
|
||||
|
||||
or appropriate split schema location if the repo already uses modular schema files.
|
||||
|
||||
Add setup persistence services:
|
||||
|
||||
src/features/setup/server/setup-state.service.ts
|
||||
src/features/setup/server/seed-manifest.service.ts
|
||||
|
||||
Add API routes:
|
||||
|
||||
GET /api/setup/run/current
|
||||
POST /api/setup/run/start
|
||||
POST /api/setup/run/step
|
||||
POST /api/setup/run/complete
|
||||
GET /api/setup/run/report
|
||||
|
||||
Update setup wizard UI to:
|
||||
|
||||
- load current setup run
|
||||
- resume prior step status
|
||||
- persist step outputs
|
||||
- show completed/pending/stale step status
|
||||
- persist finish report
|
||||
- show setup completed state
|
||||
|
||||
Update CSV commit flow to optionally record seed manifest and manifest items.
|
||||
|
||||
---
|
||||
|
||||
## Database Tables
|
||||
|
||||
### setup_runs
|
||||
|
||||
Purpose:
|
||||
|
||||
One row per setup attempt/session.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
id
|
||||
|
||||
status
|
||||
|
||||
mode
|
||||
|
||||
target_organization_id
|
||||
|
||||
started_by
|
||||
|
||||
completed_by
|
||||
|
||||
started_at
|
||||
|
||||
completed_at
|
||||
|
||||
last_error
|
||||
|
||||
metadata
|
||||
|
||||
created_at
|
||||
|
||||
updated_at
|
||||
|
||||
Status values:
|
||||
|
||||
not_started
|
||||
|
||||
readiness_checked
|
||||
|
||||
foundation_installed
|
||||
|
||||
organization_created
|
||||
|
||||
administrator_created
|
||||
|
||||
scope_configured
|
||||
|
||||
sequences_configured
|
||||
|
||||
approval_configured
|
||||
|
||||
csv_validated
|
||||
|
||||
csv_imported
|
||||
|
||||
verified
|
||||
|
||||
completed
|
||||
|
||||
failed
|
||||
|
||||
cancelled
|
||||
|
||||
Mode values:
|
||||
|
||||
production
|
||||
|
||||
demo_uat
|
||||
|
||||
dry_run
|
||||
|
||||
---
|
||||
|
||||
### setup_run_steps
|
||||
|
||||
Purpose:
|
||||
|
||||
Step-level state, input hash, output report, warning/error history.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
id
|
||||
|
||||
setup_run_id
|
||||
|
||||
step_key
|
||||
|
||||
status
|
||||
|
||||
input_hash
|
||||
|
||||
output_json
|
||||
|
||||
errors_json
|
||||
|
||||
warnings_json
|
||||
|
||||
started_at
|
||||
|
||||
completed_at
|
||||
|
||||
created_at
|
||||
|
||||
updated_at
|
||||
|
||||
Step status values:
|
||||
|
||||
not_started
|
||||
|
||||
running
|
||||
|
||||
passed
|
||||
|
||||
warning
|
||||
|
||||
failed
|
||||
|
||||
skipped
|
||||
|
||||
stale
|
||||
|
||||
---
|
||||
|
||||
### seed_manifests
|
||||
|
||||
Purpose:
|
||||
|
||||
Track seed/import package lifecycle.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
id
|
||||
|
||||
setup_run_id
|
||||
|
||||
organization_id
|
||||
|
||||
name
|
||||
|
||||
version
|
||||
|
||||
type
|
||||
|
||||
checksum
|
||||
|
||||
status
|
||||
|
||||
source
|
||||
|
||||
applied_by
|
||||
|
||||
applied_at
|
||||
|
||||
report_json
|
||||
|
||||
created_at
|
||||
|
||||
updated_at
|
||||
|
||||
Type values:
|
||||
|
||||
foundation
|
||||
|
||||
organization
|
||||
|
||||
business
|
||||
|
||||
demo_uat
|
||||
|
||||
setup_state
|
||||
|
||||
Status values:
|
||||
|
||||
pending
|
||||
|
||||
applied
|
||||
|
||||
skipped
|
||||
|
||||
warning
|
||||
|
||||
failed
|
||||
|
||||
rolled_back
|
||||
|
||||
---
|
||||
|
||||
### seed_manifest_items
|
||||
|
||||
Purpose:
|
||||
|
||||
Track per-file/per-seed item checksum and result.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
id
|
||||
|
||||
seed_manifest_id
|
||||
|
||||
item_key
|
||||
|
||||
source_file
|
||||
|
||||
checksum
|
||||
|
||||
status
|
||||
|
||||
imported_count
|
||||
|
||||
updated_count
|
||||
|
||||
skipped_count
|
||||
|
||||
error_count
|
||||
|
||||
warning_count
|
||||
|
||||
report_json
|
||||
|
||||
created_at
|
||||
|
||||
updated_at
|
||||
|
||||
---
|
||||
|
||||
## State Machine Rules
|
||||
|
||||
Use:
|
||||
|
||||
docs/setup/setup-state-machine.md
|
||||
|
||||
Required events:
|
||||
|
||||
CHECK_READINESS
|
||||
|
||||
INSTALL_FOUNDATION
|
||||
|
||||
CREATE_ORGANIZATION
|
||||
|
||||
CREATE_ADMIN
|
||||
|
||||
CONFIGURE_SCOPE
|
||||
|
||||
CONFIGURE_SEQUENCES
|
||||
|
||||
CONFIGURE_APPROVAL
|
||||
|
||||
VALIDATE_CSV
|
||||
|
||||
IMPORT_CSV
|
||||
|
||||
RUN_VERIFICATION
|
||||
|
||||
COMPLETE_SETUP
|
||||
|
||||
FAIL_STEP
|
||||
|
||||
CANCEL_SETUP
|
||||
|
||||
RESUME_SETUP
|
||||
|
||||
RESET_STEP
|
||||
|
||||
For D.7.8, implement only non-destructive events.
|
||||
|
||||
Do not implement RESET_STEP destructive behavior.
|
||||
|
||||
RESET_STEP can return:
|
||||
|
||||
not implemented until D.7.7
|
||||
|
||||
---
|
||||
|
||||
## Persistence Rules
|
||||
|
||||
Every setup step should persist:
|
||||
|
||||
- step key
|
||||
- status
|
||||
- input hash
|
||||
- output summary/report
|
||||
- warnings
|
||||
- errors
|
||||
- completed timestamp
|
||||
|
||||
If the same step is re-run:
|
||||
|
||||
- update same step row
|
||||
- keep latest report
|
||||
- mark dependent later steps as stale when needed
|
||||
|
||||
Staleness rules:
|
||||
|
||||
- readiness changed → all later steps stale
|
||||
- organization changed → admin, scope, sequence, approval, CSV, verification stale
|
||||
- scope changed → sequence, approval, CSV, verification stale
|
||||
- sequence changed → verification stale
|
||||
- approval changed → CSV and verification stale
|
||||
- CSV preview changed → commit stale
|
||||
- CSV commit changed → verification stale
|
||||
|
||||
---
|
||||
|
||||
## Setup Run Behavior
|
||||
|
||||
### Current Run
|
||||
|
||||
GET /api/setup/run/current
|
||||
|
||||
Returns:
|
||||
|
||||
- active setup run if exists
|
||||
- latest completed setup run if no active run
|
||||
- setup step summaries
|
||||
- manifest summaries
|
||||
- completion status
|
||||
|
||||
### Start Run
|
||||
|
||||
POST /api/setup/run/start
|
||||
|
||||
Creates new setup run.
|
||||
|
||||
Rules:
|
||||
|
||||
- super_admin only
|
||||
- if active run exists, return existing run unless `forceNew=true`
|
||||
- mode defaults to production
|
||||
- target organization optional until resolved
|
||||
|
||||
### Save Step
|
||||
|
||||
POST /api/setup/run/step
|
||||
|
||||
Persists step report.
|
||||
|
||||
Input:
|
||||
|
||||
- setupRunId
|
||||
- stepKey
|
||||
- status
|
||||
- inputHash
|
||||
- output
|
||||
- warnings
|
||||
- errors
|
||||
|
||||
Rules:
|
||||
|
||||
- validate step key
|
||||
- update run status based on state machine
|
||||
- mark downstream stale steps as needed
|
||||
|
||||
### Complete Run
|
||||
|
||||
POST /api/setup/run/complete
|
||||
|
||||
Rules:
|
||||
|
||||
- all required steps must be passed/warning acknowledged
|
||||
- blocking failure prevents completion
|
||||
- verification must be latest and not stale
|
||||
- writes completed_at and status completed
|
||||
- returns final report
|
||||
|
||||
### Report
|
||||
|
||||
GET /api/setup/run/report
|
||||
|
||||
Returns:
|
||||
|
||||
- setup run summary
|
||||
- steps
|
||||
- manifests
|
||||
- final readiness/verification/import summaries
|
||||
|
||||
---
|
||||
|
||||
## Seed Manifest Behavior
|
||||
|
||||
When CSV commit succeeds, create or update a manifest.
|
||||
|
||||
Recommended package:
|
||||
|
||||
crm-business-import
|
||||
|
||||
Manifest item per committed CSV file.
|
||||
|
||||
For each file:
|
||||
|
||||
- source_file
|
||||
- checksum
|
||||
- status
|
||||
- imported_count
|
||||
- updated_count
|
||||
- skipped_count
|
||||
- error_count
|
||||
- warning_count
|
||||
- report_json
|
||||
|
||||
Version:
|
||||
|
||||
1.0.0
|
||||
|
||||
Source:
|
||||
|
||||
csv
|
||||
|
||||
Type:
|
||||
|
||||
business
|
||||
|
||||
Checksum behavior:
|
||||
|
||||
- same version + same checksum = skipped/already applied
|
||||
- same version + changed checksum = warning unless force mode
|
||||
- new checksum after successful import creates new manifest revision or new manifest row depending on chosen implementation
|
||||
|
||||
If D.7.5 import is dryRun:
|
||||
|
||||
- do not write seed manifest
|
||||
- optionally persist setup step output only
|
||||
|
||||
---
|
||||
|
||||
## API Security
|
||||
|
||||
- all routes protected
|
||||
- require super_admin for D.7.8
|
||||
- never expose raw SQL errors
|
||||
- never expose passwords, password hashes, secrets, storage credentials
|
||||
- report only safe summaries
|
||||
- setup reports can include filenames and counts, not raw CSV contents
|
||||
|
||||
---
|
||||
|
||||
## UI Updates
|
||||
|
||||
Update:
|
||||
|
||||
src/features/setup/components/setup-wizard.tsx
|
||||
|
||||
Add:
|
||||
|
||||
- load current setup run on mount
|
||||
- resume banner
|
||||
- persisted step status
|
||||
- stale step badge
|
||||
- completed setup summary
|
||||
- save step result after readiness, preview, commit, verification
|
||||
- complete setup button on finish step
|
||||
- report panel from persisted data
|
||||
|
||||
Important:
|
||||
|
||||
The wizard should still work if persistence API fails, but must show a warning.
|
||||
|
||||
---
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Destructive reset/reseed
|
||||
- RESET_STEP implementation
|
||||
- installation profile engine
|
||||
- plugin runtime
|
||||
- CSV parser changes unless needed for checksum
|
||||
- setup template changes
|
||||
- storage import
|
||||
- attachment import
|
||||
- new CRM behavior
|
||||
- production setup lock enforcement beyond completed status display
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
Required schema/migration:
|
||||
|
||||
src/db/schema.ts
|
||||
|
||||
drizzle migration file
|
||||
|
||||
Required services:
|
||||
|
||||
src/features/setup/server/setup-state.service.ts
|
||||
src/features/setup/server/seed-manifest.service.ts
|
||||
|
||||
Required API routes:
|
||||
|
||||
src/app/api/setup/run/current/route.ts
|
||||
src/app/api/setup/run/start/route.ts
|
||||
src/app/api/setup/run/step/route.ts
|
||||
src/app/api/setup/run/complete/route.ts
|
||||
src/app/api/setup/run/report/route.ts
|
||||
|
||||
Required UI update:
|
||||
|
||||
src/features/setup/components/setup-wizard.tsx
|
||||
|
||||
Optional helpers:
|
||||
|
||||
src/features/setup/server/setup-state-machine.ts
|
||||
src/features/setup/server/setup-report.service.ts
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
✓ setup_runs table exists.
|
||||
|
||||
✓ setup_run_steps table exists.
|
||||
|
||||
✓ seed_manifests table exists.
|
||||
|
||||
✓ seed_manifest_items table exists.
|
||||
|
||||
✓ Drizzle migration generated.
|
||||
|
||||
✓ Current setup run API works.
|
||||
|
||||
✓ Start setup run API works.
|
||||
|
||||
✓ Save setup step API works.
|
||||
|
||||
✓ Complete setup run API works.
|
||||
|
||||
✓ Setup report API works.
|
||||
|
||||
✓ Wizard can resume current run after refresh.
|
||||
|
||||
✓ Wizard shows persisted step statuses.
|
||||
|
||||
✓ Wizard marks stale dependent steps after rerun.
|
||||
|
||||
✓ CSV commit creates seed manifest records when commit succeeds.
|
||||
|
||||
✓ dryRun commit does not create seed manifest records.
|
||||
|
||||
✓ Completed setup run stores final report.
|
||||
|
||||
✓ All APIs require super_admin.
|
||||
|
||||
✓ No destructive reset logic is implemented.
|
||||
|
||||
✓ No secrets or raw CSV contents are persisted.
|
||||
|
||||
✓ Typecheck passes or unrelated failures are documented.
|
||||
|
||||
---
|
||||
|
||||
## Suggested Verification
|
||||
|
||||
Run:
|
||||
|
||||
npm run db:generate
|
||||
|
||||
npm run db:migrate
|
||||
|
||||
npm run typecheck
|
||||
|
||||
Run scoped lint:
|
||||
|
||||
npx oxlint src/features/setup src/app/api/setup src/app/dashboard/administration/setup src/db/schema.ts
|
||||
|
||||
Manual test:
|
||||
|
||||
1. Open Setup Wizard.
|
||||
2. Start setup run.
|
||||
3. Run readiness.
|
||||
4. Refresh browser.
|
||||
5. Confirm readiness result persists.
|
||||
6. Upload CSV and preview.
|
||||
7. Refresh browser.
|
||||
8. Confirm preview step status persists without raw CSV content.
|
||||
9. Commit CSV.
|
||||
10. Confirm seed manifest and manifest item rows exist.
|
||||
11. Run verification.
|
||||
12. Complete setup.
|
||||
13. Refresh browser.
|
||||
14. Confirm completed setup summary appears.
|
||||
15. Try as non-super_admin.
|
||||
16. Confirm access denied.
|
||||
|
||||
---
|
||||
|
||||
## Follow-up
|
||||
|
||||
After D.7.8:
|
||||
|
||||
D.7.7 – Scoped Reset and Reseed Engine
|
||||
|
||||
D.7.9 – Installation Profile and Plugin Runtime Enhancement
|
||||
Reference in New Issue
Block a user