Ma trận Role · Hat · Capability (chốt)

WP-AUTH-ROLE-MATRIX-01 · D-AUTH · Surfaces CON · PAR · DRV · ADM · API Nguồn: Role enum + 04-SURFACES-CONTRACT + 14-SCREEN-MATRIX-OFFICIAL §7.

1. Không nhân JWT Role

Tầng	Số	Ghi chú
Hat (app)	4	`mobile/` `driver/` `partner/` `dashboard/`
JWT `Role`	7 (tối đa ~12)	Danh tính pháp lý
Capability tài xế	4 cờ	Việc được làm — không phải Role

7 Role hiện tại: USER · DRIVER · PARTNER_OWNER · PARTNER_STAFF · LANDLORD · DOCTOR · ADMIN

Không tạo COURIER / FOOD_DRIVER / SCHOOL_DRIVER.

2. Mở quyền

Đăng ký → luôn USER (hat CON).
Role khác chỉ BE gắn sau Admin APPROVED (giấy tờ đủ).
GET /users/me/hats — UI Tài khoản: unlocked mới mở app DRV/PAR.
Hat exclusive: DRIVER không book trên CON (WP-AUTH-HAT-SPLIT-01).

flowchart TB
  USER[USER hat CON] --> KYC[Nộp giấy]
  KYC --> ADM[Admin queue]
  ADM -->|GPLX xe selfie| DRV[Role DRIVER + capabilities]
  ADM -->|MST GPKD| PAR[PARTNER_OWNER + LANDLORD/DOCTOR theo loại DN]
  DRV --> AppD[driver/]
  PAR --> AppP[partner/]

3. Capability tài xế (`DriverProfile.capabilities`)

Cờ	Việc	Matching / màn DRV
`RIDE`	Chở người	`Ride` auto-assign · Trips
`COURIER`	FNB / grocery	`Order.driverId`
`DELIVERY`	Bưu kiện A→B	`DeliveryOrder`
`SCHOOL_TRIP`	Đưa rước HS	Chưa matching — cần mockup

Admin duyệt: mặc định RIDE+COURIER+DELIVERY (tài xế đã APPROVED được backfill). Confirm Cancel = chỉ RIDE.

4. Partner extra role

businessType chứa RENT/LANDLORD → thêm LANDLORD. MED/DOCTOR/CLINIC → thêm DOCTOR. FNB chỉ PARTNER_OWNER.

5. API

Method	Path	Ai
GET	`/users/me/hats`	JWT USER+
GET	`/users/admin/overview`	ADMIN
GET	`/users/admin`	ADMIN
PATCH	`/users/admin/:id/roles`	ADMIN
POST	`/users/admin` body `{ hat, email?, phone?, fullName?, roles? }`	ADMIN · WP-ADM-ROLES-02
PATCH	`/users/admin/:id` hồ sơ + quyền + `disabled`	ADMIN · WP-ADM-ROLES-02
DELETE	`/users/admin/:id` khoá đăng nhập (không xoá cứng)	ADMIN · WP-ADM-ROLES-02
PATCH	`/driver/admin/applications/:id` body `capabilities[]`	ADMIN

6. Màn bắt buộc

CON: Account → Vai trò (RoleSwitcher) luôn hiện; PENDING/REJECTED không mở app.
DRV: Register · KYC · Home jobs theo capability.
ADM: Driver queue hiện capability + confirm lúc duyệt.
ADM: WP-ADM-HUB-01 + WP-ADM-ROLES-01/02 màn Phân quyền — 4 hat × 7 JWT, Thêm/Sửa/Khoá theo hat.
ADM: WP-ADM-SESSION-01 persist JWT (access+refresh) cùng /auth/* với app; không đăng ký trên Dashboard.
ADM: WP-FE-ADM-LOGIN-01 màn login giống CON (OTP/mật khẩu/Google GIS).
PAR: Onboarding · chờ duyệt · vertical theo role.

Tương lai: OPS/SUPPORT (ADM) · SCHOOL_ADMIN / PHARMACIST chỉ khi pháp lý bắt buộc — không thêm trước.