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

ADDED Requirements

Requirement: H5 SHALL query popup candidates once per page entry

The system SHALL call GET /api/c/v1/popup-candidates exactly once per page entry with the current page and asset identifier, and SHALL render the returned candidate or stay silent when none exists. The query SHALL NOT be prefetched, polled, or repeated inside one entry.

Scenario: Candidate exists on page entry

• WHEN the user enters home, package_purchase, or asset_wallet_recharge and the backend returns a candidate
• THEN the system SHALL show the candidate title/body popup

Scenario: No candidate on page entry

• WHEN the backend returns an empty candidate
• THEN the system SHALL show no popup
• AND the page SHALL continue its normal flow

Scenario: Same notification id within one day

• WHEN a later page entry returns the same notification_id already handled this session
• THEN the system SHALL NOT re-popup the same notification

Requirement: Popup actions SHALL use a frontend whitelist

The system SHALL map action_type through a frontend whitelist only and SHALL NOT accept URLs or routes from the backend. package_purchase routes to the package purchase page, asset_wallet_recharge routes to the wallet page, and an empty value shows no action.

Scenario: package_purchase action

• WHEN the candidate action_type is package_purchase
• THEN the popup SHALL navigate to the package purchase page

Scenario: asset_wallet_recharge action

• WHEN the candidate action_type is asset_wallet_recharge
• THEN the popup SHALL navigate to the asset wallet page

Scenario: No action

• WHEN action_type is empty
• THEN the popup SHALL show no action button

Requirement: Popup dismissal SHALL mark the notification read

The system SHALL call PUT /api/c/v1/notifications/{id}/read with the candidate notification_id when the popup is dismissed or when its action is taken. Popup closing and action-taking SHALL NOT use read-all.

Scenario: User closes the popup

• WHEN the user closes the popup
• THEN the notification SHALL be marked read

Scenario: User takes the popup action

• WHEN the user taps the action button
• THEN the notification SHALL be marked read
• AND the mapped page SHALL open

Requirement: Resource-invisible responses SHALL be silent

The system SHALL treat HTTP 400 / code=1180 responses uniformly as resource-invisible and SHALL NOT branch UI, show special prompts, or distinguish asset-missing from not-owned states.

Scenario: Invisible asset on popup query

• WHEN the popup query returns an invisible-asset error
• THEN the system SHALL show no popup
• AND the page SHALL continue its normal flow