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