junhong_cmp_fiber/docs/ur33-package-expiry-reminder/功能总结.md

UR#33 套餐临期提醒功能总结

交付范围

• 新增 GET /api/admin/expiring-assets，平台与代理共用当前后台认证和店铺层级权限。
• 仅返回预计最终到期状态为 exact、剩余 0 至 15 个上海自然日的卡和设备。
• 返回卡、设备及合计数量，提供 pink/purple/red 高亮等级和 0 至 3 天优先标识。
• 每日上海时间 03:00 扫描 15、7、3 天节点，向资产关联个人客户写入站内通知 Outbox。
• C 端继续复用既有通知列表、未读数和弹窗机制，不新增营销、短信或企业微信提醒。

数据与幂等

• 临期时间复用 internal/query/packageexpiry 的最终到期算法，不建立临期状态快照。
• 列表候选使用当前主套餐到期时间预筛，再批量计算当前与排队主套餐的最终到期时间。
• 通知事件 ID 固化资产类型、资产 ID、到期日、节点和个人客户 ID；定时任务、Outbox Relay 和通知消费者重复执行均不会重复通知。
• 000183_add_package_expiry_scan_indexes 仅增加卡、设备主套餐到期扫描索引，不新增外键。

权限和异常边界

• 平台与超级管理员读取全局范围；代理只读取当前认证上下文的下级店铺范围。
• 代理权限范围为空时查询固定返回空集，不能因空切片退化为全局读取。
• shop_id 只缩小既有权限范围；企业账号禁止调用。
• 无关联个人客户的资产正常跳过通知，不影响临期列表事实。

联调与回滚

• 前端按 expiry_level 渲染颜色，按 is_priority 置顶，不自行重算阈值。
• 回滚应用版本后可删除迁移新增的两个扫描索引；已产生的通知和 Outbox 事实不得清表。
• 本 Change 未运行测试、完整构建、LSP 和迁移；按用户后续明确要求已运行 OpenAPI 生成器，另执行 gofmt、只读一致性检查和 git diff --check。