solution-erp/docs/changelog/sessions/2026-05-14-s23-turn1-plan-k-mig31-f2-refactor.md

# Session 23 turn 1 — 2026-05-14 — Plan K Mig 31 F2 refactor sang per-Approver-slot

**Dev:** Claude Opus 4.7 1M (4 sub-agents active + em main coordinator)
**Duration:** ~4h
**Base commit:** `eb106f2` (S22 chốt v2)
**Final HEAD:** `<latest>` (K8 docs)
**Total commits Plan K:** **8** (CHƯA push remote — chờ bro confirm K9 spawn CICD Monitor verify)

## 🎯 Trigger session

Bro nhận ra inconsistency S22+5:
- Mig 29 F1+F3 (5 flag) → per-Approver-slot ở Workflow Designer ✅
- Mig 30 F4 AllowApproverEditBudget → per-slot ở Designer ✅
- Mig 29 F2 AllowDrafterSkipToFinal → per-User flag ở **User Management page** (Plan D S22) ❌

Bro chốt 4 điểm refactor:
1. "Cấu hình cho phép edit → thực hiện trong trạng thái đang duyệt" (= F3+F4 OK pattern hiện tại)
2. "Cấu hình cho phép skip → duyệt thẳng cho phép trong trạng thái đang duyệt" (= F2 đổi semantic: Drafter from Nháp → Approver during ChoDuyet)
3. "Tất cả đều cấu hình ngay trong chỗ setup quy trình duyệt" (move F2 từ Users → Levels per-slot)
4. "Chỗ quy trình duyệt #NV 1 - Họ tên luôn" (slot label hiển thị ApproverFullName thay vì "NV 1")

→ Plan K refactor F2 storage + semantic + UI consistency.

## 🌳 Plan K 8 chunk execution

### Pre-flight (K0 + K0-bis)

- **K0 — 🟦 Investigator pre-flight audit F2 state** (~28K tokens spawn). Output: 12 file paths verified (Service + Entity + Config + DTO + FE × 2 app) + 5 surprises catch:
  - S1: fe-user KHÔNG có Designer + UsersPage (admin-only) → K3/K5 scope hẹp hơn estimate
  - S2: Prod 4/33 user flagged (drift S22+2 seed) → cần bro decision
  - S3: Slot label thực tế `NV #{ei + 1}` (per-entry index, KHÔNG phải `#NV {order}`)
  - S4: Audit comment string hardcoded line 149-150 cần rename
  - S5: F2 default false consistent với F1 mode 1-3 + F3 + F4

- **K0-bis — 👤 Chủ trì solo sqlcmd 5s** prod 4 user list: `fin.pp` + `pm.nv` (S22+2 seed) + `nv.test` (legacy UAT) + `truong.nguyen` (real user Solutions admin tick manual).

**Bro decisions chốt 2 AskUserQuestion:**
- F2 semantic: **Option B** Approver ChoDuyet skip cuối (đổi semantic, mirror F3+F4)
- Slot label: **Bỏ '#NV {order}' hẳn**, chỉ "Họ tên" user pin
- Prod 4 user: **Option A accept lose** (log audit trail, admin re-config qua Designer)
- Slot label chunk: **Pre-Mig 31 chunk riêng** (Chunk pre-A)

### Chunk pre-A — Slot label refactor (`56868bf`)

🟨 Implementer Case 2 (~5K tokens spawn). 1 file fe-admin Designer line 873:

```diff
- Quyền duyệt NV #{ei + 1}
+ Quyền duyệt {usersList.data?.find(u => u.id === entry.approverUserId)?.fullName ?? 'Chưa chọn NV'}
```

Lookup pattern reuse precedent line 535. Bundle size unchanged trivial.

### K1 — Mig 31 schema swap (`db66253`)

🟨 Implementer Case 2 (~22K tokens spawn). 6 BE files atomic:

- `User.cs` REMOVE `AllowDrafterSkipToFinal` prop (line 38)
- `ApprovalWorkflow.cs` ADD `AllowApproverSkipToFinal` prop trên `ApprovalWorkflowLevel` (sau AllowApproverEditBudget)
- `ApprovalWorkflowConfiguration.cs` ADD `HasDefaultValue(false)` (match 6 dòng existing)
- `PurchaseEvaluationWorkflowService.cs` surgical remove F2 Drafter SUBMIT skipToFinal block line 125-161 + K2 marker comment
- Mig 31 `RefactorSkipToFinalToApproverLevel` — 2 stage:
  - Stage 1: ADD Levels column FIRST
  - Stage 2: DROP Users column SECOND (manual reorder per memory `feedback_ef_migration_backfill_reorder`)
  - NO BACKFILL (Option A — 4 prod user accept lose)
- Apply Dev + Design DB

Implementer flagged 4 ambiguities:
1. UserConfiguration.cs KHÔNG exist (config inline trong ApplicationDbContext.OnModelCreating line 86) — no action
2. Application layer compile-break (UserFeatures.cs + PurchaseEvaluationFeatures.cs reference removed prop) → minimal sentinel-`false` patches + K2 marker
3. Test file line 253 still references removed prop → K7 fix
4. Service IF block scope precision — remove only `if (skipToFinal)` true-branch + flatten `else`

Test count 4039 insertions / 63 deletions (Designer + Snapshot dominate).

### K2 — BE Service Approver F2 branch + DTO refactor (`364aef6`)

👤 Chủ trì Solo (cross-stack reasoning + state machine integration). 4 files:

- `PurchaseEvaluationWorkflowService.cs`:
  - `ApproveV2Async` +`bool skipToFinal` 8th param
  - APPROVE STEP branch sau UPSERT opinion line 477:
    - if (!isAdmin && !isSystem && !matchingLevel.AllowApproverSkipToFinal) → ConflictException with helpful message
    - else → set Phase=DaDuyet + clear pointer + SLA + LogTransition "[Approver duyệt thẳng Cấp cuối — Bước X Cấp Y → DaDuyet]"
  - Caller TransitionAsync line ~144 pass skipToFinal vào ApproveV2Async
  - V1 ApproveV1LegacyAsync caller throw nếu skipToFinal=true non-admin
  - Drafter SUBMIT branch comment cleanup K1 marker → Mig 31 deprecation note
- `ApprovalWorkflowOptionsDto` +7th field `AllowApproverSkipToFinal`
- `PurchaseEvaluationDetailBundleDto` REMOVE `DrafterAllowSkipToFinal` field
- `IPurchaseEvaluationWorkflowService.cs` comment update Mig 28-31 semantic refactor
- `PurchaseEvaluationFeatures.cs` GetPe handler populate 7 Allow* + REMOVE sentinel `drafterAllowSkipToFinal`

Build PASS 0 err, test K1 transient FAIL expected → K7 fix.

### Reviewer K2 pre-K3 verify (PASS)

🟥 Reviewer K2 (~22K tokens spawn). 5-category checklist verdict:

| Category | Result | Issues |
|---|---|---|
| 1. Wire BE Approver F2 | ✅ PASS | 0 critical (branch placement đúng) |
| 2. Schema Mig 31 | ✅ PASS | 3-file rule + Up() ADD-DROP + sqlcmd verify 7 cols Levels + 0 Users.AllowDrafterSkipToFinal |
| 3. Security | ✅ PASS | admin bypass + V1 guard + clear error |
| 4. Code quality | ✅ PASS | 0 err build, anti-fiddle clean |
| 5. Tests | ✅ PASS (UAT defer K7) | — |

**2 Major + 2 Minor flagged:**
- Major #1 **Zombie endpoint** PATCH /users/{id}/allow-skip-final Admin tick = NoOp swallow silent → K5 cleanup priority
- Major #2 Stale narrative `ApprovalWorkflow.cs:78-80` F2 cũ → K5 + K8 polish
- Minor #3 `PurchaseEvaluationFeatures.cs:401` Command DTO comment → K5 polish
- Minor #4 `ApprovalWorkflowConfiguration.cs:22-24` Mig narrative → K5 polish

**New pattern caught Reviewer:** "Transient sentinel zombie" — K1 sentinel-`false` patch + chunk scope shift → endpoint NoOp silent. Mitigation: Reviewer pre-commit Smart Friend guard catch + recommend cleanup priority.

### K3 — FE Admin Designer 7th checkbox + banner rewrite (`dd52d16`)

🟨 Implementer Case 2 (~6K tokens spawn). 1 file fe-admin Designer:

- Type `LevelDto +allowApproverSkipToFinal` (7th)
- Type `EditLevelEntry +allowApproverSkipToFinal`
- Helper `makeDefaultLevelEntry` default false
- Helper `copyFromDefinition` propagate
- Inline checkbox panel mỗi Level entry: "Cho phép duyệt thẳng Cấp cuối khi đang duyệt" (cùng group amber-50/30 với 5 F1+F3 + 1 F4 → 7 checkbox grid-cols-2)
- Banner line ~623-631 rewrite: "F2 cấu hình ở User Management" (Plan D S22 stale) → "Cấu hình quyền duyệt riêng cho từng NV trong slot Approver bên dưới"
- POST/PATCH mutation body propagate 7th flag

Build PASS 0 TS err, bundle 1395.74 KB unchanged trivial.

### K5 — Zombie endpoint cleanup + Reviewer Major #1+#2 + Minor #3+#4 (`2ea8977`)

🟨 Implementer Case 2 (~12K tokens spawn). Full backout Plan D S22:

**BE drop (7 files):**
- `UsersController.cs` DELETE PATCH /allow-skip-final endpoint + Body record
- `UserFeatures.cs` DELETE SetUserAllowDrafterSkipToFinalCommand + Handler + UserDto.AllowDrafterSkipToFinal field + sentinel mapping references
- `ApprovalWorkflow.cs` rewrite stale narrative line 78-80 (Major #2)
- `PurchaseEvaluationFeatures.cs` rewrite Command DTO comment (Minor #3)
- `ApprovalWorkflowConfiguration.cs` APPEND Mig 31 narrative (Minor #4)
- `ApprovalWorkflowV2AdminFeatures.cs` clean stale DTO comment
- `IPurchaseEvaluationWorkflowService.cs` + `PurchaseEvaluationDtos.cs` clean storage references

**FE Admin drop (2 files):**
- `UsersPage.tsx` DELETE "Skip cuối" column + FastForward badge + button toggle + mutation hook
- `types/users.ts` DELETE allowDrafterSkipToFinal field

**Grep verify:** `AllowDrafterSkipToFinal` + `allow-skip-final` + `allowDrafterSkipToFinal` + `Skip cuối` + `FastForward` → 0 results src/Backend + fe-admin/src.

Build PASS BE + fe-admin. Implementer flagged 4 stale comments fe-user PeDetailTabs (cosmetic, K6 cleanup).

### K6 — Workspace × 2 app DROP Drafter + ADD Approver toggle (`ebe2469`)

👤 Chủ trì Solo (UX flow decision — Approver workflow trigger point). 6 files (3 fe-admin + 3 fe-user mirror):

**DROP Drafter Workspace checkbox:**
- `PeDetailTabs.tsx` × 2 app: REMOVE state skipToFinal + allowSkipToFinal + violet label "Gửi thẳng Cấp cuối (skip trung gian)" + mutation skipToFinal payload
- Simplify mutation signature: `opts: { skipToFinal: boolean }` → void
- Drop conditional button label + confirm dialog text

**ADD Approver Workspace toggle (Dialog approach — UX consistent với Trả lại Mode picker):**
- `PeWorkflowPanel.tsx` × 2 app: state `skipToFinalApprover` default false
- Visible khi Approve forward (NOT Cancel + NOT SendBack) + `currentLevelOptions?.allowApproverSkipToFinal === true`
- Checkbox violet panel + Amber warning "Hành động KHÔNG quay lại được"
- Mutation payload +`skipToFinal: !isReject && skipToFinalApprover`
- onSuccess reset state

**Type cleanup × 2 app:**
- `ApprovalWorkflowOptions` +`allowApproverSkipToFinal: boolean` (7th)
- `PeDetailBundle` REMOVE `drafterAllowSkipToFinal` field + Mig 29+30+31 cumulative comment

Build PASS × 2 app, bundle rotated.

### K7 — Tests regression (`6b1e2d9`)

🟨 Implementer Case 3 (~14K tokens spawn). 1 test file:

**Delete 3 deprecated Drafter F2 tests** (semantic deprecated Mig 31, no value).

**Add 3 Approver F2 service tests** pattern Implementer memory Pattern 11:
- `ApproveV2_SkipToFinal_AdminTickFlag_SetsPhaseDaDuyet` (happy path)
- `ApproveV2_SkipToFinal_FlagOff_NonAdmin_ThrowsConflictException` (denied)
- `ApproveV2_SkipToFinal_FlagOff_Admin_BypassesFlagCheck` (admin bypass)

Helper `SeedApproverF2WorkflowAsync` 2-Step variant (test multi-step verify skip → terminal NOT fallthrough).

Test count **104/104 PASS** baseline preserved (3 deleted + 3 added cancel out).

### K8 — Docs + commit + push (this commit)

- `docs/database/schema-diagram.md §14` update Mig 22-31 title + add Mig 30 + Mig 31 blocks + DROP Users column note
- `docs/STATUS.md` Last updated S23 t1 entry
- `docs/HANDOFF.md` TL;DR S23 t1 đầy đủ (top)
- Session log file này
- Memory `feedback_per_nv_permission_scope.md` reinforce 3× cumulative S23 t1
- MEMORY index update
- 2 stale FE Designer comments fe-admin (lines 73-75 + 502-504) rewrite Mig 29+30+31 cumulative
- 3 dirty agent MEMORY.md commit cùng (Investigator + Reviewer + CICD Monitor from S22 chốt + S23 t1)

## 📊 Stats S23 t1 chốt

| Metric | Trước (S22 chốt) | Sau (S23 t1) | Δ |
|---|---|---|---|
| DB tables | 59 | 59 | 0 |
| **Migrations** | 30 | **31** | **+1** (Mig 31 refactor F2) |
| Endpoints | ~146 | **~145** | **-1** (backout /allow-skip-final) |
| FE pages | 34 | 34 | 0 |
| **Unit tests** | 104 | **104** | 0 (3 deleted + 3 added cancel) |
| Gotchas | 47 | 47 | 0 |
| Memory entries | 19 | **20** | +1 reinforcement S23 t1 (cumulative entry update) |
| Skills | 6 | 6 | 0 |
| Sub-agents | 4 (seeds-only S22 cumulative) | 4 (1 Inv + 4 Imp + 1 Rev spawn) | Plan K active execution |
| Active prod users | 33 | 33 | 0 (4 user lose flag, KHÔNG remove user) |
| **Commits Plan K** | — | **8** (`56868bf..<latest>`) | pre-A + K1-K3 + K5-K8 |

## 🎯 Multi-agent ROI evidence Plan K

| Spawn | Agent | Cost (tokens) | Output | Catch |
|---|---|---|---|---|
| K0 | 🟦 Investigator | ~28K | 12 file paths + 5 surprises (S1-S5) + LOC estimate | S1 fe-user no Designer → scope giảm + S2 4 prod user drift + S3 slot label real format |
| K0-bis | 👤 Chủ trì | <1K | 4 user list (fin.pp+pm.nv+nv.test+truong.nguyen) | — |
| Chunk pre-A | 🟨 Implementer Case 2 | ~5K | 1 commit slot label rename | — |
| K1 | 🟨 Implementer Case 2 | ~22K | 1 commit Mig 31 schema swap 6 files | 3 ambiguities (UserConfig inline + compile-break workaround + test file fix K7 + IF block precision) |
| K2 | 👤 Chủ trì | ~self | 1 commit Service + DTO refactor | — |
| Reviewer K2 | 🟥 Reviewer | ~22K | PASS 0 critical + 2 Major + 2 Minor | Major #1 zombie endpoint + Major #2 stale narrative + new pattern "transient sentinel zombie" |
| K3 | 🟨 Implementer Case 2 | ~6K | 1 commit Designer 7th checkbox + banner | — |
| K5 | 🟨 Implementer Case 2 | ~12K | 1 commit zombie cleanup BE 7 + FE 2 | — |
| K6 | 👤 Chủ trì | ~self | 1 commit Workspace × 2 app refactor | — |
| K7 | 🟨 Implementer Case 3 | ~14K | 1 commit tests regression 104/104 PASS | — |
| K8 | 👤 Chủ trì | ~self | 1 commit docs + memory + push | — |
| K9 (pending) | 🟩 CICD Monitor | ~150K | post-deploy verify Mig 31 prod + bundle hash | — |

**Total Plan K spawn cost (excl K9):** ~109K tokens — under 200K budget per session.

**Multi-agent value caught:**
1. **Investigator K0 S2 4 prod user drift** — em main solo dễ bỏ qua, audit qua sqlcmd K0-bis catch real user `truong.nguyen` admin tick manual S22+ (cần follow-up post-deploy)
2. **Reviewer K2 Major #1 zombie endpoint** — em main solo K2 đã pass build clean nhưng KHÔNG nhớ cleanup Plan D S22 wire → Reviewer catch + K5 priority cleanup → giữ UX clean cho admin
3. **Reviewer K2 new pattern "transient sentinel zombie"** — pattern reusable cross-project saved Reviewer memory

## ⚠️ Pending S23 t2+

- **K9 CICD Monitor post-deploy verify** — chờ bro confirm spawn sau push remote
- **Plan B Contract V2 wire Mig 32+33** — chưa kick off (PE V2 + per-NV + F2 refactor đã proven 3×, ready mirror sang Contract entity per HANDOFF S22 pre-allocation)
- **Plan C carry test-after bundle** — defer UAT 2-3 lần ổn (Service ApplyReturnMode test catch-up Mig 29 + Mig 30 F4 service test)
- **Admin re-config `truong.nguyen` qua Designer** — real user lose flag, cần bro UAT note hoặc ping user

## 📋 Pattern reinforced

- **Per-NV admin opt-in flag pattern 3× cumulative** — Mig 29 F1+F3 (5 flag) + Mig 30 F4 (1 flag) + Mig 31 F2 (1 flag refactor). Pattern ALSO applies cho refactor existing scope, KHÔNG chỉ greenfield. Memory `feedback_per_nv_permission_scope.md` reinforced 3×.
- **EF Migration ADD→DROP no-BACKFILL pattern** cho semantic refactor (Mig 29 cumulative 3× với Mig 31). Decision lose vs preserve based on semantic similarity old vs new.
- **Multi-agent atomic per-chunk discipline** — Implementer Case 2 cookie-cutter 4 spawns, Reviewer pre-commit catch zombie, Chủ trì cross-stack reasoning. ROI evidence Week 2 trial.
- **UAT mode Phase 9 test-after** — bro confirm K7 OK sau 7 chunk UAT iteration (Implementer K1+K2+K3+K5 + Chủ trì K2+K6 build verify mỗi chunk, test verify K7 cuối).