08 — Quy tắc FE + lộ trình Figma ↔ Ma trận ↔ App

Mục tiêu: AI/ người dựng app đầy đủ theo đúng bố cục design (Home map + 5 tab), nối dây Figma/JPG → screen → navigation → API → cập nhật ma trận. Đọc kèm: 00-DOC-MAP · 01-MATRIX · design-index · FIGMA · 05-PHASE-BACKLOG

Figma file: WELIFE - Mobile App UI · fileKey=w0SRHX3cbiWLFHjzVC0pTE Fallback: JPG/PDF + skill image-to-ui (khi MCP View-only). Tokens: mobile/src/theme/tokens/ · DESIGN-TOKEN-AUDIT · WP-FIGMA-TOKENS-01 DONE · FIGMA_EXACT_SYNC: DEFERRED FE queue: figma-fe-work-queue.json → DONE_QUEUE · doc 19

1. Sơ đồ “nối dây” (bố trí như quy hoạch)

flowchart TB
  subgraph Design["Design nguồn"]
    FIG[Figma frame / JPG / PDF]
    SCR["SCR-DOMAIN-NAME"]
    IDX[design-index.md]
  end

  subgraph Matrix["Ma trận 01"]
    DOM["D-* Domain"]
    WP["WP-*-nn"]
    ROW["Hàng: Design · FE · BE · PAR · DRV · ADM"]
  end

  subgraph AppCON["Consumer mobile/ — bố cục app"]
    ROOT[RootNavigator]
    AUTH[AuthStack]
    TABS[MainTabs — 5 tab]
    STACKS[Feature stacks]
  end

  subgraph BE["api/"]
    TAG[Swagger tag]
    EP["/api/v1/..."]
  end

  FIG --> SCR
  SCR --> IDX
  SCR --> DOM
  DOM --> WP
  WP --> ROW
  SCR --> STACKS
  ROOT --> AUTH
  ROOT --> TABS
  TABS --> STACKS
  STACKS -->|api.ts + zod| EP
  EP --> TAG
  TAG --> ROW

Một màn hình = một chuỗi ID bắt buộc:

Không có SCR/Domain → không code UI.

2. Bố cục app Consumer (khớp mockup Home + Navigation)

Theo KE-HOACH §6.3 và JPG Navigation / Home map:

┌─────────────────────────────────────┐
│           Status / Header            │
│     (search · location · AI entry)   │
├─────────────────────────────────────┤
│                                     │
│         NỘI DUNG TAB HIỆN TẠI        │
│   Map = lưới dịch vụ + bản đồ        │
│   Reels / Social / Chat / Account    │
│                                     │
├─────────────────────────────────────┤
│  🗺 Map │ 🎬 Reels │ 📰 Social │ 💬 Contact │ 👤 Tài khoản │
└─────────────────────────────────────┘

2.0 Hiện / ẩn tab bar và nút Back (WP-FE-NAV-01)

Tab bar (5 icon Map · Reels · Social · Contact · Tài khoản)

Cách hiện: thanh dưới cao 54, icon 22, tab đang chọn colors.primary, tab khác colors.muted, ẩn khi bàn phím mở. Nested → display: 'none' (không để tab đè CTA / map immersive).

Nút Back (navbar trên — không dùng native stack header)

Cách hiện: icon arrow-left 24pt, vùng chạm 44×44, mép trái header, accessibilityLabel="Quay lại". Không bật headerShown của Native Stack (tránh hai nút back). Màn immersive (Call, RouteActive, matching) ẩn tab; đóng/back theo ngữ cảnh (kết thúc cuộc gọi), không pop nhầm về tab.

2.1 Năm tab gốc + feature folders

2.2 Lưới dịch vụ trên Map (ô icon → stack)

Mỗi ô trên Home map không là tab mới — là stack push từ MapTab:

2.3 Navigation tree (code)

RootNavigator
├── AuthStack          (chưa login)
│   └── Login
└── AppStack           (đã login)
    ├── MainTabs
    │   ├── MapTab → MapStack
    │   │     ├── HomeMap          (lưới dịch vụ)
    │   │     ├── PlacesNearby
    │   │     └── [Vertical stacks qua navigate]
    │   ├── ReelsTab → ReelsStack
    │   ├── SocialTab → SocialStack
    │   ├── ChatTab → ChatStack
    │   └── AccountTab → AccountStack
    └── Modal / shared
          ├── Assistant (D-ASSIST)
          ├── Notifications (D-NOTIF)
          └── MediaPicker

Quy tắc nối dây navigation

1. Tab chỉ đổi root section — không nhảy tab khi đang deep flow thanh toán (trừ explicit “Về trang chủ”).
2. Vertical từ Map: navigation.navigate('RideQuote', { … }) trong cùng MapStack hoặc nested stack đăng ký ở root.
3. Deep-link: welife://rides/:id, welife://orders/:id, welife://chat/:conversationId.
4. Partner / Driver = app riêng (partner/, driver/) — không nhét tab Partner vào Consumer.

3. Bộ quy tắc (bắt buộc khi code FE)

R1 — Gate trước khi viết UI

[ ] Domain D-* + WP-*-nn (từ 05-PHASE-BACKLOG / 01-MATRIX)
[ ] Surface: CON | PAR | DRV
[ ] Design: Figma node-id **hoặc** Read JPG (design-index)
[ ] BE: endpoint đã có trên /docs (IMP hoặc stub rõ)
[ ] Path: mobile|partner|driver/src/features/<domain>/

R2 — Nối Figma / ảnh

R3 — Nối ma trận trong app

Mỗi feature folder có file mỏng TRACE.md (optional) hoặc comment đầu screen:

/** SCR-PARK-NEARBY · D-PARK · WP-PARK-FE-01 · GET /parking/lots/nearby */

Khi Done WP FE: cập nhật cột Consumer FE + Status trong 01-MATRIX-TRACEABILITY.md.

R4 — Kiến trúc code FE (ít lỗi AI)

features/<domain>/
  screens/          # 1 file ≈ 1 SCR
  components/       # chỉ domain
  hooks/            # data + UI state
  api.ts            # gọi services/api.ts
  types.ts          # zod + types từ Swagger

• HTTP chỉ qua services/api.ts
• Parse response quan trọng bằng zod
• Shared primitives: shared/ui/
• Một turn AI = một WP / một SCR (không dựng cả 5 tab cùng lúc)

R5 — Surfaces

R6 — Trạng thái UI theo BE

4. Lộ trình phát triển từng phần (FE đầy đủ)

BE nhiều domain đã IMP — lộ trình dưới là thứ tự dựng UI + nối dây, không làm lại BE trừ khi gap.

Phase F0 — Khung app (1–2 tuần) ★ ưu tiên ngay

Ma trận: cập nhật D-PLACE / home path; navigation JPG b6ccd….

Phase F1 — Account + ví + địa chỉ (song song BE đã IMP)

Phase F2 — Vertical Map (discovery → book)

Thứ tự theo độ sẵn sàng BE:

Mỗi WP: CON UI trước → nếu có Partner mockup → WP-FE-*-PAR trên partner/.

Phase F3 — Contact + Social (BE đã IMP)

Phase F4 — Partner + Driver polish

| WP | App | Focus | | -------------- | -------- | --------------------------------------- | ------- | | WP-FE-PAR-HOME | partner/ | Dashboard overview · F&B orders · staff | IMP | | WP-FE-DRV-TRIP | driver/ | Online → accept → pickup → complete | IMP |

Phase F5 — Vertical P2 — DONE 2026-07-27

Audit tiếp: 11-FE-SURFACE-AUDIT.md (Partner pharm/med/school UI).

Phase F6 — AI · Favorites · Realtime

| WP | Việc | | ------------- | ------------------------------------- | ------- | | WP-FE-AI-01 | Assistant sheet từ header Home | IMP | | WP-FE-FAV-01 | Favorites list + toggle | IMP | | WP-FE-WS-01 | Chat WebSocket + WebRTC signal + push | IMP | | WP-RIDE-WS-01 | Rides GPS /rides | IMP |

5. Bảng link nhanh Domain → Tab → Folder → Design

Partner JPG → partner/src/features/<domain>/ (không vào mobile/).

6. Checklist một màn (DoD FE)

• SCR-* + Figma node hoặc JPG đã Read
• Screen trong đúng features/<domain>/screens
• Route đăng ký đúng tab/stack §2
• Gọi API qua api.ts + zod
• Loading / empty / error
• Tokens, không magic color
• AC trong WP pass
• Cập nhật 01-MATRIX cột FE

7. Prompt Cursor mẫu (copy)

Làm FE theo docs/08-FE-ROADMAP-FIGMA-MATRIX.md
Domain: D-PARK · WP-FE-PARK-01 · Surface: CON
Design: Read JPG 25af… (hoặc Figma node-id=…)
SCR: SCR-PARK-NEARBY
Path: mobile/src/features/parking/
Nav: MapStack → ParkingNearby
BE: GET /api/v1/parking/lots/nearby (IMP)
AC: list + distance + tap chi tiết; tokens; zod; empty state
Không đụng tab khác / partner.

8. Liên kết tài liệu