3.5 KiB
3.5 KiB
01 — 后台资产详情统一展示预计最终到期
What to build: 运营人员通过统一资产解析查看卡或设备详情时，可以看到全部有效主套餐按稳定队列连续使用后的“预计套餐到期时间”。系统以统一 Query 计算 exact、waiting_activation、none、invalid_data 四种状态，并返回预计日期、上海自然日剩余天数和临期派生结果；后台详情按状态展示明确文案，不再把当前套餐自身到期时间当作资产汇总口径。
Blocked by: .scratch/ur55-package-expiry-base/issues/05-activate-and-queue-from-package-snapshots.md — 05 — 套餐激活与队列接续只消费购买快照
Status: ready-for-agent
- 架构主通道为 Query，Infrastructure 仅负责 GORM 批量读取、历史套餐兜底和索引；完整收口预计最终到期的读取与投影边界，不迁移套餐激活、购买、退款或队列接续写逻辑。
- 建立可供单资产和批量资产入口共同调用的纯计算核心；两种入口对同一组使用记录返回完全一致的状态、预计日期、剩余自然日和临期标记，卡、设备及各端不得各自实现推算规则。
- 仅纳入未软删除、仍处于当前或排队生命周期且不属于加油包的主套餐；排除已过期、已失效和已退款记录，并按
priority ASC, created_at ASC, id ASC稳定计算。 - 当前生效主套餐的真实到期时间作为游标起点，后续套餐从前一段结束后的下一时刻接续；自然月和按天时长统一使用项目套餐生命周期日期语义，并以
Asia/Shanghai解释业务自然日。 - 排队记录优先使用各自购买时计时快照；仅允许 UR#55 上线前形成的历史缺失快照记录显式回退套餐当前值，非法队列、非法日期或无法安全解析的快照返回
invalid_data，不得伪造日期或降级为none。 - 结果完整区分
exact、waiting_activation、none、invalid_data；非exact时预计日期和剩余天数明确序列化为null，不能省略字段表达状态。 - 剩余天数按上海时区日期差计算，允许普通详情返回负数；仅
exact且剩余 0～15 个自然日时is_expiring=true。 - 后台统一资产解析接口为卡和设备返回预计日期、剩余天数、状态、状态中文名称及临期标记；查询失败向上返回统一错误，不得静默返回
none。 - 后台卡和设备详情统一显示“预计套餐到期时间”：精确日期、待激活后起算、—、数据异常分别对应四种状态；当前套餐自身到期时间只保留在套餐明细中。
- 为未软删除主套餐的资产、状态和队列读取建立经开发库
EXPLAIN ANALYZE验证的非唯一或部分索引；索引迁移包含中文注释、可逆向下迁移，代表性查询满足项目性能目标。 - 纯计算测试覆盖无套餐、仅当前套餐、多段队列、自然月、按天、月末、跨年、等待实名激活、历史回退、非法快照、重复优先级、退款、失效、软删除和加油包排除，并明确验证接续边界不多算或少算一天。
- 使用真实开发 PostgreSQL、Redis、JWT 和进程内 Fiber App 完成后台卡/设备详情集成验证；新增、退款或失效排队套餐后无需刷新快照，下一次查询立即返回新结果。
- 补充本功能中文总结文档并同步更新 README；不实现 UR#33 临期列表、Dashboard、提醒，不实现 UR#42 导出，也不维护资产级最终到期快照字段。