# 4. THUẬT TOÁN HỆ THỐNG CỐT LÕI (CORE ALGORITHMS)

Tài liệu mô tả **cách hệ thống ghi nhận và đọc cơ cấu nhân sự theo thời gian**: dữ liệu được lưu thế nào, thay đổi
được áp dụng thế nào, người duyệt được tìm ra sao, và lương hồi tố được tính thế nào. Mã nguồn DB nằm trong
[00_Init_Oracle_Schema.sql](00_Init_Oracle_Schema.sql). Change Engine được cài đặt trong CoreHR service (.NET) theo
đặc tả ở §4.2.

| Mục | Nội dung |
|---|---|
| 4.1 | Mô hình thời gian: định danh + phiên bản bitemporal, cách đọc "tại ngày d, theo hiểu biết lúc T" |
| 4.2 | Change Engine: change set, các phép ghi theo thời gian, hẹn ngày, hồi tố, sửa sai, đảo quyết định, đồng thời |
| 4.3 | Chuỗi báo cáo suy ra từ cây tổ chức + DOA theo ngày |
| 4.4 | Định biên FTE kiểm theo khoảng thời gian |
| 4.5 | Kiểm toàn vẹn trước commit (PKG_INTEGRITY) |
| 4.6 | Lương hồi tố |
| 4.7 | Kịch bản mẫu: một đợt tái cấu trúc từ đầu đến cuối |
| 4.8 | Giới hạn đã biết và hướng mở rộng |

---

## 4.1 Mô hình thời gian

### 4.1.1 Định danh + phiên bản
Mỗi đối tượng có **một bảng định danh bất biến** và **các bảng phiên bản**, tách theo nhóm thuộc tính thay đổi độc lập.

| Định danh | Phiên bản | Thay đổi khi |
|---|---|---|
| `ORG_UNIT` | `ORG_UNIT_VERSION` | đổi tên, loại, pháp nhân, cost center, giải thể |
| | `ORG_EDGE` (theo loại cây) | di chuyển trong cây quản trị / pháp nhân / tài chính |
| | `ORG_UNIT_HEAD` | đổi ghế trưởng đơn vị |
| `POSITION` | `POSITION_VERSION` | đổi đơn vị, chức danh, FTE, chế độ báo cáo, đóng băng, đóng ghế |
| | `POSITION_MATRIX_LINE` | thêm / bỏ tuyến báo cáo ma trận |
| `EMPLOYMENT` | `EMPLOYMENT_VERSION` | đổi loại hợp đồng, nghỉ việc |
| (`AssignmentKey`) | `ASSIGNMENT` | bổ nhiệm, điều chuyển, quyền trưởng, kiêm nhiệm, kết thúc |

**Vì sao phải tách nhóm thuộc tính?** Hãy xét tình huống sau với một bảng phiên bản chứa mọi thuộc tính:
- Đã có quyết định đổi tên phòng, hiệu lực 01/01.
- Hôm nay lại ra thêm quyết định chuyển phòng sang khối khác, hiệu lực 01/12.

Phiên bản 01/01 đã được ghi từ trước và vẫn chứa cha cũ. Kết quả là từ 01/01 phòng "quay về" khối cũ, và thay đổi
ngày 01/12 bị mất. Tách `ORG_EDGE` khỏi `ORG_UNIT_VERSION` loại bỏ phần lớn xung đột này. Phần còn lại (hai thay
đổi cùng một nhóm thuộc tính) được xử lý bằng quy tắc lan truyền ở §4.2.3.

### 4.1.2 Hai trục thời gian
| Trục | Cột | Câu hỏi trả lời |
|---|---|---|
| Hiệu lực (valid time) | `ValidFrom`, `ValidTo` | Ngoài đời, điều này đúng từ ngày nào đến ngày nào? |
| Hiểu biết (transaction time) | `RecordedAt`, `SupersededAt` | Hệ thống **biết** điều này từ lúc nào đến lúc nào? |

Quy ước: khoảng nửa mở `[ValidFrom, ValidTo)`, và `ValidTo = NULL` nghĩa là vô hạn.

Dòng phiên bản **bất biến tuyệt đối**. Mọi phép "đóng", "tách" hay "sửa" đều gồm hai bước: set `SupersededAt` cho
dòng cũ, rồi `INSERT` dòng mới. Việc này được cưỡng chế ở hai lớp:
- Trigger `TRG_*_IMM`: cấm `DELETE`, và chỉ cho set `SupersededAt` một lần.
- Quyền của role `HR_CORE_APP`: chỉ có `UPDATE (SupersededAt)` trên các bảng phiên bản.

### 4.1.3 Đọc dữ liệu
Mọi hàm đọc (`PKG_ORG_QUERY`, `PKG_DOA`) nhận hai tham số:
- `p_as_of`: ngày hiệu lực cần xem.
- `p_known_at`: thời điểm hiểu biết. `NULL` nghĩa là theo hiểu biết hiện tại.

| Câu hỏi | Gọi |
|---|---|
| Sơ đồ tổ chức ngày 01/01/2027 (đã lên kế hoạch) | `Subtree(root, 'MANAGEMENT', DATE '2027-01-01')` |
| Sơ đồ tổ chức ngày 15/03/2026 theo hiểu biết hiện tại (kể cả các sửa sai sau này) | `Subtree(root, 'MANAGEMENT', DATE '2026-03-15')` |
| Lúc duyệt đơn 10/03/2026 09:00, hệ thống đã coi ai là người duyệt? | `ResolveApprovers(emp, DATE '2026-03-10', p_known_at => TIMESTAMP '2026-03-10 09:00:00 +07:00')` |

Điều kiện lọc chuẩn dùng trong mọi câu SQL:
```sql
ValidFrom <= :as_of AND (ValidTo IS NULL OR ValidTo > :as_of)
AND (   (:known_at IS NULL AND SupersededAt IS NULL)
     OR (:known_at IS NOT NULL AND RecordedAt <= :known_at
         AND (SupersededAt IS NULL OR SupersededAt > :known_at)))
```

Truy vấn cây theo ngày dùng recursive CTE trên `ORG_EDGE` (đã lọc theo ngày), chi phí O(k) với k là kích thước cây
con. Truy vấn nóng cho **ngày hôm nay** (phạm vi quyền, báo cáo) đọc bảng cache `ORG_PATH_CURRENT` với
`Lineage LIKE 'prefix%'`. Bảng cache này được dựng lại bằng `PKG_ORG_CACHE.Refresh` sau mỗi change set có hiệu lực
≤ hôm nay, và bằng job chạy 00:05 hằng ngày.

---

## 4.2 Change Engine

> **Hiện thực:** [`src/Services/CoreHR`](../../src/Services/CoreHR/README.md) — `Timeline` (4.2.3) trong Domain, `ChangeEngine` (4.2.2, 4.2.6) trong Application, `OracleChangeStore` trong Infrastructure. Đã có: toàn bộ thao tác ở bảng 4.2.3 kể cả `CORRECT_RECORD`, và đảo quyết định `REVERSE_CHANGE_SET` (4.2.5, v3.4); validate dry-run; apply nguyên khối; `NEEDS_REVALIDATION` cho quyết định phụ thuộc; outbox. Hai điểm chính xác hoá khi hiện thực: (1) diff so dòng cũ / mới theo **nội dung** (khoảng + thuộc tính), không theo Id — tách rồi gộp lại như cũ thì không ghi gì; (2) phép `SetFrom` trên đối tượng không tồn tại tại ngày hiệu lực là lỗi, còn `SET_UNIT_HEAD` / `MOVE_UNIT` vào khoảng trống thì dùng `Insert` tới kế hoạch kế tiếp.

### 4.2.1 Change set — mọi thay đổi đều gắn với một quyết định
```
DRAFT ──validate──► VALIDATED ──submit──► PENDING_APPROVAL ──approve──► APPROVED ──apply──► APPLIED
  ▲                    │                                                   │                  │
  └────── sửa ─────────┘◄──────────── NEEDS_REVALIDATION ◄─────────────────┘            reverse│
                                   (đối tượng bị change set khác chạm)                        ▼
                                                                                          REVERSED
```
- `CHANGE_SET` là một quyết định (có `DecisionNo` và `EffectiveDate`). `CHANGE_ITEM` là các thao tác trong quyết
  định đó, có thứ tự `Seq`.
- Một đợt reorg vừa di chuyển đơn vị, vừa lập ghế mới, vừa điều chuyển người là **một** change set, được áp
  **nguyên khối trong một transaction**.
- Mọi dòng phiên bản được sinh ra đều mang `ChangeSetId`. Nhờ đó luôn trả lời được câu hỏi "dòng này do quyết
  định nào sinh ra?".
- Việc duyệt change set đi qua approval engine (`RequestType = ORG_CHANGE` hoặc `PERSONNEL_ACTION`).

### 4.2.2 Áp dụng (apply)
```text
Apply(changeSetId):
  BEGIN TRANSACTION
    SELECT ... FROM TENANT WHERE Id = :tenant FOR UPDATE          -- tuần tự hoá ghi cơ cấu trong tenant
    cs = SELECT ... FROM CHANGE_SET WHERE Id = :id FOR UPDATE
    require cs.Status = APPROVED
    if cs.BaseOrgVersion <> TENANT.OrgVersion:                     -- có change set khác đã áp sau lúc validate
        re-run Validate (dry-run trong cùng transaction); lỗi → ROLLBACK, cs.Status = NEEDS_REVALIDATION
    for item in cs.items order by Seq:
        ApplyItem(item)                                            -- §4.2.3 – §4.2.4
    report = PKG_INTEGRITY.VerifyChangeSet(cs.Id)                  -- §4.5, raise nếu có lỗi → ROLLBACK
    TENANT.OrgVersion += 1
    cs.Status = APPLIED, AppliedAt = now, AppliedOrgVersion = TENANT.OrgVersion, ValidationReport = report
    OUTBOX: ChangeSetApplied{ changeSetId, kind, effectiveDate, retroactive = (minItemDate < today),
                               touched: {orgUnits[], positions[], employees[]} }
            + các event nghiệp vụ theo item (EmployeeHired, EmployeeTerminated, AssignmentChanged ...)
    if minItemDate <= today: PKG_ORG_CACHE.Refresh(tenant)
  COMMIT
```
**Validate** chạy đúng các bước trên nhưng kết thúc bằng `ROLLBACK` (dry-run). Báo cáo lỗi và cảnh báo được lưu vào
`CHANGE_SET.ValidationReport`, và `BaseOrgVersion` được ghi lại. Người lập quyết định thấy ngay hậu quả trước khi
trình duyệt: vượt định biên, ghế nằm trong đơn vị bị giải thể, chuỗi báo cáo bị vòng.

### 4.2.3 Các phép ghi theo thời gian
Mọi op được xây từ ba phép nguyên thuỷ trên một bảng phiên bản `T` của đối tượng `k`. Phép "thay" luôn là: set
`SupersededAt = now` cho dòng cũ, rồi insert (các) dòng mới với `RecordedAt = now`.

**(a) `SetFrom(k, d, patch)` — "từ ngày d, các trường trong `patch` có giá trị mới"**
```text
rows = phiên bản hiện hành của k có ValidTo IS NULL OR ValidTo > d, order by ValidFrom
for r in rows:
    thay r bằng:
      nếu r.ValidFrom < d:  [r.ValidFrom, d)  giữ nguyên giá trị r
                            [d, r.ValidTo)    = r + patch
      ngược lại (r bắt đầu sau d — thay đổi đã lên kế hoạch trước):
          với mỗi trường f trong patch:
              nếu r.f == giá trị cũ của f tại ngay trước r.ValidFrom (r KHÔNG chủ động đổi f)
                  → r.f = patch.f          (lan truyền)
              ngược lại → giữ r.f           (r đã có kế hoạch riêng cho f: tôn trọng, dừng lan truyền f)
      gộp các dòng liền kề có cùng giá trị (tránh phân mảnh)
```
Ví dụ (đơn vị "App"): đã có kế hoạch đổi tên thành "App Platform" từ 01/01. Hôm nay ra quyết định đổi cost center
sang CC-200 từ 01/12:

| Trước | | Sau `SetFrom(App, 01/12, {CostCenter: CC-200})` | |
|---|---|---|---|
| [01/06, 01/01) App, CC-100 | | [01/06, 01/12) App, CC-100 | |
| [01/01, ∞) App Platform, CC-100 | | [01/12, 01/01) App, **CC-200** | |
| | | [01/01, ∞) App Platform, **CC-200** ← lan truyền, vì bản 01/01 không chủ động đổi cost center | |

**(b) `Delimit(k, d)` — "đối tượng chấm dứt từ ngày d"**
```text
cắt mọi phiên bản hiện hành phủ hoặc sau d: phần trước d giữ lại, phần từ d trở đi bỏ
nếu có phiên bản bắt đầu sau d (kế hoạch tương lai) → CẢNH BÁO: kế hoạch đó bị huỷ, hiện trong ValidationReport
```

**(c) `Insert(k, [a, b), values)`** — tạo phiên bản cho đối tượng mới, hoặc cho khoảng đang trống.

**Ánh xạ op → phép nguyên thuỷ:**

| Op | Bảng | Phép |
|---|---|---|
| `CREATE_UNIT` | `ORG_UNIT` + `ORG_UNIT_VERSION` + `ORG_EDGE` (MANAGEMENT, và LEGAL nếu có) | Insert |
| `UPDATE_UNIT` | `ORG_UNIT_VERSION` | SetFrom |
| `MOVE_UNIT` | `ORG_EDGE` (theo `HierarchyType`) | SetFrom(`{ParentId}`) |
| `CLOSE_UNIT` | `ORG_UNIT_VERSION`, mọi `ORG_EDGE` của đơn vị, `ORG_UNIT_HEAD` | Delimit. Integrity C4/C5 chặn nếu còn đơn vị con hoặc ghế bên trong |
| `SET_UNIT_HEAD` / `CLEAR_UNIT_HEAD` | `ORG_UNIT_HEAD` | SetFrom / Delimit |
| `CREATE_POSITION` | `POSITION` + `POSITION_VERSION` | Insert |
| `UPDATE_POSITION`, `MOVE_POSITION`, `FREEZE_POSITION` | `POSITION_VERSION` | SetFrom |
| `SET_REPORTING` | `POSITION_VERSION` (`ReportingMode`, `ExplicitReportsToPositionId`) | SetFrom |
| `CLOSE_POSITION` | `POSITION_VERSION` | Delimit. C7 chặn nếu còn người ngồi |
| `ADD_MATRIX_LINE` / `END_MATRIX_LINE` | `POSITION_MATRIX_LINE` | Insert / Delimit |
| `HIRE` | `EMPLOYEE` (nếu chưa có) + `EMPLOYMENT` + `EMPLOYMENT_VERSION` + `ASSIGNMENT` PRIMARY | Insert |
| `REHIRE` | `EMPLOYMENT` mới (giữ `EmployeeCode`, có thể giữ `SeniorityDate`) + `ASSIGNMENT` | Insert |
| `ASSIGN` (điều chuyển / thăng chức) | `ASSIGNMENT` cũ + `ASSIGNMENT` mới | Delimit cũ tại d, Insert mới `[d, …)` |
| `ASSIGN` (quyền / kiêm nhiệm / biệt phái) | `ASSIGNMENT` | Insert `[a, b)` (thường có ngày kết thúc) |
| `END_ASSIGNMENT` | `ASSIGNMENT` | Delimit |
| `TERMINATE` | mọi `ASSIGNMENT` của `EMPLOYMENT` + `EMPLOYMENT_VERSION` | Delimit tại ngày nghỉ + 1, set `EndReason` |
| `CORRECT_RECORD` | bất kỳ bảng phiên bản nào | Supersede (các) dòng sai + Insert dòng đúng, không đổi `ValidFrom` của đối tượng khác |

### 4.2.4 Thay đổi hẹn ngày (tương lai)
- Change set có `EffectiveDate` trong tương lai **vẫn được áp ngay khi APPROVED**: các phiên bản có `ValidFrom`
  tương lai được ghi vào DB. Trạng thái "đã lên kế hoạch" hay "đang hiệu lực" **suy ra từ ngày**, không cần job ghi dữ liệu.
- Nhờ vậy, truy vấn `as_of` một ngày tương lai thấy được cơ cấu dự kiến (lập kế hoạch nhân sự, mô phỏng ngân sách).
  Validate cũng kiểm tra luôn xung đột với các kế hoạch khác.
- Job 00:05 hằng ngày có ba việc:
  1. `PKG_ORG_CACHE.Refresh`.
  2. Phát event `ChangeSetEffective{changeSetId}` cho các change set có `EffectiveDate = hôm nay`. Workflow dùng event
     này để định tuyến lại task (05 §5.6), IAM dùng để tính lại phạm vi quyền.
  3. Không ghi thêm dữ liệu nghiệp vụ nào.

### 4.2.5 Hồi tố, sửa sai, đảo quyết định
| Tình huống | Cách ghi | Hệ quả |
|---|---|---|
| **Quyết định hồi tố** (ký 15/09, hiệu lực 01/08) | Change set bình thường, item có `EffectiveDate` trong quá khứ. `RecordedAt` = 15/09 | `ChangeSetApplied{retroactive: true}` → Payroll ghi `RETRO_TRIGGER` (§4.6), Workflow **không** đổi các đơn đã duyệt |
| **Sửa sai** (nhập nhầm ngày vào làm) | Change set `Kind = CORRECTION`, op `CORRECT_RECORD` | Dòng sai được `SupersededAt`, vẫn còn để kiểm toán. Truy vấn với `known_at` trước lúc sửa vẫn thấy dữ liệu sai, đúng như hệ thống đã tin lúc đó |
| **Đảo quyết định** (huỷ reorg đã áp) | Engine sinh change set mới `CORRECTION`, supersede mọi dòng có `ChangeSetId = X` và khôi phục các dòng mà X đã supersede. Set `X.Status = REVERSED`, `X.ReversedByChangeSetId` | Chỉ cho phép nếu các dòng của X chưa bị change set sau chạm tới. Nếu đã bị chạm, engine liệt kê các change set phụ thuộc cần xử lý trước |

**Hiện thực (v3.4)**

- **Dòng nào bị quyết định nào thay thế**: migration V4 thêm `SupersededByChangeSetId` vào 7 bảng phiên bản, ghi cùng
  lúc với `SupersededAt` (trigger bất biến đảm bảo chỉ ghi một lần). Nhờ vậy đảo quyết định biết **chính xác** các dòng
  X đã vô hiệu, không phải đoán theo thời điểm.
- **Tách bạch**: `CORRECT_RECORD` / `REVERSE_CHANGE_SET` chỉ nằm trong change set `CORRECTION`, và change set
  `CORRECTION` chỉ chứa hai thao tác này. "Thay đổi thật" và "sửa ghi nhận sai" không bao giờ trộn trong một quyết định.
- **`CORRECT_RECORD`** — phép `Timeline.ReplaceWindow(cửa sổ [a, b), các phiên bản đúng)`:

  ```text
  với mỗi phiên bản hiện hành v:
      v nằm ngoài [a, b)  → giữ nguyên
      v cắt ngang biên     → giữ phần ngoài cửa sổ ([v.From, a) và/hoặc [b, v.To))
  thêm các phiên bản đúng (phải nằm trong [a, b), không chồng nhau)
  gộp liền kề cùng thuộc tính → diff theo nội dung (không đổi gì = lỗi "dữ liệu đã đúng")
  ```
  Khác `SetFrom`: **không lan truyền**. Người sửa khẳng định sự thật trong cửa sổ, còn ngoài cửa sổ giữ nguyên.
  Danh sách phiên bản rỗng nghĩa là xoá khoảng đã ghi nhầm (đối tượng không tồn tại trong cửa sổ).
  Thuộc tính gửi dạng JSON theo bảng (ví dụ `AssignmentAttrs`); khoá là `ObjectId`, cộng thêm `HierarchyType` với
  `ORG_EDGE`, hoặc `RelatedId` với `POSITION_MATRIX_LINE`.
- **`REVERSE_CHANGE_SET(X)`**, chạy trên 7 bảng phiên bản trong cùng transaction:
  1. Chặn nếu có dòng do X ghi đã bị quyết định **khác** thay thế (hoặc bị thay thế trước V4, khi chưa rõ quyết định).
     Thông báo lỗi liệt kê các quyết định đó.
  2. Thay thế mọi dòng hiện hành do X ghi (`SupersededByChangeSetId` = quyết định đảo). Bước này phải làm **trước**,
     để không vi phạm unique index "một phiên bản hiện hành bắt đầu tại một ngày".
  3. Khôi phục các dòng X đã thay thế dưới dạng bản sao mới (`ChangeSetId` = quyết định đảo, `RecordedAt` = lúc đảo),
     trừ các dòng trung gian do chính X ghi rồi tự thay thế.
  4. `PKG_INTEGRITY`, sau đó `X.Status = REVERSED` và `ReversedByChangeSetId`. Event `ChangeSetReversed` và
     `ChangeSetApplied{reversedChangeSetIds, retroactive}` được phát. Định danh do X tạo (đơn vị, ghế…) vẫn giữ, nhưng
     không còn phiên bản nào nên coi như không tồn tại.
- Event `RecordCorrected{table, objectId, windowFrom, windowTo, reason}` được phát cho mỗi lần sửa.
  `ChangeSetApplied.retroactive` tính theo ngày sớm nhất **thực sự bị chạm**, nên sửa hay đảo dữ liệu quá khứ đều kích
  hoạt `RETRO_TRIGGER` bên Payroll.

### 4.2.6 Đồng thời và phụ thuộc giữa các change set
- **Ghi**: khoá hàng `TENANT` khiến mọi apply trong một tenant chạy tuần tự. Tái cấu trúc hiếm và ngắn, nên đánh đổi
  này chấp nhận được.
- **Validate dựa trên bản chụp**: `BaseOrgVersion` được ghi lúc validate. Khi apply, nếu `OrgVersion` đã đổi thì
  engine validate lại trong cùng transaction.
- **Phụ thuộc**: khi change set A được áp, các change set `APPROVED` (chưa áp) hoặc `VALIDATED` chạm cùng đối tượng
  với A sẽ bị chuyển sang `NEEDS_REVALIDATION`. Hai change set được coi là chạm cùng đối tượng nếu giao của tập
  `TargetId` trong `CHANGE_ITEM` khác rỗng.
- **Sửa hồ sơ không qua change set** (`EMPLOYEE_PROFILE`): dùng optimistic lock, và lịch sử được ghi bằng Oracle
  Unified Auditing.

---

## 4.3 Chuỗi báo cáo và DOA theo ngày

### 4.3.1 Chuỗi báo cáo được SUY RA, không nhập tay
`PKG_ORG_QUERY.ManagerPosition(p, d)`:
```text
v = phiên bản của ghế p tại d                        (không có → NULL: ghế không tồn tại)
nếu v.ReportingMode = EXPLICIT → trả v.ExplicitReportsToPositionId
u = v.OrgUnitId
h = HeadPosition(u, d)
nếu h ≠ NULL và h ≠ p → trả h                        (nhân viên báo cáo cho trưởng đơn vị mình)
lặp:                                                  (p là trưởng, hoặc đơn vị không có trưởng)
    u = ParentOf(u, MANAGEMENT, d);  hết cây → trả NULL (đỉnh tổ chức)
    h = HeadPosition(u, d)
    nếu h ≠ NULL và h ≠ p → trả h
```
Hệ quả:
- **Di chuyển đơn vị thì chuỗi báo cáo tự đi theo.** Sau `MOVE_UNIT(App → Khối Sản phẩm)`, trưởng phòng App tự báo
  cáo cho trưởng Khối Sản phẩm từ ngày hiệu lực, không cần sửa ghế nào.
- **Đổi trưởng đơn vị** (`SET_UNIT_HEAD`): mọi ghế trong đơn vị tự đổi người quản lý.
- Ngoại lệ có chủ đích dùng `ReportingMode = EXPLICIT`. Integrity C6 chặn trường hợp EXPLICIT tạo ra vòng.
- Tuyến ma trận (`POSITION_MATRIX_LINE`) không nằm trong chuỗi này. Workflow chọn tuyến ma trận qua quy tắc `MATRIX_MANAGER`.

### 4.3.2 `PKG_DOA.ResolveApprovers(requester, asOf, levelsUp, minGrade, startPosition, knownAt)`
```text
p = startPosition ?? ghế PRIMARY của requester tại asOf
found = 0
lặp (tối đa 60, phát hiện vòng bằng tập đã thăm):
    p = ManagerPosition(p, asOf, knownAt);  NULL → trả rỗng (workflow dùng người duyệt dự phòng)
    nếu p.IsManager và GradeRank(p) ≥ minGrade:
        holders = Holders(p, asOf, knownAt) − {requester}     -- ACTING hiệu lực thì chỉ lấy ACTING
        nếu holders ≠ ∅:
            found += 1
            nếu found = levelsUp → trả holders (≥ 1 người; workflow tạo task chế độ ANY)
    (ghế trống / không đủ cấp / chỉ có chính requester → leo tiếp = leo thang tự động)
```
- **Theo ngày**: cả cây tổ chức, trưởng đơn vị, ghế và người ngồi đều được lọc theo `asOf`. Workflow chọn `asOf`
  theo chính sách của template: ngày kích hoạt bước (mặc định) hoặc ngày nghiệp vụ (05 §5.4).
- **Tái hiện**: `knownAt` cho biết lúc đó hệ thống đã giao việc cho ai, phục vụ kiểm toán và tranh chấp.
- **Quyền trưởng (ACTING)**: người được giao quyền **thay** người giữ ghế trong việc duyệt. Chuyện này khác với uỷ
  quyền cá nhân (`HR_WF.DELEGATION`), vốn được áp dụng sau bước này.
- **Chia sẻ ghế / đồng trưởng**: trả về nhiều người. Việc có cho phép hay không là chính sách của template (chế độ ANY / ALL).
- **Chi phí**: O(d·h), với d là số cấp leo và h là số bước leo cây đơn vị khi gặp ghế trưởng. Mỗi bước là một lần
  truy cập index (`IX_PV_LOOKUP`, `IX_HEAD_UNIT`, `IX_EDGE_CHILD`, `IX_ASG_POS`). Với d ≤ 10 và h ≤ 3, số truy cập
  là vài chục.

---

## 4.4 Định biên FTE theo khoảng thời gian

v2 chỉ kiểm tra số người **tại ngày bắt đầu**. Cách đó bỏ lọt trường hợp một người đã được xếp vào ghế từ một ngày
tương lai. v3 kiểm tra trên **mọi mốc** của khoảng thời gian bị ảnh hưởng:
```text
với mỗi ghế p bị chạm bởi change set:
    mốc = {ValidFrom của mọi ASSIGNMENT và POSITION_VERSION của p} ∪ {ngày sớm nhất bị chạm}, lọc ≥ ngày đó
    với mỗi mốc t:
        dùng(t)   = Σ Fte của ASSIGNMENT hiện hành phủ t, loại ACTING   (quyền trưởng không tiêu định biên)
        budget(t) = FteBudget của phiên bản ghế phủ t
        dùng(t) > budget(t) → LỖI (TENANT.HeadcountPolicy = HARD và change set không có HeadcountOverride)
                             → CẢNH BÁO (policy WARN, hoặc override kèm OverrideReason đã được duyệt)
```
Chỉ cần kiểm tra tại các mốc, vì tổng FTE là hàm bậc thang chỉ đổi giá trị tại các ranh giới. Chi phí O(m²) với m là
số dòng của một ghế (nhỏ). Trường hợp **bàn giao có chồng lấn** (người mới vào trước khi người cũ nghỉ 2 tuần) được
xử lý bằng override kèm lý do, và việc này được duyệt cùng change set, chứ không phải bằng cách nới ràng buộc cho tất cả.

---

## 4.5 Kiểm toàn vẹn trước commit — `PKG_INTEGRITY.VerifyChangeSet`

Oracle không có exclusion constraint, nên các bất biến theo thời gian được kiểm tra **trong cùng transaction**, ngay
trước commit. Việc kiểm tra chỉ áp dụng cho các đối tượng mà change set chạm tới, tại **mọi mốc thời gian liên quan**
từ ngày sớm nhất bị chạm trở đi.

| Mã | Bất biến | Mức |
|---|---|---|
| C1 | Không hai phiên bản hiện hành chồng khoảng trên cùng đối tượng (đơn vị, cạnh cây theo loại, trưởng đơn vị, ghế, employment, assignment, tuyến ma trận) | Lỗi |
| C1b | Một người không có hai quan hệ lao động chồng thời gian với **cùng** pháp nhân | Lỗi |
| C2 | Mỗi người tối đa một ghế PRIMARY tại mọi thời điểm | Lỗi |
| C3 | Không có vòng trong mọi loại cây | Lỗi |
| C4 | Cạnh cây chỉ nối các đơn vị đang tồn tại | Lỗi |
| C5 | Ghế nằm trong đơn vị đang tồn tại; ghế trưởng thuộc đúng đơn vị mà nó làm trưởng | Lỗi |
| C6 | Chuỗi báo cáo (sau khi suy ra) không có vòng | Lỗi |
| C7 | Assignment nằm trọn trong employment; ghế tồn tại suốt khoảng; không bắt đầu vào ghế FROZEN | Lỗi |
| C8 | Tổng FTE ≤ định biên tại mọi mốc | Lỗi / Cảnh báo (§4.4) |
| C9 | Tổng FTE của một người ≤ 1 | Cảnh báo |

Nếu có lỗi, `RAISE` sẽ làm engine `ROLLBACK` toàn bộ change set. Báo cáo JSON được lưu vào
`CHANGE_SET.ValidationReport`. Số mốc kiểm tra được giới hạn ở 400 mốc gần nhất, đủ cho kế hoạch vài năm.

---

## 4.6 Lương hồi tố

### Vấn đề
Ngày 15/09 có quyết định tăng lương từ 20 triệu lên 25 triệu, **hiệu lực từ 01/08**. Kỳ lương tháng 8 đã khoá và trả
theo mức cũ. Ngoài đổi lương, còn các nguồn thay đổi khác cũng làm lương cũ sai: **điều chuyển hoặc thăng chức hồi tố**
(đổi phụ cấp chức vụ, đổi cost center), **sửa ngày vào làm**, và **sửa công sau khi đã khoá kỳ**.

### Bước A — Ghi nhận thay đổi (bitemporal, không sửa dòng nào)
`PKG_COMP.ChangeAmount(emp, 'BASE_SALARY', 25000000, DATE '2026-08-01', 'DECISION:QD-091')`:

| Id | Amount | ValidFrom | ValidTo | RecordedAt | SupersededAt |
|---|---|---|---|---|---|
| s1 | 20,000,000 | 2026-06-01 | ∞ | 2026-06-01 | **2026-09-15** |
| s2 | 20,000,000 | 2026-06-01 | 2026-08-01 | 2026-09-15 | |
| s3 | 25,000,000 | 2026-08-01 | ∞ | 2026-09-15 | |

### Bước B — Phát hiện: một cửa vào duy nhất là `HR_PAY.RETRO_TRIGGER`
| Nguồn | Ai ghi |
|---|---|
| Đổi lương hiệu lực trong kỳ đã khoá | `PKG_COMP.ChangeAmount` |
| Change set CoreHR có `retroactive = true` | Consumer `ChangeSetApplied`: mỗi nhân viên trong `touched.employees` một dòng, `FromDate` = ngày sớm nhất bị chạm |
| Sửa công sau khi khoá kỳ | Consumer `AttendanceCorrected` của T&A |

Lần tính lương kế tiếp lấy mọi dòng có `ConsumedByCalcRunId IS NULL`. Mỗi (nhân viên, kỳ đã khoá có `EndDate > FromDate`)
là một cặp cần tính lại. Tính xong thì set `ConsumedByCalcRunId`. `UQ (EmployeeId, SourceRef)` đảm bảo event giao
lặp không sinh trùng.

### Bước C — Tính chênh lệch cho mỗi cặp (e, P)
- **Đáng lẽ** = tính kỳ P theo hiểu biết **hiện tại**: lương, phụ cấp theo ghế và cost center tại từng đoạn thời
  gian (`ASSIGNMENT` + `POSITION_VERSION` lấy từ CoreHR qua API as-of), pro-rata theo ngày công.
- **Đã trả** = dòng `EARNING` của phiếu lương P, cộng các dòng `RETRO_EARNING` có `RetroForPeriodId = P` thuộc những
  kỳ **đã khoá** sau P.
- **Chênh lệch** = Đáng lẽ − Đã trả, tính theo từng khoản. Ví dụ: 25,000,000 − 20,000,000 = **+5,000,000**.

### Bước D — Ghi vào kỳ đang mở
Thêm `PAYSLIP_DETAIL(LineType = 'RETRO_EARNING', Amount = 5,000,000, RetroForPeriodId = <kỳ 08>)`. Các dòng này là
**idempotent**: dòng của kỳ đang mở được tính lại mỗi lần chạy (`CalcRunId` mới), và "đã trả" chỉ lấy các kỳ đã khoá.

### Bước E — Thuế và bảo hiểm (giả định thiết kế, **cần C&B/pháp chế xác nhận**)
- **Thuế TNCN**: khoản truy lĩnh được cộng vào thu nhập chịu thuế của **kỳ chi trả**.
- **BHXH/BHYT/BHTN**: truy đóng cho **kỳ gốc**, sinh dòng `RETRO_SOCIAL_INS`. Trần đóng bảo hiểm tính theo kỳ gốc.

### Bước F — Tái hiện phiếu lương cũ
Tính lại kỳ P với `known_at = P.LockedAt`: dùng lương từ `SALARY_COMPONENT` và cơ cấu từ CoreHR, cả hai lọc theo
`RecordedAt ≤ LockedAt < SupersededAt`. Kết quả phải khớp từng đồng với phiếu lương đã trả.

---

## 4.7 Kịch bản mẫu — tái cấu trúc từ đầu đến cuối

**Bối cảnh**: quyết định QĐ-2026-120, ký ngày 20/09, hiệu lực 01/10: chuyển "Phòng App" từ "Khối Công nghệ" sang
"Khối Sản phẩm", lập thêm ghế "Mobile Lead", và điều chuyển An sang ghế đó.

| # | CHANGE_ITEM | Phép |
|---|---|---|
| 1 | `MOVE_UNIT(App, MANAGEMENT, parent = Khối Sản phẩm)` | SetFrom trên `ORG_EDGE` |
| 2 | `UPDATE_UNIT(App, CostCenter = CC-PRD-07)` | SetFrom trên `ORG_UNIT_VERSION` |
| 3 | `CREATE_POSITION(MOB-LEAD-01, unit = App, job = Lead M1, FTE 1, IsManager)` | Insert |
| 4 | `ASSIGN(An → MOB-LEAD-01, PRIMARY, reason = PROMOTION)` | Delimit ASSIGNMENT cũ tại 01/10 + Insert mới |

1. **20/09, lập change set, trạng thái DRAFT → Validate** (dry-run). Kết quả:
   - C8 báo lỗi nếu MOB-LEAD-01 đã có người được xếp từ 15/10.
   - Cảnh báo: có một change set khác (QĐ-118, hiệu lực 01/11) cũng chạm "Phòng App", nên QĐ-118 sẽ bị chuyển sang
     `NEEDS_REVALIDATION` khi QĐ-120 được áp.
2. **Duyệt** qua approval engine (`ORG_CHANGE`), rồi **Apply ngay** dù hiệu lực là 01/10:
   - Các phiên bản `[01/10, …)` được ghi vào DB.
   - `ChangeSetApplied{retroactive: false}` được phát.
   - Truy vấn `as_of` 05/10 đã thấy cơ cấu mới, còn `as_of` hôm nay vẫn thấy cơ cấu cũ.
3. **Ngày 01/10, 00:05**: job refresh cache và phát `ChangeSetEffective`. Workflow định tuyến lại các task PENDING
   đang ở cấp giám đốc Khối Công nghệ mà người nộp thuộc Phòng App (05 §5.6). IAM tính lại phạm vi quyền của các
   HRBP phụ trách khối.
4. **Từ 01/10**:
   - Trưởng phòng App **tự động** báo cáo cho trưởng Khối Sản phẩm (INHERIT), không cần sửa ghế nào.
   - Đơn nghỉ phép (template `LEAVE`, `ResolveAsOf = ACTIVATION_DATE`) nộp ngày 02/10 cho ngày nghỉ 28/09 được giao
     cho **trưởng Khối Sản phẩm** — người đang quản lý tại lúc duyệt. Quyết định điều chuyển (template
     `PERSONNEL_ACTION`, `ResolveAsOf = BUSINESS_DATE`) thì lấy quản lý tại ngày hiệu lực của quyết định (05 §5.4).
5. **Ngày 10/10 phát hiện ngày điều chuyển của An đúng ra là 15/10**: lập change set `CORRECTION` với
   `CORRECT_RECORD`. Dòng cũ được supersede và còn lại để kiểm toán. `ChangeSetApplied{retroactive: true}` được phát,
   Payroll ghi `RETRO_TRIGGER` cho An từ 01/10, và kỳ lương tháng 10 tự tính lại phụ cấp.

---

## 4.8 Giới hạn đã biết và hướng mở rộng

| Hạng mục | Hiện trạng | Hướng mở rộng |
|---|---|---|
| Ghi cơ cấu tuần tự theo tenant | Một khoá / tenant | Khoá theo cây con nếu tần suất reorg tăng (hiếm khi cần) |
| Mốc kiểm toàn vẹn | Tối đa 400 mốc | Nếu kế hoạch dài hơn: kiểm theo cửa sổ và nightly full-check |
| Cache cây hiện tại | Dựng lại toàn bộ O(n) | Cập nhật tăng dần theo change set nếu n > 100k đơn vị |
| Ngân sách định biên theo tiền | Chỉ FTE | Bảng `POSITION_BUDGET` (lương dự kiến, theo năm tài chính) |
| Ghế dùng chung mã giữa các pháp nhân | Không | Chưa có nhu cầu |
| Lịch sử PII | Unified Auditing, không lưu bản sao | Đúng theo Nghị định 13/2023; nếu cần lịch sử tên/địa chỉ để in chứng từ cũ thì thêm `EMPLOYEE_NAME_VERSION` riêng |
