# Use Cases Master — MedBASE V2

> Tài liệu này gom các **use case chính thức** của MedBASE V2 ở mức đủ dùng cho BA / PM / QA / Dev / Ops.

## I. Nhật ký thay đổi

| Phiên bản | Ngày | Chi tiết | Người cập nhật |
|-----------|------|---------|----------------|
| 1.0 | 24/04/2026 | Chuẩn hóa theo official documentation baseline từ bộ docs/v2 và quá trình migration cấu trúc tài liệu | Huyen Tran |
| 1.1 | 24/04/2026 | Bổ sung UC-13 (Admin KYC manual + gán scope), UC-14 (Admin recall manual + 0đ invoice), UC-15 (Admin GPP/GDP manual), UC-16 (NCC upload e-invoice). | Duy Nguyễn (PO) |
| 1.2 | 24/04/2026 | **UC-14 rewrite (D-23)**: quy trình thu hồi thuốc đúng Luật Dược 44/2024 + TT 11/2018 + NĐ 123/2020; loại bỏ "hoá đơn 0đ"; NCC chủ trì reverse logistics, hoá đơn điều chỉnh giảm, biên bản thu hồi/tiêu huỷ, báo cáo Cục QLD. | Duy Nguyễn (PO) |

---

> **Ghi chú chuẩn hóa Official:** Tài liệu này là bản chính thức trong bộ `docs/official/`. Nội dung được chuẩn hóa từ `docs/v2/` và các tài liệu migration bổ sung. Nếu có điểm diễn giải chưa rõ, ưu tiên theo [01-source-of-truth.md](./01-source-of-truth.md).

## II. Nguyên tắc

- Use case mô tả hành vi nghiệp vụ và luồng thao tác chính
- Use case phải bám theo business rules và role matrix
- Mỗi use case nên liên kết với:
  - rule liên quan
  - screen liên quan
  - API liên quan
  - UAT liên quan

---

## III. UC-01 — User vào MedBASE từ referral source

### Actor
- Guest / Referral User

### Preconditions
- User đi vào MedBASE từ PMS hoặc referral source khác

### Trigger
- User click entry point / menu / webview / link

### Main Flow
1. MedBASE mở landing page
2. Hệ thống đọc referral/source metadata nếu có
3. Landing hiển thị CTA rõ ràng
4. User chọn gửi lead, đăng ký hoặc xem catalog

### Alternate / Exception
- Nếu không có source metadata hợp lệ, hệ thống vẫn cho vào landing và gán source mặc định theo policy

### Postconditions
- Entry được ghi nhận ở mức cần thiết cho reporting

### Linked Rules
- LEAD-01, LEAD-02

---

## IV. UC-02 — Guest gửi lead

### Actor
- Guest

### Preconditions
- User đang ở landing / lead form

### Trigger
- User submit form lead

### Main Flow
1. User nhập phone và optional fields
2. Hệ thống validate input tối thiểu
3. Hệ thống tạo lead record
4. Hệ thống gắn source attribution nếu có
5. Hệ thống trả trạng thái thành công

### Alternate / Exception
- Dữ liệu phone không hợp lệ → reject và hiển thị lỗi
- Nếu trùng lead → xử lý theo duplicate policy đã chốt

### Postconditions
- Lead được tạo hoặc được xử lý theo duplicate policy

### Linked Rules
- LEAD-02, LEAD-03, LEAD-05

---

## V. UC-03 — User đăng ký account MedBASE

### Actor
- Guest

### Preconditions
- User chưa có account hợp lệ

### Trigger
- User submit registration form

### Main Flow
1. User nhập dữ liệu đăng ký
2. Hệ thống validate uniqueness và format
3. Hệ thống tạo auth identity
4. Hệ thống tạo buyer shell tương ứng
5. User có thể login và đi tiếp vào onboarding

### Alternate / Exception
- Email/phone trùng → reject
- Password/confirm không khớp → reject

### Postconditions
- Account và buyer shell được tạo

### Linked Rules
- BUY-01, BUY-02

---

## VI. UC-04 — Buyer cập nhật hồ sơ cơ sở

### Actor
- Registered Buyer

### Preconditions
- User đã login
- Buyer shell đã tồn tại

### Trigger
- Buyer mở profile và submit cập nhật

### Main Flow
1. Buyer mở hồ sơ
2. Buyer cập nhật thông tin liên hệ / cơ sở
3. Hệ thống validate các field bắt buộc
4. Hệ thống lưu hồ sơ
5. Buyer được phép đi tiếp sang KYC/eligibility

### Alternate / Exception
- Thiếu field bắt buộc → reject lưu

### Postconditions
- Buyer profile được lưu

### Linked Rules
- BUY-03, BUY-04, BUY-06

---

## VII. UC-05 — Buyer nộp hồ sơ KYC / eligibility

### Actor
- Registered Buyer

### Preconditions
- Buyer đã có profile tối thiểu

### Trigger
- Buyer upload hồ sơ và bấm submit

### Main Flow
1. Buyer upload các tài liệu cần thiết
2. Hệ thống lưu file metadata và reference
3. Buyer submit case
4. Hệ thống set trạng thái PENDING_REVIEW
5. Buyer nhìn thấy trạng thái hiện tại

### Alternate / Exception
- Thiếu document bắt buộc → reject
- File type không hợp lệ → reject

### Postconditions
- KYC/eligibility case được tạo ở trạng thái chờ review

### Linked Rules
- KYC-01, KYC-02, KYC-07

---

## VIII. UC-06 — Reviewer xử lý hồ sơ KYC / eligibility

### Actor
- Admin
- Compliance Reviewer

### Preconditions
- Tồn tại case ở trạng thái PENDING_REVIEW
- Reviewer có authority phù hợp

### Trigger
- Reviewer mở case và thực hiện quyết định

### Main Flow
1. Reviewer mở queue
2. Reviewer mở chi tiết hồ sơ
3. Reviewer xem buyer profile + documents
4. Reviewer approve hoặc reject
5. Hệ thống cập nhật trạng thái hiện hành
6. Hệ thống lưu audit log

### Alternate / Exception
- Case đã được xử lý trước đó → chặn conflicting action
- Reviewer không có quyền final decision → không cho approve/reject

### Postconditions
- Buyer verification state được cập nhật theo policy

### Linked Rules
- KYC-02, KYC-03, KYC-04, KYC-08

---

## IX. UC-07 — Buyer duyệt catalog và xem product detail

### Actor
- Guest
- Registered Buyer
- Verified Buyer

### Preconditions
- Product đã có trong MedBASE catalog

### Trigger
- User mở catalog / product detail

### Main Flow
1. User vào catalog
2. Hệ thống trả product list theo visibility rule
3. User mở product detail
4. Hệ thống hiển thị thông tin phù hợp theo policy

### Alternate / Exception
- Product inactive / blocked → không cho mua, có thể ẩn hoặc hiển thị restricted theo policy

### Postconditions
- User xem được catalog/product detail trong giới hạn policy cho phép

### Linked Rules
- PROD-01, PROD-02, PROD-05, PROD-06

---

## X. UC-08 — Buyer thêm item vào cart

### Actor
- Registered Buyer
- Verified Buyer

### Preconditions
- Product được phép add-to-cart theo policy hiện hành

### Trigger
- Buyer chọn add-to-cart

### Main Flow
1. Buyer chọn product và quantity
2. Hệ thống validate quantity cơ bản
3. Hệ thống tạo hoặc nạp active cart
4. Hệ thống lưu cart item

### Alternate / Exception
- Product bị restricted/blocked → chặn add-to-cart theo policy

### Postconditions
- Cart được cập nhật

### Linked Rules
- CART-01, CART-02

---

## XI. UC-09 — Verified Buyer checkout và tạo order

### Actor
- Verified Buyer

### Preconditions
- Buyer đã đủ điều kiện theo policy
- Cart có item hợp lệ

### Trigger
- Buyer bấm xác nhận checkout

### Main Flow
1. Hệ thống resolve idempotency
2. Hệ thống re-check eligibility
3. Hệ thống chạy product / restriction checks
4. Hệ thống reserve inventory
5. Hệ thống create order và order items
6. Hệ thống trả order result

### Alternate / Exception
- Buyer chưa đủ điều kiện → chặn checkout
- Product bị blocked/restricted → chặn checkout
- Thiếu stock → reject không commit order
- Reservation xong nhưng create-order fail → compensation release

### Postconditions
- Order được commit hoặc transaction bị fail an toàn theo policy

### Linked Rules
- RX-01, RX-02, ORD-01, ORD-02, ORD-03, ORD-04, INV-03

---

## XII. UC-10 — Buyer xem order history / order detail

### Actor
- Registered Buyer
- Verified Buyer

### Preconditions
- Buyer đã có order records trong MedBASE

### Trigger
- Buyer mở order history hoặc order detail

### Main Flow
1. Buyer mở order history
2. Hệ thống trả danh sách order của chính buyer
3. Buyer mở order detail
4. Hệ thống hiển thị chi tiết order tương ứng

### Alternate / Exception
- Buyer cố truy cập order không thuộc quyền sở hữu → chặn

### Postconditions
- Buyer xem được order của chính mình trong MedBASE

### Linked Rules
- ORD-06, ORD-07

---

## XIII. UC-11 — Ops giám sát lead / KYC / order / inventory

### Actor
- Ops
- Admin

### Preconditions
- Role có quyền phù hợp

### Trigger
- Internal user mở admin/ops console

### Main Flow
1. Ops xem lead queue
2. Ops xem KYC queue theo mức quyền được cấp
3. Ops xem order monitoring
4. Ops xem inventory monitoring
5. Ops tạo manual operation request nếu cần và có flow hỗ trợ

### Alternate / Exception
- Action ngoài supported flow → không được xem là thao tác hợp lệ trong V2

### Postconditions
- Ops có đủ visibility để vận hành hằng ngày

### Linked Rules
- OPS-01, OPS-02, OPS-03, OPS-05

---

## XIV. UC-12 — Stakeholder xem reporting dashboard

### Actor
- Admin
- Ops
- Reporting Viewer

### Preconditions
- Reporting projection đã được refresh theo cadence

### Trigger
- User mở dashboard reporting

### Main Flow
1. User chọn khoảng thời gian / filter nếu có
2. Hệ thống đọc từ reporting/read model
3. Hệ thống hiển thị KPI chính
4. User dùng dashboard để quan sát và ra quyết định

### Alternate / Exception
- Reporting refresh chưa hoàn tất → dashboard có thể hiển thị độ trễ theo policy

### Postconditions
- KPI được hiển thị như read-model, không phải business truth

### Linked Rules
- RPT-01, RPT-02, RPT-03, RPT-04

---

## XIV-bis. UC-13 — Admin thẩm định KYC Buyer & gán scope **[MANUAL-P1]**

### Actor
- Admin / Compliance Reviewer

### Preconditions
- Có case KYC ở trạng thái `PENDING_REVIEW`

### Trigger
- Admin mở queue KYC trên CMS

### Main Flow
1. Admin mở chi tiết hồ sơ (CORP-01/HKD-01, CCHN-02, GXX-03, GPP-04, REP-05, ID-10, INV-12...)
2. Admin đối chiếu tính hợp lệ từng document (số hiệu, ngày hết hạn, cơ quan cấp)
3. Admin chọn **Approve** + gán `BuyerScope` thủ công (FULL / LIMITED / SPECIALTY / ENTERPRISE / NON_PHARMA) theo ma trận §IV-bis.4
4. Hệ thống chuyển buyer sang `VERIFIED` và kích hoạt quyền giao dịch tương ứng
5. Hệ thống ghi audit log (actor, time, docs reviewed, scope gán, reason nếu có)

### Alternate / Exception
- Hồ sơ thiếu/không hợp lệ → `REJECTED` hoặc `RESUBMIT_REQUIRED` kèm reason
- SLA vượt 30 phút → Ops escalate theo playbook

### Postconditions
- Buyer có scope rõ; audit trail đầy đủ

### Linked Rules
- KYC-09, KYC-10, CTRL-13

---

## XIV-ter. UC-14 — Thu hồi thuốc (Drug Recall) **[MANUAL-P1]**

> **Căn cứ pháp lý:** Luật Dược 44/2024/QH15 (Điều về thu hồi thuốc), TT 11/2018/TT-BYT (quy trình thu hồi — hoặc văn bản hiện hành thay thế), NĐ 123/2020/NĐ-CP + TT 78/2021/TT-BTC (hoá đơn điện tử).
>
> **Nguyên tắc nền:** MedBASE là **platform facilitator** — *không* tự xuất hoá đơn. **NCC/NSX/NK chủ trì** toàn bộ reverse logistics + chứng từ tài chính + báo cáo cơ quan QLD. Không có khái niệm "hoá đơn 0đ"; tài chính xử lý theo **hoá đơn điều chỉnh giảm** hoặc **hoá đơn thay thế** theo NĐ 123/2020.

### Actor
- **Primary:** NCC / NSX / NK (chủ trì thu hồi, xuất chứng từ tài chính, báo cáo QLD)
- **Facilitator:** Admin MedBASE (chặn sales, notify buyer, track evidence, support escalation)
- **Participant:** Buyer (phối hợp trả hàng, nhận hoàn tiền/cấn trừ công nợ)
- **Authority (external):** Cục Quản lý Dược / Sở Y Tế

### Preconditions
- Có **Quyết định / Thông báo thu hồi** từ cơ quan QLD (bắt buộc), HOẶC NSX/NK tự nguyện thu hồi (voluntary), HOẶC phát hiện lô lỗi/hết hạn/không đạt chất lượng
- `RecallLevel` được xác định: **Mức độ 1** (nguy hiểm tính mạng) / **Mức độ 2** (ảnh hưởng sức khoẻ) / **Mức độ 3** (ít ảnh hưởng) — theo phân loại của cơ quan QLD

### Trigger
- Admin nhận quyết định/thông báo thu hồi và tạo **RecallCase** trên CMS

### Main Flow

**Bước 1 — Khởi tạo RecallCase**
1. Admin upload QĐ/thông báo thu hồi (file), nhập mức độ (1/2/3), phạm vi (product / batch list), lý do, SLA thu hồi theo quy định cơ quan QLD
2. Hệ thống tạo `RecallCase` với status `INITIATED` + audit log

**Bước 2 — Chặn lưu thông ngay lập tức**
3. Hệ thống set `ProductStatus = RECALLED` (hoặc `BatchStatus = RECALLED`) → ẩn khỏi catalog active, chặn add-to-cart/checkout
4. Hệ thống release mọi reservation ACTIVE trên batch bị thu hồi (compensation flow)
5. Hệ thống huỷ các đơn ở trạng thái `PENDING` / `CONFIRMED` (chưa giao) → hoàn tiền nếu đã thanh toán

**Bước 3 — Xác định đơn đã giao bị ảnh hưởng**
6. Hệ thống truy vấn impacted `COMPLETED` orders theo batch (batch traceability)
7. RecallCase chuyển status `NOTIFIED`; hệ thống gửi thông báo tới buyer (email + in-app) kèm QĐ thu hồi và hướng dẫn trả hàng theo SLA mức độ

**Bước 4 — Reverse logistics (NCC chủ trì)**
8. NCC điều phối thu hồi vật lý: liên hệ buyer, sắp xếp vận chuyển lấy hàng về kho
9. Hai bên lập **Biên bản thu hồi** (có chữ ký NCC + buyer, đính kèm ảnh/evidence); Admin/NCC upload biên bản vào từng order bị ảnh hưởng
10. RecallCase từng đơn chuyển `RETURNING` → `RETURNED`

**Bước 5 — Xử lý tài chính theo NĐ 123/2020**
11. NCC xuất **hoá đơn điều chỉnh giảm** (Mẫu theo TT 78/2021) trên cơ sở biên bản thu hồi — giá trị điều chỉnh = giá trị hàng trả thực tế (không phải "0đ")
12. NCC/Admin upload hoá đơn điều chỉnh vào tài liệu đơn hàng
13. Tài chính:
    - Công nợ: trừ giá trị hàng trả vào kỳ đối soát tiếp theo
    - Thanh toán ngay: hoàn tiền về tài khoản buyer hoặc ghi credit vào số dư

**Bước 6 — Xử lý hàng thu hồi**
14. NCC phân loại hàng về kho: tiêu huỷ hoặc trả NSX theo QĐ
15. Nếu tiêu huỷ: lập **Biên bản tiêu huỷ** có chứng kiến theo quy định, upload lên CMS

**Bước 7 — Báo cáo cơ quan QLD**
16. NSX/NK lập **Báo cáo kết quả thu hồi** gửi Cục QLD/SYT theo thời hạn do QĐ thu hồi quy định
17. Admin upload báo cáo đã gửi vào RecallCase; RecallCase chuyển `CLOSED`

### Alternate / Exception
- **Thu hồi Mức độ 1:** bypass thứ tự thông báo buyer theo lô, gửi broadcast alert ngay kèm hướng dẫn ngưng sử dụng tức thì; SLA ngắn nhất theo QĐ
- **Buyer từ chối trả hàng:** Admin + NCC escalate theo quy định; ghi nhận và báo cáo QLD
- **Không xác định được batch của đơn đã giao** (thiếu batch traceability): thu hồi toàn bộ product theo mã SKU trong khoảng thời gian tương ứng; ghi nhận gap traceability vào risk log
- **NCC không phản hồi / chậm xuất hoá đơn điều chỉnh:** Admin đánh dấu case `ESCALATED`, báo cáo PM/Compliance; không đóng case cho đến khi đủ chứng từ

### Postconditions
- Product/batch không thể vào order mới
- Mọi đơn bị ảnh hưởng có: biên bản thu hồi + hoá đơn điều chỉnh giảm (nếu đã giao)
- Biên bản tiêu huỷ (nếu có) + báo cáo QLD đính kèm RecallCase
- Audit trail đầy đủ: actor, time, level, evidence files, financial adjustment refs

### Evidence / Chứng từ bắt buộc
| Chứng từ | Nguồn | Căn cứ |
|---|---|---|
| QĐ/thông báo thu hồi | Cục QLD/SYT hoặc NSX (voluntary) | Luật Dược 44/2024 |
| Biên bản thu hồi (theo cơ sở) | NCC ↔ Buyer | TT 11/2018 (hoặc thay thế) |
| Hoá đơn điều chỉnh giảm | NCC xuất qua hệ thống HĐĐT | NĐ 123/2020 + TT 78/2021 |
| Biên bản tiêu huỷ (nếu có) | NCC/NSX + bên chứng kiến | TT 11/2018 |
| Báo cáo kết quả thu hồi | NSX/NK gửi Cục QLD | Luật Dược 44/2024 |

### Linked Rules & Controls
- RCL-01, RCL-02, RCL-03, RCL-04, RCL-05, RCL-06, CTRL-14
- Liên quan: RCL-07 (Dược QG sync — D-21) cho trigger từ QĐ thu hồi của Cục QLD

### Ghi chú phạm vi
- Phase 1: hệ thống hỗ trợ **evidence tracking + order impact + notification**. Xuất hoá đơn điều chỉnh và báo cáo QLD thực hiện **bên ngoài MedBASE** bởi NCC/NSX, upload chứng từ vào CMS.
- Phase 2 (Q3 2026, D-22): tích hợp TCT để sinh hoá đơn điều chỉnh trực tiếp; template báo cáo QLD chuẩn hoá trong hệ thống.

---

## XIV-quater. UC-15 — Admin quản lý GPP/GDP certificate của Seller **[MANUAL-P1]**

### Actor
- Admin / Compliance Reviewer

### Preconditions
- Seller đang hoạt động hoặc đang onboarding

### Trigger
- Seller submit certificate, hoặc Admin review định kỳ

### Main Flow
1. Admin mở Seller management trên CMS
2. Admin upload/đối chiếu certificate GPP-04 / GDP-04 / GMP-04 / GSP-04
3. Admin nhập `expiry_date` và chọn trạng thái: `VALID` / `EXPIRED` / `PENDING`
4. Nếu `EXPIRED`: hệ thống khoá quyền đăng bán các product loại tương ứng cho đến khi certificate được cập nhật mới
5. Hệ thống ghi audit log

### Alternate / Exception
- Seller không cung cấp đúng hạn → Admin đặt `PENDING` và cảnh báo Seller

### Postconditions
- Seller có trạng thái compliance rõ ràng, không có "lỗ hổng" certificate

### Linked Rules
- KYC-11, SP-01, SP-02, CTRL-15

---

## XIV-quinquies. UC-16 — NCC upload hoá đơn điện tử vào đơn hàng **[MANUAL-P1]**

### Actor
- NCC (hoặc Admin thay mặt)

### Preconditions
- Đơn hàng ở trạng thái `COMPLETED` (đã giao & thanh toán)

### Trigger
- NCC phát hành hoá đơn điện tử bên ngoài (hệ thống TCT riêng)

### Main Flow
1. NCC xuất hoá đơn trên hệ thống TCT riêng (PDF/XML)
2. NCC/Admin mở chi tiết đơn hàng trên CMS
3. NCC/Admin upload file hoá đơn vào mục "Tài liệu đơn hàng"
4. Buyer nhìn thấy link tải hoá đơn ở order detail

### Alternate / Exception
- File sai định dạng → reject upload
- Hoá đơn điều chỉnh / thay thế: upload thêm phiên bản mới, giữ lịch sử

### Postconditions
- Buyer có đủ chứng từ thuế cho đơn hàng

### Linked Rules
- INV-EI-01, INV-EI-02, CTRL-18

---

## XV. Tuyên bố cuối cùng

Bộ use case của MedBASE V2 phải làm rõ toàn bộ hành trình:

> **referral → lead / register → profile → KYC / eligibility → catalog / cart → checkout / order → ops / reporting**

trong đó MedBASE là hệ thống sở hữu và điều phối toàn bộ business flow trong phạm vi V2.