773 lines
14 KiB
Markdown
773 lines
14 KiB
Markdown
# Task Foundation Cleanup: Admin Display Names, MS Option CRUD, Seed & Database Script Standardization
|
|
|
|
## Status
|
|
|
|
Planned
|
|
|
|
## Objective
|
|
|
|
Clean up foundational admin experience and system bootstrap workflow before continuing feature development.
|
|
|
|
This task focuses on:
|
|
|
|
* displaying human-readable names instead of raw IDs
|
|
* adding CRUD management for `ms_options`
|
|
* consolidating seed scripts
|
|
* creating a clear system bootstrap script
|
|
* creating a reset database script for development
|
|
* auditing old seed/verify/audit scripts
|
|
* documenting what system admin must run when starting from a fresh database
|
|
|
|
---
|
|
|
|
## Problem
|
|
|
|
Current system still exposes raw IDs in some UI/API responses, such as:
|
|
|
|
```txt
|
|
createdBy
|
|
updatedBy
|
|
assignedBy
|
|
branchId
|
|
salesmanId
|
|
assignedToUserId
|
|
closedByUserId
|
|
generatedBy
|
|
uploadedBy
|
|
approvedBy
|
|
```
|
|
|
|
This makes admin screens, CRM pages, approval history, audit views, and document settings difficult to read.
|
|
|
|
Current seed/setup scripts are also fragmented:
|
|
|
|
```json
|
|
"seed:super-admin"
|
|
"seed:foundation"
|
|
"seed:crm-uat"
|
|
"seed:pdf-template-version"
|
|
"migrate:membership-business-roles"
|
|
"seed:task-h1-fixture"
|
|
"verify:task-h1"
|
|
"verify:task-h3"
|
|
"verify:crm-access"
|
|
"audit:pdf:*"
|
|
"setup:db"
|
|
```
|
|
|
|
There is no clear single command for:
|
|
|
|
```txt
|
|
Fresh system bootstrap
|
|
Development reset
|
|
UAT seed
|
|
PDF template reseed
|
|
Verification
|
|
Audit
|
|
```
|
|
|
|
---
|
|
|
|
# Scope 1: Human-Readable Display Names
|
|
|
|
## Objective
|
|
|
|
Replace raw ID display with readable names across active UI and API DTOs.
|
|
|
|
## Required Display Mapping
|
|
|
|
### User-related fields
|
|
|
|
Fields that should expose display names:
|
|
|
|
```txt
|
|
createdBy
|
|
updatedBy
|
|
assignedBy
|
|
assignedToUserId
|
|
assignedSalesOwnerId
|
|
salesmanId
|
|
closedByUserId
|
|
approvedBy
|
|
requestedBy
|
|
actedBy
|
|
generatedBy
|
|
uploadedBy
|
|
voidedBy
|
|
lockedBy
|
|
```
|
|
|
|
Add readable fields where applicable:
|
|
|
|
```ts
|
|
createdByName
|
|
updatedByName
|
|
assignedByName
|
|
assignedToUserName
|
|
assignedSalesOwnerName
|
|
salesmanName
|
|
closedByName
|
|
approvedByName
|
|
requestedByName
|
|
actedByName
|
|
generatedByName
|
|
uploadedByName
|
|
```
|
|
|
|
Rules:
|
|
|
|
* Keep raw IDs for system integrity.
|
|
* Add display fields for UI.
|
|
* Do not remove ID fields from API unless all consumers are migrated.
|
|
* Use fallback:
|
|
|
|
* user name
|
|
* email
|
|
* ID as last resort
|
|
|
|
---
|
|
|
|
### Branch-related fields
|
|
|
|
Fields that should expose readable branch data:
|
|
|
|
```txt
|
|
branchId
|
|
```
|
|
|
|
Add:
|
|
|
|
```ts
|
|
branchName
|
|
branchCode
|
|
```
|
|
|
|
If branch master is not a dedicated table and comes from `ms_options`, resolve from master option category.
|
|
|
|
---
|
|
|
|
### Option-related fields
|
|
|
|
Fields that should expose labels:
|
|
|
|
```txt
|
|
productType
|
|
status
|
|
priority
|
|
stage
|
|
outcomeStatus
|
|
lostReason
|
|
cancelReason
|
|
noQuotationReason
|
|
customerType
|
|
customerStatus
|
|
leadChannel
|
|
quotationType
|
|
discountType
|
|
currency
|
|
unit
|
|
taxRate
|
|
```
|
|
|
|
Add display labels:
|
|
|
|
```ts
|
|
productTypeLabel
|
|
statusLabel
|
|
priorityLabel
|
|
stageLabel
|
|
outcomeStatusLabel
|
|
lostReasonLabel
|
|
```
|
|
|
|
Rules:
|
|
|
|
* Use `ms_options` as source of display labels.
|
|
* Do not hardcode labels in UI.
|
|
* Support fallback to raw code if option label is missing.
|
|
|
|
---
|
|
|
|
## Target Areas
|
|
|
|
Review and update active UI/API areas:
|
|
|
|
```txt
|
|
src/features/crm/leads/**
|
|
src/features/crm/opportunities/**
|
|
src/features/crm/quotations/**
|
|
src/features/crm/customers/**
|
|
src/features/crm/approval/**
|
|
src/features/foundation/approval/**
|
|
src/features/foundation/notifications/**
|
|
src/features/crm/dashboard/**
|
|
src/features/crm/document-templates/**
|
|
```
|
|
|
|
High-priority pages:
|
|
|
|
```txt
|
|
Lead list/detail
|
|
Opportunity list/detail
|
|
Quotation list/detail
|
|
Approval history
|
|
Approval settings
|
|
Notification inbox
|
|
Template settings
|
|
Dashboard widgets
|
|
Audit-safe activity views
|
|
```
|
|
|
|
---
|
|
|
|
# Scope 2: Create Shared Display Resolver
|
|
|
|
## Objective
|
|
|
|
Avoid repeating joins and label mapping everywhere.
|
|
|
|
Create shared foundation utilities:
|
|
|
|
```txt
|
|
src/features/foundation/display/server/user-display-resolver.ts
|
|
src/features/foundation/display/server/option-display-resolver.ts
|
|
src/features/foundation/display/server/branch-display-resolver.ts
|
|
src/features/foundation/display/server/display-resolver.ts
|
|
```
|
|
|
|
Recommended APIs:
|
|
|
|
```ts
|
|
resolveUserDisplays(ctx, userIds: string[])
|
|
resolveOptionLabels(ctx, category: string, codes: string[])
|
|
resolveBranchDisplays(ctx, branchIds: string[])
|
|
```
|
|
|
|
Rules:
|
|
|
|
* batch load to avoid N+1 queries
|
|
* organization scoped
|
|
* safe fallback
|
|
* reusable by CRM services
|
|
* not tied to one feature
|
|
|
|
---
|
|
|
|
# Scope 3: MS Option CRUD
|
|
|
|
## Objective
|
|
|
|
Add admin management for `ms_options`.
|
|
|
|
## Required APIs
|
|
|
|
Create:
|
|
|
|
```txt
|
|
GET /api/foundation/ms-options
|
|
POST /api/foundation/ms-options
|
|
GET /api/foundation/ms-options/[id]
|
|
PATCH /api/foundation/ms-options/[id]
|
|
DELETE /api/foundation/ms-options/[id]
|
|
```
|
|
|
|
Optional category-specific API:
|
|
|
|
```txt
|
|
GET /api/foundation/ms-options/categories
|
|
GET /api/foundation/ms-options?category=crm_opportunity_stage
|
|
```
|
|
|
|
## Required UI
|
|
|
|
Create settings page:
|
|
|
|
```txt
|
|
/dashboard/settings/master-options
|
|
```
|
|
|
|
or if CRM-scoped:
|
|
|
|
```txt
|
|
/dashboard/crm/settings/master-options
|
|
```
|
|
|
|
Recommended UI:
|
|
|
|
* category filter
|
|
* option table
|
|
* create option sheet
|
|
* edit option sheet
|
|
* soft delete / deactivate
|
|
* active toggle
|
|
* sort order
|
|
* metadata JSON viewer/editor if needed
|
|
|
|
Fields:
|
|
|
|
```txt
|
|
category
|
|
code
|
|
label
|
|
value
|
|
parentId
|
|
sortOrder
|
|
isActive
|
|
metadata
|
|
```
|
|
|
|
Rules:
|
|
|
|
* `category + code + organizationId` must remain unique
|
|
* cannot hard delete; use soft delete
|
|
* inactive options should not appear in normal dropdowns
|
|
* admin can view inactive options
|
|
* no duplicate code in same category
|
|
* code should be normalized to snake_case or documented format
|
|
|
|
---
|
|
|
|
# Scope 4: Seed Script Consolidation
|
|
|
|
## Objective
|
|
|
|
Create a clear, predictable seed hierarchy.
|
|
|
|
## Recommended Seed Layers
|
|
|
|
### 1. System seed
|
|
|
|
Required for system to boot:
|
|
|
|
```txt
|
|
organization
|
|
super admin
|
|
admin membership
|
|
base roles/permissions
|
|
foundation master options
|
|
document sequences
|
|
approval default workflow
|
|
approval matrix default
|
|
notification templates
|
|
quotation PDF template metadata
|
|
```
|
|
|
|
Command:
|
|
|
|
```json
|
|
"seed:system": "node --experimental-strip-types src/db/seeds/system.seed.ts"
|
|
```
|
|
|
|
---
|
|
|
|
### 2. UAT seed
|
|
|
|
Demo/testing data only:
|
|
|
|
```txt
|
|
sample customers
|
|
sample contacts
|
|
sample leads
|
|
sample opportunities
|
|
sample quotations
|
|
sample approvals
|
|
sample notifications
|
|
```
|
|
|
|
Command:
|
|
|
|
```json
|
|
"seed:uat": "node --experimental-strip-types src/db/seeds/uat.seed.ts"
|
|
```
|
|
|
|
---
|
|
|
|
### 3. PDF template seed
|
|
|
|
Template-only reseed:
|
|
|
|
```json
|
|
"seed:pdf-template": "node --experimental-strip-types scripts/reseed-pdf-template-version.ts"
|
|
```
|
|
|
|
---
|
|
|
|
### 4. Verification scripts
|
|
|
|
Keep as verification, not seed:
|
|
|
|
```json
|
|
"verify:encoding"
|
|
"verify:crm-access"
|
|
"verify:pdf"
|
|
```
|
|
|
|
---
|
|
|
|
## New Standard Commands
|
|
|
|
Recommended `package.json` script structure:
|
|
|
|
```json
|
|
{
|
|
"db:migrate": "drizzle-kit migrate",
|
|
"db:generate": "drizzle-kit generate",
|
|
"db:studio": "drizzle-kit studio",
|
|
|
|
"db:reset": "node --experimental-strip-types scripts/db/reset-database.ts",
|
|
"db:setup": "npm run db:migrate && npm run seed:system",
|
|
"db:setup:uat": "npm run db:setup && npm run seed:uat",
|
|
"db:fresh": "npm run db:reset && npm run db:migrate && npm run seed:system",
|
|
"db:fresh:uat": "npm run db:reset && npm run db:migrate && npm run seed:system && npm run seed:uat",
|
|
|
|
"seed:system": "node --experimental-strip-types src/db/seeds/system.seed.ts",
|
|
"seed:uat": "node --experimental-strip-types src/db/seeds/uat.seed.ts",
|
|
"seed:pdf-template": "node --experimental-strip-types scripts/reseed-pdf-template-version.ts",
|
|
|
|
"verify:encoding": "node scripts/verify-encoding.mjs",
|
|
"verify:crm-access": "node --experimental-strip-types scripts/security/verify-crm-access.ts",
|
|
"verify:pdf": "npm run audit:pdf",
|
|
|
|
"audit:pdf": "npm run audit:pdf:inventory && npm run audit:pdf:coverage && npm run audit:pdf:runtime && npm run audit:pdf:versions && npm run audit:pdf:placeholders && npm run audit:pdf:parity && npm run audit:pdf:snapshot && npm run audit:pdf:report && npm run audit:pdf:integrity"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# Scope 5: Reset Database Script
|
|
|
|
## Objective
|
|
|
|
Create a controlled development reset script.
|
|
|
|
Create:
|
|
|
|
```txt
|
|
scripts/db/reset-database.ts
|
|
```
|
|
|
|
Behavior:
|
|
|
|
* connect to configured database
|
|
* confirm environment is not production
|
|
* drop public schema
|
|
* recreate public schema
|
|
* drop drizzle schema if present
|
|
* exit cleanly
|
|
|
|
Required safety guard:
|
|
|
|
```txt
|
|
NODE_ENV must not be production
|
|
DATABASE_URL must not include production host/name
|
|
ALLOW_DB_RESET=true required
|
|
```
|
|
|
|
Example command:
|
|
|
|
```bash
|
|
ALLOW_DB_RESET=true npm run db:reset
|
|
```
|
|
|
|
Recommended SQL:
|
|
|
|
```sql
|
|
DROP SCHEMA IF EXISTS public CASCADE;
|
|
CREATE SCHEMA public;
|
|
|
|
DROP SCHEMA IF EXISTS drizzle CASCADE;
|
|
```
|
|
|
|
Rules:
|
|
|
|
* never run reset without explicit env flag
|
|
* log target database before reset
|
|
* fail fast if DATABASE_URL missing
|
|
|
|
---
|
|
|
|
# Scope 6: Existing Script Audit
|
|
|
|
## Objective
|
|
|
|
Classify existing scripts into keep, rename, merge, or remove.
|
|
|
|
Current scripts to audit:
|
|
|
|
```json
|
|
"seed:super-admin": "node scripts/seed-super-admin.js",
|
|
"seed:foundation": "node --experimental-strip-types src/db/seeds/foundation.seed.ts",
|
|
"seed:crm-uat": "node --experimental-strip-types src/db/seeds/crm-uat.seed.ts",
|
|
"seed:pdf-template-version": "node --experimental-strip-types scripts/reseed-pdf-template-version.ts",
|
|
"migrate:membership-business-roles": "node --experimental-strip-types scripts/migrate-membership-business-roles.ts",
|
|
"seed:task-h1-fixture": "node scripts/seed-task-h1-fixture.js",
|
|
"verify:task-h1": "node scripts/verify-task-h1.js",
|
|
"verify:task-h3": "node --experimental-strip-types scripts/verify-task-h3.js",
|
|
"verify:crm-access": "node --experimental-strip-types scripts/security/verify-crm-access.ts",
|
|
"audit:pdf:inventory": "node --experimental-strip-types scripts/audit-pdf-template-inventory.ts",
|
|
"audit:pdf:coverage": "node --experimental-strip-types scripts/audit-pdf-mapping-coverage.ts",
|
|
"audit:pdf:runtime": "node --experimental-strip-types scripts/audit-pdf-runtime-payload.ts",
|
|
"audit:pdf:report": "node --experimental-strip-types scripts/generate-pdf-audit-report.ts",
|
|
"verify:encoding": "node scripts/verify-encoding.mjs",
|
|
"audit:pdf:versions": "node --experimental-strip-types scripts/audit-template-version-integrity.ts",
|
|
"audit:pdf:placeholders": "node --experimental-strip-types scripts/audit-placeholder-integrity.ts",
|
|
"audit:pdf:parity": "node --experimental-strip-types scripts/audit-payload-parity.ts",
|
|
"audit:pdf:snapshot": "node --experimental-strip-types scripts/audit-approved-snapshot-parity.ts",
|
|
"audit:pdf:integrity": "node --experimental-strip-types scripts/generate-pdf-integrity-report.ts",
|
|
"audit:pdf": "npm run audit:pdf:inventory && npm run audit:pdf:coverage && npm run audit:pdf:runtime && npm run audit:pdf:versions && npm run audit:pdf:placeholders && npm run audit:pdf:parity && npm run audit:pdf:snapshot && npm run audit:pdf:report && npm run audit:pdf:integrity",
|
|
"setup:db": "npm run migrate && npm run seed:super-admin && npm run seed:foundation"
|
|
```
|
|
|
|
## Recommended Classification
|
|
|
|
### Rename / merge
|
|
|
|
```txt
|
|
seed:super-admin
|
|
seed:foundation
|
|
```
|
|
|
|
Merge into:
|
|
|
|
```txt
|
|
seed:system
|
|
```
|
|
|
|
---
|
|
|
|
### Rename
|
|
|
|
```txt
|
|
seed:crm-uat
|
|
```
|
|
|
|
to:
|
|
|
|
```txt
|
|
seed:uat
|
|
```
|
|
|
|
---
|
|
|
|
### Rename
|
|
|
|
```txt
|
|
seed:pdf-template-version
|
|
```
|
|
|
|
to:
|
|
|
|
```txt
|
|
seed:pdf-template
|
|
```
|
|
|
|
---
|
|
|
|
### Keep but mark legacy/dev fixture
|
|
|
|
```txt
|
|
seed:task-h1-fixture
|
|
verify:task-h1
|
|
verify:task-h3
|
|
```
|
|
|
|
Move under:
|
|
|
|
```txt
|
|
scripts/legacy/task-fixtures/
|
|
```
|
|
|
|
or rename:
|
|
|
|
```txt
|
|
legacy:seed:task-h1-fixture
|
|
legacy:verify:task-h1
|
|
legacy:verify:task-h3
|
|
```
|
|
|
|
If no longer used, remove after confirming no docs/CI references them.
|
|
|
|
---
|
|
|
|
### Review migration script
|
|
|
|
```txt
|
|
migrate:membership-business-roles
|
|
```
|
|
|
|
If this was one-time historical migration, move to:
|
|
|
|
```txt
|
|
scripts/legacy/migrations/
|
|
```
|
|
|
|
and remove from common package scripts.
|
|
|
|
If still needed after reset, fold into migration or seed.
|
|
|
|
---
|
|
|
|
### Keep
|
|
|
|
```txt
|
|
verify:crm-access
|
|
verify:encoding
|
|
audit:pdf:*
|
|
audit:pdf
|
|
```
|
|
|
|
These are still useful.
|
|
|
|
---
|
|
|
|
### Replace
|
|
|
|
```txt
|
|
setup:db
|
|
```
|
|
|
|
with:
|
|
|
|
```txt
|
|
db:setup
|
|
db:setup:uat
|
|
db:fresh
|
|
db:fresh:uat
|
|
```
|
|
|
|
---
|
|
|
|
# Scope 7: Bootstrap Documentation
|
|
|
|
Create:
|
|
|
|
```txt
|
|
docs/operations/system-bootstrap.md
|
|
```
|
|
|
|
Must explain:
|
|
|
|
## Fresh local development
|
|
|
|
```bash
|
|
npm install
|
|
npm run db:fresh
|
|
npm exec tsc --noEmit
|
|
npm run dev
|
|
```
|
|
|
|
## Fresh UAT/demo data
|
|
|
|
```bash
|
|
npm run db:fresh:uat
|
|
```
|
|
|
|
## Existing database upgrade
|
|
|
|
```bash
|
|
npm run db:migrate
|
|
npm run seed:system
|
|
```
|
|
|
|
## PDF template reseed only
|
|
|
|
```bash
|
|
npm run seed:pdf-template
|
|
```
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
npm exec tsc --noEmit
|
|
npm run build
|
|
npm run verify:encoding
|
|
npm run verify:crm-access
|
|
npm run audit:pdf
|
|
```
|
|
|
|
## Script guide
|
|
|
|
Explain:
|
|
|
|
```txt
|
|
db:* = database lifecycle
|
|
seed:* = data bootstrap
|
|
verify:* = validation
|
|
audit:* = diagnostics
|
|
legacy:* = old task-specific tools
|
|
```
|
|
|
|
---
|
|
|
|
# Scope 8: Acceptance Criteria
|
|
|
|
## Display names
|
|
|
|
* Created by / Updated by / Assigned by display as readable names
|
|
* Branch displays as branch name/code
|
|
* Option fields display labels
|
|
* Raw IDs are not shown in normal user-facing UI unless intentionally technical
|
|
|
|
## MS option CRUD
|
|
|
|
* Admin can list options
|
|
* Admin can create option
|
|
* Admin can update option
|
|
* Admin can deactivate / soft delete option
|
|
* Dropdowns continue to use active options
|
|
* Duplicate category/code is blocked
|
|
|
|
## Seed and setup
|
|
|
|
* `seed:system` exists
|
|
* `seed:uat` exists
|
|
* `db:reset` exists with safety guard
|
|
* `db:fresh` works
|
|
* `db:fresh:uat` works
|
|
* old scripts are classified or removed
|
|
* system bootstrap docs exist
|
|
|
|
## Verification
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm exec tsc --noEmit
|
|
npm run build
|
|
npm run verify:encoding
|
|
```
|
|
|
|
Optional:
|
|
|
|
```bash
|
|
npm run db:fresh
|
|
npm run db:fresh:uat
|
|
npm run verify:crm-access
|
|
npm run audit:pdf
|
|
```
|
|
|
|
---
|
|
|
|
# Definition of Done
|
|
|
|
Task is complete when:
|
|
|
|
* active UI no longer exposes raw user/branch/option IDs where display names are expected
|
|
* `ms_options` has CRUD API and settings UI
|
|
* system seed is consolidated
|
|
* UAT seed is separated
|
|
* database reset script exists and is guarded
|
|
* package scripts are organized and understandable
|
|
* old scripts are documented, renamed, moved, or removed
|
|
* bootstrap documentation is available
|
|
|
|
Result:
|
|
|
|
```txt
|
|
Foundation Admin UX = Improved
|
|
Master Option Management = Operational
|
|
System Bootstrap = Standardized
|
|
Database Reset = Safe and Repeatable
|
|
Script Surface = Clean and Understandable
|
|
```
|