# Sơ đồ phân rã tổng thể — WS / Module / Business Object / Action

> Cập nhật: 06/7/2026 · Phạm vi: **toàn lộ trình** (MVP → v3), không riêng giai đoạn 1 · Bản trực quan: [so-do-ws-module-feature.html](so-do-ws-module-feature.html)
> Đề xuất dựa trên **nghiệp vụ trường lái xe phổ biến** + mô hình **CP – Workspace – Module – Feature**; KHÔNG bám theo code/module hiện có.
> Tài liệu liên quan: [Quan hệ module & join dữ liệu](quan-he-module-2026-07-07.md) · [roadmap.html](roadmap.html) · [Kế hoạch GĐ1](giai-doan-1-mvp/README.md) · [Review module hiện tại](giai-doan-1-mvp/review-module-split-2026-07-06.md)

---

## 0. Nguyên tắc chia (đọc trước)

| Tầng | Ranh giới | Quy tắc quyết định |
|---|---|---|
| **Workspace (WS)** | Pháp nhân + cơ sở dữ liệu | Mỗi WS = 1 chủ thể chịu trách nhiệm pháp lý về dữ liệu, 1 DB riêng. **Chi nhánh/cơ sở (`ma_csdt`) là thuộc tính trong WS, không tách WS** |
| **Module** | Đơn vị đóng gói – cài đặt – **bán/license** | Tách module khi: bán riêng được theo gói · vòng đời nâng cấp riêng · người dùng chính khác nhau · cài/gỡ không ảnh hưởng module khác |
| **Feature** | Nhóm quyền + mục menu trong module | Mỗi feature ôm 1 nghiệp vụ con; là đơn vị gán quyền |
| **Business Object (BO)** | Chứng từ / đối tượng dữ liệu | Mỗi feature có 1 BO chính (+ BO phụ đi kèm vòng đời của nó) |
| **Action** | Thao tác trên BO | Bộ chuẩn **core 12**: `view, create, edit, delete, import, export, approve, assign, manage_role, configure, report, download` + **action đặc thù** khai qua `customActions` (`collect, reconcile, verify, book, score, send…`). ⚠️ Cấm khai custom: đồng nghĩa core (`print`→dùng `download`) và verb workflow (`submit, cancel, reject…` → mô hình hóa bằng trạng thái workflow) |

---

## 1. Tầng Control Plane & số lượng Workspace

```
CONTROL PLANE (1)
│   users · workspaces · RBAC · SSO · store/license · billing
│
├── WS admin-console (1)          — vận hành nền tảng (đội sản phẩm)
├── WS demo/sandbox (1)           — trình diễn bán hàng, dữ liệu giả
│
├── WS đào tạo  × N               — MỖI TRUNG TÂM ĐÀO TẠO = 1 WS
│     (Vĩnh An là WS đầu tiên; trung tâm có nhiều cơ sở → vẫn 1 WS, phân biệt bằng ma_csdt)
│
└── WS sát hạch × M   (v3)        — MỖI TRUNG TÂM SÁT HẠCH = 1 WS RIÊNG
      (tách khỏi WS đào tạo dù cùng chủ đầu tư: chu kỳ kiểm chuẩn BCA riêng,
       dữ liệu kỳ thi thuộc hội đồng, phần mềm phải niêm phong theo phiên bản)
```

**Vì sao WS sát hạch tách riêng:** roadmap đã chốt "hệ ôn luyện và hệ sát hạch chính thức là hai sản phẩm độc lập"; dữ liệu kỳ thi có chế độ pháp lý khác (thẩm định, niêm phong, truyền CSGT), không nên chung DB với dữ liệu vận hành đào tạo.

---

## 2. WS đào tạo — bản đồ module theo giai đoạn

```
WS ĐÀO TẠO (mỗi trung tâm)
│
├─ NỀN & DANH MỤC          catalog
├─ MVP · Lõi tuân thủ      student · course · teacher · vehicle · dat · tuition · report · notify
├─ v1.5 · Mở rộng          lms · crm · finance · payroll · hr · fleet · portal
└─ v2 · Sân bãi & bán thêm chip · booking · examops · payment · cert
                                                       (v3: bi — dashboard đa module)
```

Tổng: **9 module MVP (kể cả catalog) → 16 ở v1.5 → 21 ở v2**. Mỗi module dưới đây liệt kê **feature / BO chính / action**.

> **Chi tiết từng module** (thư mục [`modules/`](modules/) — mỗi module có bản md + HTML cùng tên):
> **MVP:** [catalog](modules/catalog-2026-07-07.md) · [student](modules/student-2026-07-07.md) · [course](modules/course-2026-07-07.md) · [teacher](modules/teacher-2026-07-07.md) · [vehicle](modules/vehicle-2026-07-07.md) · [dat](modules/dat-2026-07-07.md) · [tuition](modules/tuition-2026-07-07.md) · [report](modules/report-2026-07-07.md) · [notify](modules/notify-2026-07-07.md) · [rfcard](modules/rfcard-2026-07-07.md)
> **v1.5:** [lms](modules/lms-2026-07-07.md) · [crm](modules/crm-2026-07-07.md) · [finance](modules/finance-2026-07-07.md) · [payroll](modules/payroll-2026-07-07.md) · [hr](modules/hr-2026-07-07.md) · [fleet](modules/fleet-2026-07-07.md) · [portal](modules/portal-2026-07-07.md)
> **v2:** [chip](modules/chip-2026-07-07.md) · [booking](modules/booking-2026-07-07.md) · [examops](modules/examops-2026-07-07.md) · [payment](modules/payment-2026-07-07.md) · [cert](modules/cert-2026-07-07.md) — **v3:** [bi](modules/bi-2026-07-07.md)
> **WS sát hạch (v3):** [sh-schedule](modules/sh-schedule-2026-07-07.md) · [sh-kiosk](modules/sh-kiosk-2026-07-07.md) · [sh-theory](modules/sh-theory-2026-07-07.md) · [sh-yard](modules/sh-yard-2026-07-07.md) · [sh-road](modules/sh-road-2026-07-07.md) · [sh-moto](modules/sh-moto-2026-07-07.md) · [sh-monitor](modules/sh-monitor-2026-07-07.md) · [sh-gateway](modules/sh-gateway-2026-07-07.md)

### 2.1 Nhóm nền & danh mục

**`catalog` — Danh mục dùng chung** *(mọi module depends)*
| Feature | BO chính | Action |
|---|---|---|
| license | Hạng GPLX (km/giờ yêu cầu, tuổi, hạn) | view·create·edit·delete·import |
| training-category | Hạng đào tạo | view·create·edit·delete |
| doc-type | Loại giấy tờ + checklist theo hạng | view·create·edit·delete·configure |
| edu-level, subject | Trình độ học vấn · Môn học | view·create·edit·delete |
| code-rule | Quy tắc sinh mã (học viên/khóa/phiếu) | view·configure |

### 2.2 Nhóm MVP — lõi tuân thủ

**`student` — Học viên & hồ sơ**
| Feature | BO chính | Action |
|---|---|---|
| student | Học viên (danh bạ người) | view·create·edit·delete·export |
| hoso | Hồ sơ ghi danh theo khóa (state machine) | view·create·edit·**approve**·**transfer**(bàn giao) — *hủy hồ sơ = bước workflow* |
| giayto | Giấy tờ hồ sơ (scan, hạn) | view·create(upload)·**verify**·delete |
| lichsu | Lịch sử trạng thái (audit) | view·export |

**`course` — Khóa học & xếp lớp**
| Feature | BO chính | Action |
|---|---|---|
| course | Khóa học | view·create·edit·**close**·export |
| enrollment | Ghi danh vào khóa + phân công GV–xe | view·create·edit·**assign** |
| plan | Kế hoạch đào tạo (trình Sở) | view·create·**approve**·report |

**`teacher` — Giáo viên**
| Feature | BO chính | Action |
|---|---|---|
| teacher | Giáo viên (hồ sơ nghiệp vụ) | view·create·edit·delete·export |
| cert | Chứng chỉ GV + hạn (nhắc hạn) | view·create·edit·configure |
| assignment | Phân công dạy (khớp đăng ký Sở) | view·assign·report |

**`vehicle` — Xe tập lái**
| Feature | BO chính | Action |
|---|---|---|
| vehicle | Xe tập lái | view·create·edit·delete·export |
| license-doc | Giấy phép xe tập, đăng kiểm, bảo hiểm (hạn) | view·create·edit·configure |
| device-bind | Gắn/tháo thiết bị DAT | view·**assign** |

**`dat` — Thiết bị & dữ liệu DAT** *(painkiller)*
| Feature | BO chính | Action |
|---|---|---|
| device | Thiết bị DAT (seri, sim, hạn) | view·create·edit·delete |
| session | Phiên học DAT (km/giờ) | view·**import**·**exclude**(loại phiên)·export |
| reconcile | Kết quả đối soát theo học viên/hạng | view·**reconcile**·report |
| alert | Cảnh báo thiếu km/giờ, lệch GV/xe | view·configure·**send** |
| log | Nhật ký truyền/kết nối | view |

**`tuition` — Học phí & công nợ**
| Feature | BO chính | Action |
|---|---|---|
| pricelist | Bảng học phí theo hạng/khóa | view·create·edit·approve |
| installment | Công nợ theo đợt | view·create·edit·export |
| receipt | Phiếu thu | view·create·**collect**(thu)·**refund**·**reprint**(in lại có log) |
| discount | Miễn giảm | view·create·**approve** |

**`report` — Báo cáo tuân thủ Sở XD** *(painkiller)*
| Feature | BO chính | Action |
|---|---|---|
| template | Mẫu báo cáo (version theo thông tư) | view·configure |
| so-xd | Báo cáo đã lập (KH đào tạo, DS học viên, tốt nghiệp) | view·**generate**·edit·**approve**·download — *gửi Sở = bước workflow sau approve* |
| registry | Sổ theo dõi đã nộp (immutable) | view·export |

**`notify` — Nhắc hạn & thông báo đa kênh**
| Feature | BO chính | Action |
|---|---|---|
| rule | Quy tắc nhắc hạn (giấy tờ GV/xe/học viên) | view·configure |
| message | Thông báo đã gửi (Zalo OA/SMS/app) | view·**send**·export |

### 2.3 Nhóm v1.5 — LMS, app, back-office

**`lms` — Lý thuyết đạt chuẩn giám sát**
| Feature | BO chính | Action |
|---|---|---|
| class | Lớp/buổi học lý thuyết | view·create·edit |
| attendance | Điểm danh khuôn mặt (log hợp lệ) | view·**checkin**·export |
| question-bank | Ngân hàng 600 câu (config theo bộ đề) | view·import·configure |
| mock-exam | Thi thử + kết quả | view·create·**score**·export |
| result | Kết quả học lý thuyết (xét điều kiện) | view·approve·report |

**`crm` — Tuyển sinh**
| Feature | BO chính | Action |
|---|---|---|
| lead | Lead (Zalo/FB/web) | view·create·edit·**assign**·**convert**(→hồ sơ) |
| campaign | Nguồn/chiến dịch | view·create·edit·report |
| commission | Hoa hồng CTV | view·**approve**·export |

**`finance` — Kế toán & hóa đơn điện tử**
| Feature | BO chính | Action |
|---|---|---|
| invoice | Hóa đơn điện tử (tích hợp nhà cung cấp) | view·**issue**·**void**·export |
| ledger | Sổ thu–chi, doanh thu theo khóa/hạng | view·report·export |
| reconcile | Đối soát doanh thu (học phí ↔ hóa đơn) | view·**reconcile** |

**`payroll` — Lương giáo viên**
| Feature | BO chính | Action |
|---|---|---|
| timesheet | Bảng công từ giờ dạy DAT/phiên chip | view·**generate**·edit |
| salary | Bảng lương (giờ/khoán) | view·**generate**·**approve**·export |

**`hr` — Nhân sự**
| Feature | BO chính | Action |
|---|---|---|
| employee | Nhân viên (phòng ban, chức danh) | view·create·edit·delete |
| org | Phòng ban, chức danh (danh mục cây) | view·configure |
| contract | Hợp đồng, chứng chỉ tập huấn | view·create·edit·configure |

**`fleet` — Vận hành đội xe & tài sản**
| Feature | BO chính | Action |
|---|---|---|
| fuel | Nhiên liệu theo km DAT | view·create·report |
| maintenance | Bảo dưỡng – sửa chữa | view·create·**approve** |
| cost | Chi phí trên đầu xe | view·report |
| asset | Tài sản, khấu hao, kho vật tư | view·create·edit·export |

**`portal` — Backend app học viên**
| Feature | BO chính | Action |
|---|---|---|
| account | Tài khoản học viên trên app | view·create·**reset** |
| progress | Tra cứu tiến độ km/giờ (đọc từ dat) | view |
| booking | Đặt lịch bổ túc với GV | view·**book**·approve |
| practice | Ôn 600 câu, thi thử trên app | view |

### 2.4 Nhóm v2 — sân bãi & bán thêm

**`chip` — Xe chip ôn luyện** · thiết bị chip, 12 bài sa hình (config), phiên ôn, kết quả/lỗi từng bài → `view·import·configure·score·export`
**`booking` — Thuê xe chip & sân** · lịch sân/xe, phiên thuê, bảng giá, doanh thu phiên → `view·create·book·collect·report`
**`examops` — Vận hành kỳ sát hạch (cho mượn sân)** · kỳ thi, DS thí sinh, điều phối xe/sân, doanh thu cho thuê → `view·create·assign·report`
**`payment` — Thanh toán online** · giao dịch cổng, đối soát cổng → `view·refund·reconcile`
**`cert` — Chứng chỉ nghề** · chương trình nghề (config), học viên nghề, chứng chỉ cấp → tái dùng student+lms, `view·create·approve·download`
**`bi` (v3)** — dashboard đa module: tỷ lệ đậu theo GV/xe/khóa, hiệu suất sân bãi, chi phí/học viên → `view·report·export`

---

## 3. WS sát hạch (v3) — bản đồ module

> WS riêng cho mỗi trung tâm sát hạch — phần mềm thẩm định BCA, release theo phiên bản kiểm chuẩn.

| Module | Feature / BO chính | Action đặc thù |
|---|---|---|
| `schedule` | Kỳ sát hạch · hội đồng · ca thi · DS thí sinh | view·create·assign·**lock**(chốt DS) |
| `kiosk` | Check-in thí sinh · đối chiếu khuôn mặt · số báo danh | view·**checkin**·**verify** |
| `theory` | Phòng máy · đề thi (trộn 600 câu, điểm liệt) · bài thi · biên bản | view·**generate**·**score**·download |
| `yard` | Xe sát hạch · bài sa hình · kết quả chấm tự động · log niêm phong | view·**score**·**seal**(niêm phong)·export |
| `road` | Lộ trình đường trường · kết quả chấm · bảng nút SH viên | view·**score**·export |
| `moto` | Sát hạch A1/A2 (sân mô tô) | view·**score**·export |
| `monitor` | Camera xe/sân/phòng thi · màn hình công khai điểm · lưu vết | view·**broadcast**·export |
| `gateway` | Gói tin truyền Cục CSGT · nhật ký truyền/bù | view·**transmit**·**retry**·report |

---

## 4. Tổng hợp số lượng (đề xuất)

| Tầng | Số lượng | Ghi chú |
|---|---|---|
| Control Plane | **1** | users, RBAC, SSO, store/license |
| WS hệ thống | 2 (admin-console, demo) | |
| WS đào tạo | **N = số trung tâm** (GĐ1: 1 — Vĩnh An) | nhiều cơ sở = 1 WS, phân biệt `ma_csdt` |
| WS sát hạch | M (v3, theo số sân được thẩm định) | tách khỏi WS đào tạo |
| Module / WS đào tạo | **9 (MVP) → 16 (v1.5) → 21 (v2)** | mỗi module = 1 đơn vị license trong store |
| Module / WS sát hạch | 8 (v3) | release theo phiên bản kiểm chuẩn |
| Feature / module | 2–5 | mỗi feature = 1 BO chính |
| Action / BO | 4–8 | bộ chuẩn 10 + đặc thù (~15 action custom toàn hệ) |

### Action đặc thù toàn hệ (khai bổ sung ngoài bộ chuẩn)
`transfer` (bàn giao hồ sơ) · `verify` (đối chiếu giấy tờ/khuôn mặt) · `collect`/`refund` (thu/hoàn tiền) · `issue`/`void` (xuất/hủy hóa đơn) · `reprint` (in lại chứng từ, có log) · `reconcile` (đối soát) · `generate` (sinh báo cáo/bảng) · `send` (gửi thông báo) · `book` (đặt lịch) · `checkin` (điểm danh) · `score` (chấm) · `exclude` (loại phiên) · `seal` (niêm phong) · `transmit`/`retry` (truyền CSGT) · `broadcast` (công khai điểm) · `lock`/`close` (chốt sổ/đóng khóa) · `reset` (cấp lại tài khoản)

> **Quy ước đã chốt (07/7):** không đưa `print` vào core — in thường dùng core `download`, in mang tính phát hành/in lại dùng custom (`reprint`) kèm log. `submit`/`cancel` là **verb workflow** (validator cấm khai custom) → mô hình hóa bằng **trạng thái workflow** (vd hồ sơ `huy`, báo cáo `da_gui`), quyền gate bằng action core trên feature.

---

## 5. Đối chiếu với module đã có trong code (tham khảo)

| Đề xuất | Hiện có trong `ws_suns` | Ghi chú |
|---|---|---|
| catalog, student, course, teacher, vehicle, dat | ✅ đã scaffold (.ogapp) | student cần thêm feature `hoso/giayto`; dat cần thêm `session/reconcile/alert` |
| tuition, report, notify | ❌ chưa có | GĐ1 phải scaffold (tuition/report đã có schema đề xuất) |
| **hr, payroll, crm** (v1.5) | ✅ **built-in `hrm`, `crm`** phủ sẵn (18 model HRM) | **Không scaffold mới** — dùng built-in + phần đặc thù mỏng (GV↔Employee, timesheet-DAT, convert lead→hồ sơ, hoa hồng CTV). Xem [review core](core/core-review-2026-07-07.md) §1b |
| phòng ban / chức danh (WS0) | ✅ **built-in `org`** (OrganizationalUnit + Position) | Seed danh sách Vĩnh An vào org từ MVP — không tạo danh mục riêng |
| lms, finance, fleet, portal | ❌ chưa có | v1.5 — còn **4 module mới** (thay vì 7) |
| chip, booking, examops, payment, cert, bi | ❌ chưa có | v2–v3 |
| rfcard (hiện có) | — | giữ như module hạ tầng nhỏ, phục vụ điểm danh/DAT |
| workflow, workplace, system, iam (built-in) | ✅ có sẵn lúc boot | workflow để dành (duyệt/connector); **workplace disable ở Vĩnh An**; system = quyền hạ tầng; iam chờ RT-16 |
| account, base (hiện có) | — | demo, không cài ([đã chốt](giai-doan-1-mvp/review-module-split-2026-07-06.md)) |

> Lưu ý: đây là **sơ đồ mục tiêu** để định hướng đóng gói & bán theo gói (MVP / v1.5 / v2); khi implement từng giai đoạn có thể gộp/tách feature theo thực tế, miễn giữ nguyên tắc mục 0.