device-voice-h5/openspec/changes/add-h5-popup-candidate-flow/proposal.md

Why

The August iteration adds backend-driven H5 popups. GET /api/c/v1/popup-candidates returns at most one candidate (risk-exchange or operation) for the current page and asset; risk-exchange candidates require the user to submit a shipping address through POST /api/c/v1/risk-exchanges/{asset_id}/address. Popups are persisted as personal notifications, so the existing notification contracts change: list items gain popup_snapshot and two new type values, unread count includes popups, and a popup is only dismissed by marking its notification read (PUT /api/c/v1/notifications/{id}/read). The current H5 client-side priority re-sort contradicts the new fixed backend ordering and must be removed.

What Changes

• Query GET /api/c/v1/popup-candidates once per page entry on home (index), package_purchase (package-order), and asset_wallet_recharge (my-wallet); asset_detail is explicitly out of scope
• Render the returned candidate (title/body) in a shared PopupCandidate component and keep the popup silent when no candidate exists
• Map action_type with a frontend whitelist only: package_purchase -> package-order page, asset_wallet_recharge -> my-wallet page; empty value shows no action
• Dismiss or act on a popup only by marking the notification read through PUT /api/c/v1/notifications/{id}/read
• Risk-exchange popups show a shipping address form and submit it with the candidate asset_id (never derived from the H5 identifier); success shows the exchange number and status
• Treat invisible assets (HTTP 400 / code=1180) uniformly as resource-invisible with no UI branching
• Keep the backend-fixed notification ordering (remove client-side priority re-sort); honor the unread badge contract; include the notification id in mark-read requests
• Never use read-all inside the popup display chain

Capabilities

New Capabilities

• h5-popup-candidate: Define once-per-entry popup candidate query, rendering, whitelist action mapping, and read-mark dismissal
• h5-risk-exchange-address: Define the risk-exchange shipping address form and idempotent submission

Modified Capabilities

• personal-notification-list: Align the personal notification list/unread contracts with popup notifications

Impact

• Affected code: new api/modules/popup.js, new components/PopupCandidate.vue, pages/index/index.vue, pages/package-order/package-order.vue, pages/my-wallet/my-wallet.vue, pages/notifications/notifications.vue, api/modules/notification.js
• Backend contracts: C-end popup/risk-exchange/notification endpoints only; admin endpoints are out of scope