Mini App Spec (V3 — Complete, Living)

0) Metadata

• Scope: Consumer Zalo Mini App (end-user), không bao gồm Portal/Admin.
• Runtime target: miniapp_v2/miniapp (mock-first, production-ready contract).
• Last baseline review: 2026-02-27.
• Decision dependencies: DEC-001, DEC-002.
• Source alignment:
  • docs_hub_v3 core/module specs
  • v2 backend controllers/contracts thực tế
  • OLD_CODE/fit-miniapp-master (legacy behavior)
  • miniapp_v2/miniapp (current implementation)

1) Operating Links

• Project OS: 05_PROJECT_OPERATING_SYSTEM.md
• Engineering Rules: 06_ENGINEERING_RULES.md
• Execution Playbook: 07_EXECUTION_PLAYBOOK.md
• Decision Log: 01_DECISION_LOG.md
• API Traceability: API_TRACEABILITY.md
• Full Screen Spec Pack: miniapp_full_screen_specs/00_INDEX.md

2) Product Scope

2.1 Goals

1. Cung cấp hành trình mua hàng miniapp end-to-end: browse → cart → checkout → order tracking.
2. Hỗ trợ content/engagement: news feed, article detail/search/bookmark.
3. Hỗ trợ account self-service: profile, address book, notifications, vouchers.
4. Chuẩn hoá theo multi-tenant + Zalo login dual-flow, tương thích backend v2/*.

2.2 Non-goals

• Không bao gồm quản trị tenant/portal.
• Không bao gồm toàn bộ legacy medical/minigame flow ở mức production trong phase này.
• Không định nghĩa UI pixel-level (đã có screenspec riêng), chỉ định nghĩa contract + behavior + acceptance.

2.3 Personas

• Guest user (chưa đăng nhập).
• Logged-in customer (đăng nhập miniapp theo Zalo tenant flow).
• Tenant operator/admin (ngoài scope UI miniapp, chỉ liên quan permission backend).

3) Identity, Auth, Tenant Binding

3.1 Decision Rules (bắt buộc)

• Theo DEC-002: miniapp dùng POST /v2/iam/auth/zalo-tenant-login.
• Payload bắt buộc có thông tin bind tenant: tenantId hoặc appInstanceId + code.
• Kết quả login miniapp phải trả JWT có tenantId.

3.2 Token lifecycle

• Access token + refresh token lưu bằng storage phù hợp môi trường miniapp.
• Tất cả API nghiệp vụ tenant-scoped (/v2/catalog/*, /v2/ecommerce/*, /v2/marketing/*) gửi Authorization Bearer.
• Refresh flow qua POST /v2/iam/auth/refresh, preserve tenant context.

3.3 Guest/Protected UX contract

• Public screens: home, category/product browse, search, product detail, news list/detail/search.
• Protected screens: orders, order detail, addresses, vouchers, notifications, write review, saved news.
• Nếu chưa auth khi vào protected screen: hiển thị auth-gate, sau login phải resume action ban đầu.

4) Functional Modules & Flows

4.1 Catalog & Search

• Home load song song:
  • Categories
  • Featured products
  • Latest news
• Category list + category products hỗ trợ lọc giá/rating ở FE.
• Search flow:
  • Gợi ý trending/autocomplete.
  • Search result từ catalog API.
  • State machine: landing|typing|loading|results|empty|error.

4.2 Product Detail

• Hiển thị gallery, pricing (original/discount), stock, rating/sold.
• Actions:
  • Add to cart
  • Buy now (thêm vào cart rồi điều hướng checkout)
  • Navigate reviews
• Nếu out-of-stock: disable purchase actions.

4.3 Cart & Checkout

• Cart cho phép tăng/giảm/xoá line item, auto cập nhật subtotal.
• Checkout yêu cầu:
  • Có item trong cart
  • Có địa chỉ nhận hàng
• Voucher behavior:
  • Validate trước apply
  • Re-validate trước create order
  • Nếu requires-login khi guest: trigger auth-gate
• Shipping fee preview theo địa chỉ.
• Payment method hỗ trợ tối thiểu: cod|bank|momo (mock), mapping production theo backend gateway.

4.4 Orders

• Orders list:
  • Tabs trạng thái
  • Search theo order code/product title
  • Pull-refresh/manual refresh
• Order detail:
  • Timeline
  • Shipping/payment info
  • Pricing breakdown
  • Actions theo trạng thái:
    • Cancel (pending)
    • Retry payment (unpaid)
    • Confirm received (shipped)
    • Reorder (completed/cancelled)

4.5 Address Book

• CRUD địa chỉ + set default.
• Form validation:
  • receiverName (2-50 chars, non-numeric)
  • phone VN format
  • province/district/ward bắt buộc
  • street >= 5 chars
• Address picker dùng lại cho checkout.

4.6 Vouchers

• List vouchers + trạng thái active/expired.
• Copy voucher code.
• Voucher usability check diễn ra ở checkout.

4.7 Notifications

• List notifications theo type (ORDER|PROMOTION|SYSTEM).
• Mark-as-read per item.

4.8 News & Bookmark

• News home: category chips + latest feed.
• News detail: rich content, related articles, share, bookmark.
• News search: query → result/empty state.
• Saved news: chỉ cho user đã login.

4.9 Support

• Contact channels + FAQ + company address (content-driven).

5) Route Contract (Current miniapp_v2)

Public

• /
• /search
• /cart
• /product/:id
• /checkout
• /categories
• /category/:id
• /support
• /news
• /news/:slug
• /news/search

Protected

• /orders
• /order/:id
• /vouchers
• /notifications
• /addresses
• /write-review/:orderId/:productId
• /news/saved

6) Backend API Mapping (Production Contract)

6.1 Auth/IAM

• POST /v2/iam/auth/zalo-tenant-login
• POST /v2/iam/auth/refresh
• POST /v2/iam/auth/logout
• GET /v2/iam/auth/me

6.2 Catalog

• GET /v2/catalog/categories
• GET /v2/catalog/categories/tree
• GET /v2/catalog/products
• GET /v2/catalog/products/:id

6.3 Cart/Order

• GET /v2/ecommerce/carts
• POST /v2/ecommerce/carts/add
• PATCH /v2/ecommerce/carts/items/:productId
• DELETE /v2/ecommerce/carts/items/:productId
• POST /v2/ecommerce/orders/checkout
• GET /v2/ecommerce/orders/my
• GET /v2/ecommerce/orders/:id

6.4 Voucher

• POST /v2/marketing/vouchers/validate
• POST /v2/marketing/vouchers/apply (optional strategy, nếu BE áp dụng tách riêng)

6.5 Content/News/Notifications

• GET /v2/content/cms/articles
• GET /v2/content/cms/articles/:id
• GET /v2/content/notifications/in-app
• PATCH /v2/content/notifications/in-app/:id/read

7) Data Contract Rules (Miniapp-facing)

• Không overfetch: response chỉ trả field FE sử dụng.
• Relationship rule:
  • Persist <entity>Id
  • Response projection <entity>Summary
• Date/time standard:
  • Instant: ISO-8601 UTC (...Z)
  • Date-only: YYYY-MM-DD
• Currency hiển thị VND locale (vi-VN).
• Error model chuẩn:
  • code (machine)
  • message (user-facing safe)
  • details (optional)

8) Security & Compliance

• Enforce tenant isolation ở tất cả domain endpoints.
• Protected routes không được data-leak khi guest.
• Không expose PII quá mức trên list endpoints.
• Audit events tối thiểu cho order mutation, address mutation, voucher apply.

9) State Management Contract

• Store tối thiểu:
  • user
  • cart
  • addresses
  • bookmarks
  • loading flags
• Side-effect bắt buộc:
  • Login: load profile + bookmarks + addresses
  • Logout: clear sensitive state, giữ local-safe state
  • Checkout success: clear cart

10) Quality & Testing

Required acceptance tests

1. Guest vào protected screen phải bị chặn + resume đúng sau login.
2. Checkout fail khi thiếu address hoặc cart trống.
3. Voucher requires-login và min-order rules hoạt động đúng.
4. Order lifecycle actions theo status hoạt động đúng guard.
5. News bookmark sync đúng giữa list/detail/saved.

Recommended

• Contract tests cho payload mapping FE ↔ BE.
• E2E smoke cho 3 hành trình chính:
  • Browse → cart → checkout
  • Orders list → order detail → action
  • News browse → detail → bookmark

11) Rollout & Migration (Mock → Real API)

1. Giữ nguyên UI contract và store shape, chỉ thay MockAPI adapter bằng RealAPI adapter.
2. Migration theo feature vertical:
   • Auth + profile
   • Catalog/search/product
   • Cart/checkout/order
   • Address/voucher/notification
   • News
3. Mỗi vertical cần:
   • Endpoint mapping sheet
   • Error mapping sheet
   • UAT checklist

12) Delivery Rules (bắt buộc cho mọi change)

1. Task packet phải nêu rõ tenant-binding strategy.
2. Bất kỳ thay đổi login/session phải đối chiếu DEC-001/DEC-002.
3. Bất kỳ thay đổi order/cart/voucher phải map rõ tới backend contract.
4. Cập nhật traceability + feature status cùng lúc khi merge.