# CoreHR — Change Engine

Hiện thực của đặc tả [04 §4.2 Change Engine](../../../docs/System_Design/04_Core_Algorithms.md): mọi thay đổi cơ cấu tổ
chức và nhân sự đi qua một **quyết định (change set)** được validate, duyệt, rồi áp **nguyên khối** trên dữ liệu
bitemporal bất biến của schema `HR_CORE`.

## Kiến trúc

| Project | Vai trò | Phụ thuộc |
|---|---|---|
| `Hris.CoreHR.Domain` | Thuần logic: `Timeline` (phép ghi theo thời gian `SetFrom` / `Delimit` / `Insert` / `ReplaceWindow` + lan truyền + gộp + diff), thuộc tính phiên bản, `ChangeSet` (state machine, luật tách bạch CORRECTION), `ChangeOperation` (18 thao tác, JSON đa hình theo `op`) | — |
| `Hris.CoreHR.Application` | `ChangeEngine`: Create / AddItem / Validate (dry-run) / Submit / Approve / Apply / Cancel; ánh xạ thao tác → phép ghi; outbox event | Domain |
| `Hris.CoreHR.Infrastructure` | `OracleChangeStore` (ADO.NET / ODP.NET, user `HRIS_COREHR`), `OrgQueries` (cây theo ngày, người duyệt qua `PKG_ORG_QUERY` / `PKG_DOA`) | Application, `Oracle.ManagedDataAccess.Core` |
| `Hris.CoreHR.Api` | REST: `api/change-sets`, `api/org-units/{id}/tree`, `api/employees/{id}/approvers` | Infrastructure |

```
 API ──► ChangeEngine ──► Timeline (thuần)          ──► diff: dòng thay thế + dòng thêm
              │
              └──► IChangeStore (1 transaction) ──► Oracle HR_CORE
                     · khoá TENANT (tuần tự hoá)       · INSERT + UPDATE(SupersededAt) — không UPDATE cột khác, không DELETE
                     · PKG_INTEGRITY trước commit      · OUTBOX_MESSAGE cùng transaction
```

### Luồng Apply
1. `SELECT ... FOR UPDATE` hàng `CHANGE_SET` (phải `APPROVED`) và hàng `TENANT`.
2. Với từng item theo `Seq`: nạp phiên bản hiện hành → phép ghi thuần → ghi diff (thay thế + thêm) cùng `RecordedAt`
   (giờ DB) và `ChangeSetId`.
3. `PKG_INTEGRITY.VerifyChangeSet` (C1–C9 tại mọi mốc thời gian). Có lỗi → **ROLLBACK toàn bộ**, change set chuyển
   `NEEDS_REVALIDATION` kèm báo cáo.
4. `OrgVersion + 1`, `APPLIED`, outbox (`ChangeSetApplied{retroactive, touched}`, `EmployeeHired`, `AssignmentChanged`,
   `EmployeeTerminated`), quyết định khác chạm cùng đối tượng → `NEEDS_REVALIDATION`, refresh cache cây nếu hiệu lực
   ≤ hôm nay → **COMMIT**.

Validate chạy đúng các bước 1–3 rồi **ROLLBACK** (dry-run), lưu báo cáo và `BaseOrgVersion`.

### Quy ước
- `Guid` ↔ `RAW(16)` big-endian: `RAWTOHEX(Id)` trong DB = `Guid.ToString("N")` (chữ hoa).
- `DateOnly` ↔ `DATE`; `RecordedAt` lấy từ `SYSTIMESTAMP` của DB (một giá trị cho cả lần áp).
- Tên bind không trùng từ khoá Oracle (`:by`, `:at`… gây ORA-01745).

## Chạy

```bash
cd database && docker compose up -d oracle && docker compose run --rm flyway migrate && cd ..
export ConnectionStrings__CoreHr="User Id=HRIS_COREHR;Password=<COREHR_PASSWORD trong database/.env>;Data Source=//localhost:1521/FREEPDB1"
dotnet run --project src/Services/CoreHR/Hris.CoreHR.Api --urls http://localhost:5074
```
Ví dụ gọi API: [`Hris.CoreHR.Api.http`](Hris.CoreHR.Api/Hris.CoreHR.Api.http). Connection string không nằm trong repo
(biến môi trường hoặc `dotnet user-secrets`).

## Test

```bash
dotnet test --project tests/Hris.CoreHR.Domain.Tests        # 23 test, không cần DB
dotnet test --project tests/Hris.CoreHR.IntegrationTests    # 13 test trên Oracle dev — tự Skip nếu không có DB
```
Integration test chạy bằng user `HRIS_COREHR` trên dữ liệu seed, mỗi test trong một transaction **ROLLBACK** ở cuối
(engine lồng qua savepoint) — DB dev không bị bẩn. Mật khẩu đọc từ `HRIS_COREHR_CONNECTION` hoặc `database/.env`.

| Integration test | Kiểm |
|---|---|
| Reorg chuyển Phòng App sang Khối Sản phẩm | chuỗi duyệt tự đi theo từ ngày hiệu lực; ghế CPO trống → leo thang CEO; dòng cũ bị thay thế chứ không xoá; OrgVersion +1; outbox |
| Vượt định biên FTE | lỗi C8; có override + lý do → chỉ cảnh báo; validate không ghi dòng nào |
| Chuyển đơn vị vào cây con của chính nó | lỗi C3 |
| Quyết định sau không ghi đè kế hoạch đã có | đổi tên hẹn 90 ngày giữ nguyên khi đổi cost center hẹn 30 ngày; cost center lan truyền sang kế hoạch |
| Quyết định chờ bị vô hiệu | quyết định khác chạm cùng đơn vị được áp → `NEEDS_REVALIDATION` |
| Apply khi chưa duyệt | bị từ chối |
| Nghỉ việc | đóng quan hệ lao động + mọi bổ nhiệm, `EmployeeTerminated`, không còn người duyệt sau ngày nghỉ |
| Quyết định hồi tố | `ChangeSetApplied.retroactive = true` |
| User ứng dụng sửa / xoá lịch sử | ORA-41900 (thiếu quyền) |
| Sửa sai ngày điều chuyển (`CORRECT_RECORD`) | hiện tại thấy ngày đúng; hỏi với `knownAt` trước lúc sửa vẫn thấy đúng như hệ thống đã tin; dòng sai còn lại, biết quyết định nào đã vô hiệu nó; `RecordCorrected` |
| Đảo quyết định chuyển phòng (`REVERSE_CHANGE_SET`) | cơ cấu trở lại như trước; quyết định gốc `REVERSED` + `ReversedByChangeSetId`; dòng khôi phục là bản sao mới; OrgVersion +2; `ChangeSetReversed` |
| Đảo quyết định đã bị quyết định sau chạm tới | bị chặn, thông báo nêu quyết định phụ thuộc; quyết định gốc vẫn `APPLIED` |
| Đảo quyết định chưa áp | bị chặn |

### Sửa sai và đảo quyết định
Chỉ trong change set `CORRECTION` (và change set đó chỉ chứa hai thao tác này):

```jsonc
// Sửa: thay nội dung cửa sổ [windowFrom, windowTo) của một đối tượng — không lan truyền
{ "op": "CORRECT_RECORD", "table": "ASSIGNMENT", "objectId": "<AssignmentKey>",
  "windowFrom": "2026-10-01", "windowTo": null, "reason": "Ngày điều chuyển đúng là 15/10",
  "versions": [ { "from": "2026-10-15", "to": null,
                  "attrs": { "employmentId": "…", "employeeId": "…", "positionId": "…",
                             "assignmentType": "PRIMARY", "fte": 1, "startReason": "PROMOTION", "endReason": null } } ] }

// Đảo: khôi phục trạng thái trước quyết định X (bị chặn nếu quyết định sau đã chạm dòng của X)
{ "op": "REVERSE_CHANGE_SET", "targetChangeSetId": "<X>", "reason": "Quyết định bị thu hồi" }
```

## Chưa làm
- `approve` đang gọi tay; nối với Workflow service qua event `ApprovalCompleted` khi service đó có.
- Outbox relay → Kafka chưa có (event nằm trong `OUTBOX_MESSAGE`).
- Xác thực: người thao tác lấy từ header `X-User` tạm thời.
