feat: new

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

@@ -0,0 +1,52 @@
+## 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