商业运营指标与分析报表

[web-ppanel]

目标仓库： perfect-panel/backend
目标分支： next
规划基线： origin/main@ea28a7685f4c89f91895c4d789a5726e806aa3f0

目标

建设商业运营指标与分析报表，提供收入、订单、订阅、留存、流量、渠道、佣金、工单和异常趋势等分析能力，为运营决策服务。该项明确为 P2，不作为上线阻塞项；P1 业务异常处置工作台只处理异常状态流转和下钻，不承担完整 BI 报表。

源码已有

• 已有轻量 console、收入/用户/服务器流量统计、订单/余额/佣金列表、pending/paid reconciler、每日订单 Telegram 报告。
• 统一列表查询契约与 Read Model 基础设施 #214/改造订单、支付、提现、邀请、佣金列表及财务事实 Read Model #216/统一审计、任务运行与日志查询数据模型 #219/重构服务器、协议、节点与用户订阅流量日志 #221/增强运行时日志查询与列表日志导出 #223 已规划统一列表、日志、流量和导出底座。
• 当前缺少指标口径版本、报表 Read Model、维度分析、趋势对比和运营导出。

范围

• 定义指标口径：GMV、实收、退款、净收入、订单转化、订阅新增/续费/取消、ARPU、流量成本、佣金、工单 SLA、异常数量。
• 建立报表 Read Model / materialized aggregates，支持按日期、商品规格、支付渠道、地区、节点/协议、用户来源等维度分析。
• 支持趋势、同比/环比、漏斗、Top N、分布、留存 cohort 的后端 API。
• 报表导出复用统一导出能力，支持 CSV；XLSX/图表样式可后续评审。
• 指标口径版本化，报表页面展示口径说明和数据更新时间。

明确不做

• 不在本 Issue 内实现实时风控、自动修复、告警路由或异常状态机。
• 不承诺建设通用拖拽式 BI 平台；先提供 PPanel 固定运营报表。
• 不绕过已有列表、导出、RBAC 和审计规范直接读写业务表。

数据 / API / 流程

• 数据：metric_definitions、metric_snapshots、report_daily_facts、report_query_cache、metric_version。
• API：Admin 指标概览、趋势、维度 breakdown、Top N、cohort、导出、口径说明。
• 流程：业务事实入库 → 周期聚合 → 口径版本固化 → 报表查询 → 导出/分享 → 口径变更审计。

RBAC / 审计

• 报表查看、财务指标查看、敏感维度查看、导出、口径编辑分别登记权限点。
• 财务报表导出、口径修改、查看敏感维度写管理员审计。
• 用户标识、支付信息和收款信息按权限脱敏；导出遵守数量、时间范围和过期限制。

验收

• 至少提供收入、订单、订阅、流量、佣金、工单和异常趋势 7 类报表。
• 每个指标有口径说明、更新时间和版本号。
• 同一筛选条件下报表、明细列表和导出可对账；金额使用精确数值语义。
• 大范围查询有时间/行数限制，不造成数据库全表扫描或内存爆炸。
• MySQL/PostgreSQL 对日期、NULL、排序、聚合的结果一致。
• 报表导出与查看均受 RBAC 控制并写审计。

依赖

• 依赖 统一列表查询契约与 Read Model 基础设施 #214 查询契约、改造订单、支付、提现、邀请、佣金列表及财务事实 Read Model #216 财务列表、统一审计、任务运行与日志查询数据模型 #219 日志/任务模型、重构服务器、协议、节点与用户订阅流量日志 #221 流量模型、增加管理员审计、任务运行历史与独立日志清理 #222 审计、增强运行时日志查询与列表日志导出 #223 导出、动态 RBAC 权限系统 #205 RBAC；可消费 P1 业务异常工作台的聚合结果。

开发与测试门禁

• MySQL/PostgreSQL 迁移、OpenAPI 契约、RBAC API 权限点、管理员审计和敏感信息脱敏测试必须同步提交。
• 复用现有源码能力和 P0 底座，不重复实现支付、订阅、流量、修复命令或发布门禁执行层。