alla-allaos-fullstack/plans/task-clean-pk.md

# 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.