FitZalo Docs

Appearance

MiniApp V2 Mock — Completion Specs (Gap Closure) ​

0) Purpose ​

Tài liệu này định nghĩa spec bổ sung để đội dev chuyển miniapp_v2/miniapp từ mock-first sang production-ready, dựa trên đối chiếu:

  1. docs_hub_v3
  2. backend v2 thực tế
  3. legacy OLD_CODE/fit-miniapp-master
  4. implementation hiện tại của miniapp_v2/miniapp

1) Executive Gap Summary ​

1.1 What is already good in miniapp_v2 ​

  • Có đủ khung route cho commerce core + account + news.
  • UX state rõ: loading/empty/error ở phần lớn màn hình.
  • Store/state kiến trúc rõ ràng, tách được adapter API.
  • Có auth-gate pattern cho protected routes.

1.2 Critical gaps to close ​

  1. Toàn bộ network layer đang là MockAPI in-memory, chưa map thực vào backend v2/*.
  2. Chưa có contract mapper chuẩn cho chênh lệch payload giữa FE model và BE DTO.
  3. Chưa có chuẩn error normalization (guest/auth/tenant/permission/domain).
  4. Chưa chốt tenant bootstrap flow đầu app theo DEC-002.
  5. Chưa có bộ test contract + E2E cho hành trình chính.

1.3 Legacy parity notes ​

  • Legacy có nhiều flow rộng (medical/minigame/community) không nên kéo nguyên trạng.
  • Nên ưu tiên parity cho nhóm business critical:
    • Auth tenant login
    • Catalog/search
    • Cart/checkout/order
    • Address/voucher/notification
    • News/bookmark

2) Target Architecture (Mock-to-Real) ​

2.1 Adapter strategy (mandatory) ​

Tách interface API thành 2 implementation:

  • MockApiAdapter (giữ cho dev/demo)
  • HttpApiAdapter (production)

Yêu cầu:

  • Không đổi screen contract và store contract.
  • Không để UI gọi trực tiếp axios/fetch.
  • Mọi mapping dữ liệu qua layer mapper/*.

2.2 Required package layers ​

  1. services/api/client (auth header, refresh, retry policy)
  2. services/api/modules/* (catalog/order/news/...)
  3. services/mappers/* (BE DTO -> FE model)
  4. services/errors/normalize (domain error)

3) Detailed Completion Specs by Domain ​

3.1 AUTH + TENANT BOOTSTRAP ​

Requirements ​

  • R-AUTH-001: Init app phải chạy tenant-aware login flow theo DEC-002.
  • R-AUTH-002: Nếu thiếu tenant binding (tenantId|appInstanceId) phải fail fast với màn hình recoverable.
  • R-AUTH-003: Refresh token phải preserve tenant context.
  • R-AUTH-004: Protected route phải resume action sau login success.

Acceptance ​

  • AC-AUTH-001: App khởi động với context hợp lệ tạo được session có tenantId.
  • AC-AUTH-002: Context lỗi trả thông báo business-safe + CTA retry.
  • AC-AUTH-003: Token expired nhưng refresh success không văng khỏi flow.

3.2 CATALOG + SEARCH ​

Requirements ​

  • R-CAT-001: getCategories/getProducts/getProductDetail dùng endpoint thật v2/catalog/*.
  • R-CAT-002: FE filter local phải phân biệt với backend search/filter, không nhân đôi logic không cần thiết.
  • R-CAT-003: Search telemetry cần event schema thống nhất.

Acceptance ​

  • AC-CAT-001: Home/category/search render đúng dữ liệu backend.
  • AC-CAT-002: Empty/search error hiển thị đúng chuẩn message.
  • AC-CAT-003: Product detail hiển thị đúng stock/price/summary từ BE.

3.3 CART + CHECKOUT + ORDER ​

Requirements ​

  • R-ORD-001: Cart state cần đồng bộ backend (GET/ADD/PATCH/DELETE carts).
  • R-ORD-002: Checkout dùng endpoint POST /v2/ecommerce/orders/checkout (không tự tạo order local).
  • R-ORD-003: Voucher validate/apply đi qua backend voucher contract.
  • R-ORD-004: Order list/detail dùng backend pagination/filter.
  • R-ORD-005: Action theo trạng thái phải map đúng endpoint/permission.

Acceptance ​

  • AC-ORD-001: Cart refresh vẫn giữ đúng data server.
  • AC-ORD-002: Checkout thành công tạo order thật và clear cart UI.
  • AC-ORD-003: Voucher invalid/expired/min-order trả đúng error mapping.
  • AC-ORD-004: Order timeline/status transition đúng business rule.

3.4 ADDRESS BOOK ​

Requirements ​

  • R-ADDR-001: CRUD address phải dùng persistence backend, không trộn local/server không kiểm soát.
  • R-ADDR-002: Chỉ có 1 default address tại mọi thời điểm.
  • R-ADDR-003: Address picker trả về summary contract dùng được ngay cho checkout.

Acceptance ​

  • AC-ADDR-001: Thêm/sửa/xoá/default phản ánh đúng sau reload.
  • AC-ADDR-002: Validation FE + BE không mâu thuẫn.

3.5 VOUCHER ​

Requirements ​

  • R-VCH-001: Wallet list từ backend voucher scope theo user/tenant.
  • R-VCH-002: Code apply tại checkout phải lock race condition (double submit).
  • R-VCH-003: Voucher requires-login xử lý qua auth-gate, không alert rời rạc.

Acceptance ​

  • AC-VCH-001: Mã hợp lệ áp dụng đúng discount.
  • AC-VCH-002: Mã không hợp lệ trả thông báo chuẩn hoá.

3.6 NOTIFICATION ​

Requirements ​

  • R-NOTI-001: Dùng in-app notification endpoint thật.
  • R-NOTI-002: unread badge count sync với profile/home header.
  • R-NOTI-003: mark-read idempotent.

Acceptance ​

  • AC-NOTI-001: Read state nhất quán sau refresh/app reopen.

3.7 NEWS + BOOKMARK ​

Requirements ​

  • R-NEWS-001: News feed/detail/search dùng backend CMS/public API thống nhất.
  • R-NEWS-002: Bookmark phải sync server-side theo user, không mất khi relogin.
  • R-NEWS-003: Rich content renderer support schema versioning.

Acceptance ​

  • AC-NEWS-001: News home/detail/search/saved chạy end-to-end.
  • AC-NEWS-002: Bookmark từ detail phản ánh ngay trong saved list.

4) Cross-Cutting Specs ​

4.1 Error Normalization ​

Chuẩn hoá tất cả lỗi về format:

  • code
  • message
  • httpStatus
  • retryable

Bản đồ lỗi tối thiểu:

  • UNAUTHORIZED
  • FORBIDDEN_TENANT
  • FORBIDDEN_PERMISSION
  • VALIDATION_ERROR
  • NOT_FOUND
  • CONFLICT
  • RATE_LIMITED
  • UNKNOWN

4.2 Observability ​

  • FE events bắt buộc:
    • login_start/login_success/login_fail
    • search_submit
    • add_to_cart
    • checkout_start/checkout_success/checkout_fail
    • order_action
    • voucher_apply

4.3 Security ​

  • Không log token/PII.
  • Không lưu token vào query string.
  • Auto logout khi refresh fail hard.

5) Delivery Backlog (Recommended Priority) ​

P0 — Must have (go-live blocker) ​

  1. AUTH tenant bootstrap + refresh stability
  2. Catalog/Search real API adapter
  3. Cart/Checkout/Order real API adapter
  4. Address + Voucher real API adapter
  5. Error normalization middleware
  6. Contract tests cho 5 domain trên

P1 — Should have ​

  1. Notifications real adapter + unread sync
  2. News real adapter + bookmark persistence
  3. Unified analytics event schema
  4. Retry/backoff policy per endpoint type

P2 — Nice to have ​

  1. Offline-first cache strategy cho categories/news
  2. Optimistic UI cho bookmark/cart item qty
  3. A/B hooks cho search ranking

6) Test Plan Addendum (Mandatory) ​

6.1 Contract tests ​

  • Auth, catalog, cart/order, address, voucher, news.

6.2 E2E critical journeys ​

  1. Guest browse -> auth-gate -> login -> checkout success
  2. Order list -> order detail -> action transition
  3. News detail -> bookmark -> saved list

6.3 Regression checklist ​

  • Theme mode không ảnh hưởng data flow.
  • Protected routes không rò data khi logout.
  • Token refresh race condition khi nhiều request đồng thời.

7) Done Criteria for “MiniApp V2 Mock Completed” ​

Hoàn thành khi thỏa đồng thời:

  1. 100% feature P0 chạy bằng real backend, không phụ thuộc mock data.
  2. Contract tests pass cho tất cả domain P0.
  3. 3 E2E critical journeys pass.
  4. Traceability cập nhật trong docs_hub_v3 (feature status + API mapping).
  5. Không còn TODO blocker trong spec này.

FitZalo Platform Documentation

© 2026 FitSoft — Internal Use Only