uat-seed-script
This commit is contained in:
phaichayon
433
plans/task-clean-pk.md
Normal file
433
plans/task-clean-pk.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# Task: Clean package.json Scripts + UAT Seed + Resettable System Seed
|
||||
|
||||
## Role
|
||||
|
||||
You are a Next.js full-stack engineer working on ALLA OS CRM.
|
||||
|
||||
Tech stack:
|
||||
|
||||
* Next.js Full Stack
|
||||
* TypeScript
|
||||
* Drizzle ORM
|
||||
* PostgreSQL
|
||||
* shadcn/ui
|
||||
* Auth.js / Keycloak-compatible user model
|
||||
* pdfme document template system
|
||||
|
||||
## Objective
|
||||
|
||||
Clean unused `package.json` scripts and implement deterministic seed scripts for UAT/demo data that clearly shows the CRM workflow:
|
||||
|
||||
```text
|
||||
Marketing (MK) -> Sales -> Manager -> CEO
|
||||
```
|
||||
|
||||
The system must be resettable to a clean starting state at any time.
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Audit and Clean package.json
|
||||
|
||||
Inspect `package.json`, `scripts/`, `src/db/seeds/`, `drizzle/`, and existing documentation.
|
||||
|
||||
### Requirements
|
||||
|
||||
1. Identify scripts that are:
|
||||
|
||||
* broken
|
||||
* duplicated
|
||||
* unused
|
||||
* pointing to missing files
|
||||
* legacy from old architecture
|
||||
* confusing or overlapping
|
||||
|
||||
2. Do not delete blindly.
|
||||
|
||||
* First create a report file:
|
||||
|
||||
```text
|
||||
docs/audit/package-scripts-cleanup.md
|
||||
```
|
||||
|
||||
3. The report must include:
|
||||
|
||||
```text
|
||||
Script Name
|
||||
Current Command
|
||||
Status: keep / rename / remove / replace
|
||||
Reason
|
||||
Replacement Command if any
|
||||
```
|
||||
|
||||
4. Then update `package.json`.
|
||||
|
||||
### Recommended final script groups
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "...",
|
||||
"build": "...",
|
||||
"start": "...",
|
||||
"lint": "...",
|
||||
"typecheck": "tsc --noEmit",
|
||||
|
||||
"db:generate": "...",
|
||||
"db:migrate": "...",
|
||||
"db:studio": "...",
|
||||
"db:fresh": "...",
|
||||
"db:fresh:uat": "...",
|
||||
|
||||
"seed:system": "...",
|
||||
"seed:uat": "...",
|
||||
"seed:reset": "...",
|
||||
"seed:pdf-template": "...",
|
||||
|
||||
"verify:encoding": "...",
|
||||
"verify:crm-access": "...",
|
||||
"audit:pdf": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the actual project commands after inspection.
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Implement Resettable Seed Architecture
|
||||
|
||||
Create or normalize seed scripts under:
|
||||
|
||||
```text
|
||||
src/db/seeds/
|
||||
scripts/
|
||||
```
|
||||
|
||||
Expected command behavior:
|
||||
|
||||
### 1. System seed
|
||||
|
||||
```bash
|
||||
npm run seed:system
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
* create minimum required system data
|
||||
* organizations
|
||||
* branches
|
||||
* product types
|
||||
* roles
|
||||
* permissions
|
||||
* master options
|
||||
* document sequences
|
||||
* approval definitions
|
||||
* PDF template records
|
||||
|
||||
Must be idempotent.
|
||||
|
||||
---
|
||||
|
||||
### 2. UAT seed
|
||||
|
||||
```bash
|
||||
npm run seed:uat
|
||||
```
|
||||
|
||||
Purpose:
|
||||
Create realistic demo data for UAT so each role can log in and clearly see its own view.
|
||||
|
||||
Seed role flow:
|
||||
|
||||
```text
|
||||
MK User
|
||||
creates Lead
|
||||
|
||||
Sales User
|
||||
receives assigned Lead
|
||||
works Opportunity
|
||||
creates Quotation
|
||||
|
||||
Manager User
|
||||
sees team pipeline
|
||||
approves quotation step 1 or 2
|
||||
|
||||
CEO User
|
||||
sees executive dashboard
|
||||
final approval
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Full reset seed
|
||||
|
||||
```bash
|
||||
ALLOW_DB_RESET=true npm run seed:reset
|
||||
```
|
||||
|
||||
Purpose:
|
||||
Reset all business/UAT data and rebuild from clean baseline.
|
||||
|
||||
Rules:
|
||||
|
||||
* Must require `ALLOW_DB_RESET=true`
|
||||
* Must refuse to run without this env flag
|
||||
* Must never run accidentally in production
|
||||
* Must clear CRM transactional tables in dependency-safe order
|
||||
* Must preserve migrations
|
||||
* Must rebuild system seed
|
||||
* Must rebuild UAT seed
|
||||
|
||||
Expected flow:
|
||||
|
||||
```text
|
||||
validate environment
|
||||
clear transactional CRM data
|
||||
clear configurable seed-owned master data if needed
|
||||
run seed:system
|
||||
run seed:uat
|
||||
run audit/verification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 3: UAT Demo Users
|
||||
|
||||
Create clear users and memberships.
|
||||
|
||||
Example users:
|
||||
|
||||
```text
|
||||
mk.uat@alla.local
|
||||
sales.crane.uat@alla.local
|
||||
sales.dockdoor.uat@alla.local
|
||||
mgr.sales.uat@alla.local
|
||||
ceo.uat@alla.local
|
||||
admin.uat@alla.local
|
||||
```
|
||||
|
||||
Each user must have:
|
||||
|
||||
* deterministic id
|
||||
* name
|
||||
* email
|
||||
* role
|
||||
* businessRole
|
||||
* permissions
|
||||
* organization membership
|
||||
* branch scope
|
||||
* product type scope where applicable
|
||||
|
||||
Use existing schema and permission model. Do not invent unrelated tables.
|
||||
|
||||
---
|
||||
|
||||
## Part 4: UAT Demo Data Scenario
|
||||
|
||||
Create data that makes the dashboard and permissions obvious.
|
||||
|
||||
### Scenario A: Crane Project
|
||||
|
||||
```text
|
||||
Customer: Siam Manufacturing Co., Ltd.
|
||||
End Customer: Toyota Gateway Plant
|
||||
Project: Overhead Crane Installation Phase 1
|
||||
Product Type: Crane
|
||||
Lead created by: MK
|
||||
Assigned to: Sales Crane
|
||||
Manager: Sales Manager
|
||||
Final approver: CEO
|
||||
Quotation status: Pending Approval / Approved
|
||||
Value: realistic THB amount
|
||||
```
|
||||
|
||||
### Scenario B: Dock Door Project
|
||||
|
||||
```text
|
||||
Customer: Eastern Logistics Co., Ltd.
|
||||
End Customer: WHA Warehouse
|
||||
Project: Loading Dock Expansion
|
||||
Product Type: Dock Door
|
||||
Lead created by: MK
|
||||
Assigned to: Sales Dock Door
|
||||
Quotation status: Draft / Follow-up
|
||||
```
|
||||
|
||||
### Scenario C: Lost / No Quotation
|
||||
|
||||
```text
|
||||
Customer: Demo Lost Customer
|
||||
Reason: Budget not approved / competitor selected
|
||||
Status: Closed Lost or No Quotation
|
||||
```
|
||||
|
||||
### Scenario D: Follow-up Due
|
||||
|
||||
Create at least:
|
||||
|
||||
* one due today
|
||||
* one overdue
|
||||
* one upcoming
|
||||
|
||||
This helps test calendar/dashboard/follow-up UI.
|
||||
|
||||
---
|
||||
|
||||
## Part 5: Approval Flow Seed
|
||||
|
||||
Create approval definition:
|
||||
|
||||
```text
|
||||
Quotation Standard Approval
|
||||
Step 1: Sales Manager
|
||||
Step 2: Department Manager or Business Manager
|
||||
Step 3: CEO
|
||||
```
|
||||
|
||||
For UAT, make the flow visually simple:
|
||||
|
||||
```text
|
||||
Sales submits quotation
|
||||
Manager approves
|
||||
CEO final approves
|
||||
```
|
||||
|
||||
Seed at least:
|
||||
|
||||
* one draft quotation
|
||||
* one submitted quotation
|
||||
* one manager-approved quotation waiting for CEO
|
||||
* one fully approved quotation
|
||||
* one rejected quotation if supported
|
||||
|
||||
---
|
||||
|
||||
## Part 6: Document Sequence Seed
|
||||
|
||||
Seed document sequences for all main document types:
|
||||
|
||||
```text
|
||||
Lead
|
||||
Opportunity
|
||||
Quotation
|
||||
PO if supported
|
||||
```
|
||||
|
||||
Code format:
|
||||
|
||||
```text
|
||||
ProductType + YYMM + running
|
||||
CR2606-001
|
||||
DK2606-001
|
||||
SOL2606-001
|
||||
SV2606-001
|
||||
SP2606-001
|
||||
```
|
||||
|
||||
Branch should represent internal ALLA branch/business unit, not customer branch.
|
||||
|
||||
---
|
||||
|
||||
## Part 7: PDF Template Seed
|
||||
|
||||
Ensure PDF template seeding is included.
|
||||
|
||||
Runtime must use DB template versions, not raw JSON directly.
|
||||
|
||||
Add or confirm command:
|
||||
|
||||
```bash
|
||||
npm run seed:pdf-template
|
||||
```
|
||||
|
||||
If template reset is needed, add:
|
||||
|
||||
```bash
|
||||
npm run seed:pdf-template:reset
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
* deactivate old active template versions if needed
|
||||
* insert/update template version from source JSON
|
||||
* activate the correct version
|
||||
* run `npm run audit:pdf`
|
||||
|
||||
Do not leave multiple active versions for the same template.
|
||||
|
||||
---
|
||||
|
||||
## Part 8: Safety Requirements
|
||||
|
||||
1. All seed scripts must be idempotent.
|
||||
2. Running `npm run seed:uat` twice must not duplicate data.
|
||||
3. Reset must require explicit env flag.
|
||||
4. Scripts must log what they changed.
|
||||
5. Use deterministic IDs or stable unique keys.
|
||||
6. Do not hide errors with empty catch blocks.
|
||||
7. Use transactions where practical.
|
||||
8. Add verification output after seed.
|
||||
|
||||
---
|
||||
|
||||
## Part 9: Verification Commands
|
||||
|
||||
After implementation, run:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run build
|
||||
npm run seed:reset
|
||||
npm run verify:encoding
|
||||
npm run verify:crm-access
|
||||
npm run audit:pdf
|
||||
```
|
||||
|
||||
If some commands do not exist, either:
|
||||
|
||||
* add them properly, or
|
||||
* document why they are not available.
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
Create or update:
|
||||
|
||||
```text
|
||||
package.json
|
||||
docs/audit/package-scripts-cleanup.md
|
||||
docs/seeding/uat-seed-guide.md
|
||||
scripts/seed-system.ts
|
||||
scripts/seed-uat.ts
|
||||
scripts/seed-reset.ts
|
||||
scripts/reseed-pdf-template-version.ts if needed
|
||||
src/db/seeds/*
|
||||
```
|
||||
|
||||
The UAT seed guide must include:
|
||||
|
||||
```text
|
||||
User
|
||||
Email
|
||||
Role
|
||||
What this user should see
|
||||
Expected CRM data
|
||||
Expected approval actions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* `package.json` has no dead scripts.
|
||||
* `npm run seed:system` works.
|
||||
* `npm run seed:uat` works.
|
||||
* `ALLOW_DB_RESET=true npm run seed:reset` resets and reseeds cleanly.
|
||||
* UAT data clearly demonstrates MK -> Sales -> Manager -> CEO.
|
||||
* Each role sees different data according to permission.
|
||||
* Quotation approval flow has testable documents.
|
||||
* PDF template audit passes.
|
||||
* No duplicate active PDF template version exists.
|
||||
* TypeScript passes.
|
||||
* Build passes.
|
||||
Reference in New Issue
Block a user