[CLAUDE] Api Docs: Chunk P1+P3 — HOTFIX Controller TransitionPeBody record missing 3 fields (ROOT CAUSE F1+F2 fail)

CICD Monitor Run #202 Plan O verify catch CRITICAL caveat:

PurchaseEvaluationsController.cs:267 `TransitionPeBody` record CHỈ có
3 fields (TargetPhase, Decision, Comment) — MISSING 3 fields có trong
Command record `TransitionPurchaseEvaluationCommand`:
- ReturnMode (F1 mode Trả lại)
- ReturnTargetUserId (F1 Assignee target)
- SkipToFinal (F2 duyệt thẳng Cấp cuối)

Mediator.Send line 70 cũng drop 3 field. → FE × 2 app SEND ĐÚNG 7 fields
qua `api.post(/transitions)` body (Investigator audit confirm wire OK) →
ASP.NET Core deserialization silently DROP 3 fields ở Controller layer →
Handler nhận ReturnMode=null + SkipToFinal=false → fallback default Drafter
mode + F2 không trigger.

Bug present 2 NGÀY PROD từ Mig 28 deploy 2026-05-13 — gây TẤT CẢ F1+F2
wire fail từ FE side. Plan N (S23 t4) + Plan O (S23 t5) fix 5 lookup sites
discrimination NHƯNG controller body record bug block flow TRƯỚC KHI đến
lookup site. Em main + Reviewer + Implementer + Investigator all MISS bug
này xuyên 4 plan vì:
1. Mig 28 Command extend 3 fields (S21 t4) nhưng Controller body NOT extended
2. Plan K K2 add `skipToFinal` 8th param Service nhưng Controller NOT extended
3. Bug silent — no error, no compile fail, no test fail, FE call OK,
   BE return 204 nhưng handler nhận default args → wrong behavior

Plan P fix BE-only ~10 LOC 1 file `PurchaseEvaluationsController.cs`:

1. Add `using SolutionErp.Application.PurchaseEvaluations.Services` cho
   WorkflowReturnMode enum import (line ~7)

2. Extend `TransitionPeBody` record line 267 thêm 3 fields default:
   ```csharp
   public record TransitionPeBody(
       PurchaseEvaluationPhase TargetPhase,
       ApprovalDecision Decision,
       string? Comment,
       WorkflowReturnMode? ReturnMode = null,
       Guid? ReturnTargetUserId = null,
       bool SkipToFinal = false);
   ```

3. Update `mediator.Send` line 70 pass 7 fields:
   ```csharp
   await mediator.Send(new TransitionPurchaseEvaluationCommand(
       id, body.TargetPhase, body.Decision, body.Comment,
       body.ReturnMode, body.ReturnTargetUserId, body.SkipToFinal), ct);
   ```

Investigator (FE wire audit) verify:
- fe-user/src/components/pe/PeWorkflowPanel.tsx:113-124 + fe-admin mirror —
  api.post send ĐẦY ĐỦ 7 fields qua body
- KHÔNG cần fix FE
- Mig 28/31 Domain test đã cover handler logic — không cần test mới

Verify:
- dotnet build SolutionErp.slnx clean (0 err, 2 warn pre-existing DocxRenderer)
- dotnet test SolutionErp.slnx **111/111 PASS** unchanged (no regression)

Docs update:
- docs/STATUS.md Last updated S23 t6
- docs/HANDOFF.md TL;DR S23 t6 ngắn gọn
- .claude/agent-memory/cicd-monitor/MEMORY.md drift (Run #202 entry pre-existing)

Pattern reinforced cross-project:
- Controller body record MUST mirror Command record fields khi Command thêm
  optional params. Silent drop bug class — không test/build catch được.
- Investigator pre-flight audit FE wire trước khi fix BE (Plan P scope
  verify) tránh em main fix sai assumption.

Pending: CICD Monitor verify Plan P deploy + UAT test bro real.
Pending Bug 2 F2 đến Phan Văn Chương: verify workflow v14 DB structure
sau khi Plan P unblock F2 flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/HANDOFF.md

@@ -1,6 +1,8 @@
 # HANDOFF — Brief 5 phút cho session tiếp theo
 
-**Last updated:** 2026-05-15 (Session 23 turn 5 — **🎯 Plan O HOTFIX: 4 lookup sites cùng pattern per-NV cascade — Plan N chỉ catch 1/5 sites**. Bro UAT sau Plan N: Actor NV Test trong OR-of-N click "Trả lại Người chỉ định" → "Không phải lượt bạn" mặc dù đúng slot. Em main grep audit phát hiện 5 lookup sites cùng bug, Plan N chỉ catch 1. Plan O fix 4 sites còn lại: Service.cs:201 (EnsureCanRejectV2Async = bug bro), Service.cs:248 (ApplyReturnModeAsync read Allow flag), DetailFeatures.cs:72 (F3 guard), Features.cs:311 (F4 AdjustBudget guard). ApplyReturnModeAsync signature +`Guid? actorUserId` 4th param + caller TransitionAsync:94 update. 3 regression test mới `PurchaseEvaluationPerNvLookupRegressionTests`. **111/111 PASS** (+3 từ 108). Pattern reinforced 5 sites checklist + audit grep `FirstOrDefault.*Order ==`. Bug 2 (F2 chỉ đến Phan Văn Chương) defer follow-up — F2 logic đúng, verify workflow v14 DB. Stats: **31 mig** · 59 tables · ~145 endpoints · 34 FE pages · **111 test (+3)** · 47 gotcha · 20 memory · 6 skills.)
+**Last updated:** 2026-05-15 (Session 23 turn 6 — **🎯 Plan P HOTFIX: Controller TransitionPeBody record missing 3 fields — bug ROOT CAUSE thực sự F1+F2 fail**. CICD Monitor Plan O Run #202 catch CRITICAL caveat: Controller `TransitionPeBody:267` MISSING ReturnMode + ReturnTargetUserId + SkipToFinal. Investigator audit FE confirm: FE × 2 app mirror SEND ĐÚNG 7 fields qua `api.post()` — BE drop tại Controller body record + mediator.Send line 70. Bug present 2 ngày prod từ Mig 28 deploy 2026-05-13 → F1+F2 wire fail từ FE side. Plan N + Plan O fix lookup sites nhưng controller bug block flow trước khi đến lookup. Plan P fix BE-only ~10 LOC: TransitionPeBody +3 field default null/false + mediator.Send pass 7 fields + using import WorkflowReturnMode namespace. **111/111 PASS unchanged**. Pattern reinforced: Controller body record MUST mirror Command record fields. Multi-agent ROI: Investigator avoid cross-stack fix sai + CICD Monitor catch root cause invaluable chain. Stats: **31 mig** · 59 tables · ~145 endpoints · 34 FE pages · **111 test** · 47 gotcha · 20 memory · 6 skills.)
+
+**Last updated S23 t5:** 2026-05-15 (Session 23 turn 5 — **🎯 Plan O HOTFIX: 4 lookup sites cùng pattern per-NV cascade — Plan N chỉ catch 1/5 sites**. Bro UAT sau Plan N: Actor NV Test trong OR-of-N click "Trả lại Người chỉ định" → "Không phải lượt bạn" mặc dù đúng slot. Em main grep audit phát hiện 5 lookup sites cùng bug, Plan N chỉ catch 1. Plan O fix 4 sites còn lại: Service.cs:201 (EnsureCanRejectV2Async = bug bro), Service.cs:248 (ApplyReturnModeAsync read Allow flag), DetailFeatures.cs:72 (F3 guard), Features.cs:311 (F4 AdjustBudget guard). ApplyReturnModeAsync signature +`Guid? actorUserId` 4th param + caller TransitionAsync:94 update. 3 regression test mới `PurchaseEvaluationPerNvLookupRegressionTests`. **111/111 PASS** (+3 từ 108). Pattern reinforced 5 sites checklist + audit grep `FirstOrDefault.*Order ==`. Bug 2 (F2 chỉ đến Phan Văn Chương) defer follow-up — F2 logic đúng, verify workflow v14 DB. Stats: **31 mig** · 59 tables · ~145 endpoints · 34 FE pages · **111 test (+3)** · 47 gotcha · 20 memory · 6 skills.)
 
 **Last updated S23 t4:** 2026-05-15 (Session 23 turn 4 — **🎯 Plan N HOTFIX: BE per-NV lookup site discrimination — bug critical UAT block**. Bro UAT screenshot phát hiện admin Designer tick 7 flag TRUE cho NV Test (UAT V2) nhưng dialog Duyệt/Trả lại KHÔNG có F1+F2+F3+F4 options. Investigator audit verify Hypothesis B: `PurchaseEvaluationFeatures.cs:765` `FirstOrDefault(Order==X)` thiếu `ApproverUserId == currentUser.UserId` discriminator. Schema Mig 29 OR-of-N: 4 row cùng Order → handler luôn lấy row đầu DB (Lê Văn Bính, Drafter only), bỏ qua admin tick per-NV. Bug PRESENT 2 ngày prod từ Mig 29 deploy 2026-05-13 — chỉ bộc lộ khi lần đầu admin tick selectively. Fix 5 LOC: thêm match `ApproverUserId == currentUser.UserId` + fallback row đầu cho admin/non-approver. Test regression `GetPurchaseEvaluationCurrentLevelOptionsTests` 2 method: 4 actor distinct flag profile + admin fallback. **108/108 PASS** (+2 từ 106). Multi-agent ROI: Investigator catch root cause 1 spawn ~80K — em main solo fix nhanh. Pattern reinforced: per-NV admin opt-in flag wire checklist **9 surface points** (thêm point 9 handler lookup site discrimination). Stats: **31 mig** · 59 tables · ~145 endpoints · 34 FE pages · **108 test (+2)** · 47 gotcha · 20 memory (1 entry reinforced) · 6 skills.)