namespace SolutionErp.Application.ContractSigningPlans.Services;

// [W3 ĐỢT-1 SKELETON — S161 2026-07-29] Hợp đồng transition phiếu "Kế hoạch ký kết HĐ" (GĐ2).
//
// 🔴 ĐỢT NÀY = SKELETON THUẦN (test-before): interface + record chốt CHỮ KÝ để
// test-specialist viết 6 test RED compile được. Thân service NÉM NotImplementedException
// — logic thật (OR-of-N, con-trỏ đôi, LevelOpinions UPSERT, finalize) là ĐỢT-3.
//
// 🔴 HỢP-ĐỒNG LITERAL (lead định nghĩa @S161 — bài W2 "6 điểm đứt": 2 lane implement phải
// khớp TỪNG TÊN FIELD, không tự đổi):
//   POST /api/contract-signing-plans/{id}/transitions   [Authorize(Policy="KeHoachKyKet.Update")]
//   body     : { "action": "submit" | "approve" | "return" | "reject", "comment": string|null }
//   response : { "phase": int, "currentWorkflowStepIndex": int|null, "currentApprovalLevelOrder": int|null }
//
// Ý nghĩa 4 action:
//   submit  — người soạn trình phiếu: DangSoanThao | TraLai → ChoDuyet (chạy LẠI từ Bước 1 Cấp 1)
//   approve — approver Cấp đang chờ duyệt: tiến con-trỏ OR-of-N (+comment ⇒ UPSERT LevelOpinion)
//   return  — trả lại người soạn: → TraLai
//   reject  — từ chối: → TuChoi (terminal)
public interface IContractSigningPlanWorkflowService
{
    // Thực hiện 1 transition. Ném ConflictException/ForbiddenException/NotFoundException
    // (GlobalExceptionMiddleware map → ProblemDetails; controller KHÔNG try-catch).
    // Trả về trạng-thái SAU transition để controller phản hồi thẳng 3 field hợp-đồng.
    Task<ContractSigningPlanTransitionResult> TransitionAsync(
        Guid planId,
        string action,
        string? comment,
        bool applyLevelFinalize = true,
        CancellationToken ct = default);
}

// 3 field ĐÚNG BẰNG response hợp-đồng, KHÔNG thừa không thiếu.
// 🔴 `Phase` để kiểu `int` (KHÔNG ContractSigningPlanPhase) là CỐ Ý: hợp-đồng chốt
// `"phase": int` ⇒ ép cast tại nguồn, khỏi phụ thuộc cấu hình JsonStringEnumConverter
// (Api/Program.cs:33-34 hiện KHÔNG đăng ký converter enum, nhưng thêm sau sẽ lật kiểu
// JSON của mọi enum ⇒ khoá kiểu ở đây là rào chống hồi-quy im lặng).
// Null-semantics: 2 con-trỏ = null khi phiếu ở phase KHÔNG chạy workflow (nháp/terminal).
public record ContractSigningPlanTransitionResult(
    int Phase,
    int? CurrentWorkflowStepIndex,
    int? CurrentApprovalLevelOrder);
