# Screen & Field Specification — MedBASE V2

> Tài liệu này là **source of truth ở mức screen / field** cho MedBASE V2.
> Tài liệu này chỉ mô tả phạm vi **V2 chính thức**, không bao gồm các capability PMS deep integration đã bị loại khỏi scope.

## 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 |

---

> **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 chung

- Chỉ mô tả screen/field thuộc V2 chính thức
- Không bao gồm PMS draft cart, PMS mapping, PMS order sync hay deep orchestration
- Field-level detail ở đây phải bám theo:
  - [05-business-rules.md](./05-business-rules.md)
  - [06-role-permission-matrix.md](./06-role-permission-matrix.md)
  - [07-compliance-control-matrix.md](./07-compliance-control-matrix.md)
- Một field có thể có 3 trạng thái khác nhau:
  - visible
  - editable
  - actionable impact
- Những field có ý nghĩa pháp lý/compliance phải được ưu tiên ở admin/compliance-facing surfaces

---

## III. Public / Entry Screens

### PUB-00 — Landing / Referral Entry
| Field / Component | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Source Context | text / hidden | No | system derived | chỉ dùng cho attribution |
| Headline / Intro | text | Yes | read-only | giới thiệu MedBASE |
| CTA - Gửi lead | button | Yes | - | điều hướng sang Lead Capture |
| CTA - Đăng ký | button | Yes | - | điều hướng sang Register |
| CTA - Xem catalog | button | Yes | - | theo policy hiển thị |

### PUB-01 — Lead Capture
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Số điện thoại | text | Yes | phone format | field bắt buộc tối thiểu |
| Họ tên | text | No | trim, max length | optional |
| Nhu cầu / ghi chú | textarea | No | max length | optional |
| Source | hidden / text | Conditional | system derived | attribution only |
| Nút Gửi lead | button | Yes | enable if valid | |
| Thông báo kết quả | alert / text | No | read-only | thành công / lỗi |

### PUB-02 — Login
| Field / Component | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Email / Số điện thoại | text | Yes | email/phone format | định danh đăng nhập |
| Mật khẩu | password | Yes | required | |
| Nút Đăng nhập | button | Yes | enable if valid | |
| Link Đăng ký | link | Yes | - | |
| Link Quên mật khẩu | link | Yes | - | |
| Thông báo lỗi | alert / text | No | read-only | |

### PUB-03 — Register
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Tên cơ sở | text | Yes | trim, max length | |
| Email | email | Yes | unique, valid format | |
| Số điện thoại | text | Yes | unique, valid phone | |
| Mật khẩu | password | Yes | complexity | |
| Xác nhận mật khẩu | password | Yes | must match | |
| Loại buyer khai báo | select | Yes | allowed values | chốt theo master data |
| Đồng ý điều khoản | checkbox | Yes | must check | |
| Nút Đăng ký | button | Yes | enable if valid | |

---

## IV. Buyer Screens

### BUY-01 — Buyer Profile
| Field | Type | Required | Editable | Notes |
|---|---|---|---|---|
| Buyer ID | text | Yes | No | mã nội bộ |
| Tên cơ sở | text | Yes | Yes | |
| Loại buyer | select / text | Yes | Conditional | có thể read-only sau khi approved |
| Trạng thái account | badge | Yes | No | không đồng nghĩa verification |
| Người liên hệ | text | Yes | Yes | |
| Email liên hệ | email | Yes | Yes | |
| Số điện thoại liên hệ | text | Yes | Yes | |
| Địa chỉ cơ sở | textarea | Yes | Yes | |
| Nút Cập nhật hồ sơ | button | Yes | - | |
| Link tới KYC / hồ sơ đủ điều kiện | link/button | Yes | - | |

### BUY-02 — KYC / Eligibility Submission
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Trạng thái hồ sơ | badge | Yes | read-only | PENDING_REVIEW / VERIFIED / REJECTED / RESUBMIT_REQUIRED |
| Tên cơ sở | text | Yes | trim | prefill từ profile nếu có |
| Loại buyer | select | Yes | allowed values | |
| Số GPP / license tương ứng | text | Conditional | trim | theo policy |
| Địa chỉ cơ sở | textarea | Yes | max length | |
| Người đại diện / liên hệ | text | Yes | max length | |
| Email | email | Yes | valid email | |
| Số điện thoại | text | Yes | valid phone | |
| Upload hồ sơ chính | upload | Conditional | file type, size | |
| Upload hồ sơ bổ sung | upload | No | file type, size | |
| Lý do reject | textarea / text | No | read-only | chỉ hiển thị khi reject |
| Nút Gửi hồ sơ | button | Yes | enable if valid | |
| Nút Cập nhật / Gửi lại | button | Conditional | - | dùng cho resubmit |

### BUY-03 — Catalog Home / Listing
| Field / Component | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Search bar | text | Yes | trim | |
| Status banner | alert / banner | No | read-only | buyer chưa đủ điều kiện / bị chặn |
| Quick Filter | chips / filter | No | allowed values | |
| Product list | grid / list | Yes | read-only | |
| Cart icon | button | Yes | - | |
| Link Hồ sơ | link/menu | Yes | - | |

### BUY-04 — Product Detail
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Product ID | text | Yes | read-only | |
| Tên thuốc / tên thương mại | text | Yes | read-only | |
| Dạng bào chế | text | Conditional | read-only | |
| Thành phần / hoạt chất chính | text | Yes | read-only | |
| Hàm lượng / nồng độ / khối lượng | text | Conditional | read-only | |
| Quy cách đóng gói | text | Conditional | read-only | |
| Nhà sản xuất | text | Conditional | read-only | |
| Cơ sở nhập khẩu | text | Conditional | read-only | |
| Số đăng ký / giấy phép nhập khẩu | text | Conditional | read-only | |
| Điều kiện bảo quản | text / textarea | Conditional | read-only | |
| Tag / legal class | badge | Yes | read-only | |
| Giá | currency / text | Conditional | read-only | theo policy hiển thị |
| Trạng thái mua | badge | Yes | read-only | visible / restricted / blocked / inactive |
| Số lượng | number stepper | Conditional | >0 | |
| Nút Add to Cart | button | Conditional | enable if allowed | |
| Thông báo restricted | alert / text | No | read-only | |

### BUY-05 — Cart
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Cart ID | text | Yes | read-only | |
| Product name | text | Yes | read-only | |
| Quantity | number stepper | Yes | >0 | |
| Unit price | currency / text | Conditional | read-only | |
| Subtotal | currency / text | Conditional | read-only | |
| Validation status | badge | No | read-only | valid / invalid / restricted / out_of_stock |
| Error reason | text | No | read-only | |
| Remove item | button | Yes | - | |
| Tổng số item | number | Yes | read-only | |
| Tổng tạm tính | currency / text | Conditional | read-only | |
| Nút Checkout | button | Yes | enable if cart valid | |

### BUY-06 — Checkout
| Field | Type | Required | Validation | Notes |
|---|---|---|---|---|
| Buyer Summary | block | Yes | read-only | tên cơ sở, loại buyer, trạng thái |
| Item list | table/list | Yes | read-only | |
| Eligibility state | badge / text | Yes | read-only | |
| Product validation message | list/text | No | read-only | |
| Stock validation message | list/text | No | read-only | |
| Tổng tiền | currency / text | Conditional | read-only | |
| Nút Xác nhận đặt hàng | button | Yes | enable if valid | |
| Nút Quay lại cart | button | Yes | - | |
| Error message | alert / text | No | read-only | |

### BUY-07 — Order Result / Order History / Order Detail
Yêu cầu tối thiểu:
- order_id
- status
- created_time
- message / reject reason nếu có
- order list filter cơ bản
- buyer chỉ thấy order của chính mình

---

## V. Admin / Ops Screens

### ADM-01 — Lead Queue
| Field / Column | Type | Required | Notes |
|---|---|---|---|
| Lead ID | text | Yes | |
| Phone | text | Yes | |
| Source | text / badge | Yes | |
| Created At | datetime | Yes | |
| Current Status | badge | Yes | |
| Linked Buyer | text | No | nếu đã convert |
| Action - View Detail | button | Yes | |
| Action - Update Status | button | Conditional | theo role |

### ADM-02 — Lead Detail
Tối thiểu phải có:
- lead id
- phone
- source
- campaign/ref nếu có
- created_at
- current_status
- status history
- linked buyer nếu có
- ops note / next action theo policy

### ADM-03 — KYC Review
Tối thiểu phải có:
- queue buyer/case list
- buyer profile summary
- uploaded documents
- current status
- review note
- reject reason
- approve/reject actions theo role

### ADM-04 — Buyer Management
Tối thiểu phải có:
- buyer name
- buyer type
- account status
- verification status
- contact
- created_at
- action view detail

### ADM-05 — Product Management
Tối thiểu phải có:
- product id
- product name
- product type
- legal class
- active status
- supplier / distributor info nếu có
- action edit

### ADM-06 — Product Compliance Detail
Tối thiểu phải có:
- tên thuốc / tên thương mại
- dạng bào chế
- thành phần / hàm lượng / nồng độ
- quy cách đóng gói
- nhà sản xuất
- cơ sở nhập khẩu nếu có
- số đăng ký / giấy phép nhập khẩu
- điều kiện bảo quản
- history thay đổi field pháp lý quan trọng

### ADM-07 — Batch / Lot Management
Tối thiểu phải có:
- batch / lot number
- manufacture_date
- expiry_date
- product reference
- current batch status
- stop-sell / blocked flag nếu có

### ADM-08 — Recall / Stop-Sell Management
Tối thiểu phải có:
- target object (product / batch)
- recall / stop-sell status
- effective time
- reason
- actor
- action history

### ADM-09 — Inventory Monitoring
Tối thiểu phải có:
- product name
- available qty
- reserved qty
- last synced / updated at nếu cần
- action view reservations

### ADM-10 — Order Monitoring
Tối thiểu phải có:
- order id
- buyer
- source/channel
- status
- total amount
- created_at
- action view detail

### ADM-11 — Manual Operation Request
Tối thiểu phải có:
- request id
- target type / target id
- action requested
- reason
- requester
- approver nếu cần
- execution status
- audit trail

### ADM-12 — Reporting Dashboard
Tối thiểu phải có:
- referral count
- lead count
- registration count
- KYC submitted count
- KYC approved count
- first order count
- total orders
- GMV
- filter thời gian
- filter source/channel nếu có

---

## VI. Các màn bị loại khỏi V2 chính thức

Các màn sau **không được xem là official V2 screens**:
- PMS draft cart webview
- PMS embedded checkout handoff
- PMS mapping management
- PMS order result embedded flow như source of truth

---

## VII. Metadata field-level cần chuẩn hóa tiếp

Ở bản refinement tiếp theo, mọi field quan trọng nên có thêm:
- source_of_truth
- visible_roles
- editable_roles
- editable_statuses
- audit_required
- pii_or_sensitive_flag
- legal_required_flag

---

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

Screen-field spec của MedBASE V2 phải đảm bảo:
- đúng scope V2
- đúng rule và authority
- đủ dữ liệu để vận hành
- đủ dữ liệu để hỗ trợ compliance/control review
- không tái đưa các giả định PMS deep integration quay trở lại qua UI