# HANDOFF — tiếp tục dự án trên máy khác

Đọc file này trước tiên khi mở dự án ở máy mới hoặc sau thời gian nghỉ. Cập nhật mục **Trạng thái** và **Việc tiếp
theo** mỗi khi xong một phần việc.

_Cập nhật lần cuối: 28/09/2026 — thiết kế v3.4._

---

## 1. Trạng thái hiện tại

| Hạng mục | Trạng thái |
|---|---|
| Nhánh làm việc | `feature/candicate-hired-event` (chưa merge vào `dev` / `main`) |
| Thiết kế | v3.4 — [docs/System_Design](System_Design) (00 schema · 01 kiến trúc + nhật ký thiết kế · 02 ERD · 03 data dictionary · 04 thuật toán · 05 workflow) |
| Database | Oracle 23 Free + Flyway **V1–V4** + dev seed — [database/README.md](../database/README.md) |
| CoreHR | Change Engine .NET 10 chạy được, gồm sửa sai và đảo quyết định — [src/Services/CoreHR/README.md](../src/Services/CoreHR/README.md) |
| Test | **78 đạt**: 42 test SQL (`database/tests`) · 23 unit (`tests/Hris.CoreHR.Domain.Tests`) · 13 integration trên Oracle (`tests/Hris.CoreHR.IntegrationTests`) |
| Recruitment | Khung API cũ (`CandidateService` chỉ in log) — chưa theo thiết kế v3 |
| Payroll, Workflow, T&A, Talent, Offboarding, Identity | Mới có thiết kế (schema Payroll/Workflow đã có trong DB, chưa có service) |
| Portfolio | https://d-pro-portfolio.pages.dev/hris_enterprise/ — nguồn trong repo **D-Pro** (mục 6) |

## 2. Dựng môi trường trên máy mới

**Cài:** Git · Docker Desktop · .NET SDK **10** (đã dùng 10.0.401) · Python 3.8+ (chỉ cho công cụ portfolio).

```bash
git clone https://github.com/daochinam1081406/HRIS-microservice.git
cd HRIS-microservice
git checkout feature/candicate-hired-event

# Database
cd database
cp .env.example .env          # đặt 5 mật khẩu mới (ORACLE / COREHR / RECRUITMENT / PAYROLL / WORKFLOW)
docker compose up -d oracle   # lần đầu tải image ~1 GB; cổng chỉ mở trên 127.0.0.1:1521
docker compose run --rm flyway migrate   # V1..V4 + dev seed; kết thúc bằng "now at version v4"
cd ..

# Build + test
dotnet build HRIS-microservice.slnx                         # kỳ vọng: 0 Warning(s), 0 Error(s)
dotnet test --project tests/Hris.CoreHR.Domain.Tests        # 23 đạt
dotnet test --project tests/Hris.CoreHR.IntegrationTests    # 13 đạt (tự đọc mật khẩu từ database/.env)

# Test SQL (tuỳ chọn)
docker cp database/tests/test_scenarios.sql hris-oracle:/tmp/
docker exec -e NLS_LANG=AMERICAN_AMERICA.AL32UTF8 hris-oracle sqlplus -s / as sysdba @/tmp/test_scenarios.sql
# kỳ vọng: "=== CORE: 36 pass, 0 fail" và "=== PAY fail=0"

# Chạy API CoreHR
export ConnectionStrings__CoreHr="User Id=HRIS_COREHR;Password=<COREHR_PASSWORD>;Data Source=//localhost:1521/FREEPDB1"
dotnet run --project src/Services/CoreHR/Hris.CoreHR.Api --urls http://localhost:5074
# ví dụ gọi API: src/Services/CoreHR/Hris.CoreHR.Api/Hris.CoreHR.Api.http
```

`database/.env` **không** nằm trong git: máy mới tạo mật khẩu mới là đủ (DB dựng lại từ đầu). Reset DB dev:
`docker compose down -v` rồi chạy lại `up` + `migrate`.

**Windows / Git Bash:** lệnh `docker` có đường dẫn `/tmp/...` cần `MSYS_NO_PATHCONV=1` phía trước, nếu không Git Bash
đổi thành `C:/Program Files/Git/tmp/...`.

## 3. Bản đồ repo

```
database/                 Flyway: migrations/V1..V4, seed/dev (afterMigrate), tests/, docker-compose.yml
docs/System_Design/       Thiết kế (00 là bản thiết kế tương ứng V1; thay đổi sau V1 nằm ở migration)
docs/HANDOFF.md           File này
src/Services/CoreHR/      Domain · Application (ChangeEngine) · Infrastructure (Oracle) · Api
src/Services/Recruitment/ Khung cũ
src/Shared/               Hris.Shared.Contracts (event — CandidateHiredEvent cũ, cần đổi theo 01 §1.4)
tests/                    Domain.Tests (không cần DB) · IntegrationTests (Oracle dev, rollback mỗi test)
global.json               Bật Microsoft Testing Platform cho `dotnet test` (.NET 10)
```

## 4. Quy tắc bắt buộc (đã trả giá mới biết)

**Thiết kế dữ liệu**
- Bảng phiên bản **bất biến**: chỉ `INSERT` + `UPDATE (SupersededAt, SupersededByChangeSetId)`, không `DELETE` — trigger
  `TRG_*_IMM` + quyền cột của `HR_CORE_APP`. Mọi thay đổi cơ cấu / nhân sự đi qua **change set** (04 §4.2).
- Sửa sai / đảo quyết định chỉ trong change set `CORRECTION`, và `CORRECTION` chỉ chứa hai thao tác đó.
- Ứng dụng kết nối bằng user của service (`HRIS_COREHR`…), **không** bằng SYS/SYSTEM/owner schema.

**Migration (Flyway 11 + Oracle)**
- Không sửa migration đã áp (checksum). Thay đổi = `V{n+1}__mo_ta.sql`; nhỏ, một việc (Oracle không có DDL giao dịch).
- Không dùng `CREATE ... IF NOT EXISTS` — parser Flyway hiểu nhầm `IF`, gộp nhiều câu lệnh.
- Khối PL/SQL kết thúc bằng dòng `/`; `ALTER TABLE s.t ADD (...)` viết nhiều dòng kết thúc `);` (công cụ portfolio đọc
  dạng này để lấy cột mới).
- File `.sql` giữ LF (`database/.gitattributes`).

**Code .NET / ODP.NET**
- Tên bind không trùng từ khoá Oracle (`:by`, `:at`… → ORA-01745).
- `Guid` ↔ `RAW(16)` big-endian (`RAWTOHEX(Id)` = `Guid.ToString("N")`).
- Diff phiên bản so theo **nội dung**, không theo Id (tránh ghi lịch sử vô nghĩa).
- PL/SQL: khai báo biến trước procedure/function lồng; hàm cục bộ không dùng được trong câu SQL.

## 5. Việc tiếp theo (theo thứ tự đề xuất)

1. **Workflow service** (`HR_WF` đã có schema + 5 template trong seed): approval engine theo 05 §5.1–5.8, gọi CoreHR
   `ResolveApprovers`; phát `ApprovalCompleted` → CoreHR `ChangeEngine.ApproveAsync` (thay endpoint `approve` gọi tay).
2. **Outbox relay → Kafka** (Kafka chưa có trong compose) + consumer có Inbox; Payroll ghi `RETRO_TRIGGER` từ
   `ChangeSetApplied{retroactive}`.
3. **Recruitment theo v3**: `OfferAccepted` (01 §1.4) thay `CandidateHiredEvent`; CoreHR consumer lập change set `HIRE`.
4. **Xác thực** (Identity, `HR_IAM` logic ở 02 §2.9) thay header `X-User`.
5. Các BC còn ở mức logic: T&A, Talent, Offboarding, Hợp đồng — cần schema (migration) + service.
6. Quy mô: partition bảng phiên bản, lưu trữ dữ liệu cũ, test tải `PKG_INTEGRITY` (04 §4.8).

## 6. Trang portfolio

- Nguồn: repo **D-Pro** (`github.com/daochinam1081406/D-Pro`), thư mục `docs/hris_enterprise/`, nhánh **`namdaoint`**.
  Push `docs/**` lên `namdaoint` → GitHub Actions (wrangler) deploy Cloudflare Pages.
- Cập nhật ERD / panel chi tiết / tài liệu đính kèm: `python scripts/hris_enterprise/build_page.py --hris <repo HRIS>`
  (xem `scripts/hris_enterprise/README.md` trong D-Pro). Phần chữ (mục Engine, số liệu, lịch sử) sửa tay trong `index.html`.
- Thẻ HRIS trên trang chủ portfolio: `docs/portfolio.html` + từ điển `docs/assets/js/i18n.js` (tăng `?v=` khi sửa).
- Trong D-Pro thường có thay đổi dở của dự án ERP ở `src/` — chỉ stage `docs/` và `scripts/hris_enterprise/`.

## 7. Bảo mật

- Token GitHub từng dán vào chat và đang nằm trong URL remote của repo D-Pro trên máy cũ → **revoke** token đó, máy mới
  dùng Git Credential Manager (`git remote set-url origin https://github.com/daochinam1081406/D-Pro.git`).
- Không commit `database/.env`, connection string, mật khẩu (đã có trong `.gitignore`).
