allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
a16dc8e54837e9f290c1280e6d4f6a5c25fe5248
alla-allaos-fullstack/plans/task-d.7.8.md
phaichayon 9b05743b1e task-d.7.8
2026-07-03 10:19:03 +07:00

682 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 View Git Blame Copy Permalink