one-pipe-system/openspec/changes/add-asset-wallet-auto-renewal-config/specs/asset-wallet-auto-renewal/spec.md

ADDED Requirements

Requirement: 自动续费配置查询

The admin frontend SHALL load the single global asset wallet auto-renewal configuration through GET /api/admin/asset-auto-renewal-config. 响应字段 SHALL 包含并展示 enabled+enabled_name、scope+scope_name、package_ids、days_before_expiry、config_version、updater、updated_at。

Scenario: 读取全局自动续费配置

• WHEN 用户进入资产钱包自动续费配置页面
• THEN 前端 MUST 调用 GET /api/admin/asset-auto-renewal-config
• AND 页面 MUST 展示总开关及中文名称、适用范围及中文名称、指定主套餐集合、统一到期前天数、配置版本、最近保存操作者与最近保存时间

Requirement: 自动续费配置保存

The admin frontend SHALL save the configuration through PUT /api/admin/asset-auto-renewal-config with request body { enabled, scope, package_ids, days_before_expiry }。enabled SHALL 取值 0/1 且必填；scope SHALL 取值 all（全部主套餐）或 specified（指定主套餐）且必填；package_ids 仅在 scope=specified 时必填非空且只能选择当前可售主套餐；days_before_expiry SHALL 取值 1 至 90 且必填。配置为单行、无新增/删除；保存 SHALL 递增 config_version 并记录操作者与前后值快照；配置变更 SHALL 只影响后续扫描，历史记录不重算。

Scenario: 保存全部主套餐范围配置

• WHEN 用户设置适用范围为「全部主套餐」并提交
• THEN 前端 MUST 调用 PUT /api/admin/asset-auto-renewal-config
• AND 请求体携带 enabled、scope=all、days_before_expiry
• AND package_ids 以空数组提交
• AND 保存成功后页面 MUST 以响应中的 config_version、updater、updated_at 刷新展示

Scenario: 保存指定主套餐范围配置

• WHEN 用户设置适用范围为「指定主套餐」并选择若干当前可售主套餐后提交
• THEN package_ids MUST 非空且只包含当前可售主套餐
• AND 前端 MUST 携带 scope=specified 与非空 package_ids 提交

Scenario: 参数校验

• WHEN enabled 缺失、scope 非法、scope=specified 时 package_ids 为空或包含不可售套餐，或 days_before_expiry 超出 1–90
• THEN 前端 MUST 阻止提交并给出校验提示

Scenario: 仅影响后续扫描

• WHEN 用户修改并保存配置
• THEN 历史自动续费记录 MUST NOT 被重算
• AND 新配置 MUST 只对保存后的扫描生效

Requirement: 自动续费配置访问权限

Only super admin and platform accounts SHALL be allowed to query or save the asset wallet auto-renewal configuration. 代理、企业与个人客户等身份访问时 SHALL 返回 403 并提示「无权限操作该资源或资源不存在」；无权限与不存在的表现 MUST NOT 可区分。

Scenario: 授权访问

• WHEN 超级管理员或平台账号访问配置接口
• THEN 页面 MUST 正常查询与保存配置

Scenario: 无权限访问

• WHEN 代理、企业或个人客户账号访问配置接口
• THEN 页面 MUST 按 403 无权限处理并展示统一提示
• AND 前端 MUST NOT 通过响应区分无权限与资源不存在

Requirement: 自动续费失败后台通知

The admin notification center SHALL display the new notification type asset.auto_renewal.failed（类别 expiry、级别 warning）through the existing notification APIs，接收人为业务员/店铺账号。目标 target_type 的 iot_card 与 device SHALL 位于通知导航白名单；当目标 available=false 时页面 SHALL 只展示正文且不跳转；该类型通知 SHALL 计入未读数。

Scenario: 展示并跳转自动续费失败通知

• WHEN 通知列表返回 asset.auto_renewal.failed 类型且目标可用
• THEN 通知中心 MUST 将该通知归入 expiry 类别展示
• AND 用户点击后 MUST 通过既有目标接口按 iot_card / device 跳转到对应资产详情

Scenario: 目标不可用

• WHEN 目标接口返回 available=false
• THEN 页面 MUST 只展示通知正文且不发起跳转

Requirement: H5 客户侧通知边界

This capability SHALL NOT 新增或修改 H5 客户侧接口与页面。asset.auto_renewal.failed 类型已由后端加入客户可见白名单，通过既有 GET /api/c/v1/notifications 与 unread-count 返回；客户侧仅展示文案（资产标识、套餐、原因、到期日），无跳转接口、无需新页面。该类型属 expiry 类别，展示期以业务到期时间为准，套餐到期后从列表消失（既有类别行为）。

Scenario: H5 复用既有接口

• WHEN 客户侧通知接口返回该类型
• THEN 客户侧 MUST 仅展示文案且不提供跳转
• AND 本次变更 MUST NOT 新增 H5 客户侧接口或页面

Scenario: 到期展示期

• WHEN 对应套餐业务到期
• THEN 该通知按 expiry 类别既有行为从客户侧列表消失

Requirement: 功能范围边界

This capability SHALL NOT 包含以下内容：自动续费记录页/异常记录页、尝试记录查询、「有余额就不停机」开关、H5 客户侧新接口。

Scenario: 明确不提供的功能

• WHEN 前端对接本次资产钱包自动续费能力
• THEN 页面 MUST NOT 提供或依赖自动续费记录页、异常记录页、尝试记录查询接口与「有余额就不停机」开关