task-fix-display2

plans/task-fix-display2.md

@@ -0,0 +1,228 @@
+# Task Fix: Document Sequence Branch Display Name
+
+## Objective
+
+Fix `/dashboard/crm/settings/document-sequences` so Branch displays as a readable name/code instead of raw UUID.
+
+Current issue:
+
+```txt
+1b960bfc-91de-4b69-a389-f060ef21bed2
+```
+
+should display as:
+
+```txt
+Branch Name
+```
+
+or:
+
+```txt
+Branch Code - Branch Name
+```
+
+---
+
+## Problem
+
+Document Sequence records store:
+
+```txt
+branchId
+```
+
+but the settings UI currently displays the raw ID directly.
+
+This breaks admin usability and is inconsistent with the display-name cleanup direction.
+
+---
+
+## Mandatory Review
+
+Review:
+
+```txt
+src/features/foundation/document-sequence/**
+src/app/dashboard/crm/settings/document-sequences/**
+src/db/schema.ts
+src/features/foundation/display/**
+src/features/foundation/master-options/**
+```
+
+Search:
+
+```bash
+rg "branchId|branch_id|document-sequences|DocumentSequence" src/features/foundation src/app/dashboard/crm/settings/document-sequences
+```
+
+---
+
+## Scope 1: API / DTO Display Fields
+
+Update document sequence read model to include:
+
+```ts
+branchId?: string | null;
+branchCode?: string | null;
+branchName?: string | null;
+branchDisplayName?: string | null;
+```
+
+Display rule:
+
+```txt
+branchId = null
+→ All Branches
+
+branchCode + branchName
+→ {branchCode} - {branchName}
+
+branchName only
+→ {branchName}
+
+unknown branch
+→ Unknown Branch ({branchId})
+```
+
+Do not remove `branchId`; keep it for update/generate logic.
+
+---
+
+## Scope 2: Resolve Branch Display Server-Side
+
+In document sequence service/list API, resolve branch display before returning response.
+
+Preferred:
+
+```txt
+Use shared branch display resolver if already created.
+```
+
+Fallback:
+
+* If branch is table-backed, join branch table.
+* If branch is `ms_options`, resolve from the branch option category.
+* If unknown, return fallback display string.
+
+Avoid N+1 queries.
+
+Batch resolve all branch IDs in the list.
+
+---
+
+## Scope 3: UI Rendering Fix
+
+Update document sequence table/cards.
+
+Replace:
+
+```tsx
+{row.branchId}
+```
+
+with:
+
+```tsx
+{row.branchDisplayName ?? 'All Branches'}
+```
+
+or:
+
+```tsx
+<BranchDisplay value={row.branchDisplayName} />
+```
+
+Rules:
+
+* never show raw UUID in normal UI
+* raw ID may be visible only in debug/dev details if explicitly labelled
+* use muted text for fallback unknown branch
+
+---
+
+## Scope 4: Form Select Display
+
+If create/edit form has branch select:
+
+* show readable branch names in dropdown
+* value remains `branchId`
+* include option:
+
+```txt
+All Branches
+```
+
+for nullable branch
+
+Dropdown labels:
+
+```txt
+ALL - All Branches
+BKK - Bangkok
+RYG - Rayong
+```
+
+---
+
+## Scope 5: Seed Check
+
+Verify seed creates branch data that can be resolved.
+
+Check whether branch source is:
+
+```txt
+branch table
+```
+
+or:
+
+```txt
+ms_options category
+```
+
+If document sequence references a branch ID that seed does not create, fix seed.
+
+---
+
+## Scope 6: Verification
+
+Run:
+
+```bash
+npm exec tsc --noEmit
+npm run build
+```
+
+Manual verification:
+
+```txt
+Open /dashboard/crm/settings/document-sequences
+No raw UUID is shown for branch
+All Branches displays correctly for null branchId
+Known branch displays readable name/code
+Unknown branch fallback is readable
+Create/edit branch dropdown shows names, not IDs
+Saving still persists branchId correctly
+Document number generation still works
+```
+
+---
+
+## Definition of Done
+
+Task is complete when:
+
+* Document Sequence list does not show raw branch UUID
+* API returns branch display fields
+* UI uses branch display fields
+* branch select uses readable labels
+* document sequence generation behavior remains unchanged
+
+Result:
+
+```txt
+Document Sequence Branch Display = Fixed
+Admin UX = Improved
+Raw Branch UUID Leakage = Removed
+```