task-d.7.7
This commit is contained in:
phaichayon
611
plans/task-d.7.7.md
Normal file
611
plans/task-d.7.7.md
Normal file
@@ -0,0 +1,611 @@
|
||||
# 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
Block a user