junhong_cmp_fiber/openspec/changes/add-operations-reports/design.md

Decisions

• 只读 Query 分别以卡首次激活成功事实和续购套餐实际生效事实为权威源；不以当前订单/资产状态反推历史。
• 激活按卡去重，续费同时计算订单计数和资产去重计数；金额始终聚合分。
• 先施加请求人数据范围，再关联设备、套餐、用户组、店铺、业务员维度；缺失维度用占位值保留事实。
• 导出复用同一 Query 并保存筛选、范围、时区和口径版本快照。

查询与导出契约

激活情况统计

• GET /operations-reports/activations：仅超级管理员、平台用户；请求 start_time、end_time 必填，上海时区左闭右开，及可选 device_type、package_id、business_user_group_id、shop_id、business_owner_account_id、group_by。先应用既有资产/店铺范围，再以卡 activated_at 的首次成功激活事实过滤和聚合；同一卡在区间内至多贡献 1。
• 响应返回统计边界、分组维度代码/名称、activation_count；关联的设备、套餐、用户组、店铺或业务员物理缺失时返回固定“未知/已删除”占位，不用当前资产状态、退款、换货或取消结果排除历史激活。

套餐续费情况统计

• GET /operations-reports/package-renewals：筛选与分组维度同激活报表。权威事实是续购订单支付成功且对应主套餐使用记录实际生效；新购、加油包、失败/关闭支付、仅支付成功未生效均排除。
• 每个分组返回 renewal_order_count、renewal_asset_count（按资产去重）、received_renewal_amount（分）。同一资产多笔生效续购增加订单数和金额但只增加一次资产数；金额从订单冻结实收金额读取，禁止由套餐当前售价反算。

权限与导出

• 不在调用者数据范围内的 shop_id、资产或维度筛选返回既有无权/空集合语义，不返回越权聚合。时间缺失、格式无效、开始不早于结束或不支持的 group_by 返回稳定参数错误，不执行聚合。
• POST /operations-reports/activations/export 与 /package-renewals/export 创建异步任务，保存请求人、报表类型、规范化筛选、上海时区、口径版本、授权范围和创建时间。Worker 复用相同 Query，生成的列与页面指标一致，并记录文件、行数、完成时间或安全失败摘要；后续角色/店铺变化不得扩大范围。

Verification

验证跨日边界、首次激活去重、退款后激活保留、续购未生效排除、多次续费、维度缺失、权限和导出一致性。