task-d.7.2
This commit is contained in:
phaichayon
775
plans/task-d.7.1.md
Normal file
775
plans/task-d.7.1.md
Normal file
@@ -0,0 +1,775 @@
|
||||
# Task D.7.1 – Setup Blueprint & Seed Specification
|
||||
|
||||
## Objective
|
||||
|
||||
Create a complete implementation blueprint for the ALLA OS Initial Setup, Seed Framework, CSV Import, Reset/Reseed, and Verification workflow before starting code implementation.
|
||||
|
||||
This task must convert the Phase 1/2 audit from Task D.7 into a precise technical specification that can be implemented safely without guessing, duplicating seed logic, or breaking existing CRM, RBAC, approval, document sequence, storage, or PDF behavior.
|
||||
|
||||
No production code implementation should begin in this task except documentation/specification files and optional CSV template drafts.
|
||||
|
||||
---
|
||||
|
||||
# Scope
|
||||
|
||||
## In Scope
|
||||
|
||||
- Complete Seed Matrix
|
||||
- CSV Template Specification
|
||||
- CSV Import Mapping
|
||||
- Setup Wizard Flow Specification
|
||||
- Setup State Machine
|
||||
- Verification Matrix
|
||||
- Reset/Reseed Matrix
|
||||
- Seed Version Strategy
|
||||
- Seed Manifest Strategy
|
||||
- Setup Plugin Architecture
|
||||
- Implementation Slice Plan for D.7.2+
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Building the final Setup Wizard UI
|
||||
- Building the CSV import engine
|
||||
- Running destructive reset logic
|
||||
- Changing existing seed behavior
|
||||
- Changing production CRM business logic
|
||||
- Adding unsupported first-class domains without schema decision
|
||||
|
||||
---
|
||||
|
||||
# Phase 1 — Review Existing Audit
|
||||
|
||||
Start from the existing Task D.7 Phase 1/2 audit report.
|
||||
|
||||
Review:
|
||||
|
||||
- `plans/task-d.7.md`
|
||||
- Task D.7 audit output
|
||||
- `AGENTS.md`
|
||||
- `docs/standards/*`
|
||||
- `docs/adr/*`
|
||||
- `src/db/schema.ts`
|
||||
- `src/db/seeds/**/*`
|
||||
- `scripts/seed-system.ts`
|
||||
- `scripts/seed-uat.ts`
|
||||
- `scripts/seed-reset.ts`
|
||||
- `scripts/db/reset-database.ts`
|
||||
- `src/features/foundation/**/*`
|
||||
- `src/features/crm/**/*`
|
||||
- `src/features/setup/**/*`
|
||||
|
||||
Do not repeat the same audit. Extend it into a blueprint.
|
||||
|
||||
---
|
||||
|
||||
# Phase 2 — Complete Seed Matrix
|
||||
|
||||
Create a complete seed matrix covering all known setup-related tables and concepts.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/seed-matrix.md
|
||||
```
|
||||
|
||||
Required columns:
|
||||
|
||||
```text
|
||||
Module
|
||||
Entity
|
||||
Table / Storage
|
||||
Seed Type
|
||||
Required For First Login
|
||||
Required For CRM
|
||||
Required For Quotation
|
||||
CSV Importable
|
||||
Wizard Editable
|
||||
Auto Generated
|
||||
Source of Truth
|
||||
Dependencies
|
||||
Import Order
|
||||
Reset Scope
|
||||
Notes
|
||||
```
|
||||
|
||||
Seed Type values:
|
||||
|
||||
```text
|
||||
foundation
|
||||
organization
|
||||
business
|
||||
demo_uat
|
||||
runtime_generated
|
||||
runtime_only
|
||||
unsupported_pending_schema
|
||||
```
|
||||
|
||||
Example row:
|
||||
|
||||
```text
|
||||
Foundation | Branch | ms_options(category=crm_branch) | organization | yes | yes | yes | yes | yes | no | CSV/Wizard | organization, created_by_user | 08 | organization_reset | Branch is currently modeled as master option, not a branch table.
|
||||
```
|
||||
|
||||
The matrix must explicitly include:
|
||||
|
||||
- users
|
||||
- organizations
|
||||
- memberships
|
||||
- CRM role profiles
|
||||
- CRM user role assignments
|
||||
- ms_options
|
||||
- crm_branch options
|
||||
- crm_product_type options
|
||||
- document sequences
|
||||
- approval workflows
|
||||
- approval steps
|
||||
- approval matrices
|
||||
- document templates
|
||||
- document template versions
|
||||
- document template mappings
|
||||
- document libraries
|
||||
- notification templates
|
||||
- report definitions
|
||||
- customers
|
||||
- contacts
|
||||
- contact shares
|
||||
- leads
|
||||
- opportunities
|
||||
- quotations
|
||||
- quotation items
|
||||
- quotation topics
|
||||
- quotation topic items
|
||||
- quotation project parties
|
||||
- followups
|
||||
- audit logs
|
||||
- notification events
|
||||
- generated PDFs / document artifacts
|
||||
- uploaded files / attachments
|
||||
- setup state
|
||||
- seed manifests
|
||||
|
||||
Also include unsupported or ambiguous items:
|
||||
|
||||
- departments
|
||||
- teams
|
||||
- warehouses
|
||||
- sites
|
||||
- price books
|
||||
- services
|
||||
- tax rate table if not first-class
|
||||
- email provider config if not first-class
|
||||
|
||||
---
|
||||
|
||||
# Phase 3 — CSV Template Specification
|
||||
|
||||
Create CSV template specification.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/csv-template-spec.md
|
||||
```
|
||||
|
||||
For each supported CSV, define:
|
||||
|
||||
```text
|
||||
File Name
|
||||
Purpose
|
||||
Target Table / Service
|
||||
Seed Type
|
||||
Required Columns
|
||||
Optional Columns
|
||||
Generated Columns
|
||||
Validation Rules
|
||||
Relationship Resolution
|
||||
Duplicate Detection
|
||||
Upsert Key
|
||||
Import Order
|
||||
Example Rows
|
||||
Error Examples
|
||||
```
|
||||
|
||||
Required CSV specs:
|
||||
|
||||
```text
|
||||
organizations.csv
|
||||
users.csv
|
||||
memberships.csv
|
||||
crm-role-assignments.csv
|
||||
master-options.csv
|
||||
branches.csv
|
||||
product-types.csv
|
||||
document-sequences.csv
|
||||
approval-workflows.csv
|
||||
approval-steps.csv
|
||||
approval-matrix.csv
|
||||
customers.csv
|
||||
contacts.csv
|
||||
contact-shares.csv
|
||||
leads.csv
|
||||
opportunities.csv
|
||||
opportunity-parties.csv
|
||||
quotations.csv
|
||||
quotation-items.csv
|
||||
quotation-parties.csv
|
||||
quotation-topics.csv
|
||||
quotation-topic-items.csv
|
||||
```
|
||||
|
||||
Unsupported/deferred specs must be marked clearly:
|
||||
|
||||
```text
|
||||
departments.csv
|
||||
teams.csv
|
||||
warehouses.csv
|
||||
sites.csv
|
||||
services.csv
|
||||
price-books.csv
|
||||
tax-rates.csv
|
||||
attachments.csv
|
||||
email-settings.csv
|
||||
```
|
||||
|
||||
Each CSV section must include at least one example row.
|
||||
|
||||
Example:
|
||||
|
||||
```csv
|
||||
organization_code,organization_name,slug,tax_id,default_currency,status
|
||||
ALLA,ALLA Public Company Limited,alla,0107558000393,THB,active
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Phase 4 — Import Mapping Specification
|
||||
|
||||
Create import mapping specification.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/import-mapping.md
|
||||
```
|
||||
|
||||
For every supported CSV, define:
|
||||
|
||||
```text
|
||||
CSV Column
|
||||
Target Field
|
||||
Transform
|
||||
Validation
|
||||
Required
|
||||
Reference Resolver
|
||||
Fallback
|
||||
Notes
|
||||
```
|
||||
|
||||
Important mappings:
|
||||
|
||||
## branches.csv
|
||||
|
||||
Must map to:
|
||||
|
||||
```text
|
||||
ms_options
|
||||
category = crm_branch
|
||||
organization_id = selected organization
|
||||
value/code = branch_code
|
||||
label = branch_name
|
||||
metadata = prefix, address, tax info if applicable
|
||||
```
|
||||
|
||||
## product-types.csv
|
||||
|
||||
Must map to:
|
||||
|
||||
```text
|
||||
ms_options
|
||||
category = crm_product_type
|
||||
value/code = product_type_code
|
||||
label = product_type_name
|
||||
metadata = document_prefix
|
||||
```
|
||||
|
||||
## document-sequences.csv
|
||||
|
||||
Must resolve:
|
||||
|
||||
```text
|
||||
organization_code
|
||||
branch_code
|
||||
product_type_code
|
||||
document_type
|
||||
period_format
|
||||
prefix
|
||||
current_number
|
||||
```
|
||||
|
||||
## users.csv + memberships.csv
|
||||
|
||||
Must clarify whether user creation and organization membership are separate or combined.
|
||||
|
||||
## crm-role-assignments.csv
|
||||
|
||||
Must resolve:
|
||||
|
||||
```text
|
||||
user_email
|
||||
organization_code
|
||||
crm_role_code
|
||||
branch_code
|
||||
product_type_code
|
||||
```
|
||||
|
||||
## customers.csv
|
||||
|
||||
Must resolve:
|
||||
|
||||
```text
|
||||
organization_code
|
||||
owner_user_email
|
||||
customer_type
|
||||
customer_group
|
||||
```
|
||||
|
||||
## leads/opportunities/quotations
|
||||
|
||||
Must resolve:
|
||||
|
||||
```text
|
||||
organization_code
|
||||
customer_code
|
||||
contact_email
|
||||
branch_code
|
||||
product_type_code
|
||||
owner_user_email
|
||||
created_by_email
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Phase 5 — Setup Wizard Blueprint
|
||||
|
||||
Create wizard blueprint.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/setup-wizard-blueprint.md
|
||||
```
|
||||
|
||||
Define:
|
||||
|
||||
```text
|
||||
Step Number
|
||||
Step Name
|
||||
Purpose
|
||||
Inputs
|
||||
Validation
|
||||
Actions
|
||||
APIs
|
||||
Can Skip
|
||||
Can Go Back
|
||||
Resume Behavior
|
||||
Error Handling
|
||||
Output
|
||||
```
|
||||
|
||||
Required wizard steps:
|
||||
|
||||
1. System Readiness
|
||||
2. Foundation Install
|
||||
3. Organization Setup
|
||||
4. Branch & Product Type Setup
|
||||
5. Administrator Setup
|
||||
6. Document Sequence Setup
|
||||
7. Approval Workflow Setup
|
||||
8. CSV Import
|
||||
9. Verification
|
||||
10. Finish & Report
|
||||
|
||||
Each step must define required fields.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Organization Setup Inputs
|
||||
|
||||
organization_name: required
|
||||
organization_code: required, uppercase, unique
|
||||
slug: required, lowercase, unique
|
||||
tax_id: optional
|
||||
phone: optional
|
||||
email: optional email format
|
||||
address: optional
|
||||
default_currency: required, default THB
|
||||
timezone: required, default Asia/Bangkok
|
||||
logo: optional
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Phase 6 — Setup State Machine
|
||||
|
||||
Create setup state specification.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/setup-state-machine.md
|
||||
```
|
||||
|
||||
Define state model:
|
||||
|
||||
```text
|
||||
not_started
|
||||
readiness_checked
|
||||
foundation_installed
|
||||
organization_created
|
||||
administrator_created
|
||||
scope_configured
|
||||
sequences_configured
|
||||
approval_configured
|
||||
csv_validated
|
||||
csv_imported
|
||||
verified
|
||||
completed
|
||||
failed
|
||||
cancelled
|
||||
```
|
||||
|
||||
Define events:
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
Define persistence strategy.
|
||||
|
||||
If no setup table exists, propose new table:
|
||||
|
||||
```text
|
||||
setup_runs
|
||||
setup_run_steps
|
||||
seed_manifests
|
||||
seed_manifest_items
|
||||
```
|
||||
|
||||
Do not implement migrations in this task unless explicitly approved.
|
||||
|
||||
---
|
||||
|
||||
# Phase 7 — Verification Matrix
|
||||
|
||||
Create verification matrix.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/verification-matrix.md
|
||||
```
|
||||
|
||||
Required columns:
|
||||
|
||||
```text
|
||||
Check ID
|
||||
Area
|
||||
Check Name
|
||||
Purpose
|
||||
Required For
|
||||
Method
|
||||
Pass Condition
|
||||
Warning Condition
|
||||
Fail Condition
|
||||
Suggested Fix
|
||||
API / Service
|
||||
```
|
||||
|
||||
Checks must include:
|
||||
|
||||
- environment variable presence
|
||||
- database connectivity
|
||||
- migration status
|
||||
- storage read/write/delete smoke test
|
||||
- upload directory readiness
|
||||
- first administrator exists
|
||||
- administrator membership exists
|
||||
- administrator CRM role assignment resolves
|
||||
- organization active
|
||||
- branch option exists
|
||||
- product type option exists
|
||||
- document sequence preview works
|
||||
- quotation approval workflow resolves
|
||||
- approval matrix resolves
|
||||
- PDF template exists
|
||||
- PDF template version active
|
||||
- PDF mapping exists
|
||||
- notification templates exist
|
||||
- report definitions exist
|
||||
- email configuration optional dry-run
|
||||
|
||||
---
|
||||
|
||||
# Phase 8 — Reset / Reseed Matrix
|
||||
|
||||
Create reset/reseed specification.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/reset-reseed-matrix.md
|
||||
```
|
||||
|
||||
Define reset scopes:
|
||||
|
||||
```text
|
||||
foundation_reset
|
||||
organization_reset
|
||||
business_reset
|
||||
demo_uat_reset
|
||||
full_reset
|
||||
csv_import_rollback
|
||||
setup_run_reset
|
||||
```
|
||||
|
||||
For each scope define:
|
||||
|
||||
```text
|
||||
Tables affected
|
||||
Data retained
|
||||
Data deleted
|
||||
Safety guard
|
||||
Requires confirmation
|
||||
Allowed environment
|
||||
Transaction behavior
|
||||
Storage cleanup behavior
|
||||
Audit behavior
|
||||
Recommended command/API
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Production destructive reset must be blocked.
|
||||
- Reset must require explicit confirmation.
|
||||
- Storage cleanup must be compensated and reported.
|
||||
- Runtime generated approved artifacts must not be casually deleted outside explicit full reset/demo reset.
|
||||
|
||||
---
|
||||
|
||||
# Phase 9 — Seed Version and Manifest Strategy
|
||||
|
||||
Create seed lifecycle specification.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/seed-version-manifest.md
|
||||
```
|
||||
|
||||
Define:
|
||||
|
||||
```text
|
||||
Seed Package
|
||||
Version
|
||||
Dependencies
|
||||
Checksum
|
||||
Applied At
|
||||
Applied By
|
||||
Target Organization
|
||||
Source
|
||||
Status
|
||||
Report
|
||||
```
|
||||
|
||||
Propose manifest format:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "crm-foundation",
|
||||
"version": "1.0.0",
|
||||
"type": "foundation",
|
||||
"dependencies": ["system-core@1.0.0"],
|
||||
"items": [
|
||||
{
|
||||
"file": "master-options.csv",
|
||||
"checksum": "...",
|
||||
"required": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Define upgrade behavior:
|
||||
|
||||
```text
|
||||
same version + same checksum = skip
|
||||
same version + changed checksum = warn/block unless force
|
||||
newer version = apply if compatible
|
||||
older version = block unless rollback mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Phase 10 — Setup Plugin Architecture
|
||||
|
||||
Create plugin architecture proposal.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
docs/setup/setup-plugin-architecture.md
|
||||
```
|
||||
|
||||
Goal:
|
||||
|
||||
Future modules can register setup behavior without editing the core wizard.
|
||||
|
||||
Plugin contract should cover:
|
||||
|
||||
```text
|
||||
module_id
|
||||
display_name
|
||||
setup_steps
|
||||
csv_templates
|
||||
seed_tasks
|
||||
verification_checks
|
||||
reset_scopes
|
||||
dependencies
|
||||
enabled_condition
|
||||
```
|
||||
|
||||
Example modules:
|
||||
|
||||
```text
|
||||
core
|
||||
foundation
|
||||
crm
|
||||
quotation
|
||||
approval
|
||||
document
|
||||
notification
|
||||
reporting
|
||||
future_asset
|
||||
future_hr
|
||||
```
|
||||
|
||||
No implementation required, but the design must be concrete enough for future implementation.
|
||||
|
||||
---
|
||||
|
||||
# Phase 11 — Implementation Plan for D.7.2+
|
||||
|
||||
Create implementation slice plan.
|
||||
|
||||
Output file:
|
||||
|
||||
```text
|
||||
plans/task-d.7.2.md
|
||||
```
|
||||
|
||||
Recommended slices:
|
||||
|
||||
## D.7.2
|
||||
|
||||
Setup Readiness and Verification APIs
|
||||
|
||||
## D.7.3
|
||||
|
||||
CSV Template Generator and Static Template Pack
|
||||
|
||||
## D.7.4
|
||||
|
||||
CSV Preview Validation Engine
|
||||
|
||||
## D.7.5
|
||||
|
||||
CSV Commit Import Engine
|
||||
|
||||
## D.7.6
|
||||
|
||||
Dashboard Setup Wizard UI
|
||||
|
||||
## D.7.7
|
||||
|
||||
Scoped Reset and Reseed Engine
|
||||
|
||||
## D.7.8
|
||||
|
||||
Seed Manifest and Setup State Persistence
|
||||
|
||||
Each slice must include:
|
||||
|
||||
```text
|
||||
Objective
|
||||
Files to review
|
||||
Implementation scope
|
||||
Out of scope
|
||||
Acceptance criteria
|
||||
Risk notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Deliverables
|
||||
|
||||
The task is complete only when the following files exist:
|
||||
|
||||
```text
|
||||
docs/setup/seed-matrix.md
|
||||
docs/setup/csv-template-spec.md
|
||||
docs/setup/import-mapping.md
|
||||
docs/setup/setup-wizard-blueprint.md
|
||||
docs/setup/setup-state-machine.md
|
||||
docs/setup/verification-matrix.md
|
||||
docs/setup/reset-reseed-matrix.md
|
||||
docs/setup/seed-version-manifest.md
|
||||
docs/setup/setup-plugin-architecture.md
|
||||
plans/task-d.7.2.md
|
||||
```
|
||||
|
||||
Optional drafts:
|
||||
|
||||
```text
|
||||
setup/templates/*.csv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
- The setup implementation can be started without guessing.
|
||||
- Every setup-related entity is classified.
|
||||
- Every supported CSV has required fields, validation, mapping, upsert key, and examples.
|
||||
- Unsupported CSVs are clearly marked with the reason.
|
||||
- Wizard steps have inputs, validation, actions, APIs, outputs, and resume behavior.
|
||||
- Setup state machine is defined.
|
||||
- Verification checks are actionable.
|
||||
- Reset/reseed scopes are safe and explicit.
|
||||
- Seed version and manifest behavior is defined.
|
||||
- Future module setup plugin strategy is documented.
|
||||
- No existing production behavior is changed.
|
||||
|
||||
---
|
||||
|
||||
# Implementation Log
|
||||
|
||||
## 2026-07-02 - Blueprint documentation completed
|
||||
|
||||
- Created complete setup blueprint/specification deliverables under `docs/setup/`.
|
||||
- Created next implementation slice plan at `plans/task-d.7.2.md`.
|
||||
- No production code behavior was changed.
|
||||
Reference in New Issue
Block a user