break
370fd3e67f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 10m49s
27 lines
2.6 KiB
Markdown
27 lines
2.6 KiB
Markdown
## 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
|
||
|
||
验证跨日边界、首次激活去重、退款后激活保留、续购未生效排除、多次续费、维度缺失、权限和导出一致性。 |