allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
6d6cd3a6df5e381bbe40a6e65d30b174dc986944
alla-allaos-fullstack/plans/task-clean-pk.md
phaichayon e12ae120b0 uat-seed-script
2026-06-30 10:48:15 +07:00

7.4 KiB
Raw Blame History

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:

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:
docs/audit/package-scripts-cleanup.md
  1. The report must include:
Script Name
Current Command
Status: keep / rename / remove / replace
Reason
Replacement Command if any
  1. Then update package.json.

Recommended final script groups

{
  "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:

src/db/seeds/
scripts/

Expected command behavior:

1. System seed

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

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:

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

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:

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:

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

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

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

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:

Quotation Standard Approval
Step 1: Sales Manager
Step 2: Department Manager or Business Manager
Step 3: CEO

For UAT, make the flow visually simple:

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:

Lead
Opportunity
Quotation
PO if supported

Code format:

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:

npm run seed:pdf-template

If template reset is needed, add:

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:

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:

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:

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 View Git Blame Copy Permalink