junhong_cmp_fiber/openspec/changes/archive/2026-09-18-add-operations-reports/tasks.md

1. 表与模型

• 1.1 新增成对迁移 migrations/000231_create_operations_report_snapshot.up.sql / .down.sql：日级头行表（snapshot_date 唯一）、设备粒度激活行表（唯一键 (snapshot_date, device_id)）、到期事件粒度续费行表（唯一键 (snapshot_date, expired_usage_id)），含全部列、唯一索引、(snapshot_date, shop_id) 与 (snapshot_date, series_id) 索引与列注释，不设软删除列
• 1.2 新增 GORM 模型与表名映射（三张表），字段与迁移列逐一对齐
• 1.3 在隔离库执行 up → down → up 并核对三表结构与索引与迁移一致

2. 口径域与快照生成

• 2.1 新增报表口径域：GB 换算常量（1 GB = 1024 MB，域内自持）、比率与卡均计算、分母为零语义（空值）、预测卡均的当月口径（结束日所在上海自然月、已过天数、当月总天数）
• 2.2 实现采购数量口径函数（截至快照日系统内未删除设备数），收敛为单点可切换（设计 D6）
• 2.3 实现激活口径：设备「任一当前有效关联卡已实名」、有效主套餐（主套餐 + 生效或已用完 + 未退款）、真流量合计与活跃判定；累计激活数允许下降、新增激活数允许为负
• 2.4 实现真流量取值集合（设备自身 + 当前有效关联卡的当前有效使用记录的真已用量）与禁止来源校验（不得取卡级全生命周期累计、自然月累计、通道读数、虚量与展示量）
• 2.5 实现续费口径：到期日锚定、接续主套餐判定（未退款、生效时间晚于本条到期或待生效）、按资产去重、分子为分母子集
• 2.6 新增生成用例（Application）：单事务内先删该日三表行再整体写入，写入头行与两类明细行，并校验不变量（分组行之和等于头行值、续费资产数不大于到期资产数）
• 2.7 新增只读数据访问适配（基础设施）：设备与设备属性、当前有效卡绑定、卡实名状态、套餐使用记录、店铺与业务员、业务用户组、套餐与套餐系列
• 2.8 新增任务类型常量、任务处理器与队列映射，并在 pkg/queue/handler.go 注册
• 2.9 注册每日调度 CRON_TZ=Asia/Shanghai 30 3 * * *，payload 只含单一目标上海自然日，并加去重窗口；确认时间点在到期处理与既有落盘、临期提醒之后
• 2.10 确认无任何按日期区间批量生成入口与补跑接口；失败重试沿用同一目标日期

3. 查询与趋势

• 3.1 新增只读查询：单日/闭区间汇总（单分组维度、同期筛选、合计、头行合计），只读三张快照表
• 3.2 新增趋势查询：granularity=day|month，累计取期末快照、新增取相邻期之差，无快照的期不出现
• 3.3 新增请求与响应 DTO：时间参数复用共享严格解析器（带时区 RFC3339 秒级、闭区间、非法即拒），实现快照日期落界规则（D 零点落入区间），响应含是否有快照标记与实际命中快照日期集合
• 3.4 实现结束日无快照时的空值语义：累计类与派生指标为空、分组行返回空集、不回退更早快照
• 3.5 实现可见店铺范围过滤（按快照行店铺列），越权与不存在统一不可见
• 3.6 新增 Handler：四个查询入口（两张报表的汇总与趋势），错误交全局 ErrorHandler，响应用 pkg/response

4. 导出

• 4.1 新增两个导出场景常量（设备激活情况、套餐续费情况）与显示名称映射：本仓库没有独立的「场景名 → 中文显示名」映射表，场景显示名只落在常量行内注释与导出任务 DTO 的两处 description 文案（白名单与文案改动见 4.4）
• 4.2 新增两个数据源实现（Scene/Count/Headers/Fetch）：只读快照表、施加冻结店铺范围、Count 与 Fetch 同筛选构造、列等于页面字段并含合计行、分母为零写「-」、不含文字总结
• 4.3 在导出注册表登记两个数据源，并补齐支持场景判定列表
• 4.4 在导出任务 DTO 的联合类型白名单两处加入新场景名
• 4.5 判定并登记严格时间场景集合是否纳入新场景（若不纳入须在设计登记理由）
• 4.6 新增两个受控导出端点 Handler：创建期冻结筛选、操作者与可见店铺范围，非法时间在创建期拒绝
• 4.7 实现导出场景级角色自检（按任务内冻结的账号类型复核超管或平台），不通过时任务失败并写安全失败摘要

5. 权限与审计

• 5.1 新增路由组级门禁，挂在功能前缀上（超管或平台），复用既有拒绝文案，确认未挂在后台根组
• 5.2 核对并登记查询不写统一审计事件（无业务事实变化，四类事实均不涉及）
• 5.3 核对导出复用既有导出任务审计动作与写入器，不新增动作码；确认任务行保存筛选、创建时间、操作者、结果文件与行数

6. 路由与文档

• 6.1 新增路由注册文件（6 个端点含 RouteSpec 元数据）并在后台路由装配中挂载，静态路径先于动态路径
• 6.2 同步 Handler 装配六处：bootstrap Handlers 结构体、bootstrap 真实装配、文档工厂、运行时文档装配、离线文档生成入口与路由注册文件
• 6.3 运行 go run cmd/gendocs/main.go 连续两次，确认输出一致
• 6.4 更新 ARCHITECTURE.md 模块导航与 Spec 索引
• 6.5 同步 docs/verification/context-reset/ 两份 JSON：行为 Requirement 证据链（6 条 Requirement 的入口/用例/持久化/验证命令）与入口—能力—Requirement 矩阵（6 条 HTTP 入口 + 1 条异步入口）

7. 验证

• 7.1 结构验证：gofmt -w、go build ./cmd/api ./cmd/worker、openspec validate add-operations-reports --strict、openspec doctor --json
• 7.2 冒烟：在隔离环境手工入队快照任务，核对三表行数、头行与分组行不变量（分组行之和等于头行值、续费资产数不大于到期资产数）、同任务重复执行结果不变
• 7.3 场景验证（导出产物行级内容、列等于页面字段、无文字总结、分母为零写「-」已由真实运行验证；唯一未达项为「同一任务变更冻结权限类型前后的产物行数对照」，原因见验证记录 E-2）：上线前日期无快照且不回退；同日重复执行口径不变；实名逆转导致累计下降且新增为负；设备多卡仅一卡已实名计一次；到期当天存在待生效后续主套餐计一次到期一次续费且续费率为 100%；同一资产期内两次到期各计一次；采购为零时激活率为空且导出为「-」；快照后归属变更不改写历史行；越权与不存在统一不可见；导出与列表同筛选同口径且创建后权限变化不扩大范围
• 7.4 越权与规模确认（导出执行期冻结账号类型自检已由真实运行验证，见验证记录 33）：代理、企业与个人客户账号请求报表被拒绝；核对导出任务执行期账号类型自检生效
• 7.5 记录自动化测试按项目决策为 N/A，并保留冒烟命令与输出作为验证证据：无 *_test.go；证据为 docs/verification/add-operations-reports-verification.md（原始命令与原始输出），口径与解释登记于 design「实施登记（2026-09-17）」