feat: 完善接口19-顶部通知铃铛与站内通知中心

openspec/changes/add-admin-expiring-assets-notifications/specs/admin-expiring-assets/spec.md

@@ -0,0 +1,111 @@
+## ADDED Requirements
+
+### Requirement: Admin Expiring Asset Query
+
+The admin frontend SHALL provide an expiring asset list backed by `GET /api/admin/expiring-assets`. The query SHALL support `asset_type`, `keyword`, `shop_id`, `package_id`, `days_min`, `days_max`, `expires_from`, `expires_to`, `page`, and `size`.
+
+#### Scenario: Filter expiring assets
+
+- **WHEN** 管理端用户打开临期资产列表并提交筛选条件
+- **THEN** 前端 MUST send the documented query parameters to `GET /api/admin/expiring-assets`
+- **AND** 页面 MUST display the paginated response items
+
+#### Scenario: Exclude unavailable assets
+
+- **WHEN** 接口返回临期列表
+- **THEN** 页面 MUST not add expired assets or assets without an estimable final expiry to the list on the client side
+
+### Requirement: Expiring Asset Fields
+
+Each expiring asset item SHALL preserve and display the backend fields `asset_type`, `asset_id`, `identifier`, `shop_name`, `package_name`, `estimated_final_expires_at`, `days_until_final_expiry`, `expiry_level`, `expiry_level_name`, and `can_renew`. The frontend MUST use backend-provided expiry results and MUST NOT calculate the estimated final expiry from package details.
+
+#### Scenario: Display an estimable asset
+
+- **WHEN** 临期接口返回资产及 `estimated_final_expires_at`
+- **THEN** 页面 MUST display the asset identifier, shop, package, estimated final expiry, remaining days, and backend expiry level name
+
+#### Scenario: Preserve backend result
+
+- **WHEN** 临期接口返回 `estimated_final_expires_at` 或 `days_until_final_expiry`
+- **THEN** 前端 MUST display the returned values
+- **AND** 前端 MUST NOT derive or replace them from current or queued package data
+
+### Requirement: Expiring List Ordering And Highlighting
+
+The expiring asset API and standalone admin list SHALL return and preserve records with 0-3 remaining days first, then order the remaining records by `estimated_final_expires_at` ascending. The list SHALL apply pink highlighting to 8-15 days, purple highlighting to 4-7 days, and red highlighting to 0-3 days.
+
+#### Scenario: Order critical assets first
+
+- **GIVEN** the response contains assets in multiple expiry ranges
+- **WHEN** 页面渲染临期列表
+- **THEN** the API response MUST place assets with 0-3 remaining days before assets with more remaining days
+- **AND** the API response MUST order records in the remaining ranges by estimated final expiry ascending
+- **AND** the frontend MUST preserve that cross-page ordering
+
+#### Scenario: Highlight by remaining days
+
+- **WHEN** 页面渲染临期资产
+- **THEN** 8-15 days MUST use the pink visual treatment
+- **AND** 4-7 days MUST use the purple visual treatment
+- **AND** 0-3 days MUST use the red visual treatment
+
+### Requirement: Ordinary Admin Asset List Highlighting
+
+The admin card and device lists SHALL apply the same expiry color treatment to returned expiring asset fields without changing their existing server or client sort order.
+
+#### Scenario: Highlight ordinary asset rows
+
+- **WHEN** 卡列表或设备列表返回临期字段
+- **THEN** 页面 MUST apply the matching expiry color treatment
+- **AND** 页面 MUST preserve the list's existing ordering
+
+### Requirement: Admin Expiring Asset Renewal Entry
+
+The admin expiring asset list SHALL display a renewal action only when the backend item has `can_renew=true`. The action SHALL navigate to the existing management-side renewal or recharge flow for the asset type.
+
+#### Scenario: Renewable asset
+
+- **GIVEN** 临期资产项返回 `can_renew=true`
+- **WHEN** 用户查看临期列表
+- **THEN** 页面 MUST provide the management-side renewal entry
+- **AND** the entry MUST target the corresponding asset and preserve asset type context
+
+#### Scenario: Non-renewable asset
+
+- **GIVEN** 临期资产项返回 `can_renew=false`
+- **WHEN** 用户查看临期列表
+- **THEN** 页面 MUST NOT display an enabled renewal action
+
+### Requirement: Agent Dashboard Expiry Counts
+
+The agent-facing admin home SHALL display the number of expiring cards and expiring devices using backend-provided summary fields and SHALL provide navigation to the standalone expiring asset list.
+
+#### Scenario: Display expiry counts
+
+- **WHEN** 代理首页概览数据返回临期卡和设备数量
+- **THEN** 页面 MUST display the expiring card count and expiring device count
+- **AND** 页面 MUST not calculate the counts from a paginated asset list
+
+### Requirement: Admin Expiry Notifications
+
+The notification center SHALL display backend-generated admin expiry reminders for 15 days, 7 days, and 3 days through the existing notification API and target navigation. The admin frontend SHALL not display WeCom expiry messages.
+
+#### Scenario: Display expiry reminder
+
+- **WHEN** 通知接口返回 15 天、7 天或 3 天的临期提醒
+- **THEN** 通知中心 MUST classify it as a 临期提醒
+- **AND** 用户点击通知后 MUST navigate to the returned management-side target
+
+#### Scenario: Exclude WeCom expiry message
+
+- **WHEN** 管理端加载通知中心
+- **THEN** 页面 MUST not add or render a separate WeCom expiry message channel
+
+### Requirement: Admin-Only Scope
+
+This capability SHALL be limited to the management frontend. It SHALL NOT add or modify C-end asset expiry display, C-end renewal buttons, C-end renewal APIs, or C-end notification behavior.
+
+#### Scenario: Keep C-end unchanged
+
+- **WHEN** this change is implemented
+- **THEN** C-end asset pages and renewal flows MUST remain outside the change scope