3.0 KiB
3.0 KiB
Context
临期结果由后端根据资产当前套餐及排队套餐计算。管理端需要在独立列表、普通资产列表、代理首页和通知中心保持相同的临期语义。本变更只覆盖管理端，C 端资产和续费能力不纳入实现范围。
Goals / Non-Goals
- Goals: 统一消费
estimated_final_expires_at、days_until_final_expiry、expiry_level、expiry_level_name和can_renew；提供临期查询、排序、高亮、统计、通知跳转和管理端续费入口。 - Goals: 由后端负责临期边界、预计到期结果和通知触发，前端只负责展示和路由。
- Non-Goals: 不计算套餐接续到期时间，不修改历史订单或已购套餐，不实现 C 端入口，不展示企微临期消息。
Decisions
- Decision: 临期独立列表使用
GET /api/admin/expiring-assets，查询参数保持文档约定的asset_type、keyword、shop_id、package_id、days_min、days_max、expires_from、expires_to、page、size。 - Decision: 临期接口负责跨分页排序，返回结果按 0-3 天优先、其余按
estimated_final_expires_at升序排列；前端只保留接口顺序，不改变普通资产列表原始接口排序。 - Decision: 颜色只按剩余天数映射：8-15 天粉红、4-7 天紫色、0-3 天红色。已过期和不可预计记录由接口排除，前端不把它们补入临期列表。
- Decision: 续费入口由
can_renew控制，具体续费动作复用现有管理端续费/充值路由和接口，不新增 C 端逻辑。 - Decision: 通知中心继续复用现有通知接口和目标跳转协议；临期通知由后端按 15 天、7 天、3 天生成，前端按通知目标跳转到临期列表或对应资产详情。
- Alternatives considered: 前端从普通资产列表筛选临期记录。Rejected because it无法保证全量、统一排序和后端预计最终到期结果的一致性。
Risks / Trade-offs
- 风险：代理首页当前概览接口未必已有临期计数字段。Mitigation：在现有首页/概览响应中增加
expiring_card_count和expiring_device_count，避免前端分页统计。 - 风险：不同资产列表的字段结构不完全一致。Mitigation：在各自 API 类型中复用同一组临期字段语义，并通过统一展示格式处理空值和等级。
- 风险：续费入口的现有路由可能依赖资产类型。Mitigation：由
asset_type和asset_id选择对应管理端续费入口，按钮仅在can_renew=true时展示。
Migration Plan
- 先扩展管理端 API 类型和服务，确认列表、首页统计和通知目标字段。
- 上线临期列表及普通列表高亮，再接入首页统计和续费入口。
- 最后验证通知中心过滤、已读和跳转，不修改 C 端功能。
Open Questions
- 代理首页现有概览接口的具体路径和响应字段名称，需要以后端接口实现为准确认。
- 管理端卡/设备续费入口的现有路由是否统一，需实现时复用当前权限和路由定义。