# 5. MÔ HÌNH WORKFLOW (APPROVAL ENGINE + BUSINESS FLOWS)

Tài liệu gồm hai phần:
- **Phần A — Approval Engine**: phê duyệt động dùng chung cho mọi loại đơn (nghỉ phép, OT, tạm ứng, tin tuyển
  dụng, offer, điều chỉnh lương…). Schema: `HR_WF` trong [00_Init_Oracle_Schema.sql](00_Init_Oracle_Schema.sql).
- **Phần B — Business Workflow**: luồng xuyên service từ yêu cầu tuyển dụng đến ngày đầu đi làm, cài đặt bằng
  saga dạng choreography.

---

# PHẦN A — APPROVAL ENGINE

## 5.1 Nguyên tắc
1. **Engine không hiểu nghiệp vụ.** Engine chỉ biết `RequestType`, `SourceService`, `SourceRefId` và một
   `Payload` JSON (snapshot dữ liệu dùng để đánh giá điều kiện). Kết quả được trả về service sở hữu nghiệp vụ qua
   event `ApprovalCompleted`.
2. **Định nghĩa có version.** Request gắn cố định với version template tại lúc submit. Sửa quy trình sẽ tạo
   version mới và không ảnh hưởng tới các đơn đang chạy.
3. **Người duyệt được tính khi bước được kích hoạt**, không tính trước toàn bộ lúc submit, vì tổ chức có thể thay
   đổi giữa chừng. Kết quả được **snapshot** vào `APPROVAL_TASK` để audit.
4. **Engine không đọc DB của CoreHR.** Việc tìm người duyệt theo tổ chức đi qua gRPC `CoreHR.ResolveApprovers`
   (bọc `PKG_DOA`).
5. **Mọi chuyển trạng thái đều ghi `APPROVAL_LOG`** (append-only) trong cùng transaction.

## 5.2 Mô hình khái niệm

```
 ĐỊNH NGHĨA (design-time)                 THỰC THI (run-time)
 ┌────────────────────────┐   submit     ┌────────────────────────┐
 │ WORKFLOW_TEMPLATE      │─────────────►│ APPROVAL_REQUEST       │── Payload (JSON snapshot)
 │  RequestType + Version │              │  Status, CurrentStepNo │
 └──────────┬─────────────┘              └──────────┬─────────────┘
            │ 1..n                                  │ 0..n (theo bước)
 ┌──────────▼─────────────┐   resolve    ┌──────────▼─────────────┐
 │ WORKFLOW_STEP_DEF      │─────────────►│ APPROVAL_TASK          │── AssigneeEmployeeId (snapshot)
 │  ApproverRule/Param    │  + DELEGATION│  Status, DueAt         │── OnBehalfOf (uỷ quyền)
 │  ConditionExpr, Mode   │              └──────────┬─────────────┘
 │  SlaHours, OnTimeout   │                         │ mọi hành động
 └────────────────────────┘              ┌──────────▼─────────────┐
                                         │ APPROVAL_LOG (bất biến)│
                                         └────────────────────────┘
```

## 5.3 State machine

### APPROVAL_REQUEST
```mermaid
stateDiagram-v2
    [*] --> SUBMITTED : Submit (IdempotencyKey)
    SUBMITTED --> IN_PROGRESS : kích hoạt bước đầu tiên có điều kiện đúng
    SUBMITTED --> APPROVED : không có bước nào áp dụng (auto-approve)
    IN_PROGRESS --> IN_PROGRESS : bước N hoàn tất → kích hoạt bước N+1
    IN_PROGRESS --> APPROVED : bước cuối hoàn tất
    IN_PROGRESS --> REJECTED : một task bị REJECT / AUTO_REJECT khi quá hạn
    IN_PROGRESS --> RETURNED : người duyệt yêu cầu bổ sung
    RETURNED --> SUBMITTED : người nộp sửa và nộp lại (chạy lại từ bước 1)
    SUBMITTED --> CANCELLED : người nộp huỷ
    IN_PROGRESS --> CANCELLED : người nộp huỷ / service gốc huỷ nghiệp vụ
    RETURNED --> CANCELLED
    APPROVED --> [*]
    REJECTED --> [*]
    CANCELLED --> [*]
```

### APPROVAL_TASK
```mermaid
stateDiagram-v2
    [*] --> PENDING : bước được kích hoạt
    PENDING --> APPROVED : Approve
    PENDING --> REJECTED : Reject
    PENDING --> RETURNED : Return for info
    PENDING --> ESCALATED : quá SLA và OnTimeout = ESCALATE (sinh task mới ở cấp trên)
    PENDING --> SKIPPED : bước ANY đã có người khác duyệt / người duyệt trùng bước trước
    PENDING --> CANCELLED : request bị huỷ / người duyệt nghỉ việc (sinh task thay thế)
    APPROVED --> [*]
    REJECTED --> [*]
    RETURNED --> [*]
    ESCALATED --> [*]
    SKIPPED --> [*]
    CANCELLED --> [*]
```

## 5.4 Quy tắc chọn người duyệt (ApproverRule)

| ApproverRule | RuleParam | Cách tính | Nguồn |
|---|---|---|---|
| `LINE_MANAGER` | `levelsUp=1`, `minGrade=50`, `startFrom=payload.positionId` | `PKG_DOA.ResolveApprovers` (04 §4.3): leo chuỗi báo cáo **suy ra từ cây tổ chức** tại ngày resolve, bỏ ghế trống / không đủ cấp / chính người nộp. Trả **mọi** người giữ ghế ở cấp tìm được (ưu tiên người đang giữ quyền ACTING) → task chế độ ANY. `startFrom`: xuất phát từ ghế trong payload (OFFER/REQUISITION: quản lý của **ghế đang tuyển**) | gRPC CoreHR |
| `MATRIX_MANAGER` | `lineType=FUNCTIONAL` | Người giữ ghế ở đầu kia của `POSITION_MATRIX_LINE` (tuyến chuyên môn / dự án) của ghế người nộp tại ngày resolve. Không có tuyến → bỏ qua bước (log `STEP_SKIPPED`) | gRPC CoreHR |
| `ORG_HEAD` | `orgType=DIVISION` | Leo `ORG_EDGE` (MANAGEMENT) từ đơn vị của người nộp tới tổ tiên gần nhất có `OrgType` khớp, lấy người giữ ghế trong `ORG_UNIT_HEAD` tại ngày resolve. Là chính người nộp → lên trưởng cấp trên | gRPC CoreHR |
| `AUTHORITY_MATRIX` | — | Tra `AUTHORITY_MATRIX` theo `RequestType` + `Payload.amount` (hiệu lực tại ngày resolve) → `MinGradeRank`, rồi gọi `ResolveApprovers(minGrade = MinGradeRank)`. Đổi hạn mức = thêm phiên bản ma trận, không sửa template | HR_WF + gRPC CoreHR |
| `ROLE` | `role=HRBP` / `role=C&B` | Người giữ vai trò đó phụ trách đơn vị của người nộp (bảng phân công RBAC) | Identity |
| `SPECIFIC_POSITION` | `positionCode=CFO-01` | Người đang ngồi ghế đó | gRPC CoreHR |

**Ngày resolve** (chính sách theo template, trường `ResolveAsOf`):
- `ACTIVATION_DATE` (mặc định): cơ cấu tại **thời điểm bước được kích hoạt** — người đang chịu trách nhiệm quản lý
  bây giờ là người duyệt, kể cả với đơn nghỉ phép cho ngày đã qua.
- `BUSINESS_DATE`: cơ cấu tại ngày nghiệp vụ trong payload (vd `payload.effectiveDate` của quyết định điều chuyển —
  người duyệt là quản lý tại ngày quyết định có hiệu lực).
- Kiểm toán / tranh chấp: gọi lại với `knownAt = thời điểm kích hoạt` để tái hiện chính xác "lúc đó hệ thống giao cho ai".

Sau khi có người duyệt gốc, engine áp dụng thêm các bước sau:
1. **Uỷ quyền**: nếu có `DELEGATION` hiệu lực hôm nay, khớp `RequestType` (hoặc `RequestType` NULL), thì
   `AssigneeEmployeeId` = người được uỷ quyền và `OnBehalfOfEmployeeId` = người uỷ quyền. Không uỷ quyền bắc cầu
   (chỉ đi đúng một bước).
2. **Chặn tự duyệt**: nếu assignee = người nộp, dù trực tiếp hay qua uỷ quyền, thì leo thêm một cấp (`levelsUp + 1`).
3. **Gộp người duyệt trùng**: nếu assignee đã duyệt ở bước trước của cùng request thì task được tạo với trạng
   thái `SKIPPED`, lý do `DUPLICATE_APPROVER`. Chính sách này bật/tắt được theo template.
4. **Không tìm được ai**: giao cho vai trò `HR_ADMIN` và ghi log `FALLBACK_APPROVER`.

## 5.5 Điều kiện bước (ConditionExpr)
Điều kiện là JSON đánh giá trên `Payload`. Bước có điều kiện sai sẽ bị **bỏ qua** và ghi log `STEP_SKIPPED`.
```json
{ "all": [ { "field": "amount",   "op": ">",  "value": 50000000 },
           { "field": "currency", "op": "==", "value": "VND" } ] }
```
Toán tử hỗ trợ: `== != > >= < <= in`, nhóm bằng `all` / `any`. Engine **không** chạy code tuỳ ý: không dùng
`eval` hay expression động, để tránh chèn mã độc qua dữ liệu template.

## 5.6 Xử lý của engine (pseudocode)

```text
Submit(cmd):
  if exists APPROVAL_REQUEST(tenant, cmd.IdempotencyKey): return existing        # idempotent
  tpl  = active WORKFLOW_TEMPLATE(tenant, cmd.RequestType)
  req  = insert APPROVAL_REQUEST(Status=SUBMITTED, Payload=cmd.Payload, TemplateId=tpl.Id)
  log(req, SUBMITTED)
  ActivateNextStep(req, fromStep = 0)

ActivateNextStep(req, fromStep):
  for step in tpl.steps where StepNo > fromStep order by StepNo:
      if not Evaluate(step.ConditionExpr, req.Payload): log(req, STEP_SKIPPED, step); continue
      approvers = Resolve(step, req)                     # 5.4 — có thể nhiều người nếu Mode=ALL
      for a in approvers: insert APPROVAL_TASK(PENDING, DueAt = now + step.SlaHours)
      req.Status = IN_PROGRESS; req.CurrentStepNo = step.StepNo; req.RowVersion++
      outbox(ApprovalTaskAssigned)                        # → Notification (email/push)
      return
  req.Status = APPROVED; outbox(ApprovalCompleted{outcome=APPROVED})

Act(taskId, actor, action, comment):                      # action ∈ APPROVE | REJECT | RETURN
  rows = UPDATE APPROVAL_TASK SET Status=action, ActedAt=now
         WHERE Id=taskId AND Status='PENDING' AND AssigneeEmployeeId=actor
  if rows == 0: return Conflict("đã được xử lý hoặc không phải người được giao")   # chống double-click
  log(req, action, task)
  switch action:
    REJECT : cancel các task PENDING khác của bước; req.Status=REJECTED; outbox(ApprovalCompleted{REJECTED})
    RETURN : cancel các task PENDING; req.Status=RETURNED; outbox(ApprovalReturned)
    APPROVE:
      if step.Mode == ANY or mọi task của bước đã APPROVED:
          SKIPPED các task PENDING còn lại của bước (nếu Mode == ANY)
          ActivateNextStep(req, req.CurrentStepNo)
  UPDATE APPROVAL_REQUEST ... WHERE Id=req.Id AND RowVersion=:expected             # optimistic lock

TimeoutSweeper (mỗi 5 phút, dùng IX_TASK_DUE):
  for task in PENDING where DueAt < now:
    REMIND     → gửi nhắc, DueAt += SlaHours (tối đa 2 lần, sau đó chuyển thành ESCALATE)
    ESCALATE   → task.Status = ESCALATED; tạo task mới cho Resolve(levelsUp + 1)
    AUTO_REJECT→ Act(task, SYSTEM, REJECT, "Quá hạn SLA")
```

**Phản ứng với thay đổi tổ chức (consumer event từ CoreHR):**

| Event | Hành động của Workflow |
|---|---|
| `EmployeeTerminated` (khi có hiệu lực) | Task `PENDING` của người đó chuyển thành `CANCELLED`, resolve lại bước hiện tại và tạo task thay thế. Request **do** người đó nộp chuyển thành `CANCELLED` |
| `ChangeSetEffective` / `ChangeSetApplied` (hiệu lực ≤ hôm nay) | Với mỗi task `PENDING` có `AssigneeEmployeeId` thuộc `touched.employees` **hoặc** người nộp thuộc đơn vị / ghế trong `touched`: resolve lại bước; nếu người duyệt mới khác người cũ → task cũ `CANCELLED` (lý do `REORG_REROUTE`), tạo task mới, ghi log. Nếu vẫn là người cũ → giữ nguyên |
| `AssignmentChanged` loại `ACTING` bắt đầu / kết thúc | Như trên — người được giao quyền nhận các task của ghế từ ngày bắt đầu, trả lại khi kết thúc |
| Change set hồi tố (`retroactive = true`) | **Không** mở lại đơn đã kết thúc — quyết định đã duyệt giữ nguyên hiệu lực; chỉ task đang chờ được xét lại như trên |

## 5.7 Nhất quán và đồng thời

| Rủi ro | Biện pháp |
|---|---|
| Client submit hai lần (mạng chập chờn) | `UQ_REQ_IDEMP (TenantId, IdempotencyKey)`, trả về request đã có |
| Hai người cùng duyệt bước `ANY` trong cùng một giây | `UPDATE ... WHERE Status='PENDING'` + `RowVersion` trên request. Người đến sau nhận 409 |
| Event `ApprovalCompleted` bị giao lặp | Service nhận kiểm tra `INBOX_MESSAGE` trước khi xử lý |
| Mất event khi service gặp sự cố | Outbox ghi cùng transaction, relay retry với backoff |
| Sửa quy trình khi đơn đang chạy | Request gắn `TemplateId` cố định (theo version) |

## 5.8 Template mẫu

| RequestType | Bước | ApproverRule (param) | Điều kiện | SLA / Timeout |
|---|---|---|---|---|
| `LEAVE` | 1 | LINE_MANAGER (levelsUp=1) | — | 24h / ESCALATE |
| | 2 | ORG_HEAD (orgType=DEPARTMENT) | `days > 3` | 48h / ESCALATE |
| `ADVANCE` (tạm ứng) | 1 | LINE_MANAGER | — | 24h / REMIND |
| | 2 | LINE_MANAGER (minGrade=60) | `amount > 50,000,000` | 48h / ESCALATE |
| | 3 | ROLE (role=FINANCE) | — | 48h / REMIND |
| `REQUISITION` | 1 | ORG_HEAD (orgType=DEPARTMENT) | — | 48h / ESCALATE |
| | 2 | ROLE (role=FINANCE) | `isNewHeadcount == true` | 72h / REMIND |
| `ORG_CHANGE` (duyệt change set tái cấu trúc) | 1 | ORG_HEAD (orgType=DIVISION, của đơn vị cao nhất bị chạm) | — | 48h / ESCALATE |
| | 2 | ROLE (role=HR_DIRECTOR) | — | 72h / REMIND |
| | 3 | ROLE (role=FINANCE) | `fteDelta > 0` (tăng định biên) | 72h / REMIND |
| `PERSONNEL_ACTION` (điều chuyển / thăng chức) | 1 | LINE_MANAGER, `ResolveAsOf = BUSINESS_DATE` | — | 24h / ESCALATE |
| | 2 | AUTHORITY_MATRIX | `salaryDelta > 0` | 48h / ESCALATE |
| `OFFER` | 1 | LINE_MANAGER (startFrom=payload.positionId) | — | 24h / ESCALATE |
| | 2 | ROLE (role=HRBP) | — | 24h / REMIND |
| | 3 | ROLE (role=C&B) | `salary > bandMax` | 48h / AUTO_REJECT |

---

# PHẦN B — BUSINESS WORKFLOW: TỪ TUYỂN DỤNG ĐẾN NHẬN VIỆC

## 5.9 Sơ đồ tuần tự (saga choreography)

```mermaid
sequenceDiagram
    autonumber
    actor HM as Hiring Manager
    participant ATS as Recruitment (HR_ATS)
    participant WF as Workflow (HR_WF)
    participant CORE as CoreHR (HR_CORE)
    participant PAY as Payroll (HR_PAY)
    participant K as Kafka

    HM->>ATS: Tạo JOB_REQUISITION (PositionId)
    ATS->>CORE: gRPC GetPosition — kiểm tra ghế ACTIVE, còn định biên
    ATS->>WF: Submit(REQUISITION, sourceRef = reqId)
    WF->>CORE: gRPC ResolveApprovers (từng bước, as-of ngày kích hoạt)
    WF-->>K: ApprovalCompleted(APPROVED)
    K-->>ATS: Requisition → OPEN
    Note over ATS: Ứng tuyển → phỏng vấn → Offer
    ATS->>WF: Submit(OFFER, payload{salary, bandMax})
    WF-->>K: ApprovalCompleted(APPROVED)
    K-->>ATS: Offer → APPROVED → SENT
    Note over ATS: Ứng viên ký nhận
    ATS-->>K: OfferAccepted (không mang lương)
    K-->>CORE: tiêu thụ OfferAccepted
    alt còn định biên FTE và ghế ACTIVE
        CORE->>CORE: Change set PERSONNEL (HIRE: EMPLOYEE + EMPLOYMENT + ASSIGNMENT) → VerifyChangeSet → Apply + Outbox
        CORE-->>K: EmployeeHired
        K-->>PAY: tiêu thụ EmployeeHired
        PAY->>ATS: gRPC GetOfferCompensation (scope payroll.read)
        PAY->>PAY: PKG_COMP.ChangeAmount(BASE_SALARY, validFrom = StartDate)
        K-->>ATS: Application → HIRED, Requisition → FILLED (khi đủ Openings)
    else VerifyChangeSet lỗi C8 (hết định biên) / C7 (ghế FROZEN)
        CORE-->>K: HireRejected(reason = HEADCOUNT_EXCEEDED)
        K-->>ATS: Offer → ON_HOLD, báo HR xử lý (bù trừ)
    end
```

## 5.10 Các điểm thiết kế quan trọng của luồng

| Điểm | Quyết định | Lý do |
|---|---|---|
| Ai quyết định "đã thành nhân viên" | **CoreHR**, qua change set `PERSONNEL` (op `HIRE`) được áp tự động — việc tuyển đã được duyệt ở bước OFFER | Chỉ CoreHR kiểm được định biên FTE trên cả khoảng thời gian và áp nguyên khối (04 §4.4) |
| Tạo trùng nhân viên khi event lặp | `INBOX_MESSAGE` + `UX_EMPLOYEE_CANDIDATE` | Hai lớp bảo vệ: theo message và theo nghiệp vụ |
| Lương trong event | **Không**. Payroll kéo lương qua API có phân quyền | Topic Kafka có nhiều consumer (IT, L&D, Asset) không được phép thấy lương |
| Bù trừ khi thất bại | `HireRejected` → Offer `ON_HOLD` | Saga không rollback được việc ứng viên đã ký. Chỉ có thể chuyển sang trạng thái cần con người xử lý |
| Thứ tự event | Partition key = `EmployeeId` (hoặc `CandidateId`) | Đảm bảo `EmployeeHired` luôn tới trước `AssignmentChanged` của cùng người |

## 5.11 Ánh xạ sang code hiện tại và việc cần làm

| Hiện trạng | Việc cần làm |
|---|---|
| [CandidateService.cs](../../src/Services/Recruitment/Hris.Recruitment.Api/Services/CandidateService.cs) tạo `CandidateHiredEvent` rồi chỉ `Console.WriteLine`, và trả về `HIRED` ngay | Đổi thành `OfferAccepted`, ghi outbox. Trạng thái trả về là `PENDING_ONBOARDING`, chỉ thành `HIRED` khi nhận `EmployeeHired` |
| [CandidateHiredEvent.cs](../../src/Shared/Hris.Shared.Contracts/CandidateHiredEvent.cs) có `PositionApplied` (string), `BranchCode` và `Salary` | Dùng contract `OfferAccepted` ở 01 §1.4: có `PositionId` Guid, không mang lương, có envelope `EventId`/`TenantId` |
| CoreHR chưa có consumer | Thêm `OfferAcceptedConsumer`: Inbox → lập change set `PERSONNEL` (op `HIRE`, `SourceCandidateId`) → Change Engine Apply → Outbox |
| ✅ Change Engine CoreHR (v3.3) | Đã có — [`src/Services/CoreHR`](../../src/Services/CoreHR/README.md). Việc còn lại phía workflow: consumer `ApprovalCompleted` gọi `ChangeEngine.ApproveAsync` thay cho endpoint `approve` gọi tay; template `ORG_CHANGE` / `PERSONNEL_ACTION` đã có trong dev seed |
| Chưa có Workflow service | Thêm `Hris.Workflow.Api` theo Phần A. Bắt đầu với `LEAVE` và `OFFER` |
