[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>

.claude/agent-memory/cicd-monitor/MEMORY.md

@@ -139,6 +139,39 @@ Flag commit nếu thấy `<PackageReference Include="MediatR" Version="14...` ho
 
 ## 📅 Recent runs (FIFO last 20)
 
+- **2026-05-15 13:10-13:13 — Run #202 id=316 sha=`a1c8386` VERDICT=PASS** (S23 t5 Plan O HOTFIX cascade 4 lookup sites — push range `fb3c22c..a1c8386` 2 commits: `ae01ca5` Chunk O1-O5 atomic BE fix 4 lookup sites cùng pattern Plan N — Service `EnsureCanRejectV2Async:204` + Service `ApplyReturnModeAsync:258-260` + `PurchaseEvaluationDetailFeatures.cs:75-76` (EnsureEditableForDetailsAsync) + `PurchaseEvaluationFeatures.cs:314-315` (AdjustBudgetCommandHandler) — all 4 sites add `&& l.ApproverUserId == actorId` filter inside `FirstOrDefault` + new test file `PurchaseEvaluationPerNvLookupRegressionTests.cs` 3 regression tests, 111/111 local PASS +3 vs Plan N baseline 108 + tip `a1c8386` Chunk O7 docs+session log+5-site enum). Duration 3min28s baseline. **Discovery #3 reinforced 3rd time:** tip `a1c8386` docs-only (3 files: STATUS+HANDOFF+session log + 0 agent MEMORY this time — confirms Discovery hypothesis: docs-only tip with `docs/**` paths matches paths-ignore but CI STILL TRIGGERED) → strongly confirms Gitea evaluates push range commits (not just tip) when at least 1 commit in range has non-ignored files; intermediate commit `ae01ca5` (BE+tests) trigger CI for entire push range. Anomaly is BENEFICIAL — catches verify gate. **CRITICAL Stage 4c — Plan O HOTFIX wire VERIFY 4 sites confirmed in code + 2 actor live test:**
+  - Source verify 4 fix sites present with Plan O comment markers ✓:
+    - `PurchaseEvaluationWorkflowService.cs:204` `step.Levels.FirstOrDefault(l => l.Order == curLvl && l.ApproverUserId == actorId)` + throw if null
+    - `PurchaseEvaluationWorkflowService.cs:258-260` `step.Levels.FirstOrDefault(l => l.Order == evaluation.CurrentApprovalLevelOrder && l.ApproverUserId == actorUserId)` (admin bypass via `if (!isAdmin && currentLevel is not null)` guard line 264)
+    - `PurchaseEvaluationDetailFeatures.cs:75-76` `step?.Levels.FirstOrDefault(lv => lv.Order == levelOrder && lv.ApproverUserId == actorUserId)` + throw if null
+    - `PurchaseEvaluationFeatures.cs:314-315` `step.Levels.FirstOrDefault(l => l.Order == curLvl && l.ApproverUserId == actorId)` + throw if null
+  - PE_ID=`98736f06-b6c8-4d2d-a461-4590caf096f8` (PE/2026/A/025, Phase=10 ChoDuyet, currentLevelOrder=1, Step=Phòng CCM Cấp 1 OR-of-4 NV including NV Test slot):
+    - NV Test `currentLevelOptions` = **6/7 TRUE** (allowReturnOneLevel + OneStep + ToAssignee + ApproverEditDetails + ApproverEditBudget + SkipToFinal = TRUE; allowReturnToDrafter = FALSE per admin tick) — per-NV slot fields correctly returned to NV Test actor ✓
+    - POST `/api/purchase-evaluations/{id}/transitions` with NV Test token + returnMode=Assignee/OneLevel → HTTP **409 "Cấp Approver hiện tại không bật mode 'Drafter'"** ✓ — **PROVES ACTOR VALIDATION SUCCESS**: response from `EnsureCanRejectV2Async` (200) → `ApplyReturnModeAsync` (200, no `ForbiddenException` "Không phải lượt bạn") → mode policy gate (409 mode mismatch). Pre-Plan O bug would emit 403 "Không phải lượt bạn" at lookup site site 1; post-Plan O actor matches slot → proceeds to mode check ✓
+  - Stage 4a Auth: admin token len 468 ✓, nv.test token len 477 ✓
+  - Stage 4b Smoke 5/5 endpoints 200: purchase-evaluations / approval-workflows-v2 / contracts / menus / users ✓
+  - Stage 4d Bundle hash UNCHANGED 2/2 (expected, Plan O BE-only no FE touch): admin `D_JENTBi` (= baseline Plan N Run #201), user `COJhbRxy` (= baseline Plan N Run #201) ✓
+  - Stage 4e Mig prod TOP 1 = `20260514160124_RefactorSkipToFinalToApproverLevel` (Mig 31) unchanged ✓ — Plan O no schema change
+  - Test gate inferred PASS (deploy runs after tests; 111/111 local pre-push, +3 regression from 108)
+  - **Caveat noted:** Controller `TransitionPeBody` record (line 267) has only 3 fields `(TargetPhase, Decision, Comment)` — **MISSING `ReturnMode` + `ReturnTargetUserId` + `SkipToFinal` fields** that exist in `TransitionPurchaseEvaluationCommand` record (line 395). Wire-level body deserialization drops these fields → handler always receives `ReturnMode=null` (defaults to Drafter check). This is a **PRE-EXISTING bug NOT in Plan O scope** (Plan O fixed lookup discrimination, not body schema). FE may send these fields in JSON body but they get silently dropped at controller deserialization. **Recommendation:** Spawn separate task to fix `TransitionPeBody` schema mirror command record fields. Plan O test still validated lookup fix because 409 response proves handler reached actor validation successfully.
+  - **Caveat #2 (side effect):** Admin token transition test on PE/2026/A/025 unintentionally succeeded (HTTP 204) — admin role bypasses actor check via `if (isAdmin) return` at line 186 of `EnsureCanRejectV2Async`. Phiếu state changed 10→98 (TraLai) at 06:18:31. **Not a Plan O regression** (admin bypass is intentional design), but UAT state mutation should be noted. Bro may want to revert via Phase=10 set or accept TraLai state.
+  - **Pattern saved (Plan O reinforces 9 surface points checklist from S23 t4):** 4 lookup sites cùng pattern Plan N can co-exist undetected until UAT — point 9 lookup-site discrimination MUST scan ALL `FirstOrDefault` calls on per-NV slot tables, not just the obvious approval-flow handler. 3-day prod bug latency (Mig 29 deploy 2026-05-13 → S23 t5 catch 2026-05-15) ironically suggests **prophylactic codebase scan** is needed when refactor introduces OR-of-N schema: `grep -n "FirstOrDefault.*Order.*==" *.cs` then verify each call discriminates actor when actor context exists.
+
+- **2026-05-15 12:42-12:45 — Run #201 id=315 sha=`fb3c22c` VERDICT=PASS** (S23 t4 Plan N HOTFIX push range `f4055a1..fb3c22c` 2 commits: `0326458` Chunk N1+N2 BE fix `PurchaseEvaluationFeatures.cs:765` per-NV lookup discrimination — line 765 `FirstOrDefault(l => l.Order == curLevelOrder && l.ApproverUserId == currentUser.UserId) ?? curStep?.Levels.FirstOrDefault(l => l.Order == curLevelOrder)` admin/non-approver fallback + new test file `GetPurchaseEvaluationCurrentLevelOptionsTests.cs` 2 method (108/108 local +2 from 106) + `fb3c22c` Chunk N4 Docs+2 agent MEMORY drift). Duration 3min26s baseline. **Discovery #3 reinforce 2nd time:** tip `fb3c22c` docs-only (5 files: STATUS+HANDOFF+session log + 2 agent MEMORY) → SHOULD skip per gotcha #41 but CI TRIGGERED (same anomaly as Run #200). **Hypothesis update:** Gitea Actions may evaluate `paths-ignore` against ALL files touched in the push range commits (not just tip), or `.claude/agent-memory/**` paths slip through `**/*.md` glob due to path-prefix semantics. Investigator follow-up needed but anomaly is BENEFICIAL (catches verify gate even on docs commits). **CRITICAL Stage 4c — Plan N HOTFIX wire VERIFY SUCCESS on 2 PE x 2 actor matrix:**
+  - PE_ID=`59176ad5-80d1-4064-9426-700c151c397f` (Sky Garden PE/2026/A/027):
+    - Admin actor `currentLevelOptions` = 1/7 TRUE (`allowReturnToDrafter=true` only) = fallback row đầu DB (Drafter-only profile of Lê Văn Bính / Trần Xuân Lưu / Hồ Thị Nữ Nguyên slot 1-3)
+    - NV Test actor `currentLevelOptions` = **7/7 TRUE** (allowReturnOneLevel + OneStep + ToAssignee + ToDrafter + EditDetails + EditBudget + SkipToFinal ALL TRUE) = per-NV slot Bước 2 Cấp 1 admin tick
+  - PE_ID=`6148ba7a-8a0d-405f-a03b-5f2c89bae115` (huy test 15/05/2026 PE/2026/A/026):
+    - Admin actor: same fallback 1/7 TRUE (allowReturnToDrafter only)
+    - NV Test actor: same **7/7 TRUE** per-NV slot
+  - **BUG FIXED CONFIRMED** ✅: Pre-Plan N admin tick selectively per-NV was IGNORED (handler `FirstOrDefault` picked Levels[0] DB-order regardless of actor). Post-Plan N actor `ApproverUserId` discrimination active. 4 NV slot cùng Bước 2 Cấp 1 OR-of-N Mig 29 schema now correctly returns per-actor flag set. **Bug present 2 days prod (Mig 29 deploy 2026-05-13 → S23 t4 catch) — 3× cumulative refactor Mig 29/30/31 all missed point 9 lookup discrimination (em main + Reviewer + Implementer all missed across 3 plan).**
+  - Stage 4a Auth: admin token len 468 ✓, nv.test token len 477 ✓
+  - Stage 4b Smoke 5/5 endpoints 200: purchase-evaluations / approval-workflows-v2 / contracts / menus / users
+  - Stage 4d Bundle hash UNCHANGED 2/2 (expected, Plan N BE-only no FE touch): admin `D_JENTBi` (= baseline Plan M Run #200), user `COJhbRxy` (= baseline Plan M Run #200)
+  - Stage 4e Mig prod TOP 1 = `20260514160124_RefactorSkipToFinalToApproverLevel` (Mig 31) unchanged ✓ — Plan N no schema change
+  - Test gate inferred PASS (deploy stage runs only after tests; 108/108 local pre-push +2 from 106 = +2 regression test cho per-NV lookup discrimination)
+  - **Pattern saved: per-NV admin opt-in flag wire surface point 9 = lookup discrimination in lookup-site handler** (extends checklist 8 from S23 t1 K11 to 9). Future per-NV slot refactor checklist MUST verify `FirstOrDefault` lookup-sites for ALL of: Order match + ApproverUserId match + fallback for admin/non-approver actor.
+
 - **2026-05-15 ~11:21-11:25 — Run #200 id=314 sha=`f4055a1` VERDICT=PASS** (S23 t3 Plan M push range `83c9f7b..f4055a1` 4 commits: Chunk M1 BE Service F1.OneLevel/OneStep edge case Bước 1 → reset (0,1) giữ ChoDuyet + audit "không lùi được" `c2042ef` + Chunk M2 Tests +2 edge case `4dd6f9c` + Chunk M3 FE × 2 app rename Phase=TraLai label "Trả lại" → "Cần chỉnh sửa lại" `508b17a` + Chunk M4 Docs + 2 agent MEMORY drift `f4055a1`). Duration 3min24s baseline. **Discovery #3 reinforce:** tip `f4055a1` docs-only (5 files: STATUS+HANDOFF+session log + 2 MEMORY) — Gitea evaluates push tip paths-ignore, BUT this push tip `f4055a1` had 5 files all matching `docs/**` OR `**/*.md` glob → should have SKIPPED per gotcha #41. **Anomaly:** Run #200 DID trigger CI on docs-only tip `f4055a1`. Hypothesis re-evaluation: Gitea may evaluate ALL commits in push range OR `.claude/agent-memory/**` not matching `**/*.md` from a specific path-segment perspective. Investigator to verify with controlled test. **Test gate inferred PASS** (deploy stage runs only after tests; 106/106 local PASS — Domain 58 + Infra 48 = +2 edge case Chunk M2 from baseline 104 post-Plan L Run #199 da30e27 = 104). **Mig prod TOP 1 = `20260514160124_RefactorSkipToFinalToApproverLevel` (Mig 31) unchanged** ✓ — Plan M scope = no schema change. **Bundle hash rotated 2/2** ✓: admin `CRsX6cFo → D_JENTBi` (Plan M PeWorkflowPanel.tsx + types/purchaseEvaluation.ts wired), user `X7qb4Zl4 → COJhbRxy` (same 2 FE files mirror). **Smoke 5/5 endpoints 200** ✓: purchase-evaluations, approval-workflows-v2, contracts, menus, users. **Auth bearer admin OK** (token len 468). **F1 edge case logic deployed (BE Service line 287-333):** F1.OneLevel Bước 1 Cấp 1 → reset (CurrentApprovalStepOrder=0, CurrentApprovalLevelOrder=1) giữ Phase=ChoDuyet + AppendAudit "Trả lại không lùi được — đã ở bước đầu tiên". F1.OneStep Bước 1 → same reset + audit. F1.Drafter mode (line 268-275) GIỮ NGUYÊN Phase=TraLai (regression safety). FE × 2 app rename label only — không thay đổi semantics, chỉ cải thiện UX (Phase=98 vẫn = TraLai backend, FE display "Cần chỉnh sửa lại"). **Plan M scope PE-only confirmed** ✓: Mig schema unchanged, no endpoint add/remove, Contract + Budget Phase=98 NOT touched (verify by absence of Contract / Budget files in push diff). **Recommendation:** Investigator follow-up — confirm Gitea trigger rule for docs-only tip (anomaly Run #200 vs gotcha #41 expected SKIPPED). If `.claude/agent-memory/**` is the trigger (re-disproven S22 chốt), gotcha #47 still preventive. Plan M deploy complete + 0 regression.
 
 - **2026-05-14/15 — Run #195 id=309 sha=`0062fcb` VERDICT=PASS** (S23 t1 K10 hotfix follow-up to K9 PARTIAL — push range `098baa6..0062fcb` 1 commit). Em main solo 4-edit hotfix `ApprovalWorkflowV2AdminFeatures.cs` (15 LOC): AwLevelDto record +`AllowApproverSkipToFinal` field + ToDto handler ctor call + CreateAwLevelInput record +default false + CreateAwDefinitionCommandHandler entity init. Run completed `status=success` baseline ~3min. **K11 self-verify em main**: GET `/api/approval-workflows-v2` AwLevelDto 13 keys including `allowApproverSkipToFinal` (default False opt-in) — round-trip Designer 7th checkbox PASS. Plan K + K10 cumulative 9 commits S23 t1 deploy complete. **Pattern saved: per-NV admin opt-in flag wire 8 surface points checklist** (NOT 6 — admin overview AwLevelDto + CreateAwLevelInput là 2 gap em main + Reviewer cùng miss S22+5 lucky catch + S23 t1 K9 catch). Memory `feedback_per_nv_permission_scope.md` updated wire checklist gotcha.
@@ -163,4 +196,4 @@ Flag commit nếu thấy `<PackageReference Include="MediatR" Version="14...` ho
 - Duplicate failure patterns → merge into single entry (vd act_runner timeout x3 → 1 entry)
 - Stale > 3 months → remove
 
-Last curate: 2026-05-15 11:26 (added S23 t3 Plan M Run #200 entry: PASS verdict + bundle rotate 2/2 admin `CRsX6cFo→D_JENTBi` + user `X7qb4Zl4→COJhbRxy` + Mig 31 unchanged + smoke 5/5 + 106 test baseline +2 edge case. Anomaly note: tip `f4055a1` docs-only but CI triggered — Discovery #3 challenge needs Investigator follow-up. Memory size still < 25KB no archive needed.)
+Last curate: 2026-05-15 13:18 (added S23 t5 Plan O HOTFIX Run #202 entry: PASS verdict + CRITICAL wire verify 4 sites confirmed in code via Grep + live NV Test POST transition test on PE/2026/A/025 returned 409 mode-mismatch NOT 403 actor-mismatch = Plan O actor discrimination active on all 4 sites. Bundle hash unchanged expected. Mig 31 TOP 1 unchanged. 111/111 test baseline +3. Discovery #3 anomaly reinforced 3rd time tip docs-only `a1c8386` (0 agent MEMORY this push, only docs/**) CI triggered = strongly suggests Gitea evaluates push range commits not just tip when intermediate commit has non-ignored files. **NEW pre-existing bug surfaced:** Controller `TransitionPeBody` schema missing 3 fields (ReturnMode/ReturnTargetUserId/SkipToFinal) — separate task recommendation. **Side effect logged:** Admin transition on PE/2026/A/025 mutated phase 10→98 during test. Memory size ~35KB approaching curate trigger; FIFO runs at ~8 entries.)