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

src/Backend/SolutionErp.Api/Controllers/PurchaseEvaluationsController.cs

@@ -4,6 +4,7 @@ using Microsoft.AspNetCore.Mvc;
 using SolutionErp.Application.Common.Models;
 using SolutionErp.Application.PurchaseEvaluations;
 using SolutionErp.Application.PurchaseEvaluations.Dtos;
+using SolutionErp.Application.PurchaseEvaluations.Services;  // WorkflowReturnMode (Plan P S23 t6)
 using SolutionErp.Domain.Contracts;
 using SolutionErp.Domain.PurchaseEvaluations;
 
@@ -67,7 +68,14 @@ public class PurchaseEvaluationsController(IMediator mediator) : ControllerBase
     [HttpPost("{id:guid}/transitions")]
     public async Task<IActionResult> Transition(Guid id, [FromBody] TransitionPeBody body, CancellationToken ct)
     {
-        await mediator.Send(new TransitionPurchaseEvaluationCommand(id, body.TargetPhase, body.Decision, body.Comment), ct);
+        // Plan P S23 t6 (2026-05-15) — Pass 7 fields (incl 3 new F1+F2 fields).
+        // Pre-fix bug: body record + Send call drop ReturnMode/ReturnTargetUserId/
+        // SkipToFinal → handler nhận default Drafter mode + skipToFinal=false →
+        // F1 Assignee/OneLevel/OneStep + F2 skip thẳng KHÔNG hoạt động từ FE.
+        // Root cause bro UAT 2026-05-15 "Trả lại Người chỉ định fail".
+        await mediator.Send(new TransitionPurchaseEvaluationCommand(
+            id, body.TargetPhase, body.Decision, body.Comment,
+            body.ReturnMode, body.ReturnTargetUserId, body.SkipToFinal), ct);
         return NoContent();
     }
 
@@ -264,7 +272,18 @@ public record CreateContractFromEvaluationBody(
     string? TenHopDong,
     bool BypassProcurementAndCCM = false);
 
-public record TransitionPeBody(PurchaseEvaluationPhase TargetPhase, ApprovalDecision Decision, string? Comment);
+// Plan P S23 t6 — Mig 28 + Mig 31 (S21 t4 + S23 t1) extended Command record với
+// 3 fields F1+F2 (ReturnMode/ReturnTargetUserId/SkipToFinal) nhưng Controller
+// body record chỉ giữ 3 fields cũ → ASP.NET deserialization drop → handler
+// nhận default Drafter mode + skipToFinal=false → FE F1+F2 wire fail 2 ngày
+// prod từ Mig 28 deploy 2026-05-13.
+public record TransitionPeBody(
+    PurchaseEvaluationPhase TargetPhase,
+    ApprovalDecision Decision,
+    string? Comment,
+    WorkflowReturnMode? ReturnMode = null,     // F1 mode Trả lại
+    Guid? ReturnTargetUserId = null,           // F1 Assignee target
+    bool SkipToFinal = false);                 // F2 duyệt thẳng Cấp cuối
 
 public record AddSupplierBody(
     Guid SupplierId,