System Design Case Study Oracle 23ai .NET 9 Microservices Kafka · Outbox / Inbox Dự án cá nhân — đang phát triển

HRIS Enterprise
thiết kế theo vị trí, dữ liệu theo thời gian

Hệ thống quản trị nhân sự cho tập đoàn: cơ cấu tổ chức nhiều tầng, định biên theo ghế, phê duyệt động theo chuỗi báo cáo, và tính lương hồi tố với audit trail đầy đủ. Trang này trình bày bản thiết kế v2 ở phiên bản v3. Ở v3, toàn bộ cơ cấu tổ chức được lưu theo hai trục thời gian, và mọi thay đổi đều đi qua một quyết định được kiểm toàn vẹn rồi áp nguyên khối. Trang kèm cỗ máy thời gian cơ cấu và trình mô phỏng workflow chạy trực tiếp trên trình duyệt.

Dự án cá nhân, độc lập, không liên quan đến bất kỳ doanh nghiệp nào. Schema và PL/SQL chạy trên Oracle Database 23 Free (Flyway V1–V4). Change Engine .NET 10 đã chạy được trên chính DB đó, gồm cả sửa sai và đảo quyết định. Tổng cộng 78 test tự động đạt: 42 test kịch bản SQL, 23 unit test, 13 integration test. Chưa có: relay Kafka, xác thực người dùng.

10Bounded context
78Test tự động đạt
42Bảng có SQL
5Package PL/SQL
9Bất biến kiểm trước commit
01 · Nguyên tắc kiến trúc

Thiết kế để vận hành, không để trình diễn

Mục tiêu: chịu được cơ cấu phức tạp (nhiều pháp nhân, 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à luôn ghi nhận đúng quá trình.

Người · ghế · đơn vị tách rời

Ba đối tượng, mỗi đối tượng có lịch sử riêng. Người ngồi ghế qua ASSIGNMENT: chính, kiêm nhiệm, quyền trưởng hoặc biệt phái, có FTE.

Quan hệ lao động gắn với pháp nhân (EMPLOYMENT), nên xử lý được chuyển pháp nhân trong tập đoàn, tuyển lại và thâm niên.

Mọi thứ theo hai trục thời gian

Tên đơn vị, vị trí trong cây, trưởng đơn vị, ghế và bổ nhiệm đều là phiên bản ValidFrom/ValidTo × RecordedAt/SupersededAt.

Nhờ vậy trả lời được hai câu hỏi: "cơ cấu ngày X thế nào?" và "lúc T hệ thống đã tin điều gì?"

Dòng phiên bản bất biến

Đóng, tách hay sửa đều là: set SupersededAt cho dòng cũ, rồi thêm dòng mới. Không DELETE, không sửa giá trị.

Được cưỡng chế bằng trigger TRG_*_IMM và quyền cột. Role ứng dụng chỉ có UPDATE (SupersededAt).

Mọi thay đổi là một quyết định

CHANGE_SET được validate (dry-run), duyệt, rồi áp nguyên khối. Hỗ trợ hẹn ngày, hồi tố, sửa sai, đảo quyết định và phát hiện xung đột giữa các quyết định.

Mọi dòng dữ liệu mang ChangeSetId, nên luôn truy được về quyết định sinh ra nó.

Chuỗi báo cáo suy ra từ cây

Ghế báo cáo cho trưởng đơn vị của nó (INHERIT). Nhờ đó di chuyển phòng hay đổi trưởng thì chuỗi duyệt tự đi theo, không phải sửa ghế nào.

Ngoại lệ dùng EXPLICIT. Có thêm tuyến ma trận và ba loại cây: quản trị, pháp nhân, tài chính.

DB tự bảo vệ bất biến

PKG_INTEGRITY kiểm tra C1–C9 tại mọi mốc thời gian trước commit: 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…

Mỗi service một schema, tham chiếu chéo bằng ID và event. PII được mã hoá TDE.

02 · Service & dữ liệu

10 bounded context, 4 service đã có schema chi tiết

Viền tím là các service đã có đầy đủ bảng, ràng buộc và package trong script Oracle. Các BC còn lại mới dừng ở mức ERD logic.

API Gateway · JWT · RBAC · TenantId

CoreHR

HR_CORE · OM + CE
  • CHANGE_SET · CHANGE_ITEM (quyết định)
  • ORG_UNIT → _VERSION · ORG_EDGE · ORG_UNIT_HEAD
  • POSITION → _VERSION · MATRIX_LINE
  • LEGAL_ENTITY · EMPLOYMENT → _VERSION
  • ASSIGNMENT (chính/kiêm/quyền/biệt phái)
Change Engine · PKG_ORG_QUERY · PKG_DOA · PKG_INTEGRITY

Recruitment

HR_ATS · ATS
  • JOB_REQUISITION
  • CANDIDATE · APPLICATION
  • INTERVIEW_SCHEDULE
  • OFFER_LETTER
1 offer ACCEPTED / application

Payroll

HR_PAY · PY
  • PAYROLL_PERIOD (khoá kỳ)
  • SALARY_COMPONENT (bitemporal)
  • PAYSLIP · PAYSLIP_DETAIL
  • RETRO_TRIGGER (mọi nguồn hồi tố)
PKG_COMP.ChangeAmount

Workflow

HR_WF · SYS
  • WORKFLOW_TEMPLATE (version)
  • WORKFLOW_STEP_DEF
  • APPROVAL_REQUEST · TASK
  • APPROVAL_LOG · DELEGATION
  • AUTHORITY_MATRIX (hạn mức)
gRPC → CoreHR.ResolveApprover

T&A · Talent · Offboarding

HR_TA · HR_TAL · HR_OFF
  • Chấm công, nghỉ phép, OT
  • KPI/OKR, L&D, 9-Box, kế nhiệm
  • Nghỉ việc, bàn giao, tài sản
ERD logic — chưa có schema
Kafka ChangeSetAppliedChangeSetEffectiveOfferAcceptedEmployeeHiredHireRejected AssignmentChangedEmployeeTerminatedApprovalCompleted
Mọi event mang envelope EventId · TenantId · OccurredAt · CorrelationId · SchemaVersion Partition key = EmployeeId để giữ thứ tự theo từng người
03 · Cơ cấu theo thời gian

Cỗ máy thời gian cơ cấu — hai trục thời gian

Kịch bản QĐ-120 (04 §4.7): ký ngày 20/09, hiệu lực 01/10. Nội dung: chuyển Phòng App từ Khối Công nghệ sang Khối Sản phẩm, lập ghế Mobile Lead và điều chuyển An sang ghế đó. Ngày 10/10 phát hiện ngày điều chuyển của An đúng ra là 15/10, nên lập change set sửa sai. Chọn ngày hiệu lực (ngoài đời) và thời điểm hiểu biết (hệ thống biết đến lúc nào). Mọi thứ bên dưới được tính bằng đúng điều kiện lọc của PKG_ORG_QUERY.

Ngày hiệu lực (as_of)
Thời điểm hiểu biết (known_at)

Cây quản trị tại ngày đã chọn

An — ghế và chuỗi báo cáo (suy ra)

Các dòng phiên bản trong DB

đang được dùngkhông phủ ngày nàyđã bị thay thế (theo known_at)chưa được ghi (sau known_at)

BảngDòngHiệu lựcRecordedAtSupersededAtQuyết định

04 · Mô hình dữ liệu

ERD đầy đủ — 42 bảng có SQL, 5 bounded context mức logic

Tab SQL khớp từng cột với script Oracle. Tab logic là thiết kế cho các BC chưa có schema, theo cùng quy ước. Nét liền là FK trong cùng schema; nét đứt là tham chiếu xuyên service bằng ID, không có FK.

Vừa khung Kéo để di chuyển · bấm vào bảng để xem chi tiết · 02_Database_ERD.md
Đang tải Mermaid…
05 · Mô hình workflow

Approval engine — thử trực tiếp

Engine không hiểu nghiệp vụ: nó chỉ nhận RequestType cùng một payload JSON, đánh giá điều kiện từng bước, rồi tìm người duyệt tại thời điểm bước được kích hoạt. Hãy đổi loại đơn, người nộp, hoặc bật "ghế trống" / "uỷ quyền" để xem DOA leo thang ra sao, sau đó bấm Submit và duyệt, từ chối hay giả lập quá hạn SLA.

Tạo đơn

Loại đơn (RequestType)
Người nộp
Tình huống tổ chức

Lộ trình duyệt

APPROVAL_REQUEST.Status
Task đang chờ
APPROVAL_LOG (append-only) & event phát ra
THành độngActorChi tiết
06 · Business workflow

Từ yêu cầu tuyển dụng đến ngày đầu đi làm

Đây là saga dạng choreography qua Kafka. Điểm mấu chốt: chỉ CoreHR được quyết định "đã thành nhân viên", vì chỉ CoreHR khoá được hàng POSITION để kiểm tra định biên một cách nguyên tử. Nếu hết định biên, saga không thể "rollback" chữ ký của ứng viên. Nó chỉ có thể bù trừ bằng cách đưa offer sang ON_HOLD.

07 · Thuật toán lõi

Ba bài toán kinh điển của HRIS

Trích từ đặc tả (04) và package PL/SQL. Chi tiết về các phép ghi theo thời gian, hồi tố, sửa sai và đảo quyết định nằm trong tài liệu 04.

Chuỗi báo cáo suy ra + DOA theo ngày

Ghế báo cáo cho trưởng đơn vị của nó, không lưu cột "báo cáo cho ai". DOA leo chuỗi đó tại ngày được hỏi (và theo thời điểm hiểu biết nếu cần). Ghế trống, không đủ cấp hoặc là chính người nộp thì leo thang tự động. Chi phí O(d·h).

-- PKG_ORG_QUERY.ManagerPosition(p, d)
v := phiên bản của ghế p phủ d
IF v.ReportingMode = 'EXPLICIT' THEN RETURN v.ExplicitReportsTo
u := v.OrgUnitId
h := HeadPosition(u, d)                -- ORG_UNIT_HEAD phủ d
IF h <> p THEN RETURN h                -- báo cáo trưởng đơn vị
LOOP                                   -- p là trưởng: leo cây
  u := ParentOf(u, 'MANAGEMENT', d)    -- ORG_EDGE phủ d
  EXIT WHEN u IS NULL
  h := HeadPosition(u, d)
  IF h <> p THEN RETURN h
END LOOP;

Tái cấu trúc = một quyết định

Ví dụ QĐ-120 gồm bốn thao tác, được validate trên mọi mốc thời gian, duyệt, rồi áp nguyên khối. Phép SetFrom tách phiên bản tại ngày hiệu lực và lan truyền sang các kế hoạch sau đó nếu chúng không chủ động đổi cùng trường.

CHANGE_SET QĐ-120  hiệu lực 01/10  (ký 20/09)
  1 MOVE_UNIT       App → Khối Sản phẩm   SetFrom ORG_EDGE
  2 UPDATE_UNIT     App.CostCenter=CC-PRD SetFrom ORG_UNIT_VERSION
  3 CREATE_POSITION MOB-LEAD-01 (FTE 1)   Insert
  4 ASSIGN          An → MOB-LEAD-01      Delimit + Insert

Validate  → PKG_INTEGRITY C1..C9 (dry-run, ROLLBACK)
Approve   → approval engine (ORG_CHANGE)
Apply     → lock TENANT · ghi phiên bản [01/10, ∞)
          → VerifyChangeSet · OrgVersion+1 · COMMIT
          → ChangeSetApplied · (01/10) ChangeSetEffective

Lương hồi tố — bitemporal

Ngày 15/09 có quyết định tăng lương từ 20 lên 25 triệu, hiệu lực từ 01/08. Kỳ tháng 8 đã khoá ngày 05/09. PKG_COMP.ChangeAmount không sửa dòng nào mà đánh dấu thay thế rồi tách dòng mới. Chọn thời điểm để xem hệ thống "biết gì":

IdAmountValidFromValidToRecordedAtSupersededAt
08 · Hiện thực

Change Engine (.NET 10) — từ đặc tả thành code chạy

Đặc tả 04 §4.2 đã có code. Mọi quyết định cơ cấu / nhân sự được validate (áp thử rồi rollback), duyệt, rồi áp nguyên khối trên Oracle bằng user ứng dụng HRIS_COREHR. User này chỉ có INSERT và UPDATE (SupersededAt) trên bảng phiên bản, nên kể cả code ứng dụng cũng không sửa được lịch sử.

42test kịch bản SQL (Oracle 23)
23unit test domain
13integration test engine trên Oracle
V1–V4migration Flyway + dev seed

Kiến trúc CoreHR

Apiapi/change-sets · org-units/{id}/tree · employees/{id}/approvers
ApplicationChangeEngine: validate (dry-run) · submit · approve · apply nguyên khối · outbox
DomainTimeline: SetFrom / Delimit / Insert / ReplaceWindow · lan truyền · diff theo nội dung · ChangeSet state machine · 18 thao tác (kể cả sửa sai, đảo quyết định)
Infrastructure → OracleODP.NET · khoá TENANT · PKG_INTEGRITY trước commit · PKG_DOA / PKG_ORG_QUERY để đọc

Apply — một transaction

lock CHANGE_SET (APPROVED) + TENANT
for item in items order by Seq:
    versions = load(current rows)
    diff     = Timeline.SetFrom | Delimit | Insert  -- thuần
    write(diff)   -- UPDATE SupersededAt + INSERT
report = PKG_INTEGRITY.VerifyChangeSet(cs)
if report.errors: ROLLBACK → NEEDS_REVALIDATION
OrgVersion+1 · APPLIED · OUTBOX · COMMIT

Lõi của SetFrom — lan truyền sang kế hoạch đã có

Khi ra quyết định mới, các phiên bản đã lên kế hoạch sau ngày hiệu lực chỉ nhận giá trị mới cho những trường mà chúng không chủ động đổi. Gặp phiên bản đã có kế hoạch riêng cho trường đó thì dừng lan truyền, vì kế hoạch ấy được tôn trọng.

else // phiên bản bắt đầu SAU ngày hiệu lực d (kế hoạch đã có)
{
    var attrs = v.Attrs;
    var contiguous = prevOld is not null && prevOld.To == v.From;
    foreach (var c in changes)
    {
        if (!propagating[c.Name]) continue;
        if (v.From == d || (contiguous && Equals(c.Get(v.Attrs), c.Get(prevOld!.Attrs))))
            attrs = c.Apply(attrs);
        else
            propagating[c.Name] = false;   // kế hoạch sau đã chủ động đổi f → tôn trọng
    }
    next.Add(Equals(attrs, v.Attrs) ? v : new Version<T>(null, v.From, v.To, attrs));
}
Integration test (Oracle, user HRIS_COREHR, rollback mỗi test)Kiểm
Chuyển Phòng App sang Khối Sản phẩmChuỗi duyệt tự đi theo từ ngày hiệu lực; ghế CPO trống thì leo thang lên CEO; dòng cũ bị thay thế chứ không xoá; OrgVersion +1; outbox
Vượt định biên FTELỗi C8; có override kèm lý do thì 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 gặp kế hoạch đã cóĐổi tên hẹn 90 ngày được giữ nguyên; đổi cost center hẹn 30 ngày lan truyền sang kế hoạch đó
Hai quyết định chạm cùng đơn vịQuyết định đang chờ chuyển sang NEEDS_REVALIDATION khi quyết định kia được áp
Áp khi chưa duyệtBị từ chối
Nghỉ việcĐóng quan hệ lao động và mọi bổ nhiệm; phát EmployeeTerminated; không còn người duyệt sau ngày nghỉ
Quyết định hồi tốChangeSetApplied.retroactive = true, để Payroll tính lại lương
User ứng dụng sửa hoặc xoá lịch sửORA-41900 (không có quyền)
Sửa sai ngày điều chuyển (CORRECT_RECORD)Hiện tại thấy ngày đúng; hỏi "theo hiểu biết lúc đó" vẫn thấy đúng như hệ thống đã tin; dòng sai còn lại và biết quyết định nào đã vô hiệu nó
Đả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 chuyển REVERSED; dòng khôi phục là bản sao mới, lịch sử không mất dòng nào
Đảo quyết định đã bị quyết định sau chạm tớiBị chặn, thông báo nêu quyết định phụ thuộc
Đảo quyết định chưa ápBị chặn

Lỗi thật do test bắt được

Diff so theo Id: gọi SetFrom với đúng giá trị cũ vẫn sinh cặp "thay thế + thêm" vô nghĩa, làm bẩn lịch sử. Nay diff so theo nội dung.

PKG_COMP: SourceRef trùng khi hai lần đổi lương rơi vào cùng mili giây. PKG_INTEGRITY: bắt đầu kiểm tra từ ngày khai báo, nên dòng ghi sớm hơn có thể lọt vòng báo cáo.

Môi trường chạy được

Docker Compose chạy Oracle 23 Free (có volume, cổng chỉ mở trên localhost) cùng Flyway. Mỗi service có một user riêng với quyền tối thiểu và logon trigger đặt schema.

Dev seed idempotent: 6 đơn vị, 11 nhân sự, 5 quy trình duyệt, ma trận hạn mức, 4 kỳ lương.

Sửa sai và đảo quyết định

Sửa sai: thay nội dung một khoảng thời gian của đối tượng, không áp sang kế hoạch sau. Đảo: vô hiệu dòng của quyết định X rồi khôi phục bản sao các dòng X đã thay thế. Bị chặn nếu quyết định sau đã dựa trên X.

Mỗi dòng biết quyết định nào đã thay thế nó (migration V4). Hai thao tác này chỉ nằm trong quyết định CORRECTION.

Còn lại: nối bước approve với Workflow service, relay outbox sang Kafka, xác thực người dùng.

09 · Lịch sử thiết kế

Từ v1 đến v3

v1 → v2 sửa các lỗi sẽ làm hệ thống chạy sai. v2 → v3 chuyển từ "thiết kế đúng" sang "vận hành được": cơ cấu thay đổi liên tục mà lịch sử vẫn đúng.

v3Giới hạn của v2Cách giải quyết ở v3
CAODOA hỏi theo ngày quá khứ nhưng chuỗi báo cáo chỉ có trạng thái hiện tại, nên kết quả trộn hai thời điểm.Chuỗi báo cáo suy ra từ ORG_UNIT_HEAD + ORG_EDGE theo ngày; hàm đọc có as_of và known_at.
CAODi chuyển đơn vị không cập nhật chuỗi báo cáo, đơn từ vẫn đi tới giám đốc khối cũ.INHERIT: ghế báo cáo trưởng đơn vị, nên chuỗi tự đi theo cây. EXPLICIT chỉ cho ngoại lệ.
CAOCơ cấu tổ chức không có lịch sử; không có reorg hẹn ngày.Định danh + phiên bản bitemporal cho đơn vị, cây, trưởng, ghế; change set hẹn ngày được ghi ngay và có hiệu lực theo ngày.
CAOThao tác ghi rời rạc, một đợt reorg có thể chỉ được áp một nửa.CHANGE_SET áp nguyên khối + PKG_INTEGRITY trước commit + phát hiện xung đột giữa các quyết định.
TBĐịnh biên chỉ kiểm tại ngày bắt đầu; ghế quản lý bắt buộc 1 người.FTE theo thời gian, kiểm tại mọi mốc; quyền trưởng (ACTING), chia sẻ ghế, override có duyệt.
TBMột tuyến báo cáo, một cây, một pháp nhân.Tuyến ma trận; ba loại cây (quản trị, pháp nhân, tài chính); EMPLOYMENT theo pháp nhân.
TBHồi tố lương chỉ nhìn bảng lương.RETRO_TRIGGER gom mọi nguồn: đổi lương, điều chuyển hoặc thăng chức hồi tố, sửa công.
v3.1–3.4Từ thiết kế sang hệ thống chạy đượcKết quả
3.1Chạy schema trên Oracle 23 Free và viết 42 test kịch bản42/42 đạt; sửa 2 lỗi PL/SQL do test phát hiện
3.2Flyway, user ứng dụng theo service, dev seed, Docker ComposeQuyền tối thiểu được kiểm bằng chính user ứng dụng; migration có checksum ổn định
3.3Change Engine .NET 10 (Domain / Application / Infrastructure / Api)17 unit test + 9 integration test trên Oracle đạt; sửa lỗi diff và bind trùng từ khoá
3.4Sửa sai (CORRECT_RECORD) và đảo quyết định (REVERSE_CHANGE_SET); migration V4 SupersededByChangeSetId23 unit test + 13 integration test đạt; 42 test SQL vẫn đạt sau V4

v1 → v2

MứcVấn đề ở v1Cách sửa ở v2
CAOTrigger Lineage đọc lại chính bảng nên gây ORA-04091 khi UPDATE. Cây con giữ đường dẫn cũ.PKG_ORG.MoveOrgUnit: một câu UPDATE thay tiền tố, kèm chống vòng. Trigger guard chỉ kiểm tra cờ, không query bảng.
CAODOA bắt đầu từ ghế người nộp mà không loại LEVEL 1, nên quản lý tự duyệt đơn của mình.lvl > 1, NOCYCLE, ORDER BY LEVEL, loại chính người nộp, ghế quản lý có HeadcountPlan = 1.
CAOThuật toán hồi tố cần "dòng mới tạo" nhưng bảng không có CreatedAt. Tháng 8 có hai mức lương cùng hiệu lực.Bitemporal (RecordedAt/SupersededAt), PAYROLL_PERIOD.LockedAt, dòng RETRO_EARNING idempotent.
CAOKhông có ràng buộc "một ghế chính đang mở", có thể chồng lấn thời gian và vượt định biên.Unique index function-based, cùng PKG_EMPLOYMENT khoá hàng EMPLOYEE và POSITION.
TB"Tuyệt đối không UPDATE" mâu thuẫn với SCD2. EMPLOYEE.Status bị ghi đè.Append-only có kiểm soát do trigger cưỡng chế. Trạng thái suy ra qua V_EMPLOYEE_CURRENT.
TBMicroservices nhưng dùng một schema, có FK xuyên module.Mỗi service một schema. Tham chiếu chéo bằng ID và event. DOA cung cấp qua gRPC.
TBUNIQUE (TenantId, WorkEmail): Oracle coi (T, NULL) là trùng.Function-based unique index, bỏ qua các hàng NULL.
TBTuyên bố O(1) cho truy vấn cây. ERD để 1-1 cho các quan hệ tuỳ chọn.Ghi đúng O(d) / O(log n + k). Sửa 6 cardinality, thêm bảng APPLICATION.
TBEvent tuyển dụng mang lương và PositionApplied dạng chuỗi.Đổi thành OfferAccepted, có PositionId Guid, không mang lương. Payroll lấy lương qua API có phân quyền.
10 · Tài liệu

Bộ tài liệu thiết kế đầy đủ

Sáu file này nằm trong repo dự án. Mã nguồn để private, còn tài liệu thiết kế được công khai tại đây.