229 lines
3.6 KiB
Markdown
229 lines
3.6 KiB
Markdown
# 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
|
|
```
|