36 lines
3.0 KiB
Markdown
36 lines
3.0 KiB
Markdown
## 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
|
||
|
||
1. 先扩展管理端 API 类型和服务，确认列表、首页统计和通知目标字段。
|
||
2. 上线临期列表及普通列表高亮，再接入首页统计和续费入口。
|
||
3. 最后验证通知中心过滤、已读和跳转，不修改 C 端功能。
|
||
|
||
## Open Questions
|
||
|
||
- 代理首页现有概览接口的具体路径和响应字段名称，需要以后端接口实现为准确认。
|
||
- 管理端卡/设备续费入口的现有路由是否统一，需实现时复用当前权限和路由定义。
|