MINIAPP V2 Backend + Spec Gap Audit (2026-02-27)

Scope

• Miniapp FE: miniapp_v2/miniapp/src/App.tsx + related screens/components
• Backend v2 controllers/services: v2/libs/modules/*
• Full screen specs + sub-screen specs: docs_hub_v3/02_SPECS/core/miniapp_full_screen_specs/*
• Traceability: FEATURE_TAG_MATRIX_MINIAPP_V2.md, WORKITEM_BOARD.md

Executive Summary

• Route coverage FE/spec: 20/20 complete.
• Auxiliary sub-screen coverage: 8/8 complete.
• Backend parity status after deep rescan:
  • Ready/usable: auth tenant login, carts, orders checkout/basic detail, voucher validate/apply, MDM locations.
  • Partial/gap: notifications guard consistency, news public/read-by-slug/search contract, bookmark APIs, address CRUD APIs, support/Q&A APIs.

Verified Backend Reality (Code Truth)

1) Auth bootstrap

• Existing endpoint: POST /v2/iam/auth/zalo-tenant-login
• File evidence: v2/libs/modules/iam/src/lib/auth/auth.controller.ts
• Status: usable for MA.AUTH.001.

2) Cart/Order/Voucher

• Carts: v2/ecommerce/carts (GET, POST add, PATCH qty, DELETE item)
• Orders: v2/ecommerce/orders (checkout, my, :id, status/bulk/split/refund)
• Vouchers: v2/marketing/vouchers (validate, apply, list/manage)
• Files:
  • v2/libs/modules/ecommerce/src/lib/controllers/cart.controller.ts
  • v2/libs/modules/ecommerce/src/lib/controllers/order.controller.ts
  • v2/libs/modules/voucher/src/lib/controllers/voucher.controller.ts

3) Locations for address cascade

• Existing endpoint: GET /v2/admin/mdm/locations (public)
• Query supports type/parentCode filtering via QueryLocationDto
• File: v2/libs/modules/mdm/src/lib/mdm.controller.ts
• Impact: Address form should map to MDM location source instead of assuming missing /v2/common/locations/*.

4) Notifications

• In-app endpoints exist:
  • GET /v2/content/notifications/in-app
  • PATCH /v2/content/notifications/in-app/:id/read
  • PATCH /v2/content/notifications/in-app/read-all
  • GET /v2/content/notifications/in-app/unread-count
• File: v2/libs/modules/email/src/lib/notification.controller.ts
• Gap/risk: guard usage appears explicit for email-manage/outbox routes, but not explicit on in-app read endpoints in this controller -> requires IAM/SEC verification of effective global guard chain.

5) News/CMS

• Existing controller path: v2/content/cms/articles
• Current contract supports:
  • GET /articles with status, category
  • GET /articles/:id
• Files:
  • v2/libs/modules/cms/src/lib/cms.controller.ts
  • v2/libs/modules/cms/src/lib/cms.service.ts
• Gaps vs miniapp screens:
  • no explicit by-slug endpoint for /news/:slug
  • no related endpoint
  • no explicit search query (q) contract
  • current permission path uses CMS internal permission model, may not match public miniapp read flow.

6) Missing modules/contracts for miniapp support flows

• No clear public controllers found for:
  • support category/article API dedicated for miniapp support center
  • Q&A (question-and-answer, send-question)
  • news bookmarks for /news/saved
  • address CRUD dedicated endpoints (/v2/ecommerce/addresses*)

Spec Corrections Applied in this audit cycle

1. X03_ADDRESS_FORM_MODAL.md

• Updated location mapping from PROPOSED /v2/common/locations/* to existing GET /v2/admin/mdm/locations?....

2. X08_CONTACT_SUPPORT.md

• Added fallback data source using GET /v2/admin/mdm/registries/:type (e.g. support channels) in addition to proposed dedicated endpoint.

3. FEATURE_TAG_MATRIX_MINIAPP_V2.md

• Updated tags/actions:
  • MA.NOTI.001 now includes BE_GUARD_RISK.
  • MA.NEWS.001, MA.NEWS.002, MA.NEWS.003 moved to BE_CONTRACT_GAP.
  • MA.ADDR.003 next action aligned with MDM location endpoint.

4. WORKITEM_BOARD.md

• Added new workitems from rescan:
  • WI-MA-S2-010 (MDM location adapter for address cascade)
  • WI-MA-S3-010 (notifications guard hardening)
  • WI-MA-S3-011 (public news read APIs)
  • WI-MA-S3-012 (news by-slug + related)
  • WI-MA-S3-013 (news search q contract)

Remaining Highest-priority Gaps (after patch)

1. Address API module absence (MA.ADDR.001~003) remains P0 blocker.
2. News contract mismatch (MA.NEWS.001~003) remains P1 integration blocker.
3. Bookmark API absence (MA.NEWS.004) remains P1 blocker.
4. Support/Q&A backend absence (MA.SUP.003~005) remains P1 blocker.
5. Notification guard verification (MA.NOTI.001) remains security verification item.

Recommended Immediate Next Moves

1. Backend: spin up addresses module/API and close WI-MA-S2-003 + S2-010.
2. CMS: define miniapp public read API surface (feed/detail/search/by-slug/related/bookmark).
3. IAM/SEC: verify effective guards on in-app notifications and patch if needed.
4. Governance: keep this audit linked in sprint tracking until all P0 blockers exit BE_CONTRACT_GAP.