update

openspec/changes/add-operations-reports/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

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

@@ -0,0 +1,27 @@
+## 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
+
+验证跨日边界、首次激活去重、退款后激活保留、续购未生效排除、多次续费、维度缺失、权限和导出一致性。

openspec/changes/add-operations-reports/proposal.md

@@ -0,0 +1,25 @@
+## Scope
+
+- 迭代编号：`AUG26-015`。
+
+## Why
+
+首期运营分析需有统一、可导出的激活和套餐续费统计，避免把订单、退款、钱包等不同行为混成一个泛化报表。
+
+## What Changes
+
+- 新增按首次激活成功时间统计的激活情况统计表。
+- 新增按套餐续购实际生效时间统计的套餐续费情况统计表。
+- 固化设备、套餐、用户组、店铺、业务员维度、金额/数量口径、权限与导出快照。
+
+## Capabilities
+
+### New Capabilities
+- `operations-report`: 激活与套餐续费运营报表。
+
+### Modified Capabilities
+- 无。
+
+## Impact
+
+影响资产/卡激活、套餐使用、订单、店铺/业务员维度、导出和数据权限查询。

openspec/changes/add-operations-reports/specs/operations-report/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: 激活情况统计报表
+系统 SHALL 提供激活情况统计表，按上海时区、卡实际首次激活成功时间统计。查询必须支持时间范围及设备类型、套餐、用户组、店铺、业务员维度筛选和分组；返回激活数量、各维度名称及“未知/已删除”历史维度占位值。取消、退款、换货或当前资产状态变化不得改写已发生的首次激活事实；同一卡仅计一次首次成功激活。
+
+#### Scenario: 已激活资产后续退款
+- **WHEN** 卡在统计区间内首次激活成功，后续套餐退款或资产状态变化
+- **THEN** 系统仍按首次激活时间计入激活数量，不重复或撤销该历史激活事实
+
+### Requirement: 套餐续费情况统计报表
+系统 SHALL 提供套餐续费情况统计表，按上海时区、套餐续购订单支付成功并使套餐续期生效的时间统计。查询支持时间范围及设备类型、套餐、用户组、店铺、业务员维度筛选和分组；返回续费订单数、续费资产数、实收续费金额（分）和各维度名称。新购、加油包购买、失败/关闭支付和未生效续购不计入续费；同一资产在区间内多次成功续费按订单数累计，资产数按资产去重。
+
+#### Scenario: 续购支付成功但套餐未生效
+- **WHEN** 续购支付成功但套餐生效事务尚未完成或最终失败
+- **THEN** 系统不将该订单计入套餐续费统计
+
+### Requirement: 报表权限、导出与口径快照
+仅超级管理员和平台用户 SHALL 查询或导出报表，并按既有数据范围过滤店铺、代理和资产。时间范围必填、按左闭右开区间解释；导出冻结请求人、筛选条件、时区、统计口径版本和授权范围，记录操作人、导出时间、筛选条件及导出结果。导出列与页面对应指标一致，异步执行不得因后续权限变化扩大数据范围。
+
+#### Scenario: 无权范围筛选
+- **WHEN** 请求人筛选其无权访问的店铺
+- **THEN** 系统拒绝请求或按既有范围规则不返回该店铺聚合值，不泄露任何统计结果

openspec/changes/add-operations-reports/specs/operations-reporting/spec.md

@@ -0,0 +1,12 @@
+## Purpose
+
+为 2026 年 8 月迭代提供独立、可验证的 激活与套餐续费日报 行为契约，避免与既有模块的兼容行为混淆。
+
+## ADDED Requirements
+
+### Requirement: 激活与套餐续费日报
+系统 SHALL 自功能上线后每日生成激活和套餐续费稳定日报快照，不回填上线前历史。查询支持日/月趋势、单一业务维度分组及异步导出，并按已确认的采购、激活、在网、活跃和续费率口径计算。
+
+#### Scenario: 规则命中
+- **WHEN** 业务请求或任务满足本需求定义的前置条件
+- **THEN** 系统按上述规则完成处理、保留可追溯事实，并拒绝与状态、权限或幂等约束冲突的重复操作

openspec/changes/add-operations-reports/tasks.md

@@ -0,0 +1,9 @@
+## 1. 两张报表
+- [ ] 1.1 确认首次激活成功和续购实际生效的权威表、终态/时间字段及维度关联。
+- [ ] 1.2 实现激活情况统计：时间范围、五类维度、卡去重、历史维度占位和数据范围。
+- [ ] 1.3 实现套餐续费统计：生效门槛、订单数/资产数/实收金额和数据范围。
+- [ ] 1.4 实现同 Query 导出及筛选、时区、口径、权限快照和操作审计；更新路由/OpenAPI。
+
+## 2. 验证
+- [ ] 2.1 验证首次激活、多次续费、退款、未生效续购、跨日、维度缺失、权限和导出一致性。
+- [ ] 2.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-operations-reports --strict` 和 `openspec doctor --json`；自动化测试按项目决策为 N/A。