uat-seed-script

2026-06-30 10:48:15 +07:00
parent e4573ac0c9
commit e12ae120b0
31 changed files with 1791 additions and 314 deletions
--- a/docs/audit/package-scripts-cleanup.md
+++ b/docs/audit/package-scripts-cleanup.md
@@ -0,0 +1,88 @@
+# Package Scripts Cleanup Audit
+
+## Scope
+
+- reviewed `package.json`
+- reviewed `scripts/**`
+- reviewed `src/db/seeds/**`
+- reviewed `docs/operations/system-bootstrap.md`
+- cross-checked historical references in `docs/implementation/**` and setup copy
+
+## Decision Summary
+
+| Script Name | Current Command | Status | Reason | Replacement Command |
+| --- | --- | --- | --- | --- |
+| `dev` | `next dev` | keep | core runtime entrypoint | - |
+| `build` | `npm run verify:encoding && next build` | keep | build already guards encoding drift | - |
+| `start` | `next start` | keep | production runtime entrypoint | - |
+| `lint` | `oxlint` | keep | active lint entrypoint | - |
+| `lint:fix` | `oxlint --fix && bun format` | keep | active fix workflow | - |
+| `lint:strict` | `oxlint --deny-warnings` | keep | stricter CI-style lint path | - |
+| `format` | `oxfmt --write .` | keep | active formatter entrypoint | - |
+| `format:check` | `oxfmt --check .` | keep | active formatter verification | - |
+| `prepare` | `husky` | keep | install hook bootstrap | - |
+| `typecheck` | `tsc --noEmit` | add | required by task and docs verification flow | - |
+| `gen` | `npm run verify:encoding && npx drizzle-kit generate` | remove | duplicate of `db:generate` with unclear shorthand | `npm run db:generate` |
+| `db:generate` | `npx drizzle-kit generate` | keep | canonical drizzle generate command | - |
+| `db:migrate` | `npx drizzle-kit migrate` | keep | canonical drizzle migrate command | - |
+| `db:studio` | `npx drizzle-kit studio` | keep | canonical drizzle studio command | - |
+| `db:reset` | `node --experimental-strip-types scripts/db/reset-database.ts` | keep | guarded destructive operation with env safety | - |
+| `db:setup` | `npm run db:migrate && npm run seed:system` | keep | still referenced by setup flow and valid | - |
+| `db:setup:uat` | `npm run db:setup && npm run seed:uat` | keep | valid setup composition for UAT | - |
+| `db:fresh` | `npm run db:reset && npm run db:migrate && npm run seed:system` | keep | clean local bootstrap path | - |
+| `db:fresh:uat` | `npm run db:fresh && npm run seed:uat` | keep | clean UAT bootstrap path | - |
+| `migrate` | `npm run db:migrate` | remove | duplicate shorthand | `npm run db:migrate` |
+| `studio` | `npm run db:studio` | remove | duplicate shorthand | `npm run db:studio` |
+| `setup:db` | `npm run db:setup` | keep | compatibility alias still referenced by setup wizard copy | `npm run db:setup` |
+| `seed:super-admin` | `node scripts/seed-super-admin.js` | keep | useful low-level bootstrap step | - |
+| `seed:foundation` | `node --experimental-strip-types src/db/seeds/foundation.seed.ts` | keep | useful low-level seed for troubleshooting | - |
+| `seed:crm-uat` | `node --experimental-strip-types src/db/seeds/crm-uat.seed.ts` | keep | useful low-level data-only seed for troubleshooting | - |
+| `seed:system` | old direct seed file | replace | now routes through `scripts/seed-system.ts` wrapper and includes PDF template reseed | `npm run seed:system` |
+| `seed:uat` | old direct seed file | replace | now routes through `scripts/seed-uat.ts` wrapper and seeds users before CRM data | `npm run seed:uat` |
+| `seed:reset` | not present | add | task-required guarded reset + migrate + reseed orchestration | `npm run seed:reset -- --allow-db-reset` |
+| `seed:pdf-template` | `node --experimental-strip-types scripts/reseed-pdf-template-version.ts` | keep | canonical operator-facing PDF template sync | - |
+| `seed:pdf-template-version` | same as `seed:pdf-template` | keep | compatibility alias for historical docs and task lineage | `npm run seed:pdf-template` |
+| `pdf:reseed` | duplicate reseed alias | remove | overlapping alias with no added behavior | `npm run seed:pdf-template` |
+| `pdf:activate:product` | targeted activation command | keep | still useful for product-v1 operator flow | - |
+| `migrate:membership-business-roles` | migration utility | keep | one-off but still valid migration helper | - |
+| `seed:task-h1-fixture` | fixture utility | keep | still referenced by historical PDF verification docs | - |
+| `legacy:seed:task-h1-fixture` | duplicate legacy alias | remove | duplicate of active fixture command | `npm run seed:task-h1-fixture` |
+| `verify:task-h1` | fixture verification utility | keep | still referenced by historical docs | - |
+| `legacy:verify:task-h1` | duplicate legacy alias | remove | duplicate of active verification command | `npm run verify:task-h1` |
+| `verify:task-h3` | historical verification utility | keep | still valid and referenced | - |
+| `legacy:verify:task-h3` | duplicate legacy alias | remove | duplicate of active verification command | `npm run verify:task-h3` |
+| `verify:encoding` | `node scripts/verify-encoding.mjs` | keep | build safety prerequisite | - |
+| `verify:crm-access` | CRM access audit | keep | task-required verification | - |
+| `audit:pdf:*` | PDF audit suite | keep | active verification foundation | - |
+
+## Changes Applied
+
+- added `typecheck`
+- added `seed:reset`
+- moved `seed:system` to `scripts/seed-system.ts`
+- moved `seed:uat` to `scripts/seed-uat.ts`
+- kept `seed:pdf-template-version` only as compatibility alias
+- removed duplicate shorthand and legacy aliases:
+  - `gen`
+  - `migrate`
+  - `studio`
+  - `pdf:reseed`
+  - `legacy:seed:task-h1-fixture`
+  - `legacy:verify:task-h1`
+  - `legacy:verify:task-h3`
+
+## Seed Architecture Notes
+
+- `seed:system` now guarantees:
+  - super admin
+  - foundation data
+  - active PDF template reseed
+- `seed:uat` now guarantees:
+  - deterministic UAT users and memberships
+  - CRM role profiles and role assignments
+  - CRM demo dataset
+- `seed:reset` now guarantees:
+- explicit `--allow-db-reset` confirmation or `ALLOW_DB_RESET=true`
+  - database reset safety guard
+  - migrations reapplied before seeding
+  - `seed:system` then `seed:uat`
--- a/docs/implementation/pdf-audit-report.json
+++ b/docs/implementation/pdf-audit-report.json
@@ -1,30 +1,61 @@
 {
-  "generatedAt": "2026-06-30T01:35:48.376Z",
+  "generatedAt": "2026-06-30T02:56:00.835Z",
  "overallStatus": "PASS",
-  "quotationCode": "QT2606-1122",
+  "quotationCode": "CR2606-1124",
  "expectedFixtureCode": "QT-H5-AUDIT",
  "template": {
-    "templateName": "ALLA Quotation Standard",
-    "version": "2.1",
-    "versionId": "86f99414-4656-44a9-9937-8457794dc710",
+    "templateName": "ALLA Demo Organization Quotation Standard",
+    "version": "1.0",
+    "versionId": "850b13a2-c9ae-4992-89e7-a43f50c34378",
    "fieldCount": 44,
-    "previousVersion": "2.0",
-    "deletedFields": [
-      "__section_role__customer",
-      "__section_role__product_items",
-      "__section_role__signature",
-      "__section_role__topics",
-      "items_table",
-      "product_items_currency_value",
-      "product_items_footer_note",
-      "product_items_line_168",
-      "product_items_line_35",
-      "product_items_subtitle",
-      "product_items_title",
-      "product_items_total_label",
-      "product_items_total_value"
+    "previousVersion": null,
+    "deletedFields": [],
+    "newFields": [
+      "Please_do_not",
+      "app1",
+      "app1_position",
+      "app2",
+      "app2_position",
+      "app3",
+      "app3_position",
+      "att_label",
+      "colon",
+      "colon copy",
+      "colon_att",
+      "colon_email",
+      "colon_fax",
+      "colon_project",
+      "colon_site",
+      "colon_tel",
+      "company1",
+      "company2",
+      "company_addr1",
+      "company_addr2",
+      "company_email",
+      "company_tax",
+      "company_tel",
+      "customer_addr",
+      "customer_att",
+      "customer_email",
+      "customer_name",
+      "customer_tel",
+      "data_topic",
+      "dear_sirs",
+      "email_label",
+      "line",
+      "project_label",
+      "project_name",
+      "quotation_code_data",
+      "quotation_code_lable",
+      "quotation_date_data",
+      "quotation_date_labe",
+      "quotation_price_data",
+      "site_label",
+      "site_location",
+      "tel_label",
+      "topic",
+      "yours_faithfuly"
    ],
-    "newFields": [],
    "duplicateFields": [],
    "unknownFields": [],
    "classifications": [
@@ -232,7 +263,7 @@
  "consistency": {
    "status": "PASS",
    "approvedSnapshotAvailable": true,
-    "approvedArtifactReference": "artifact:ec300b87-3710-43a4-a63c-a72168fe3933",
+    "approvedArtifactReference": null,
    "inconsistentKeys": []
  },
  "integritySummary": {
--- a/docs/implementation/pdf-audit-report.md
+++ b/docs/implementation/pdf-audit-report.md
@@ -1,10 +1,10 @@
 # PDF Audit Report

- Generated At: 2026-06-30T01:35:48.376Z
+- Generated At: 2026-06-30T02:56:00.835Z
 - Overall Status: PASS
- Quotation Code: QT2606-1122
- Template: ALLA Quotation Standard v2.1
- Previous Version: 2.0
+- Quotation Code: CR2606-1124
+- Template: ALLA Demo Organization Quotation Standard v1.0
+- Previous Version: None

 ## Metrics

--- a/docs/operations/system-bootstrap.md
+++ b/docs/operations/system-bootstrap.md
@@ -4,15 +4,21 @@

 ```bash
 npm install
-ALLOW_DB_RESET=true npm run db:fresh
-npm exec tsc --noEmit
+npm run db:fresh
+npm run typecheck
 npm run dev
 ```

 ## Fresh UAT or demo data

 ```bash
-ALLOW_DB_RESET=true npm run db:fresh:uat
+npm run db:fresh:uat
+```
+
+## Reset and reseed existing local/UAT data
+
+```bash
+npm run seed:reset -- --allow-db-reset
 ```

 ## Existing database upgrade
@@ -44,7 +50,7 @@ npm run seed:pdf-template
 ## Verification

 ```bash
-npm exec tsc --noEmit
+npm run typecheck
 npm run build
 npm run verify:encoding
 npm run verify:crm-access
--- a/docs/seeding/uat-seed-guide.md
+++ b/docs/seeding/uat-seed-guide.md
@@ -0,0 +1,86 @@
+# UAT Seed Guide
+
+## Purpose
+
+Seeded UAT data is designed to make the CRM flow visible end-to-end:
+
+`Marketing (MK) -> Sales -> Manager -> CEO`
+
+Default password for all seeded UAT accounts:
+
+```text
+UatDemo123!
+```
+
+## Seeded Users
+
+| User Email | Role | What this user should see | Expected CRM data | Expected approval actions |
+| --- | --- | --- | --- | --- |
+| `mk.uat@alla.local` | Marketing | lead intake, assigned lead queue, follow-up workload, dashboard without final commercial authority | newly created and assigned leads including crane and dock door stories | assign leads to sales, monitor follow-up only |
+| `sales.crane.uat@alla.local` | Sales - Crane | own crane opportunities and quotations, pricing-visible commercial pipeline for crane work | crane project stories such as Siam Manufacturing / Toyota Gateway Plant | submit crane quotation for approval, track follow-up |
+| `sales.dockdoor.uat@alla.local` | Sales - Dock Door | own dock door opportunities and quotations, follow-up workload | dock door stories such as Eastern Logistics / WHA Warehouse | submit dock door quotation, maintain follow-up and revisions |
+| `mgr.sales.uat@alla.local` | Sales Manager + Department Manager | team-wide quotation queue, approval steps 1 and 2, broader sales pipeline | pending manager approval, manager-approved waiting CEO, revised quotations | approve, reject, return, and advance quotations |
+| `ceo.uat@alla.local` | CEO / Top Manager | executive dashboard, organization-wide quotations, final approval queue | manager-approved quotations waiting final decision, approved deal visibility | final approve or reject quotations |
+| `admin.uat@alla.local` | CRM Admin | full setup/admin visibility including master options, sequences, approvals, document templates | complete seeded organization data | verify configuration, inspect all data, no special workflow dependency |
+
+## Seeded Workflow Scenarios
+
+### Scenario A: Crane Project
+
+- Customer: `Siam Manufacturing Co., Ltd.`
+- End Customer: `Toyota Gateway Plant`
+- Project: `Overhead Crane Installation Phase 1`
+- Product Type: `Crane`
+- Owner flow: MK -> Sales Crane -> Sales Manager -> CEO
+- Expected status: manager-approved and waiting final CEO approval
+
+### Scenario B: Dock Door Project
+
+- Customer: `Eastern Logistics Co., Ltd.`
+- End Customer: `WHA Warehouse`
+- Project: `Loading Dock Expansion`
+- Product Type: `Dock Door`
+- Owner flow: MK -> Sales Dock Door
+- Expected status: draft/follow-up style commercial progress before final submission
+
+### Scenario C: Lost / No Quotation
+
+- Customer: `Demo Lost Customer`
+- Expected status: `No Quotation`
+- Expected reason: `Budget not approved`
+
+### Scenario D: Follow-up Due States
+
+- seeded at least one follow-up due today
+- seeded at least one overdue follow-up
+- seeded at least one upcoming follow-up
+
+## Approval Flow Expectation
+
+Seeded workflow: `Quotation Standard Approval`
+
+1. Sales submits quotation
+2. Sales Manager approves
+3. Department Manager approves
+4. CEO final approves
+
+For UAT simplicity, `mgr.sales.uat@alla.local` holds both manager stages so the queue is easy to validate visually.
+
+## Seed Commands
+
+```bash
+npm run seed:system
+npm run seed:uat
+npm run seed:reset -- --allow-db-reset
+```
+
+## Verification
+
+```bash
+npm run typecheck
+npm run build
+npm run seed:reset -- --allow-db-reset
+npm run verify:encoding
+npm run verify:crm-access
+npm run audit:pdf
+```