# 1. TỔNG QUAN KIẾN TRÚC (ARCHITECTURE OVERVIEW)

| | |
|---|---|
| **Dự án** | HRIS Enterprise — Human Resources Information System quy mô tập đoàn (dự án cá nhân) |
| **CSDL** | Oracle Database 23ai (trước đây gọi là 23c) |
| **Kiến trúc** | Microservices theo Domain-Driven Design, giao tiếp bất đồng bộ qua Kafka |
| **Code** | .NET 10 — CoreHR: Domain / Application (Change Engine) / Infrastructure (Oracle) / Api ([README](../../src/Services/CoreHR/README.md)); Recruitment; `src/Shared/Hris.Shared.Contracts`; `tests/` |
| **Bộ tài liệu** | 00 Schema SQL · 01 Kiến trúc · 02 ERD · 03 Data Dictionary · 04 Thuật toán · 05 Workflow |
| **Database** | [`database/`](../../database/README.md): Oracle 23 Free + Flyway (V1 schema, V2 user ứng dụng, V3 …), dev seed, test kịch bản |

---

## 1.1 NGUYÊN TẮC KIẾN TRÚC LÕI

Mục tiêu vận hành: hệ thống phải chịu được **cơ cấu nhân sự phức tạp** (nhiều pháp nhân, nhiều tầng, kiêm nhiệm,
quyền trưởng, báo cáo ma trận), **thay đổi thường xuyên** (tái cấu trúc hẹn ngày, hồi tố, sửa sai), và vẫn **ghi
nhận đúng quá trình**: ở bất kỳ ngày nào, hệ thống trả lời được "cơ cấu lúc đó thế nào" và "lúc đó hệ thống đã tin
điều gì".

### P1. Position-based — tách người khỏi ghế, ghế khỏi đơn vị
- `EMPLOYEE` (con người), `POSITION` (ghế / định biên) và `ORG_UNIT` (đơn vị) là ba đối tượng độc lập, mỗi đối
  tượng có lịch sử riêng.
- Người ngồi ghế qua `ASSIGNMENT`, với bốn loại:
  - `PRIMARY`: ghế chính.
  - `CONCURRENT`: kiêm nhiệm.
  - `ACTING`: quyền trưởng.
  - `SECONDMENT`: biệt phái.
  Mỗi assignment có tỷ lệ **FTE**.
- Quan hệ lao động với từng **pháp nhân** (`EMPLOYMENT`) được tách khỏi việc ngồi ghế. Nhờ vậy xử lý được chuyển
  pháp nhân trong tập đoàn, tuyển lại và thâm niên.
- Định biên là **FTE theo thời gian** (`POSITION_VERSION.FteBudget`), được kiểm tra trên cả khoảng thời gian chứ không
  chỉ tại ngày bắt đầu.

### P2. Mọi thứ trong cơ cấu đều theo thời gian (bitemporal), và bất biến
- Mẫu chung: **bảng định danh bất biến + các bảng phiên bản**, tách theo nhóm thuộc tính thay đổi độc lập (tên đơn
  vị ≠ vị trí trong cây ≠ trưởng đơn vị). Chi tiết ở 04 §4.1.
- Hai trục thời gian:

  | Trục | Cột | Ý nghĩa |
  |---|---|---|
  | Valid time | `ValidFrom`, `ValidTo` | Điều này đúng ngoài đời từ ngày nào đến ngày nào (nửa mở; `NULL` = vô hạn) |
  | Transaction time | `RecordedAt`, `SupersededAt` | Hệ thống biết điều này từ lúc nào đến lúc nào |

- **Dòng phiên bản bất biến tuyệt đối**. Đó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ột: role ứng dụng chỉ có `UPDATE (SupersededAt)`.
- Trạng thái "đang làm việc", "đơn vị còn hoạt động" hay "ai là trưởng" **không lưu thành cột trạng thái**, mà được
  suy ra từ phiên bản phủ ngày đang hỏi.

### P3. Mọi thay đổi đi qua một quyết định (Change Set) và được kiểm toàn vẹn trước khi commit
- `CHANGE_SET` là một quyết định có số hiệu và ngày hiệu lực, gồm các `CHANGE_ITEM`. Change set được **validate**
  (dry-run), **duyệt**, rồi **áp nguyên khối** trong một transaction.
- Hỗ trợ đủ năm loại thay đổi: hẹn ngày (tương lai), hồi tố, sửa sai (`CORRECTION`), đảo quyết định (`REVERSED`),
  và phát hiện xung đột giữa các quyết định (`NEEDS_REVALIDATION`).
- Mọi dòng dữ liệu mang `ChangeSetId`, nên truy được quyết định sinh ra nó.
- `PKG_INTEGRITY.VerifyChangeSet` kiểm tra các bất biến (không chồng lấn, không vòng, ghế nằm trong đơn vị còn tồn
  tại, định biên FTE…) tại **mọi mốc thời gian** liên quan. Có lỗi thì rollback. Chi tiết ở 04 §4.2, §4.5.

### P3b. Chuỗi báo cáo được suy ra từ cây tổ chức
- Mặc định (`ReportingMode = INHERIT`): ghế báo cáo cho **ghế trưởng** của đơn vị mình. Nếu chính ghế là trưởng,
  hoặc đơn vị không có trưởng, thì báo cáo cho trưởng của đơn vị cha gần nhất. Hệ quả là **di chuyển đơn vị hay đổi
  trưởng thì chuỗi duyệt tự đi theo**.
- Ngoại lệ có chủ đích dùng `EXPLICIT`. Tuyến chuyên môn / dự án dùng `POSITION_MATRIX_LINE`.
- Nhiều loại cây song song: `MANAGEMENT` (quản trị, dùng cho DOA), `LEGAL` (pháp nhân), `FINANCIAL` (trung tâm
  chi phí).

| Truy vấn | Kỹ thuật | Chi phí |
|---|---|---|
| Cây con **tại một ngày bất kỳ** | Recursive CTE trên `ORG_EDGE` lọc theo ngày | O(k), với k = kích thước cây con |
| Cây con **hôm nay** (truy vấn nóng: phạm vi quyền, báo cáo) | Cache `ORG_PATH_CURRENT`, `Lineage LIKE 'prefix%'` | O(log n + k) |
| Người duyệt tại ngày d | `PKG_DOA.ResolveApprovers`: leo `ManagerPosition` | O(d·h), với d = số cấp, h = số bước leo cây đơn vị |
| Tái cấu trúc | Change set: `SetFrom` trên `ORG_EDGE` | O(số item). Chuỗi báo cáo không phải ghi lại |

### P4. Mỗi service sở hữu dữ liệu của mình (Database-per-Service)
- Mỗi service có **một schema Oracle riêng**. Không có FK xuyên schema, và không service nào đọc bảng của service khác.
- Tham chiếu sang service khác là `RAW(16)` thuần, được đồng bộ bằng **event** (Kafka) hoặc lấy qua **API** (gRPC).
- Logic cần dữ liệu tổ chức (tìm người duyệt DOA, cây theo ngày) nằm ở **CoreHR**. Workflow service gọi
  `ResolveApprovers` qua gRPC chứ không `JOIN` chéo DB.
- **Change Engine** chạy trong CoreHR (.NET), được test ở tầng domain. DB giữ các bất biến rẻ và chắc chắn
  (constraint, trigger bất biến, `PKG_INTEGRITY`) cùng các hàm đọc theo thời gian.

### P5. Nhất quán dữ liệu giữa các service
- **Transactional Outbox**: event được ghi vào `OUTBOX_MESSAGE` **trong cùng transaction** với dữ liệu nghiệp vụ.
  Một relay đọc outbox và đẩy sang Kafka, đảm bảo *at-least-once*.
- **Idempotent Consumer**: bảng `INBOX_MESSAGE(MessageId, Consumer)` kết hợp khoá nghiệp vụ (ví dụ
  `EMPLOYEE.SourceCandidateId`), nên một event bị giao lặp lại chỉ được xử lý một lần.
- **Saga (choreography)** cho các luồng dài như tuyển dụng → nhận việc, có event bù trừ khi thất bại
  (chi tiết ở [05_Workflow_Model.md](05_Workflow_Model.md)).

### P6. Bảo mật dữ liệu cá nhân (PII)
- PII được tách sang `EMPLOYEE_PROFILE`, có quyền truy cập riêng.
- Production: bật TDE column encryption cho `NationalId`, `TaxCode`, `SocialInsNo` và `BankAccNumber`, và áp
  `DBMS_REDACT` cho mọi role ngoài `HR_PII_READER`.
- **Không** đưa lương hay PII vào topic Kafka dùng chung (xem mục 1.4).

---

## 1.2 BOUNDED CONTEXT VÀ SERVICE TRIỂN KHAI

Có 10 bounded context (BC) nghiệp vụ. Không phải BC nào cũng là một service riêng: các BC gắn chặt về giao dịch
được gộp chung một service, để tránh transaction phân tán.

| # | Bounded Context | Phạm vi | Service triển khai | Schema |
|---|---|---|---|---|
| 1 | Organization Management (OM) | Cây tổ chức đa phân cấp theo thời gian, ghế/định biên FTE, chức danh, change set, DOA | **CoreHR** | `HR_CORE` |
| 2 | Core Employee (CE) | Hồ sơ, pháp nhân – quan hệ lao động, bổ nhiệm (chính/kiêm nhiệm/quyền/biệt phái), hợp đồng | **CoreHR** | `HR_CORE` |
| 3 | Time & Attendance (T&A) | Ca, chấm công, nghỉ phép, OT | TimeAttendance | `HR_TA` |
| 4 | Payroll & Compensation (PY) | Cấu trúc lương, kỳ lương, phiếu lương, thuế, BHXH | **Payroll** | `HR_PAY` |
| 5 | Applicant Tracking (ATS) | Tin tuyển dụng, ứng viên, phỏng vấn, offer | **Recruitment** | `HR_ATS` |
| 6 | Performance & Goal (PM) | KPI, OKR, đánh giá định kỳ | Talent | `HR_TAL` |
| 7 | Learning & Development (L&D) | Khoá học, lớp, chứng chỉ | Talent | `HR_TAL` |
| 8 | Talent & Succession (TM) | 9-Box, kế nhiệm | Talent | `HR_TAL` |
| 9 | Offboarding & Asset (OA) | Nghỉ việc, bàn giao, tài sản | Offboarding | `HR_OFF` |
| 10 | System & Workflow (SYS) | Phê duyệt động, RBAC, tenant | **Workflow** + Identity | `HR_WF` |

**In đậm** là các service đã có schema chi tiết trong [00_Init_Oracle_Schema.sql](00_Init_Oracle_Schema.sql).
Các BC còn lại mới được mô tả ở mức ERD (02).

Vì sao OM và CE nằm chung **CoreHR**? Vì một quyết định tái cấu trúc vừa di chuyển đơn vị, vừa lập ghế, vừa điều
chuyển người, và phải được **kiểm toàn vẹn rồi áp nguyên khối trong một transaction**: định biên FTE, ghế không nằm
trong đơn vị đã giải thể, chuỗi báo cáo không có vòng. Nếu tách làm hai service thì những bất biến này trở thành
eventual consistency, và một quyết định có thể chỉ được áp một nửa.

```
                    ┌──────────────┐
    Web / Mobile ──►│ API Gateway  │── JWT (Identity) ── RBAC + TenantId
                    └──────┬───────┘
         ┌─────────────┬───┴─────────┬──────────────┬──────────────┐
         ▼             ▼             ▼              ▼              ▼
   ┌──────────┐  ┌────────────┐ ┌──────────┐  ┌───────────┐  ┌──────────┐
   │ CoreHR   │  │Recruitment │ │ Payroll  │  │ Workflow  │  │ T&A ...  │
   │ HR_CORE  │  │  HR_ATS    │ │  HR_PAY  │  │  HR_WF    │  │          │
   └────┬─────┘  └─────┬──────┘ └────┬─────┘  └─────┬─────┘  └────┬─────┘
        │   Outbox     │   Outbox    │              │  gRPC        │
        │              │             │  ResolveApprovers ──► CoreHR│
        └──────────────┴──────┬──────┴──────────────┴──────────────┘
                              ▼
                     ┌─────────────────┐
                     │  Kafka (topics) │
                     └─────────────────┘
```

---

## 1.3 GIAO TIẾP GIỮA CÁC SERVICE

| Kiểu | Khi nào dùng | Ví dụ |
|---|---|---|
| **Event (Kafka)** | Thông báo một việc **đã xảy ra**, nơi nhận tự phản ứng | `EmployeeHired`, `ChangeSetApplied`, `ApprovalCompleted` |
| **gRPC (sync)** | Cần câu trả lời **ngay** để tiếp tục, và dữ liệu thuộc service khác | Workflow → CoreHR `ResolveApprovers` (as-of) |
| **REST** | Client bên ngoài (Web/Mobile) gọi qua API Gateway | `POST /api/candidates/{id}/hire` |

---

## 1.4 DANH MỤC EVENT CHÍNH

| Event | Producer | Consumer | Payload tối thiểu |
|---|---|---|---|
| `OfferAccepted` | Recruitment | CoreHR, Payroll | xem bên dưới |
| `ChangeSetApplied` | CoreHR | Payroll (`RETRO_TRIGGER` nếu `retroactive`), Workflow, IAM, Reporting | `changeSetId`, `kind`, `effectiveDate`, `retroactive`, `touched{orgUnits, positions, employees}` |
| `ChangeSetEffective` | CoreHR (job 00:05) | Workflow (định tuyến lại task), IAM (tính lại phạm vi quyền) | `changeSetId`, `effectiveDate` |
| `EmployeeHired` | CoreHR | Payroll, IT Provisioning, L&D, Asset | `employeeId`, `employmentId`, `positionId`, `validFrom` |
| `HireRejected` | CoreHR | Recruitment (bù trừ) | `offerId`, `reasonCode` |
| `AssignmentChanged` | CoreHR | Payroll, Workflow | `employeeId`, `assignmentKey`, `positionId`, `assignmentType`, `reason`, `validFrom`, `validTo` |
| `EmployeeTerminated` | CoreHR | Payroll, Workflow, Asset, Identity | `employeeId`, `lastDay`, `reason` |
| `ApprovalCompleted` | Workflow | Service sở hữu `SourceRefId` | `requestId`, `sourceRefId`, `outcome` |

**Envelope chuẩn** cho mọi event: `EventId` (khoá idempotent), `EventType`, `TenantId`, `OccurredAt`,
`CorrelationId` và `SchemaVersion`.

> **Cần sửa code hiện tại** — [CandidateHiredEvent.cs](../../src/Shared/Hris.Shared.Contracts/CandidateHiredEvent.cs)
> đang có các vấn đề sau:
> - Dùng `string PositionApplied` và `BranchCode`, trong khi mô hình dữ liệu dùng `PositionId` (Guid) và
>   không có khái niệm "Branch" (chi nhánh chính là một `ORG_UNIT` có `OrgType`).
> - Mang `Salary` lên topic dùng chung.
>
> Contract đề xuất, đổi tên thành `OfferAccepted` vì ứng viên chỉ thành nhân viên **sau khi** CoreHR xác nhận
> còn định biên:
>
> ```csharp
> public record OfferAccepted(
>     Guid EventId, Guid TenantId, DateTimeOffset OccurredAt, Guid CorrelationId,
>     Guid OfferId, Guid CandidateId, string FullName, string WorkEmail,
>     Guid PositionId, DateOnly StartDate);
> // Lương KHÔNG nằm trong event: Payroll gọi Recruitment GET /offers/{id}/compensation
> // (endpoint yêu cầu scope payroll.read) hoặc đọc topic riêng có ACL hạn chế.
> ```

---

## 1.5 YÊU CẦU PHI CHỨC NĂNG (NFR)

| Hạng mục | Mục tiêu | Cách đạt |
|---|---|---|
| Audit | Truy vết mọi thay đổi nhân sự, lương và phê duyệt | Bitemporal + `APPROVAL_LOG` append-only + trigger chặn sửa/xoá |
| Nhất quán | Không mất event, không tạo trùng nhân viên | Outbox + Inbox + unique `SourceCandidateId` |
| Đồng thời | Không vượt định biên, không chồng lấn, không áp nửa quyết định | Khoá hàng `TENANT` khi apply + `PKG_INTEGRITY` trước commit + `BaseOrgVersion` / `NEEDS_REVALIDATION` |
| Lịch sử | Trả lời "cơ cấu ngày X" và "lúc T hệ thống tin gì" | Bitemporal toàn phần + hàm đọc `as_of` / `known_at` |
| Tái cấu trúc | Di chuyển khối vài trăm đơn vị; chuỗi duyệt tự đi theo | `SetFrom` trên `ORG_EDGE` (O(số item)); báo cáo INHERIT không phải ghi lại |
| Đa tenant | Cô lập dữ liệu | `TenantId` trên mọi bảng; production dùng thêm VPD/RLS policy |
| PII | Tuân thủ Nghị định 13/2023 về bảo vệ dữ liệu cá nhân | Tách bảng, TDE, Redaction, không đưa PII lên event |

---

## 1.6 NHẬT KÝ THAY ĐỔI THIẾT KẾ

| Phiên bản | Thay đổi chính |
|---|---|
| v1 (27/09/2026) | Bản đầu: 10 BC, schema lõi 5 bảng, 3 thuật toán |
| v2 (27/09/2026) | Sửa trigger `Lineage` bị ORA-04091 → `PKG_ORG`. Sửa DOA (loại người nộp, `NOCYCLE`, lấy node gần nhất). Chuyển sang bitemporal cho lương và công tác. Mỗi service một schema. Thêm Outbox/Inbox. Đồng bộ data dictionary với SQL. Sửa cardinality ERD. Thêm mô hình Workflow (05). |
| v3 (27/09/2026) | **Mục tiêu vận hành enterprise.** Cơ cấu tổ chức toàn phần theo thời gian (định danh + phiên bản bitemporal bất biến). Change set / change engine (hẹn ngày, hồi tố, sửa sai, đảo, phát hiện xung đột). Cây đa phân cấp (quản trị / pháp nhân / tài chính). Chuỗi báo cáo suy ra từ cây, có override và tuyến ma trận. Pháp nhân + quan hệ lao động tách khỏi bổ nhiệm; bổ nhiệm chính / kiêm nhiệm / quyền / biệt phái theo FTE. Định biên FTE kiểm theo khoảng. DOA theo ngày và theo thời điểm hiểu biết. `PKG_INTEGRITY` trước commit. `RETRO_TRIGGER` gom mọi nguồn hồi tố. Ma trận hạn mức duyệt. |
| v3.1 (27/09/2026) | **Chạy thật trên Oracle Database 23 Free**: cài đặt 0 lỗi, 0 đối tượng INVALID; 42/42 test kịch bản đạt (`database/tests/`). Sửa 2 lỗi do test phát hiện: `RETRO_TRIGGER.SourceRef` trùng khi nhiều thay đổi lương cùng mili giây; `VerifyChangeSet` bắt đầu kiểm từ ngày khai báo thay vì ngày sớm nhất thực sự ghi. |
| v3.2 (27/09/2026) | **Môi trường dev sẵn sàng cho code**: Flyway (V1 schema, V2 role + user ứng dụng theo service với quyền tối thiểu và logon trigger, V3 `WORKFLOW_TEMPLATE.ResolveAsOf`), dev seed idempotent, Docker Compose (volume, cổng chỉ localhost). Bỏ `IF NOT EXISTS` (parser Flyway hiểu nhầm). 42/42 test đạt trên DB dựng bằng migration. |
| v3.3 (27/09/2026) | **Change Engine chạy được** (.NET 10, CoreHR): Domain `Timeline` (SetFrom / Delimit / Insert, lan truyền, gộp, diff theo nội dung), `ChangeSet` state machine, 16 thao tác; Application `ChangeEngine` (validate dry-run, apply nguyên khối, outbox, vô hiệu quyết định phụ thuộc); Infrastructure Oracle (user `HRIS_COREHR`, savepoint cho test); API change set + cây theo ngày + người duyệt. Test: 17 unit + 9 integration trên Oracle đạt. Lỗi test phát hiện: diff so theo RowId sinh cặp thay thế/thêm vô nghĩa; bind `:by` trùng từ khoá (ORA-01745). Chưa làm: CORRECT_RECORD, đảo quyết định, relay Kafka. |
| v3.4 (28/09/2026) | **Sửa sai và đảo quyết định**: migration V4 `SupersededByChangeSetId` (dòng bị quyết định nào thay thế); `CORRECT_RECORD` = `Timeline.ReplaceWindow` (thay nội dung cửa sổ, không lan truyền); `REVERSE_CHANGE_SET` (thay thế dòng của X, khôi phục bản sao dòng X đã thay thế, chặn nếu quyết định sau đã chạm); luật tách bạch: hai thao tác này chỉ nằm trong change set CORRECTION. Event `RecordCorrected`, `ChangeSetReversed`; `retroactive` theo ngày thực sự bị chạm. 04 §4.2.5. |
