04 — Hợp đồng Surfaces (FE · BE · Dashboard)

1. Định nghĩa surface

ID	Tên	Repo path	Vai trò JWT
S-CON	Consumer	`mobile/`	`USER`
S-PAR	Partner	`partner/`	`PARTNER_OWNER`, `PARTNER_STAFF`, `LANDLORD`, `DOCTOR`…
S-DRV	Driver	`driver/`	`DRIVER`
S-ADM	Admin Dashboard	`dashboard/`	`ADMIN`
S-API	Backend	`api/`	phát hành JWT
S-WEB	Marketing site	`web/`	— (static; CTA APK / Admin)

2. Contract giao tiếp

Từ → Đến	Protocol	Chuẩn
Mọi FE → API	HTTPS REST `/api/v1`	OpenAPI Swagger
FE realtime → API	WebSocket / Socket.IO	channel theo `02-ARCHITECTURE`
FE → Maps	SDK (Google/Mapbox)	API key env — không hardcode
Dashboard → API	REST + JWT admin	cùng NestJS, prefix có thể `/admin` trong module

3. Phiên bản & tương thích

URI version: v1
Breaking change: tăng version hoặc thêm field optional — không đổi nghĩa field cũ
Stub response shape cố định:

{
  "status": "stub",
  "operation": "<domain.action>",
  "message": "Swagger contract — chưa implement business logic"
}

Khi IMP: bỏ status: stub, trả DTO thật; cập nhật ma trận Status → IMP.

4. Shared resources (dùng chung nhiều surface)

Resource	Consumer	Partner	Driver	Admin
User profile	●	○	○	●
Place / POI	●	○ claim	—	● CMS
Order	●	●	○	●
Trip	●	—	●	●
Wallet ledger	●	○	●	●
Media files	●	●	○	●
Reviews	●	● reply	● reply	● mod
Chat thread	●	●	●	○

5. Naming API

/api/v1/<resource>
/api/v1/<resource>/:id
/api/v1/<resource>/nearby?lat=&lng=
/api/v1/<vertical>/partner/...   # partner scoped
/api/v1/driver/...               # driver scoped

Partner scope: BE bắt buộc filter theo storeId / ownership từ JWT — không tin client gửi storeId tự do.

6. Design tokens & UI

Consumer/Partner/Driver: mobile/src/theme/tokens.ts (tái sử dụng package theme sau)
Dashboard: tokens web riêng nhưng cùng brand primary #0B4F9C
Copy tiếng Việt theo mockup

7. Khi scaffold Dashboard

Tạo dashboard/ (Next.js hoặc Vite React) với:

dashboard/src/modules/<domain>/
dashboard/src/shared/api.ts   # cùng base URL API

Mỗi module dashboard map 1:1 domain trong ma trận cột Admin Dashboard.

8. Navigation & RBAC (chốt — xem doc 14)

Chi tiết screen/nav: 14-SCREEN-MATRIX-OFFICIAL.md §2–§7.

Surface	Nav chốt	Role
CON	Tabs Map · Reels · Social · Chat · Account (+ MapStack services)	`USER`
PAR	Auth → Onboarding → Home vertical → Overview/Ops/Form/Finance/Account	`PARTNER_*` · `LANDLORD` · `DOCTOR`
DRV	Auth → MainTabs Home · Trips · Wallet · Ratings · Account	`DRIVER`
ADM	Sidebar Overview · KYC · Partners · Drivers · Ops · Wallet · Support · Verticals · CMS	`ADMIN`

Ownership: BE filter storeId/orgId từ JWT — không tin client.

Hat exclusive (WP-AUTH-HAT-SPLIT-01): DRIVER không login/book trên mobile/ · USER không ops chuyến trên driver/ (trừ đăng ký hồ sơ). Không dual-account CON+DRV trên cùng JWT hat.

Role matrix (WP-AUTH-ROLE-MATRIX-01): 7 JWT · capability RIDE|COURIER|DELIVERY|SCHOOL_TRIP trên DriverProfile · GET /users/me/hats · chi tiết ROLE-MATRIX.md.