allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
setup-wizrad
alla-allaos-fullstack/plans/task-d.7.7.md
phaichayon ccfd7c6cd7 task-d.7.7
2026-07-03 11:05:13 +07:00

612 lines
11 KiB
Markdown
Raw Permalink 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.7 – Scoped Reset and Reseed Engine
## Objective
Implement a safe, non-production Scoped Reset and Reseed Engine for ALLA OS Initial Setup.
This task must allow controlled reset/reseed operations for setup, foundation, organization, business, demo/UAT, and CSV-imported data while preserving production safety guards.
D.7.7 must use the Setup State and Seed Manifest foundations from D.7.8 where possible.
This task must not introduce any destructive reset path for production.
---
## 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
- plans/task-d.7.8.md
- docs/setup/reset-reseed-matrix.md
- docs/setup/seed-version-manifest.md
- docs/setup/setup-state-machine.md
- docs/setup/seed-matrix.md
- docs/setup/import-mapping.md
- src/db/schema.ts
- src/features/setup/**
- src/app/api/setup/**
- scripts/seed-reset.ts
- scripts/db/reset-database.ts
- scripts/seed-system.ts
- scripts/seed-uat.ts
- src/db/seeds/**/*
- existing storage provider implementation
---
## Implementation Scope
Create reset/reseed services:
src/features/setup/server/reset.service.ts
src/features/setup/server/reseed.service.ts
Optional helpers:
src/features/setup/server/reset-guards.ts
src/features/setup/server/reset-report.ts
src/features/setup/server/reset-scopes.ts
Create API routes:
POST /api/setup/reset/preview
POST /api/setup/reset/execute
POST /api/setup/reseed/preview
POST /api/setup/reseed/execute
Optional UI integration:
Add a Maintenance panel in Setup Wizard or Administration Setup page.
---
## Reset Scopes
Implement scopes from docs/setup/reset-reseed-matrix.md:
foundation_reset
organization_reset
business_reset
demo_uat_reset
csv_import_rollback
setup_run_reset
full_reset
---
## Scope Rules
### foundation_reset
Deletes and optionally reseeds organization-scoped foundation rows.
May affect:
- ms_options
- document_sequences
- approval workflows
- approval steps
- approval matrices
- document template foundation rows
- document library foundation rows
- notification templates
- report definitions
Must retain:
- users
- organizations
- memberships
- business CRM data unless explicitly selected
---
### organization_reset
Deletes target organization and tenant-scoped rows.
Must require exact organization code/name confirmation.
Must retain:
- global users unless explicitly selected
Must delete:
- memberships for target organization
- CRM role assignments/profiles for target organization
- organization-scoped foundation rows
- business rows for target organization
---
### business_reset
Deletes CRM business records for target organization.
May affect:
- customers
- contacts
- contact shares
- leads
- opportunities
- quotations
- quotation items
- quotation parties
- quotation topics
- quotation topic items
- followups
- business attachment metadata
Must retain:
- organization
- users
- memberships
- foundation rows
- setup run history unless explicitly selected
---
### demo_uat_reset
Deletes deterministic Demo/UAT rows only.
Must rely on:
- UAT seed markers
- deterministic emails/codes
- seed manifest records
- known UAT seed package names
Must retain:
- production foundation
- non-UAT business data
---
### csv_import_rollback
Rolls back rows associated with a seed manifest/import package when safely reversible.
Rules:
- only rollback manifest-owned rows
- block rollback if rows were changed after import and no safe conflict policy exists
- if rollback is not fully safe, return warning and require manual review
- do not pretend arbitrary rollback is safe
---
### setup_run_reset
Deletes setup run metadata only.
May affect:
- setup_runs
- setup_run_steps
- seed_manifests
- seed_manifest_items
Must not delete:
- business data
- foundation data
- organizations
- users
---
### full_reset
Must use existing guarded reset script behavior.
Rules:
- block in production
- require explicit allow flag
- require typed confirmation
- local/test only by default
- do not expose casually in UI
---
## Safety Guards
All destructive actions require:
- super_admin
- non-production environment
- explicit scope
- target organization when scope is organization-aware
- typed confirmation
- preview before execute
- confirmation token generated from preview
- token expires after short duration
- execute must match preview hash/token
Block when:
- NODE_ENV=production
- production-like database host/name is detected
- missing target organization
- missing typed confirmation
- preview was not run
- preview token expired
- preview hash mismatch
- affected row count exceeds safe threshold unless force flag is provided
---
## Preview Behavior
Reset preview must not delete anything.
Preview returns:
- scope
- target organization
- affected tables
- estimated row counts
- retained data
- deleted data
- storage cleanup plan
- manifest impact
- warnings
- blocking errors
- confirmation phrase
- previewHash
- confirmationToken
Example:
{
"scope": "business_reset",
"targetOrganization": "ALLA",
"summary": {
"tables": 12,
"rows": 520,
"warnings": 2,
"errors": 0
},
"affectedTables": [],
"confirmationPhrase": "RESET BUSINESS ALLA",
"previewHash": "...",
"confirmationToken": "..."
}
---
## Execute Behavior
Execute requires:
- scope
- previewHash
- confirmationToken
- typed confirmation phrase
Execution must:
1. Rebuild preview.
2. Compare previewHash.
3. Validate token.
4. Validate typed confirmation.
5. Run reset inside transaction where DB-only.
6. Handle storage cleanup best-effort.
7. Persist reset report to setup run if available.
8. Return final report.
---
## Reseed Behavior
Reseed is optional but recommended for:
- foundation_reset
- demo_uat_reset
- csv_import_rollback after cleanup
Reseed must call existing seed services/scripts through safe wrappers.
Do not duplicate seed data.
Supported reseed targets:
foundation
demo_uat
csv_manifest
Rules:
- foundation reseed is idempotent
- demo/UAT reseed is deterministic
- csv_manifest reseed requires original manifest/files available or block with clear reason
---
## Storage Cleanup
Storage cleanup must be:
- best-effort
- scoped
- reported
- never silent
Rules:
- delete setup-owned temp objects only when safe
- delete demo-generated objects only under demo prefix
- do not delete approved immutable artifacts unless explicit full reset/demo reset and policy allows
- if cleanup fails, DB transaction should not necessarily rollback unless storage cleanup is required by scope
- report leftover keys
---
## Seed Manifest Integration
Use D.7.8 seed manifest tables.
Reset preview should show:
- affected seed manifests
- affected seed manifest items
- whether import rollback is safe
- checksum/package info
Reset execute should update manifest status when applicable:
- rolled_back
- warning
- failed
Do not delete manifest rows unless scope is setup_run_reset.
---
## Setup State Integration
Reset should update setup run state when applicable.
Examples:
- business_reset marks csv_commit and verification stale
- foundation_reset marks readiness, scope, sequence, approval, CSV, and verification stale
- setup_run_reset clears setup state only
- organization_reset cancels or invalidates active setup runs for that organization
Do not implement destructive RESET_STEP from UI unless explicitly scoped.
---
## API Contracts
### POST /api/setup/reset/preview
Input:
scope
organizationId?
organizationCode?
manifestId?
options?
Output:
ResetPreviewReport
---
### POST /api/setup/reset/execute
Input:
scope
previewHash
confirmationToken
confirmationPhrase
organizationId?
organizationCode?
manifestId?
options?
Output:
ResetExecuteReport
---
### POST /api/setup/reseed/preview
Input:
target
organizationId?
organizationCode?
manifestId?
options?
Output:
ReseedPreviewReport
---
### POST /api/setup/reseed/execute
Input:
target
previewHash
confirmationToken
confirmationPhrase
organizationId?
organizationCode?
manifestId?
options?
Output:
ReseedExecuteReport
---
## UI Requirements If Implemented
Add Maintenance panel:
- Reset scope selector
- Target organization selector
- Preview button
- Affected tables/counts
- Warnings/errors
- Typed confirmation input
- Execute button
- Final report
UI must hide or disable destructive actions when environment is production.
---
## Out Of Scope
- Production reset workflow
- Silent automatic reset
- Arbitrary rollback without manifest ownership
- Deleting approved production artifacts
- New seed data creation
- Installation profile engine
- Plugin runtime
- Backup/restore
- Data anonymization
- Cross-environment migration
- Email/storage secret reset
- Changing CRM business behavior
---
## Deliverables
Required:
src/features/setup/server/reset.service.ts
src/features/setup/server/reseed.service.ts
src/features/setup/server/reset-guards.ts
src/features/setup/server/reset-report.ts
API routes:
src/app/api/setup/reset/preview/route.ts
src/app/api/setup/reset/execute/route.ts
src/app/api/setup/reseed/preview/route.ts
src/app/api/setup/reseed/execute/route.ts
Optional:
src/features/setup/components/setup-maintenance-panel.tsx
---
## Acceptance Criteria
✓ Reset preview API exists.
✓ Reset execute API exists.
✓ Reseed preview API exists.
✓ Reseed execute API exists.
✓ All APIs require super_admin.
✓ Production destructive reset is blocked.
✓ Preview is required before execute.
✓ Execute requires valid previewHash.
✓ Execute requires valid confirmationToken.
✓ Execute requires typed confirmation phrase.
✓ Organization-aware scopes require target organization.
✓ Preview returns affected tables and estimated rows.
✓ Execute uses transaction for DB-only deletes.
✓ Storage cleanup is best-effort and reported.
✓ Seed manifest status updates for rollback/reset where applicable.
✓ Setup run steps are marked stale after reset.
✓ full_reset delegates to existing guarded reset behavior or blocks with clear instructions.
✓ No reset deletes approved immutable artifacts unless explicitly allowed by scope policy.
✓ No seed logic is duplicated.
✓ Typecheck passes or unrelated failures are documented.
---
## Suggested Verification
Run:
npm run typecheck
Run scoped lint:
npx oxlint src/features/setup src/app/api/setup
Manual test:
1. Run business_reset preview for ALLA.
2. Confirm affected table counts are shown.
3. Execute without preview token.
4. Confirm blocked.
5. Execute with wrong confirmation phrase.
6. Confirm blocked.
7. Execute with valid token and phrase in local environment.
8. Confirm rows deleted and foundation retained.
9. Run setup verification.
10. Confirm CSV/verification steps stale.
11. Try in NODE_ENV=production.
12. Confirm destructive reset is blocked.
13. Run setup_run_reset.
14. Confirm setup metadata deleted but business rows remain.
15. Run csv_import_rollback for manifest.
16. Confirm only manifest-owned rows are affected or rollback is blocked with manual review warning.
---
## Follow-up
After D.7.7:
D.7.9 – Installation Profile and Plugin Runtime Enhancement
D.7.10 – Setup Integration Test and Golden Dataset
Reference in New Issue View Git Blame Copy Permalink