# Role & Permission Matrix — MedBASE V2

> Tài liệu này mô tả **vai trò, quyền hành động và ranh giới authority** trong MedBASE V2.

## 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 6 BuyerScope (FULL / LIMITED / SPECIALTY / CHAIN-by-site / ENTERPRISE / NON_PHARMA) và hành vi chặn RESTRICTED/SPECIAL. | 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 phân quyền

- quyền giao dịch có ý nghĩa business chỉ được xác lập trong MedBASE
- role permission là một phần của business control, không chỉ là security control
- có quyền xem không đồng nghĩa có quyền quyết định
- có quyền thao tác thủ công không đồng nghĩa có quyền bypass domain rules

---

## III. Danh sách role chính thức

| Role | Mô tả |
|---|---|
| Guest | user chưa đăng nhập, có thể đến từ PMS referral/webview entry |
| Registered Buyer | buyer đã có account nhưng chưa chắc đủ điều kiện giao dịch |
| Verified Buyer | buyer đã đủ điều kiện theo policy hiện hành của V2 |
| Admin | role quản trị và kiểm soát cao nhất trong V2 |
| Compliance Reviewer | role xử lý review KYC/eligibility theo policy |
| Ops | role vận hành hằng ngày |
| Catalog Manager | role quản lý catalog / product content theo policy |
| Inventory Ops | role giám sát / xử lý inventory trong phạm vi được cấp quyền |
| Reporting Viewer | role chỉ xem dashboard và KPI |

---

## IV. Ma trận quyền cấp capability

| Capability | Guest | Registered Buyer | Verified Buyer | Admin | Compliance Reviewer | Ops | Catalog Manager | Inventory Ops | Reporting Viewer |
|---|---|---|---|---|---|---|---|---|---|
| Mở landing / entry page | Có | Có | Có | Có | Có | Có | Có | Có | Có |
| Gửi lead | Có | Có | Có | Không | Không | Không | Không | Không | Không |
| Đăng ký tài khoản | Có | Không | Không | Không | Không | Không | Không | Không | Không |
| Đăng nhập | Có | Có | Có | Có | Có | Có | Có | Có | Có |
| Xem / cập nhật hồ sơ của chính mình | Không | Có | Có | Không | Không | Không | Không | Không | Không |
| Nộp hồ sơ KYC / eligibility | Không | Có | Có | Không | Không | Không | Không | Không | Không |
| Xem trạng thái KYC của chính mình | Không | Có | Có | Không | Không | Không | Không | Không | Không |
| Duyệt catalog | Có | Có | Có | Có | Có | Có | Có | Có | Không |
| Xem chi tiết sản phẩm | Có | Có | Có | Có | Có | Có | Có | Có | Không |
| Thêm vào giỏ hàng | Không | Có theo policy | Có | Không | Không | Không | Không | Không | Không |
| Checkout / create order | Không | Không | Có theo policy | Không | Không | Không | Không | Không | Không |
| Xem order của chính mình | Không | Có nếu có order | Có | Không | Không | Không | Không | Không | Không |
| Xem lead queue | Không | Không | Không | Có | Không | Có | Không | Không | Không |
| Cập nhật lead status | Không | Không | Không | Có | Không | Có | Không | Không | Không |
| Xem KYC queue | Không | Không | Không | Có | Có | Có xem/support | Không | Không | Không |
| Final approve/reject KYC | Không | Không | Không | Có | Có theo cấu hình policy | Không trừ khi được cấp quyền rõ ràng | Không | Không | Không |
| Xem order monitoring | Không | Không | Không | Có | Không | Có | Không | Không | Không |
| Xem inventory monitoring | Không | Không | Không | Có | Không | Có | Không | Có | Không |
| Điều chỉnh stock thủ công qua supported flow | Không | Không | Không | Có theo policy | Không | Không | Không | Có theo policy | Không |
| Quản lý product content cơ bản | Không | Không | Không | Có | Không | Không | Có | Không | Không |
| Quản lý product compliance fields theo policy | Không | Không | Không | Có | Consult / Review | Không | Có theo policy | Không | Không |
| Thực hiện manual operation request qua flow hỗ trợ | Không | Không | Không | Có | Không | Có theo policy | Không | Có theo policy | Không |
| Xem reporting dashboard | Không | Không | Không | Có | Có | Có | Không | Không | Có |

---

## V. Authority rule quan trọng

### KYC / Eligibility Decision
- quyền final approve/reject không mặc định thuộc Ops
- nếu Ops chỉ support queue, Ops không được thực hiện final decision
- authority cuối cùng phải được cấu hình rõ và audit được

### Checkout Authority
- chỉ Verified Buyer mới có thể đi qua checkout thành công theo policy V2
- Registered Buyer có thể có cart capability theo policy, nhưng không được commit order khi chưa đủ điều kiện

### Product / Compliance Authority
- Catalog Manager không đương nhiên có quyền quyết định compliance override
- Product compliance fields nhạy cảm phải theo policy và audit trail

### Inventory Authority
- Inventory Ops chỉ được điều chỉnh inventory qua supported flow
- không được chỉnh phá reservation invariants

### Reporting Authority
- Reporting Viewer chỉ có read-only access
- reporting access không kéo theo quyền sửa business truth

---

## V-bis. Buyer Scope (gán sau khi KYC approved)

> Scope là "sub-role" của Verified Buyer, quyết định **phạm vi product** mà buyer được phép xem giá, add-to-cart, checkout. Nguồn gốc từ phân loại Buyer tại [03-business-overview-brd.md §IV-bis.1](./03-business-overview-brd.md) và ma trận tại §IV-bis.4.

| Scope | Buyer type tương ứng | Hành vi khi gặp ETC | Hành vi khi gặp RESTRICTED | Hành vi khi gặp SPECIAL |
|---|---|---|---|---|
| **SCOPE_FULL** | Pharmacy, Chain (điểm bán đủ giấy phép) | ✅ Mua được (nếu có REP-05) | ✅ Mua được | ✅ Mua được (theo điều kiện bảo quản + báo cáo) |
| **SCOPE_LIMITED** | Drugstore | ✅ (thiết yếu) | 🚫 Chặn add-to-cart + cảnh báo lý do | 🚫 Chặn tuyệt đối |
| **SCOPE_SPECIALTY** | Clinic / Medical | ✅ (nội bộ chuyên môn) | 🚫 Chặn | 🚫 Chặn |
| **SCOPE_ENTERPRISE** | Pharma Enterprise | 🚫 Chặn | 🚫 Chặn | 🚫 Chặn |
| **SCOPE_NON_PHARMA** | Non-Pharma, Spa/Retail | 🚫 Không thấy giá | 🚫 Không thấy giá | 🚫 Không thấy giá |
| **(chưa gán)** | Buyer ở trạng thái PENDING_REVIEW | Xem được product nhưng **không thấy giá**, không add-to-cart | Như trên | Như trên |

### Quy trình gán scope **[MANUAL-P1]**
- Phase 1: Admin gán `BuyerScope` **thủ công** trên CMS ngay sau khi approve KYC. SLA 30 phút/case.
- Không có auto-derive scope từ document OCR ở Phase 1.
- Đổi scope sau khi đã gán: yêu cầu Admin tạo `ManualOperationRequest` kèm lý do (OPS-03).

---

## VI. Data visibility rule ở mức nguyên tắc

| Data Surface | Principle |
|---|---|
| Buyer own profile | buyer chỉ xem/sửa dữ liệu của chính mình theo policy |
| Buyer own order history | buyer chỉ xem order của chính mình |
| Lead queue | chỉ Admin/Ops được xem |
| KYC detail | Admin/Compliance Reviewer xem đầy đủ; Ops chỉ theo mức cần thiết theo policy |
| Product compliance detail | chỉ role nội bộ được cấp quyền phù hợp |
| Inventory detail | chỉ Admin/Ops/Inventory Ops |
| Reporting dashboard | Admin/Ops/Reporting Viewer |

---

## VII. Các quyền ngoài phạm vi V2

Không tồn tại permission V2 cho:
- PMS buyer mapping review
- PMS draft cart handling
- PMS sync retry management
- PMS callback processing
- deep orchestration với Viettel PMS

---

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

Ma trận quyền của V2 phải luôn giữ nguyên tắc:

> **mọi quyền có ý nghĩa giao dịch hoặc compliance đều do MedBASE kiểm soát, và không role nào được phá business truth bằng shortcut ngoài flow ứng dụng hỗ trợ.**