# statisticService 设计文档

> **创建日期**: 2026-06-04
> **状态**: 规格自审通过
> **前置文档**: `docs/figma-analysis-data-dashboard.md`(前端设计分析)
> **范围**: 为数据看板新建后端微服务,支持未来扩展(埋点、未知需求)

---

## 〇、文档信息

| 项 | 内容 |
|------|------|
| 服务名 | `statisticService` |
| 端口 | `tri://127.0.0.1:20009`(Dubbo triple) |
| HTTP 路径 | `/api/v1/dashboard/*`(经 gateway,前端已固定) |
| 数据库 | PostgreSQL(复用现有实例,新建 `statistic` schema) |
| 缓存 | Redis(复用现有实例) |
| 范围 | 看板 7 RPC + 事件采集框架 + 预留扩展(MQ 通道、SDK 端点、OLAP 通道、实时通道) |
| 目标读者 | 后端开发、前端联调、运维、架构师 |

### 核心设计原则

1. **单一服务,内部模块化** - 看板 + 事件采集 + 预聚合,职责清晰,易重构
2. **EventSink 抽象** - 预留 MQ / 双写 / 采样等扩展点
3. **物化视图 + 预聚合表混用** - 历史数据走 MV,实时性要求高的走预聚合表
4. **按日分区** - events 表按 received_at 按日分区,30 天滚动清理
5. **准实时 + 预留实时** - 5 分钟刷新,可切换到同步通道
6. **JWT + 粉丝身份双校验** - 经 gateway 鉴权,业务侧校验 fan_profile

### 核心特点(4 大设计亮点)

| # | 特点 | 价值 |
|---|------|------|
| 1 | **多层缓存 + 读写分离** | 看板读 90% 命中 Redis 5min TTL,不进 DB;事件写 channel 非阻塞,异步批量落库 |
| 2 | **MV + 预聚合混用** | 历史数据走 MV(全量重算简单);实时性窗口数据(week_rank / recent_level_ups)走预聚合表 Worker 增量维护 |
| 3 | **EventSink 抽象 + 开关** | 后续 OLAP/实时/MQ 都是 `cfg.EnableXxx` 开关,无需重构;本期只实现最简版本 |
| 4 | **按日分区 + 自动管理** | 7 天预创建 + 30 天滚动清理,运维零干预;单分区 50M 行,操作快 |

### 与 figma 文档 4.2 节关键差异

| 项 | figma 文档 | statisticService(本期) | 理由 |
|---|----------|-------------------|------|
| HTTP 路径前缀 | `/api/v1/dashboard/*` | **保持** | 前端已固定,改前端成本巨大 |
| 响应包装 | figma 没明确 | `{code: 200, data: <resp>}` | 对齐前端 `.data` 访问 |
| `week_rank` | figma 写"可选" | **完整实现** | 用户确认 |
| `week_total_users` | 无 | **新增** | 用于"击败 X%"展示 |
| 鉴权字段 | 请求带 user_id | 从 JWT 取 | 安全 |

---

## 〇·一、本期实施范围（2026-06-08 追加）

> **状态**: 本期聚焦看板 7 RPC + 事件采集框架两个范围,业务侧 5 服务集成在本期内,OLAP/SDK/实时/采样/多赛季/灰度发布策略等延后。本节不替换原设计,只标注"本期做 vs 不做",并给出阶段划分与特性清单,作为实施依据。

### 0.1.1 范围矩阵

| # | 类别 | 项目 | 本期 | 来源章节 |
|---|------|------|------|----------|
| 1 | **看板 7 RPC** | `GetTodayOverview` / `Get7DayIncomeCurve` / `GetExhibitionIncomeSummary` / `GetLikeIncomeByLevel` / `GetTopAssetsByEarning` / `GetAssetLevelDistribution` / `GetAssetUpgradeProgress` | ✅ | §2.3、§3.4-3.5、§4.2 |
| 2 | **事件采集** | `TrackEvent` / `BatchTrackEvent` + EventSink 抽象 + Worker 批量落库 | ✅ | §2.2、§3.2、§4.3 |
| 3 | **预聚合表** | `metric_weekly_user_income` / `metric_recent_level_ups` / `metric_upcoming_level_ups` | ✅ | §3.5 |
| 4 | **物化视图** | `mv_daily_user_income` / `mv_daily_exhibition_revenue` / `mv_daily_like_income` / `mv_asset_level_distribution` | ✅ | §3.4 |
| 5 | **分区管理** | events 表按日分区 + 7 天预创建 + 30 天清理 | ✅ | §3.3、§4.5 |
| 6 | **Gateway 路由** | 7 个 `/api/v1/dashboard/*` 路由 + JWT 鉴权 + 粉丝身份校验 | ✅ | §2.4-2.6、§4.2 |
| 7 | **业务侧集成** | 5 个服务改造（social/asset/gallery/task/user）逐步加 TrackEvent | ✅ | §5.7 |
| 8 | **可观测性** | Prometheus 指标（§4.7 全量）+ healthz + refresh_log | ✅ | §4.7、§4.8 |
| 9 | **OLAP 双写** | ClickHouse 集成 | ❌ | §3.10、§6.2 |
| 10 | **实时通道** | 同步 TrackEvent 实时通道 | ❌ | §3.10、§6.2 |
| 11 | **SDK 端点** | HTTP `/api/v1/dashboard/track` 暴露 | ❌ | §2.4、§3.10 |
| 12 | **采样** | 客户端采样 + `EnableSampling` | ❌ | §3.8、§4.9 |
| 13 | **多赛季** | `season_id` 字段 / 赛季 Tab | ❌ | §3.10、§6.2 |
| 14 | **灰度发布** | 10%→100% 灰度策略 + Stage 1-6 步骤 | ❌（保留机制但简化执行） | §5.8 |
| 15 | **完整告警实现** | 钉钉/飞书 webhook（10 条规则） | ❌（指标埋点保留，告警由监控平台处理） | §4.8 |
| 16 | **Channel 满载 Level 2-5** | 加大缓冲 / Worker 并发 / 解耦预聚合 / 降级 / 采样 | ❌（仅 Level 1 监控） | §4.9 |

### 0.1.2 阶段划分（4 阶段 / 事件先看板后）

| 阶段 | 名称 | 周期（估） | 关键产出 | 关键验证 |
|------|------|-----------|---------|---------|
| **P1** | 服务骨架 | 2-3 天 | go.mod / proto / main.go / config / healthz / 启动接入 go.work / 10 个 SQL 迁移 | `go build` 通过 + `go test ./...` 通过 + 契约测试（proto json schema 校验）+ DB 迁移可重放 + P1 末预检查清单通过 |
| **P2** | 事件采集 | 4-5 天 | events 表（已建）+ TrackEvent/BatchTrackEvent RPC + EventSink 接口 + event_flusher Worker + 3 个预聚表 + partitioner | 单元测试 + 集成测试（dockertest 真实 PG）+ 业务侧 socialService 一个服务联调通 |
| **P3** | 看板 7 RPC | 4-5 天 | 4 个 MV + 7 个 RPC service + main.go 启动预热 7 cache 逻辑 + gateway 7 路由 + Redis 5min TTL | 集成测试（7 RPC 全覆盖）+ gateway 端到端 + 性能测试（k6/wrk 缓存命中/未命中 P99）+ 前端切流量 + cache hit rate > 80% |
| **P4** | 业务侧补全 | 2-3 天 | 4 个服务集成（galleryService→taskService→assetService→userService）+ 各服务单元测试 + 联调 | 各服务 `go test` 通过 + 看板数据逐步出现 7 个事件类型 |

**关键依赖 / 决策：**

- **P2 不依赖 P3**：事件写入和看板读取在 service 层完全解耦（service 写 events，dashboard 读 MV），但都需要 PG schema + proto + config
- **P3 启动时预热**：dashboard 7 个 RPC 各走独立 cache key + 启动 hook 预热 7 个 cache（防冷启动雪崩）
- **P4 顺序**：galleryService（exhibition.start/end）→ taskService（exhibition.revenue）→ assetService（asset.mint/level_up）→ userService（crystal.change）。先做高频路径（gallery 展出是核心场景），后做低频路径

**对外接口冻结点：**

- P1 末：proto 文件定稿（7 RPC + 2 事件 RPC，事件 RPC 内部可用）
- P2 末：TrackEvent RPC 内部可用，业务侧可接入
- P3 末：前端可切流量

### 0.1.3 特性清单（每阶段具体做什么）

#### P1 · 服务骨架

**目标：** 起个空服务能跑起来，迁移能跑通。

| 任务 | 涉及文件 | 备注 |
|------|---------|------|
| go.mod 创建 | `backend/services/statisticService/go.mod` | 沿用 taskService 的依赖（pkg/database / pkg/redis / pkg/dubbo / pkg/metrics） |
| go.work 集成 | `backend/go.work` | 加 `./services/statisticService` |
| proto 定义 | `backend/proto/event.proto`、`backend/proto/statistic.proto` | **关键：冻结 proto**，7 RPC + 2 事件 RPC |
| 配置 | `backend/services/statisticService/config/statistic_config.go` | 端口 20009 + schema=statistic + Redis + 刷新间隔 + Channel 配置 + 4 个 EnableXxx=false（OLAPDualWrite / RealtimeChannel / SDKEndpoint / Sampling） |
| main.go | `backend/services/statisticService/main.go` | Dubbo triple 注册 + HTTP healthz + 启动 Worker hook |
| DB 迁移 10 个 SQL | `backend/migrations/2026_06_08_001_statistic_events.sql` 等 10 个 | events 分区表 + 4 MV + 3 预聚表 + refresh_log + 初始 7 天分区 |
| healthz 端点 | `backend/services/statisticService/handler/healthz.go` | 暴露 6 个关键指标（DB ping / Redis ping / Worker 状态 / 事件 channel 大小 / 预聚表行数） |
| metrics 埋点骨架 | `backend/services/statisticService/metrics/metrics.go` | §4.7 全部 20+ 指标先声明，本期不全部埋数据 |
| 启动验证 | 本地 + CI | `go build` + `go test ./...` + DB 迁移重放 + healthz 200 |

**P1 末预检查清单**（P2 开工前必须验证）：

| # | 检查项 | 来源 | 验证方式 |
|---|--------|------|---------|
| 1 | socialService 有 `LikeAsset` 方法（或等价的写 asset_likes 入口） | §2.2 事件类型 | `grep -rn "asset_likes\|LikeAsset" backend/services/socialService/` |
| 2 | galleryService 有 `PlaceAsset`（开始展出）/ `RemoveFromSlot`（结束展出）方法 | §2.2 | `grep -rn "^func.*PlaceAsset\|^func.*RemoveFromSlot" backend/services/galleryService/service/` |
| 3 | taskService 有 `OnExhibitionCompleted` 方法（派发展览收益） | §2.2 | `grep -n "OnExhibitionCompleted" backend/services/taskService/service/revenue_service.go` |
| 4 | assetService 有 `CreateMintOrder`（铸造）/ `CheckUpgrade` 或 `logLevelChange`（升级）方法 | §2.2 | `grep -n "CreateMintOrder\|CheckUpgrade\|logLevelChange" backend/services/assetService/service/{mint_service,asset_level_service}.go`；**实际等级变更点需 P1 末向 assetService 同学确认** |
| 5 | userService 有 `UpdateCrystalBalance` 方法（水晶账本变动） | §2.2 | `grep -n "UpdateCrystalBalance" backend/services/userService/service/user_service.go` |
| 6 | public 库的 `assets` 表有 `level` 字段、`status='active'` 软删除状态、`deleted_at IS NULL` 约定（MV4 假设） | §3.4 MV4 | `\d+ public.assets` 或 DBeaver 看 schema |
| 7 | public 库的 `asset_likes` / `crystal_log` / `level_up_log` 表存在 | §3.4、§3.5 | `\dt public.*` |
| 8 | Dubbo triple 端口 20009 未被占用 | §1.4 | `lsof -i :20009` |
| 9 | 业务侧 5 个服务的 Dubbo 注册名（`tri://...:20000/20001/20002/20003/20006`）可达 | §1.2、§5.5 | `nc -zv` 或本地 e2e 调通 |
| 10 | PostgreSQL `statistic` schema 创建权限 OK | §3.1 | 用业务账号 `CREATE SCHEMA statistic` 测试 |

**核对不过则不进 P2。**

#### P2 · 事件采集框架

**目标：** 服务能收事件、能落库、能维护预聚表；socialService 一个业务方联调通。

| 模块 | 涉及文件 | 备注 |
|------|---------|------|
| **model** | `model/event.go` | Event 结构 + JSONB 序列化 |
| **repository** | `repository/event_repo.go` | 批量 INSERT ON CONFLICT DO NOTHING + event_id 去重 |
| **repository** | `repository/metric_repo.go` | 3 个预聚表读写 |
| **sink** | `sink/event_sink.go`（接口）+ `sink/channel_sink.go`（本期实现） | EventSink 接口预留 OLAP/实时/采样实现点 |
| **service** | `service/event_service.go` | 校验（event_id 格式 / user_id 存在 / event_type 白名单 / properties < 1KB）+ 推入 channel |
| **worker** | `worker/event_flusher.go` | 攒批 100 条/1s + 批量落库 + 触发 metric_recent_level_ups 同步更新 |
| **worker** | `worker/metric_recent_level_ups_updater.go` | 同步更新（被 event_flusher 调用） |
| **worker** | `worker/metric_upcoming_level_ups_updater.go` | 15min ticker（不依赖 event） |
| **worker** | `worker/metric_weekly_user_income_updater.go` | 5min ticker，pg_try_advisory_lock 防多实例重复 |
| **worker** | `worker/partitioner.go` | 启动时 + 每天 00:05 创建未来 7 天 / 每天 00:30 清理 30 天前 |
| **proto handler** | `handler/track_event.go` | TrackEvent / BatchTrackEvent RPC 实现 |
| **业务侧集成** | socialService 的 `like_income_log` 写入后 | 调用 `statisticClient.TrackEvent` 异步（fire-and-forget） |
| **测试** | `service/event_service_test.go`、`worker/event_flusher_test.go`、`integration/track_event_test.go` | 单元 + 集成（dockertest 真实 PG） |

**EventSink 接口设计（关键）：**

```go
type EventSink interface {
    Submit(ctx context.Context, e *event.Event) error
    SubmitBatch(ctx context.Context, es []*event.Event) error
    Close() error
}
// 本期实现：ChannelEventSink（推到 channel，由 event_flusher 消费）
// 未来扩展：KafkaEventSink / ClickHouseDualWriteSink / SamplingEventSink
```

#### P3 · 看板 7 RPC

**目标：** 7 个看板端到端通，前端可切流量。

| 模块 | 涉及文件 | 备注 |
|------|---------|------|
| **model** | `model/metric.go` | 7 个响应结构对齐 proto |
| **repository** | `repository/dashboard_repo.go` | 7 个聚合 SQL（读 MV/预聚表，公共 schema 关联 assets/exhibitions） |
| **service** | `service/dashboard_service.go` | 7 个 RPC 业务逻辑 + Redis 5min TTL + 缓存穿透防护 + 跨服务调用降级（userService.crystal_balance 失败时用 stale 标记） |
| **service** | `service/metric_service.go` | MV 刷新协调（被 materializer 调用） |
| **worker** | `worker/materializer.go` | 4 个 MV 用 REFRESH MATERIALIZED VIEW CONCURRENTLY + pg_try_advisory_lock + 错开执行时间（避免 DB 瞬时压力） + refresh_log 记录 |
| **cache** | `service/cache.go` | 封装 pkg/redis，cache key 格式 `dash:{rpc}:{star_id}:{user_id}` |
| **gateway 路由** | `backend/gateway/router/router.go` | 7 个 GET 路由 |
| **gateway controller** | `backend/gateway/controller/statistic_controller.go` | 7 个方法 + JWT 鉴权 + 粉丝身份校验（调 userService.fan_profile）+ 响应包装 `{code:200, data:resp}` |
| **业务侧消费** | gateway 调 7 个 RPC，前端 dashboardApi 已固定 | 切流量前确认前端 mock 数据准确性 |
| **测试** | `service/dashboard_service_test.go`（7 RPC 单测）、`integration/dashboard_rpc_test.go`（7 RPC dockertest）、`integration/gateway_test.go`（端到端） | 100% RPC 覆盖 |

**看板冷启动优化（启动 hook 预热）：**

```go
// main.go 启动时
go func() {
    for _, starID := range getTopNStars(100) {  // 取前 100 star
        for _, rpc := range dashboardRPCs {
            go callAndCache(rpc, starID, sampleUserID)
        }
    }
}()
```

#### P4 · 业务侧补全（4 个服务）

| 顺序 | 服务 | 事件类型 | 集成位置 |
|------|------|---------|---------|
| 1 | galleryService | `exhibition.start`、`exhibition.end` | `PlaceAsset`（开始）/ `RemoveFromSlot`（结束）后 |
| 2 | taskService | `exhibition.revenue` | `OnExhibitionCompleted` 调用后 |
| 3 | assetService | `asset.mint`、`asset.level_up` | `CreateMintOrder`（铸造）/ `CheckUpgrade`（升级）后 |
| 4 | userService | `crystal.change` | `UpdateCrystalBalance` 调用后 |

**集成模式（统一封装）：**

```go
// 各服务引入 pkg/statistic 客户端
type StatisticClient interface {
    TrackEvent(ctx context.Context, e *event.Event) error
    BatchTrackEvent(ctx context.Context, es []*event.Event) error
}
// 业务调用方用 defer + recover 保证 fire-and-forget 不影响主流程
defer func() {
    if r := recover(); r != nil {
        log.Errorf("statistic track panic: %v", r)
    }
    go statisticClient.TrackEvent(bgCtx, buildEvent(...))
}()
```

**每个服务必做：**

- 加 `statisticClient` 注入
- 在指定业务方法后加 `defer go TrackEvent`
- 单测验证 `TrackEvent` 被调用（用 mock client）
- 联调验证事件能落库 + 看板数据能出现

---

## 一、架构总览

### 1.1 服务定位

`statisticService` 是 TopFans 平台的数据统计与看板服务,提供两类核心能力:

| 能力 | 描述 | 读者 |
|------|------|------|
| **数据看板** | 为 figma 数据看板页面提供 7 个聚合查询 RPC | 前端 `dashboard.vue` |
| **事件采集** | 提供业务事件接入通道(EventSink 抽象),用于埋点 | 内部各服务 + 未来前端 SDK |

### 1.2 服务位置

```
backend/services/statisticService/      # 新建
backend/proto/statistic.proto            # 新建
backend/proto/event.proto                # 新建(通用事件类型)
backend/gateway/router/router.go         # 修改:注册 /api/v1/dashboard/* 路由
backend/gateway/controller/statistic_controller.go  # 新建
backend/go.work                          # 修改:加入 statisticService
backend/migrations/                      # 新建:statistic 表迁移(10 个 SQL)
```

### 1.3 目录结构(参照 taskService)

```
backend/services/statisticService/
├── main.go
├── go.mod / go.sum
├── config/
│   └── statistic_config.go              # 配置: 端口、DB、Redis、刷新间隔、扩展开关
├── provider/
│   ├── statistic_internal_provider.go   # 内部服务调用方(其他服务 TrackEvent)
│   └── statistic_mobile_provider.go     # 移动端/前端调用方(看板 7 RPC)
├── service/                              # 业务逻辑层
│   ├── dashboard_service.go            # 看板 7 RPC 业务逻辑
│   ├── event_service.go                # 事件采集业务逻辑(批量落库)
│   └── metric_service.go               # 预聚合/物化视图管理
├── repository/                           # 数据访问层
│   ├── event_repo.go                   # events 表操作
│   ├── metric_repo.go                  # 预聚合表查询
│   └── dashboard_repo.go               # 看板聚合 SQL
├── model/                                # 数据模型
│   ├── event.go                        # 通用事件模型
│   └── metric.go                       # 预聚合模型
├── worker/                               # 后台任务
│   ├── materializer.go                 # 物化视图定时刷新
│   ├── event_flusher.go                # 事件批量落库 worker
│   └── partitioner.go                  # events 按日分区自动管理
├── client/                               # 调用其他服务
│   ├── gallery_client.go
│   ├── asset_client.go
│   ├── user_client.go
│   └── task_client.go
└── docs/                                 # 服务级文档
    ├── EVENT_TYPES.md                   # 事件类型注册表
    ├── RUNBOOK.md                       # 运维手册
    └── FAQ.md                           # 常见问题
```

### 1.4 端口

- **Dubbo triple 端口**: `tri://127.0.0.1:20009`
- **HTTP 经 gateway**: `http://gateway:8080/api/v1/dashboard/*`
- 端口冲突检查: 20000-20006, 20008 已被其他服务占用,20007 / 20009 空闲,选定 20009

### 1.5 与其他服务的关系

```
                        [Frontend dashboard.vue]
                                ↓ HTTP (USE_MOCK_API=false)
                          [Gateway :8080]
                                ↓ gRPC
                          [statisticService :20009]
                                ↓ gRPC 调用
                ┌───────────────┼───────────────┐
                ↓               ↓               ↓
         [galleryService] [assetService]  [userService]   [taskService]   [socialService]
            :20001            :20003         :20000         :20006          :20002
                ↓               ↓               ↓               ↓               ↓
              [PostgreSQL public schema: assets / exhibitions / users / level_up_logs / crystal_logs / like_income_logs]
                                ↓
                       [statisticService 物化视图 + 预聚合]
                                ↓
                          [PostgreSQL: statistic schema]
```

**职责分工:**

- `statisticService` 主要是**只读聚合 + 事件写入**,不持有核心业务数据
- 通过 gRPC 调用其他服务获取实时数据(如 `crystal_balance` 走 userService)
- 通过 PostgreSQL 物化视图做预聚合,看板查询走 MV
- 通过 Redis 缓存看板结果(5 分钟 TTL)

---

## 二、Proto + HTTP 设计

### 2.1 路径与服务命名约定

| 层 | 名称 | 说明 |
|------|------|------|
| **Dubbo 服务名** | `statistic.StatisticService` | gRPC 服务注册名 |
| **服务端口** | `tri://127.0.0.1:20009` | Dubbo triple 协议 |
| **HTTP 路径前缀(看板)** | `/api/v1/dashboard/*` | **经 gateway 暴露给前端,前端已固定** |
| **HTTP 路径前缀(预留 SDK)** | `/api/v1/dashboard/track` | POST,经 gateway,本期不实现 |

> 关键决策: gRPC 服务名 = `statistic`,HTTP 路径 = `/dashboard`(因前端已固定,改名成本巨大)

### 2.2 event.proto(通用事件,**独立文件**)

```protobuf
syntax = "proto3";
package event;
option go_package = "github.com/topfans/backend/pkg/proto/event";

message Event {
  string event_id = 1;          // 事件 ID(UUID,客户端生成,用于去重)
  int64 user_id = 2;            // 用户 ID
  int64 star_id = 3;            // 顶粉星城 ID
  string event_type = 4;        // 事件类型(如 "asset.like", "exhibition.start")
  int64 occurred_at = 5;        // 事件发生时间(ms timestamp)
  int64 received_at = 6;        // 服务端接收时间(ms,服务端填充)
  map<string, string> properties = 7;  // 自定义属性(扁平 key-value)
}

message BatchEventRequest {
  repeated Event events = 1;
}
```

**为什么独立 event.proto?**

- 跨服务复用(其他服务可只引用 event.proto,不必引用 statistic.proto)
- 避免循环依赖
- 未来独立升级(`event/v2.proto` 可并存)
- 与项目 `common.proto` 风格一致(共享类型单独)

**事件类型字符串规范(枚举化,但用字符串便于扩展):**

| 事件类型 | 来源服务 | properties 示例 |
|---------|---------|----------------|
| `asset.like` | socialService | `{"asset_id": "123", "level": "SSR", "amount": "10"}` |
| `asset.mint` | assetService | `{"asset_id": "123", "level": "UR"}` |
| `exhibition.start` | galleryService | `{"asset_id": "123", "slot_id": "1"}` |
| `exhibition.end` | galleryService | `{"asset_id": "123", "duration_ms": "86400000"}` |
| `exhibition.revenue` | taskService | `{"asset_id": "123", "amount": "100", "duration_ms": "60000"}` |
| `asset.level_up` | assetService | `{"asset_id": "123", "from": "SR", "to": "SSR"}` |
| `crystal.change` | userService | `{"amount": "+100", "reason": "exhibition"}` |

**事件类型注册表:** `backend/services/statisticService/docs/EVENT_TYPES.md`(不在代码里硬编码)

### 2.3 statistic.proto(主服务协议,字段对齐前端)

```protobuf
syntax = "proto3";
package statistic;
option go_package = "github.com/topfans/backend/pkg/proto/statistic";
import "event.proto";

service StatisticService {
  // ============ 看板 7 RPC(经 gateway 暴露) ============
  rpc GetTodayOverview(GetTodayOverviewRequest) returns (GetTodayOverviewResponse);
  rpc Get7DayIncomeCurve(Get7DayIncomeCurveRequest) returns (Get7DayIncomeCurveResponse);
  rpc GetExhibitionIncomeSummary(GetExhibitionIncomeSummaryRequest) returns (GetExhibitionIncomeSummaryResponse);
  rpc GetLikeIncomeByLevel(GetLikeIncomeByLevelRequest) returns (GetLikeIncomeByLevelResponse);
  rpc GetTopAssetsByEarning(GetTopAssetsByEarningRequest) returns (GetTopAssetsByEarningResponse);
  rpc GetAssetLevelDistribution(GetAssetLevelDistributionRequest) returns (GetAssetLevelDistributionResponse);
  rpc GetAssetUpgradeProgress(GetAssetUpgradeProgressRequest) returns (GetAssetUpgradeProgressResponse);

  // ============ 事件采集(内部 RPC) ============
  rpc TrackEvent(event.Event) returns (TrackEventResponse);
  rpc BatchTrackEvent(event.BatchEventRequest) returns (TrackEventResponse);
}

// ====== 1. 今日概览 ======
message GetTodayOverviewRequest { int64 star_id = 1; }
message GetTodayOverviewResponse {
  int64 crystal_balance = 1;
  int64 today_income = 2;
  int32 week_rank = 3;          // 本期完整实现
  int32 week_total_users = 4;   // 用于"击败 X%"
}

// ====== 2. 七日收益曲线 ======
message Get7DayIncomeCurveRequest { int64 star_id = 1; }
message DailyIncomePoint {
  string date = 1;
  int64 income = 2;
  bool is_today = 3;
  bool is_peak = 4;
}
message Get7DayIncomeCurveResponse {
  repeated DailyIncomePoint points = 1;
  int64 total_income = 2;
  int64 avg_income = 3;
}

// ====== 3. 展出收益中心 ======
message GetExhibitionIncomeSummaryRequest { int64 star_id = 1; }
message TopExhibitionItem {
  int64 asset_id = 1;
  string asset_name = 2;
  string asset_thumb = 3;
  string duration_7d = 4;
  int64 earnings_7d = 5;
  int32 avg_earnings = 6;
}
message GetExhibitionIncomeSummaryResponse {
  int32 exhibiting_count = 1;
  int32 starbook_count = 2;
  string total_duration = 3;  // 格式: "D:HH:MM:SS"(< 24h 时省略 D) / Mock 样例: "712:13:56"
  int64 total_earnings = 4;
  repeated TopExhibitionItem top5 = 5;
}

// ====== 4. 点赞收益按等级 ======
message GetLikeIncomeByLevelRequest { int64 star_id = 1; }
message LikeIncomeLevelItem {
  string level = 1;
  int32 asset_count = 2;
  int64 total_income = 3;
  string thumb = 4;
}
message GetLikeIncomeByLevelResponse {
  int64 total_like_count = 1;
  int64 total_income = 2;
  repeated LikeIncomeLevelItem levels = 3;
}

// ====== 5. 藏品 TOP5 ======
message GetTopAssetsByEarningRequest { int64 star_id = 1; }
message TopAssetItem {
  int64 asset_id = 1;
  string asset_name = 2;
  string asset_thumb = 3;
  int64 total_earnings = 4;
  int32 rank = 5;
}
message GetTopAssetsByEarningResponse {
  repeated TopAssetItem items = 1;
}

// ====== 6. 藏品等级分布 ======
message GetAssetLevelDistributionRequest { int64 star_id = 1; }
message AssetLevelItem {
  string level = 1;
  int32 count = 2;
  int32 total = 3;
}
message GetAssetLevelDistributionResponse {
  repeated AssetLevelItem items = 1;
}

// ====== 7. 升级进度 ======
message GetAssetUpgradeProgressRequest { int64 star_id = 1; }
message UpcomingLevelUpItem {
  int64 asset_id = 1;
  string asset_name = 2;
  string asset_thumb = 3;
  int32 like_progress = 4;
  int32 duration_progress = 5;
}
message RecentLevelUpItem {
  int64 asset_id = 1;
  string asset_name = 2;
  string asset_thumb = 3;
  string new_level = 4;
  int64 upgrade_time = 5;
}
message GetAssetUpgradeProgressResponse {
  repeated UpcomingLevelUpItem upcoming = 1;
  repeated RecentLevelUpItem recent = 2;
}

// ====== 事件采集响应 ======
message TrackEventResponse {
  int32 accepted = 1;
  int32 rejected = 2;
}
```

### 2.4 HTTP 路径与 gRPC 方法映射

| HTTP 路径 | HTTP 方法 | Gateway 调用的 gRPC | 前端 dashboardApi 方法 |
|-----------|----------|---------------------|------------------------|
| `/api/v1/dashboard/today-overview` | GET | `StatisticService.GetTodayOverview` | `dashboardApi.getTodayOverview(starId)` |
| `/api/v1/dashboard/income-curve` | GET | `StatisticService.Get7DayIncomeCurve` | `dashboardApi.get7DayIncomeCurve` |
| `/api/v1/dashboard/exhibition-summary` | GET | `StatisticService.GetExhibitionIncomeSummary` | `dashboardApi.getExhibitionSummary` |
| `/api/v1/dashboard/like-income-by-level` | GET | `StatisticService.GetLikeIncomeByLevel` | `dashboardApi.getLikeIncomeByLevel` |
| `/api/v1/dashboard/top-assets` | GET | `StatisticService.GetTopAssetsByEarning` | `dashboardApi.getTopAssets` |
| `/api/v1/dashboard/level-distribution` | GET | `StatisticService.GetAssetLevelDistribution` | `dashboardApi.getLevelDistribution` |
| `/api/v1/dashboard/upgrade-progress` | GET | `StatisticService.GetAssetUpgradeProgress` | `dashboardApi.getUpgradeProgress` |
| `/api/v1/dashboard/track` (预留) | POST | `StatisticService.TrackEvent` | (未来 SDK) |

### 2.5 Gateway 响应包装

Gateway 在调用 gRPC 后,统一包 `{code: 200, data: <gRPC 响应>}`:

```go
// 伪代码 - gateway controller
func (c *DashboardController) GetTodayOverview(ctx *gin.Context) {
    starID := parseInt64(ctx.Query("star_id"))
    userID := getUserIDFromJWT(ctx)  // 鉴权后注入
    if userID == 0 { 
        respondUnauthorized(ctx); return 
    }
    
    resp, err := c.statisticClient.GetTodayOverview(ctx, &pb.GetTodayOverviewRequest{
        StarId: starID,
    })
    if err != nil {
        respondError(ctx, 500, err); return
    }
    respondOK(ctx, gin.H{
        "code": 200,
        "data": resp,  // 直接把 gRPC 响应作为 data
    })
}
```

### 2.6 鉴权

- **HTTP `/api/v1/dashboard/*`(看板 7 RPC)**: 经 gateway 的 JWT 中间件鉴权,从 token 取 user_id(注入到 ctx),star_id 从 query 取
- **HTTP `/api/v1/dashboard/track`(预留 SDK)**: 经 gateway JWT 鉴权,从 token 取 user_id
- **gRPC `TrackEvent`(服务间内部)**: Dubbo 内网白名单 + 调用方服务名校验

### 2.7 关键设计决策汇总

| 决策点 | 选择 | 理由 |
|--------|------|------|
| **请求字段** | 只传 `star_id`,不传 `user_id` | `user_id` 从 JWT 取,前端不可信 |
| **批量上报** | 提供 `BatchTrackEvent` | SDK/服务可批量,减少 RPC 次数 |
| **事件 ID** | 客户端生成(UUID) | 服务端去重,防止重试导致重复 |
| **时间字段** | 双时间戳(occurred_at + received_at) | 区分业务时间和入仓时间 |
| **属性存储** | `map<string, string>` | 扁平 key-value,适合 JSONB 存储 |
| **错误处理** | 走 rejected 计数 + log | 埋点不应阻塞业务 |
| **响应包装** | `{code: 200, data: <resp>}` | 对齐前端 `.data` 访问 |

---

## 三、数据表设计

### 3.1 数据库与 Schema

- 复用现有 PostgreSQL 实例,新建 schema `statistic`
- 数据库连接复用 `pkg/database`,只新增一个 schema 配置项

```
[PostgreSQL]
├── public (现有 9 个服务的业务表,只读访问)
└── statistic (本服务专用,可读写)
    ├── events               # 事件原始表(按日分区)
    ├── materialized_views    # 物化视图
    ├── metric_*              # 预聚合表
    └── refresh_log           # 物化视图刷新日志
```

### 3.2 核心表:`statistic.events`(按日分区)

```sql
CREATE TABLE statistic.events (
    id              BIGSERIAL,
    event_id        UUID         NOT NULL,
    user_id         BIGINT       NOT NULL,
    star_id         BIGINT       NOT NULL,
    event_type      VARCHAR(64)  NOT NULL,
    occurred_at     TIMESTAMPTZ  NOT NULL,
    received_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    properties      JSONB        NOT NULL DEFAULT '{}',
    
    PRIMARY KEY (id, received_at)
) PARTITION BY RANGE (received_at);

-- 按日分区示例(2026-06-04 这一天)
CREATE TABLE statistic.events_2026_06_04 PARTITION OF events
  FOR VALUES FROM ('2026-06-04 00:00:00+08') TO ('2026-06-05 00:00:00+08');
-- 注意: 分区键是 TIMESTAMPTZ,要带时区

-- 唯一约束(去重):同一 event_id 不能重复
CREATE UNIQUE INDEX idx_events_event_id ON statistic.events (event_id, received_at);

-- 看板查询主索引(覆盖 90% 查询)
CREATE INDEX idx_events_user_star_type_time
  ON statistic.events (user_id, star_id, event_type, received_at DESC);

-- 趋势分析索引
CREATE INDEX idx_events_star_type_time
  ON statistic.events (star_id, event_type, received_at DESC);

-- JSONB 属性 GIN 索引
CREATE INDEX idx_events_properties_gin ON statistic.events USING GIN (properties);
```

**按日分区优劣:**

| 优势 | 代价 |
|------|------|
| 看板 7 日查询只走 7 个 partition,极快 | partition 数多(30 天保留 ≈ 30 个) |
| 旧数据可按天快速 DROP(DETACH+DROP) | 需要自动管理 partition 创建/删除 |
| 单 partition 容量小(50M 行),操作快 | 时间函数计算稍多 |
| 适合按日归档/分析 | - |

### 3.3 分区自动管理

```go
// worker/partitioner.go
func EnsureFuturePartitions(ctx context.Context, db *sql.DB, days int) error {
    now := time.Now().In(AsiaShanghai)
    for i := 0; i <= days; i++ {
        day := now.AddDate(0, 0, i)
        next := day.AddDate(0, 0, 1)
        partitionName := fmt.Sprintf("events_%s", day.Format("2006_01_02"))
        sql := fmt.Sprintf(`
            CREATE TABLE IF NOT EXISTS statistic.%s 
            PARTITION OF statistic.events
            FOR VALUES FROM ('%s 00:00:00+08') TO ('%s 00:00:00+08');
        `, partitionName, day.Format("2006-01-02"), next.Format("2006-01-02"))
        if _, err := db.ExecContext(ctx, sql); err != nil {
            return err
        }
    }
    return nil
}
```

**调度:**

- Worker 启动时调用 1 次(确保未来 7 天 partition 存在)
- 每天 00:05 调用 1 次(滚动创建)

**分区保留策略:**

- 默认保留 30 天(配置项 `PartitionRetentionDays`)
- 超过保留期的旧分区用 `DETACH PARTITION ... DROP` 删除
- 避免磁盘无限增长

### 3.4 物化视图(全量重算,准实时)

**MV1: `statistic.mv_daily_user_income`(每日用户水晶收益)**

```sql
CREATE MATERIALIZED VIEW statistic.mv_daily_user_income AS
SELECT
  user_id,
  star_id,
  DATE(received_at AT TIME ZONE 'Asia/Shanghai') AS income_date,
  -- 只统计"产生水晶收入"的事件: 展出收益(任务派发) + 水晶账本变动
  -- asset.level_up 不直接携带 amount,等级变更由 crystal.change 同步上报
  SUM(
    CASE
      WHEN event_type IN ('exhibition.revenue', 'crystal.change')
        AND COALESCE((properties->>'amount')::BIGINT, 0) > 0
      THEN COALESCE((properties->>'amount')::BIGINT, 0)
      ELSE 0
    END
  ) AS total_crystal
FROM statistic.events
WHERE event_type IN ('exhibition.revenue', 'crystal.change')
GROUP BY user_id, star_id, income_date;

CREATE UNIQUE INDEX idx_mv_daily_user_income_pk
  ON statistic.mv_daily_user_income (user_id, star_id, income_date);
```

**服务于:** 七日收益曲线、今日收益

**MV2: `statistic.mv_daily_exhibition_revenue`(每日展出收益,按藏品)**

```sql
CREATE MATERIALIZED VIEW statistic.mv_daily_exhibition_revenue AS
SELECT
  user_id,
  star_id,
  (properties->>'asset_id')::BIGINT AS asset_id,
  DATE(received_at AT TIME ZONE 'Asia/Shanghai') AS revenue_date,
  SUM(COALESCE((properties->>'duration_ms')::BIGINT, 0)) AS total_duration_ms,
  SUM(COALESCE((properties->>'amount')::BIGINT, 0)) AS total_earnings
FROM statistic.events
WHERE event_type = 'exhibition.revenue'
GROUP BY user_id, star_id, asset_id, revenue_date;

CREATE UNIQUE INDEX idx_mv_exhibition_revenue_pk
  ON statistic.mv_daily_exhibition_revenue (user_id, star_id, asset_id, revenue_date);
```

**服务于:** 展出收益中心(top5)、藏品矩阵 TOP5

**MV3: `statistic.mv_daily_like_income`(每日点赞按等级)**

```sql
CREATE MATERIALIZED VIEW statistic.mv_daily_like_income AS
SELECT
  e.user_id,
  e.star_id,
  a.level AS asset_level,
  DATE(e.received_at AT TIME ZONE 'Asia/Shanghai') AS like_date,
  COUNT(*) AS like_count,
  SUM(COALESCE((e.properties->>'amount')::BIGINT, 0)) AS total_crystal
FROM statistic.events e
JOIN public.assets a 
  ON a.id = (e.properties->>'asset_id')::BIGINT
WHERE e.event_type = 'asset.like'
GROUP BY e.user_id, e.star_id, a.level, like_date;

CREATE UNIQUE INDEX idx_mv_like_income_pk
  ON statistic.mv_daily_like_income (user_id, star_id, asset_level, like_date);
```

**服务于:** 点赞收益按等级(累计)

**MV4: `statistic.mv_asset_level_distribution`(藏品等级分布)**

> **假设**: `public.assets` 表存在 `status='active'` 软删除状态字段和 `deleted_at IS NULL` 软删除约定(项目既有规范);若不成立,需调整 WHERE 条件。

```sql
CREATE MATERIALIZED VIEW statistic.mv_asset_level_distribution AS
SELECT
  user_id,
  star_id,
  level AS asset_level,
  COUNT(*) AS asset_count
FROM public.assets
WHERE status = 'active' AND deleted_at IS NULL
GROUP BY user_id, star_id, level;

CREATE UNIQUE INDEX idx_mv_level_dist_pk
  ON statistic.mv_asset_level_distribution (user_id, star_id, asset_level);
```

**服务于:** 藏品等级分布环形图

### 3.5 预聚合表(Worker 维护,实时性更高)

**为什么部分用预聚合表?**

- 物化视图全量重算,适合"全量数据 + 定期刷新"场景
- 预聚合表 Worker 增量维护,适合"实时性要求高"或"含时间窗口"场景
- week_rank / recent_level_ups 这类需要按时间窗口,物化视图做不到

**预聚合表:`statistic.metric_weekly_user_income`(本周收入 + 排名)**

```sql
CREATE TABLE statistic.metric_weekly_user_income (
    star_id          BIGINT       NOT NULL,
    user_id          BIGINT       NOT NULL,
    week_start       DATE         NOT NULL,  -- 周一日期(Asia/Shanghai)
    total_crystal    BIGINT       NOT NULL DEFAULT 0,
    rank_in_star     INT          NOT NULL DEFAULT 0,
    updated_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    
    PRIMARY KEY (star_id, user_id, week_start)
);
CREATE INDEX idx_weekly_rank 
  ON statistic.metric_weekly_user_income (star_id, week_start, rank_in_star);
```

**服务于:** GetTodayOverview 的 `week_rank` + `week_total_users`

**week_rank 实现细节:**

```sql
-- 本周收入用户排行(实际查询预聚合表,毫秒级)
SELECT
  rank_in_star    AS rank,
  total_crystal   AS income
FROM statistic.metric_weekly_user_income
WHERE star_id = $1
  AND user_id = $3
  AND week_start = $2;  -- 本周开始时间(周一 00:00,Asia/Shanghai)

-- week_total_users: 本周 star 下有收益的用户总数
SELECT COUNT(*)
FROM statistic.metric_weekly_user_income
WHERE star_id = $1
  AND week_start = $2
  AND total_crystal > 0;

-- 注: 上方 SQL 是概念示意;实际由 Worker 每 5 分钟从 public.crystal_log
--     全量重算写入 metric_weekly_user_income,并计算 rank_in_star。
--     看板查询不直接读 crystal_log。
```

- 预聚合表: `statistic.metric_weekly_user_income(star_id, user_id, week_start, total_crystal, rank_in_star)`
- Worker 每 5 分钟刷新一次
- 看板查询走预聚合表,毫秒级返回
- Redis 缓存 5 分钟
- 边界: 用户本周无收益 → `week_rank = -1`,前端显示"暂无排名"
- 跨周: worker 在周一 00:05 触发,清除上周数据

**预聚合表:`statistic.metric_recent_level_ups`(最近升级记录,只保留近 30 天)**

```sql
CREATE TABLE statistic.metric_recent_level_ups (
    id               BIGSERIAL PRIMARY KEY,
    user_id          BIGINT       NOT NULL,
    star_id          BIGINT       NOT NULL,
    asset_id         BIGINT       NOT NULL,
    from_level       VARCHAR(8)   NOT NULL,
    to_level         VARCHAR(8)   NOT NULL,
    upgrade_time     TIMESTAMPTZ  NOT NULL,
    asset_name       VARCHAR(128),
    asset_thumb      VARCHAR(512)
);
CREATE INDEX idx_recent_level_ups_user
  ON statistic.metric_recent_level_ups (user_id, star_id, upgrade_time DESC);

-- 自动清理: 30 天前的记录定时 DELETE
```

**服务于:** GetAssetUpgradeProgress 的 `recent[]`

**预聚合表:`statistic.metric_upcoming_level_ups`(即将升级进度)**

```sql
CREATE TABLE statistic.metric_upcoming_level_ups (
    user_id            BIGINT       NOT NULL,
    star_id            BIGINT       NOT NULL,
    asset_id           BIGINT       NOT NULL,
    like_progress      INT          NOT NULL,  -- 0-100
    duration_progress  INT          NOT NULL,  -- 0-100
    updated_at         TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    
    PRIMARY KEY (user_id, star_id, asset_id)
);
```

**服务于:** GetAssetUpgradeProgress 的 `upcoming[]`

### 3.6 物化视图刷新日志

```sql
CREATE TABLE statistic.refresh_log (
    id              BIGSERIAL PRIMARY KEY,
    mv_name         VARCHAR(128)  NOT NULL,
    started_at      TIMESTAMPTZ   NOT NULL,
    finished_at     TIMESTAMPTZ,
    row_count       BIGINT,
    status          VARCHAR(16)   NOT NULL,  -- 'running' / 'success' / 'failed'
    error_message   TEXT
);
CREATE INDEX idx_refresh_log_mv_time
  ON statistic.refresh_log (mv_name, started_at DESC);
```

**用于:** 监控物化视图刷新状态 + 失败告警

### 3.7 刷新策略(Worker,可自定义)

| 物化视图 / 预聚合表 | 默认刷新频率 | 配置项 | 优先级 |
|----------|---------|--------|--------|
| `mv_daily_user_income` | 5 分钟 | `RefreshIntervals.DailyUserIncome` | 高 |
| `mv_daily_exhibition_revenue` | 5 分钟 | `RefreshIntervals.DailyExhibitionRevenue` | 中 |
| `mv_daily_like_income` | 5 分钟 | `RefreshIntervals.DailyLikeIncome` | 中 |
| `mv_asset_level_distribution` | 15 分钟 | `RefreshIntervals.AssetLevelDistribution` | 低 |
| `metric_weekly_user_income` | 5 分钟 | `RefreshIntervals.WeeklyUserIncome` | 高 |
| `metric_recent_level_ups` | 实时 | TrackEvent 同步触发 | 高 |
| `metric_upcoming_level_ups` | 15 分钟 | `RefreshIntervals.UpcomingLevelUps` | 中 |
| `metric_recent_level_ups` 清理 | 每天 00:35 | 固定 | 后台 |
| 创建未来 N 天 partition | 每天 00:05 | 固定 | 后台 |
| 清理过期 partition | 每天 00:30 | 固定 | 后台 |

**实现技术:**

- Go Worker 协程 + `time.Ticker`
- 刷新用 `REFRESH MATERIALIZED VIEW CONCURRENTLY`(不阻塞读)
- 并发控制: PostgreSQL Advisory Lock 防止多实例重复刷

### 3.8 配置项(预留扩展开关)

```go
// config/statistic_config.go
type StatisticConfig struct {
    Port           int
    DBUrl          string
    DBSchema       string  // 默认 "statistic"
    RedisUrl       string
    WorkerEnabled  bool
    RefreshIntervals struct {  // 可自定义刷新频率
        DailyUserIncome          time.Duration
        DailyExhibitionRevenue   time.Duration
        DailyLikeIncome          time.Duration
        AssetLevelDistribution   time.Duration
        WeeklyUserIncome         time.Duration
        UpcomingLevelUps         time.Duration
    }
    
    // 分区管理
    PartitionRetentionDays int
    PartitionPreCreateDays int
    
    // 事件 channel
    EventChannelCapacity  int
    EventWorkerCount      int
    EventBatchSize        int
    EventBatchInterval    time.Duration
    
    // 告警阈值
    AlertChannelSizeRatio       float64  // 默认 0.8
    AlertDropRateThreshold      float64  // 默认 0.01
    AlertMVRefreshFailureCount  int      // 默认 3
    
    // 预留扩展(本期默认 false)
    EnableOLAPDualWrite    bool   // 双写 ClickHouse
    EnableRealtimeChannel  bool   // 同步 TrackEvent 实时通道
    EnableSDKEndpoint      bool   // 暴露 HTTP /track 端点
    EnableSampling         bool   // 客户端采样
    SampleRate             float64
}
```

### 3.9 性能预估

**数据量假设:**

- 假设百万 DAU,平均每用户每日产生 50 个事件
- 每日事件量 ≈ 5000 万条
- 7 日事件量 ≈ 3.5 亿条
- 30 日事件量 ≈ 15 亿条

**索引评估:**

- `idx_events_user_star_type_time` 单 user 查询: 命中 7 日分区,毫秒级
- `idx_events_star_type_time` 跨用户统计: 扫描本月分区(50M 行),秒级
- `mv_*` 物化视图查询: 毫秒级(预聚合)

**瓶颈与应对:**

- 看板冷启动 7 个并发请求,各走不同 MV,互不阻塞 ✅
- 物化视图刷新时,`REFRESH CONCURRENTLY` 允许读不阻塞 ✅
- week_rank 实时性: 5 分钟刷新,用户无感 ✅

### 3.10 未来扩展预留(表层)

| 预留 | 实现方式 | 启用时机 |
|------|---------|---------|
| **OLAP 双写** | `events` 表加 `cfg.EnableOLAPDualWrite`,Worker 加 ClickHouse 写入分支 | 数据量 > 1亿/天 |
| **实时通道** | `cfg.EnableRealtimeChannel`,同步 TrackEvent 路径 | 实时性要求提高 |
| **SDK 端点** | `cfg.EnableSDKEndpoint`,暴露 HTTP /track | 前端 SDK 启动 |
| **多赛季** | 预聚合表加 `season_id` 字段,MV 加分区 | 赛季结束归档时 |

---

## 四、关键流程

### 4.1 流程总览

```
┌─────────────────────────────────────────────────────────────┐
│                  statisticService 核心流程                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  流程 A: 看板查询(读)                                          │
│  Gateway → gRPC StatisticService.GetXxx → 查物化视图/MV     │
│                                                              │
│  流程 B: 事件采集(写)                                          │
│  其他服务 → gRPC StatisticService.TrackEvent → 写events表   │
│                                                              │
│  流程 C: 物化视图刷新(后台)                                     │
│  Worker 协程 → 定时器触发 → REFRESH MATERIALIZED VIEW        │
│                                                              │
│  流程 D: 分区管理(后台)                                         │
│  Worker 协程 → 每天 00:05 创建未来 7 天 / 00:30 清理过期分区   │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 4.2 流程 A:看板查询(读路径)

**时序图(以 `GetTodayOverview` 为例):**

```
Frontend                Gateway             statisticService           PostgreSQL / Redis
   │                       │                       │                            │
   │ GET /api/v1/dashboard/│                       │                            │
   │   today-overview      │                       │                            │
   │ ?star_id=123          │                       │                            │
   ├──────────────────────>│                       │                            │
   │                       │ 1. JWT 鉴权            │                            │
   │                       │    从 token 提 user_id │                            │
   │                       │ 2. 解析 query          │                            │
   │                       │    star_id = 123       │                            │
   │                       │ 3. 校验:               │                            │
   │                       │    user.fan_profile    │                            │
   │                       │    .star_id == 123     │                            │
   │                       │                       │                            │
   │                       │ gRPC GetTodayOverview  │                            │
   │                       │ (tri://20009)         │                            │
   │                       ├──────────────────────>│                            │
   │                       │                       │ 1. 查 Redis 缓存            │
   │                       │                       │    Key: dash:overview      │
   │                       │                       │    :123:user_456          │
   │                       │                       ├──────────────────────────>│
   │                       │                       │<────── HIT ────────────────│
   │                       │                       │                            │
   │                       │                       │ (缓存 miss 则:            │
   │                       │                       │  2. 查 metric_weekly      │
   │                       │                       │     user_income           │
   │                       │                       │  3. 查 userService        │
   │                       │                       │     .crystal_balance)     │
   │                       │                       │                            │
   │                       │ GetTodayOverviewResp  │                            │
   │                       │ {                     │                            │
   │                       │   crystal_balance:2713│                            │
   │                       │   today_income:213    │                            │
   │                       │   week_rank:12        │                            │
   │                       │   week_total_users:341│                            │
   │                       │ }                     │                            │
   │                       │<──────────────────────┤                            │
   │                       │                       │                            │
   │                       │ HTTP 包装:            │                            │
   │                       │ { code: 200,          │                            │
   │                       │   data: { ... } }     │                            │
   │                       │                       │                            │
   │   HTTP 200 OK         │                       │                            │
   │<──────────────────────┤                       │                            │
   │                       │                       │                            │
```

**关键设计点:**

1. **JWT 鉴权** - Gateway 在路由层完成,service 收到的请求已带 user_id(注入到 ctx)
2. **粉丝身份校验** - 必须验证 user 真的加入了该 star(查 userService.fan_profile),防止越权
3. **Redis 缓存** - 5 分钟 TTL,缓存 Key 包含 star_id + user_id
4. **缓存穿透防护** - 缓存 miss 时查 DB,DB 也无数据则缓存空值 1 分钟
5. **多 RPC 并发** - 前端 `Promise.allSettled` 一次发 7 个,各走独立 cache key,互不阻塞
6. **降级兜底** - 跨服务调用(如 `userService.GetCrystalBalance`)失败时,该字段用上次缓存值并打 stale 标记,其他字段继续用 MV 返回,不阻断整个看板;连续 3 次失败再返回 5xx

### 4.3 流程 B:事件采集(写路径)

**时序图(以 `socialService` 上报点赞事件为例):**

```
socialService               statisticService                 PostgreSQL
   │                             │                              │
   │ 用户点赞:                    │                              │
   │ 1. 写 like_income_log       │                              │
   │ 2. 更新 asset.like_count    │                              │
   │                             │                              │
   │ (异步,失败不影响主流程)      │                              │
   │ gRPC TrackEvent             │                              │
   │ (tri://20009)               │                              │
   │ { event_id: uuid,           │                              │
   │   user_id: 10000001,        │                              │
   │   star_id: 123,             │                              │
   │   event_type: "asset.like", │                              │
   │   occurred_at: ts,          │                              │
   │   properties: {             │                              │
   │     "asset_id": "456",      │                              │
   │     "amount": "10"          │                              │
   │   }                         │                              │
   │ }                           │                              │
   ├────────────────────────────>│                              │
   │                             │ 1. 校验:                     │
   │                             │    - event_id 格式           │
   │                             │    - user_id 存在            │
   │                             │    - event_type 在白名单    │
   │                             │    - properties 大小 < 1KB   │
   │                             │                              │
   │                             │ 2. 推入 channel(非阻塞)      │
   │                             │    缓冲 1000 条,满则降级     │
   │                             │                              │
   │ TrackEventResponse          │                              │
   │ { accepted: 1, rejected: 0 }│                              │
   │<────────────────────────────┤                              │
   │                             │                              │
   │                             │ ── Worker 协程(独立) ──     │
   │                             │ 3. 批量读 channel            │
   │                             │    攒批 100 条 / 1秒        │
   │                             │ 4. 去重:                     │
   │                             │    SELECT event_id FROM      │
   │                             │    events WHERE event_id IN  │
   │                             │    (?, ?, ...)              │
   │                             ├─────────────────────────────>│
   │                             │<───── 已有 0 条 ─────────────│
   │                             │                              │
   │                             │ 5. 批量 INSERT              │
   │                             │    INSERT INTO events ...   │
   │                             │    ON CONFLICT DO NOTHING    │
   │                             ├─────────────────────────────>│
   │                             │<───── 100 行已写入 ──────────│
   │                             │                              │
   │                             │ 6. 触发预聚合同步更新        │
   │                             │    metric_recent_level_ups   │
   │                             │    (同步,不阻塞事件写入)     │
   │                             │    注: metric_upcoming      │
   │                             │    _level_ups 走 15 分钟     │
   │                             │    Worker,不在此路径        │
```

**关键设计点:**

1. **不阻塞业务** - socialService 调用 `TrackEvent` 是 fire-and-forget,gRPC 调用快速返回(< 50ms)
2. **批量落库** - Worker 协程攒批 100 条/1秒,降低 DB 压力
3. **去重** - 用 event_id 唯一约束 + `ON CONFLICT DO NOTHING`,客户端重试安全
4. **降级策略** - channel 满时拒绝新事件(返回 `rejected: 1`),但不影响主流程
5. **预聚合同步** - TrackEvent 同步触发 `metric_recent_level_ups` 更新(MV 刷新走 5 分钟定时器)

**批量上报优化(预留):**

```go
// 业务侧可一次性上报 100 条事件,减少 RPC 次数
resp, err := client.BatchTrackEvent(ctx, &event.BatchEventRequest{
    Events: events,  // 100 个 Event
})
// 返回: accepted=100, rejected=0
```

### 4.4 流程 C:物化视图刷新(后台)

**时序图(以 5 分钟定时刷新为例):**

```
statisticService Worker                  PostgreSQL
        │                                    │
        │ (5 分钟 ticker 触发)               │
        │                                    │
        │ 1. 抢 Advisory Lock                │
        │    pg_try_advisory_lock(1234)      │
        ├───────────────────────────────────>│
        │<─────── true(抢到) ────────────────│
        │                                    │
        │ 2. REFRESH MATERIALIZED VIEW       │
        │    CONCURRENTLY                    │
        │    mv_daily_user_income;           │
        ├───────────────────────────────────>│
        │    (5-10 秒)                        │
        │<─────── 完成,新数据可见 ───────────│
        │                                    │
        │ 3. 记录 refresh_log                │
        │    INSERT INTO refresh_log ...     │
        ├───────────────────────────────────>│
        │                                    │
        │ 4. 释放 Advisory Lock              │
        │    pg_advisory_unlock(1234)        │
        ├───────────────────────────────────>│
        │                                    │
        │ 5. 等待下一个 tick                  │
```

**关键设计点:**

1. **多实例防重复** - 用 `pg_try_advisory_lock` 保证多实例下只有一个跑刷新
2. **不阻塞读** - `REFRESH CONCURRENTLY` 允许查询继续用旧数据
3. **失败重试** - 3 次重试,失败写 refresh_log 状态 'failed'
4. **告警** - refresh_log 连续 N 次失败触发告警(可对接钉钉/飞书)
5. **优先级** - 不同 MV 错开执行,避免 DB 瞬时压力大

### 4.5 流程 D:分区管理(后台)

- **Worker 启动时**: 调用 `EnsureFuturePartitions(7)`,创建未来 7 天分区
- **每天 00:05**: 调用 `EnsureFuturePartitions(7)`,滚动创建
- **每天 00:30**: 调用 `CleanupOldPartitions(30)`,清理 30 天前分区

### 4.6 异常场景处理

| 场景 | 处理 |
|------|------|
| **DB 不可用** | 看板查询返回 500 + 日志告警;事件采集降级为"丢弃但记录指标" |
| **Redis 不可用** | 缓存全部走 DB(降级),不阻塞 |
| **物化视图刷新失败** | 重试 3 次 → 写 refresh_log failed → 告警 → 看板返回 5 分钟前的数据 |
| **Advisory Lock 抢不到** | 本实例跳过本轮,下个 tick 再试 |
| **事件 channel 满** | 返回 `rejected: N`,记录 `metric_event_dropped` 指标 |
| **JWT 鉴权失败** | Gateway 返回 401,前端跳登录 |
| **粉丝身份不匹配** | Gateway 返回 403 "未加入该顶粉星城" |
| **限流** | 看板 RPC 100 QPS / user_id,超限返回 429;在 gateway 中间件用 Redis 滑动窗口实现(项目现有 `pkg/ratelimit` 组件) |

### 4.7 监控指标(Prometheus)

```go
// 看板 RPC
metrics.NewCounter("dashboard_rpc_total", []string{"rpc", "status"})
metrics.NewHistogram("dashboard_rpc_duration_seconds", []string{"rpc"})
metrics.NewGauge("dashboard_cache_hit_rate")

// 事件采集
metrics.NewCounter("event_track_total", []string{"event_type", "result"})  // result: accepted/rejected
metrics.NewGauge("event_channel_size")
metrics.NewGauge("event_channel_capacity")
metrics.NewCounter("event_dropped_total")
metrics.NewHistogram("event_batch_size")
metrics.NewCounter("event_db_insert_total", []string{"status"})

// 物化视图
metrics.NewCounter("mv_refresh_total", []string{"mv_name", "status"})
metrics.NewHistogram("mv_refresh_duration_seconds", []string{"mv_name"})

// Worker
metrics.NewGauge("worker_running_count", []string{"worker_name"})
metrics.NewHistogram("worker_loop_duration", []string{"worker_name"})

// 分区管理
metrics.NewGauge("events_partition_count")
metrics.NewCounter("events_partition_created_total")
metrics.NewCounter("events_partition_dropped_total")
```

### 4.8 告警规则(本期实现,Level 1)

| 告警项 | 触发条件 | 严重度 | 通知方式 |
|--------|---------|--------|---------|
| **MV 刷新失败** | refresh_log.status='failed' 连续 3 次 | 高 | 飞书/钉钉 + 邮件 |
| **事件 channel 满** | `event_channel_size` > 80% 容量 持续 1 分钟 | 中 | 飞书/钉钉 |
| **事件丢失率过高** | `event_dropped_total / event_track_total` > 1% 持续 5 分钟 | 高 | 飞书/钉钉 + 邮件 |
| **DB 写入慢** | `event_db_insert_duration` P99 > 500ms 持续 5 分钟 | 中 | 飞书/钉钉 |
| **看板 RPC 失败率高** | `dashboard_rpc_total{status=error}` / `dashboard_rpc_total` > 5% 持续 5 分钟 | 中 | 飞书/钉钉 |
| **缓存命中率低** | `dashboard_cache_hit_rate` < 50% 持续 15 分钟 | 低 | 飞书/钉钉 |
| **Advisory Lock 抢不到** | 累计 10 次未抢到 | 中 | 飞书/钉钉 |
| **Worker 不健康** | `worker_running_count=0` 持续 1 分钟 | 高 | 飞书/钉钉 + 邮件 |
| **分区缺失** | 当前日期 partition 不存在 | 高 | 飞书/钉钉 + 邮件 |
| **跨时区异常** | (本期不监控) | - | - |

**告警实现:**

- 本期不引入 AlertManager,只暴露 Prometheus 指标
- 告警规则由 Grafana / 运维侧的告警系统订阅执行(项目已有 Prometheus)
- statisticService 内部加一个"健康度自检"端点 `GET /healthz`,暴露关键指标

### 4.9 Channel 满载分析(本期)

**为什么 channel 会满?(7 类原因)**

1. **生产速率 > 消费速率(最常见)**
   - 消费端慢:DB 慢查询、批量插入性能瓶颈、Worker 被阻塞
   - 生产端快:业务高峰期、某服务异常、并发上报
2. **DB 突发压力**:业务高峰、DB 维护、慢 SQL 阻塞
3. **预聚合同步更新慢**:`metric_recent_level_ups` 同步写慢
4. **资源限制**:channel 容量偏小、Worker 数量少、连接池耗尽
5. **某个调用方异常**:死循环、retry storm、单事件过大
6. **GC 压力**:大量 Event 对象、频繁 GC 暂停 worker
7. **时区/分区问题**:`occurred_at` 路由错误、写入不存在分区

**本期承诺(Level 1):**

- 默认 `EventChannelCapacity: 1000` + `EventWorkerCount: 1` + `EventBatchSize: 100` + `EventBatchInterval: 1s`
- 加监控:`event_channel_size`、`event_dropped_total`、`worker_loop_duration`
- **不预设 Level 2-5 的实现**(加大缓冲 / Worker 并发 / 解耦预聚合 / 降级 / 采样),留好配置项和代码 hook
- 后续根据监控数据决定是否升级

### 4.10 性能与 SLA

#### 4.10.1 核心性能指标

| 指标 | 目标 | 实测方式 |
|------|------|---------|
| 看板单 RPC P99 延迟 | < 200ms | Prometheus + Grafana |
| 看板 7 RPC 并发 P99 | < 500ms | e2e 测试 |
| TrackEvent P99 延迟 | < 50ms | 调用方埋点 |
| 物化视图刷新耗时 | < 30s/视图 | refresh_log 统计 |
| 缓存命中率 | > 80% | Redis 监控 |

**SLA:**

- 可用性: 99.5%(中等,看板不是核心交易)
- 数据延迟: 准实时(5 分钟内,可自定义)
- 事件丢失率: < 0.1%(进程崩溃可能丢失 channel 内未落库事件)

#### 4.10.2 读性能分析(7 RPC 详细)

| RPC | 数据源 | 缓存命中 | 缓存未命中 |
|-----|--------|---------|-----------|
| GetTodayOverview | metric_weekly + userService RPC | <10ms | ~50ms(1 SQL + 1 gRPC) |
| Get7DayIncomeCurve | mv_daily_user_income(扫 7 日分区) | <10ms | ~30ms(1 SQL) |
| GetExhibitionIncomeSummary | mv_daily_exhibition_revenue + exhibitions | <10ms | ~50ms(2 SQL) |
| GetLikeIncomeByLevel | mv_daily_like_income(JOIN assets) | <10ms | ~40ms(1 SQL + JOIN) |
| GetTopAssetsByEarning | mv_daily_exhibition_revenue ORDER BY | <10ms | ~30ms |
| GetAssetLevelDistribution | mv_asset_level_distribution | <10ms | ~20ms |
| GetAssetUpgradeProgress | metric_recent + metric_upcoming | <10ms | ~40ms(2 SQL) |

**7 RPC 并发 P99 预估: 200~400ms**(各自独立 cache key,无相互阻塞)。

#### 4.10.3 写性能分析(TrackEvent + Worker + 刷新)

| 操作 | 路径 | 延迟 | 备注 |
|------|------|------|------|
| **TrackEvent 单条** | gRPC → channel(非阻塞)→ 返回 | **<5ms** | 不等落库,fire-and-forget |
| **TrackEvent 批量 100 条** | gRPC → channel | <20ms | 减少 RPC 次数 |
| **Worker 批量落库** | 攒批 100 条/1s → `INSERT ... ON CONFLICT DO NOTHING` | ~50ms/batch | **持续 50 万/分钟吞吐** |
| **MV 刷新(单视图)** | `REFRESH MATERIALIZED VIEW CONCURRENTLY` | 5~15s | SHARE UPDATE EXCLUSIVE 锁 |
| **预聚合表刷新** | Worker 增量写 | <5s | 单 SQL,取决于 star 数 |
| **分区创建/清理** | 每天 1 次(7 天预创建 + 30 天清理) | <1s | 几乎无感 |

#### 4.10.4 瓶颈与风险点

| # | 瓶颈 | 影响 | 缓解 |
|---|------|------|------|
| 1 | **MV 刷新阻塞 INSERT** | 刷新期间 events 表写入排队 1-2 万/5min(≈1% 事件丢失) | 错开不同 MV 刷新时间;`REFRESH CONCURRENTLY` 已有 |
| 2 | **冷启动 7 RPC 并发** | 启动瞬间 14 个请求(含 userService)冲击 DB | 启动 hook 预热 7 个 cache;首屏请求合并 |
| 3 | **JSONB GIN 索引膨胀** | 15 亿行 × 500B/properties × GIN 膨胀 ≈ 30-50GB 索引 | 30 天清理自然控制;高频字段可降级 btree |
| 4 | **跨服务调用失败** | `crystal_balance` 取不到,看板数据不全 | 已有 stale 缓存兜底(§4.2 第 6 条);连续 3 次失败才 5xx |
| 5 | **week_rank 全量重算** | 100 star × 1 万 user = 100 万行,5min 一次 | PostgreSQL 几秒搞定;预聚合表 + 索引已就绪 |
| 6 | **磁盘 IO** | 30 天 × 5000 万/天 × 500B ≈ 750GB | 按日分区,旧分区可单独放慢盘;运维侧监控 |

> **相关风险见 §6.1 风险登记表**(16 个风险中已覆盖大部分瓶颈)。

#### 4.10.5 一句话总结

**看板读 P99 控制在 200~400ms(全 Redis 命中场景下 <100ms);TrackEvent 完全不阻塞业务(<5ms 返回);MV 刷新阶段有 1% 事件丢失风险(可接受,看板非核心交易)**。最大扩展点是 EventSink 抽象让后续 OLAP/实时/SDK 接入零重构。

---

## 五、测试与部署

### 5.1 测试策略

| 层级 | 范围 | 工具 | 覆盖率 |
|------|------|------|--------|
| **单元测试** | service / repository / worker | Go testing + testify | > 80% |
| **集成测试** | 7 个 RPC + TrackEvent 端到端 | Go testing + dockertest(postgres) | 100% RPC |
| **Worker 测试** | 物化视图刷新 + 预聚合维护 | Go testing + sqlmock | > 70% |
| **性能测试** | 7 RPC 并发 P99、TrackEvent 吞吐 | k6 / wrk | 关键路径 |
| **E2E** | 前端 dashboard.vue → 网关 → 后端 | Playwright | 1 条主路径 |
| **契约测试** | 7 个 RPC 响应 schema 不变 | json schema 校验 | 100% |

**测试夹具(fixture):**

- `testdata/events_sample.json`: 500 条样例事件,覆盖所有 event_type
- `testdata/expected/`: 每个 RPC 的预期响应(对齐前端 mock)
- 测试用 PostgreSQL: 每次 test 启动前 truncate,test 结束 teardown

### 5.2 单元测试重点

```go
// service/dashboard_service_test.go
func TestGetTodayOverview_WeekRank(t *testing.T) {
    // 1. 准备测试数据(metric_weekly_user_income 表)
    // 2. 构造请求
    // 3. 调用 service
    // 4. 验证响应字段
}

func TestGet7DayIncomeCurve_EmptyWeek(t *testing.T) {
    // 边界: 本周无收益,返回空数组
}

func TestTrackEvent_Deduplication(t *testing.T) {
    // 同一 event_id 两次上报,只入库一次
}

func TestTrackEvent_ChannelFull(t *testing.T) {
    // channel 满时降级,返回 rejected > 0
}
```

### 5.3 集成测试(7 RPC 全覆盖)

```go
// integration/dashboard_rpc_test.go
func TestDashboardService_GetTodayOverview_Integration(t *testing.T) {
    // 启动真实 PostgreSQL + statisticService
    // 调用 gRPC GetTodayOverview
    // 验证响应字段对齐前端 mock
}

func TestDashboardService_GetExhibitionIncomeSummary_Integration(t *testing.T) {
    // 验证 top5 排序
    // 验证 total_duration 格式
}
```

### 5.4 性能基准(关键路径)

| 测试项 | 目标 |
|--------|------|
| GetTodayOverview 缓存命中 | < 10ms (P99) |
| GetTodayOverview 缓存未命中 | < 200ms (P99) |
| 7 RPC 并发 | < 500ms (P99) |
| TrackEvent 单条 | < 50ms (P99) |
| TrackEvent 批量 100 条 | < 100ms (P99) |
| 物化视图刷新(单视图) | < 30s |
| Channel 满载处理 | 不阻塞业务调用方 |

### 5.5 部署清单

**新增文件:**

```
backend/services/statisticService/                # 整个目录
backend/proto/statistic.proto
backend/proto/event.proto
backend/gateway/controller/statistic_controller.go
backend/gateway/router/router.go                  # 修改:注册路由
backend/go.work                                  # 修改:加入 statisticService
backend/migrations/                               # 新建:statistic 表迁移
  2026_06_04_001_statistic_events.sql
  2026_06_04_002_statistic_mv_daily_user_income.sql
  2026_06_04_003_statistic_mv_daily_exhibition_revenue.sql
  2026_06_04_004_statistic_mv_daily_like_income.sql
  2026_06_04_005_statistic_mv_asset_level_distribution.sql
  2026_06_04_006_statistic_metric_weekly_user_income.sql
  2026_06_04_007_statistic_metric_recent_level_ups.sql
  2026_06_04_008_statistic_metric_upcoming_level_ups.sql
  2026_06_04_009_statistic_refresh_log.sql
  2026_06_04_010_statistic_partitions_initial.sql
docker/                                          # 修改:加 statisticService 容器
```

**配置项(统计服务 .env):**

```bash
# 服务端口
STATISTIC_SERVICE_PORT=20009

# 数据库
STATISTIC_DB_URL=postgres://user:pass@postgres:5432/topfans?sslmode=disable
STATISTIC_DB_SCHEMA=statistic

# Redis
STATISTIC_REDIS_URL=redis://redis:6379/0

# 业务服务 URL(用于跨服务调用,获取实时数据)
DUBBO_USER_SERVICE_URL=tri://userservice:20000
DUBBO_GALLERY_SERVICE_URL=tri://galleryservice:20001
DUBBO_ASSET_SERVICE_URL=tri://assetservice:20003
DUBBO_TASK_SERVICE_URL=tri://taskservice:20006
DUBBO_SOCIAL_SERVICE_URL=tri://socialservice:20002

# 事件 channel
STATISTIC_EVENT_CHANNEL_CAPACITY=1000
STATISTIC_EVENT_WORKER_COUNT=1
STATISTIC_EVENT_BATCH_SIZE=100
STATISTIC_EVENT_BATCH_INTERVAL=1s

# 物化视图刷新(可自定义)
STATISTIC_REFRESH_DAILY_USER_INCOME=5m
STATISTIC_REFRESH_DAILY_EXHIBITION_REVENUE=5m
STATISTIC_REFRESH_DAILY_LIKE_INCOME=5m
STATISTIC_REFRESH_ASSET_LEVEL_DISTRIBUTION=15m
STATISTIC_REFRESH_WEEKLY_USER_INCOME=5m
STATISTIC_REFRESH_UPCOMING_LEVEL_UPS=15m

# 分区管理
STATISTIC_PARTITION_RETENTION_DAYS=30
STATISTIC_PARTITION_PRECREATE_DAYS=7

# 预留扩展(本期默认 false)
STATISTIC_ENABLE_OLAP_DUAL_WRITE=false
STATISTIC_ENABLE_REALTIME_CHANNEL=false
STATISTIC_ENABLE_SDK_ENDPOINT=false
```

### 5.6 部署顺序

1. **数据库迁移** - 先执行 10 个 SQL 迁移文件
2. **proto 编译** - `protoc` 生成 Go 代码
3. **服务构建** - `go build` statisticService
4. **gateway 路由注册** - 修改 `router.go`,加 7 个 dashboard 路由
5. **前端开关** - `frontend/utils/api.js` 顶部 `USE_MOCK_API = false`
6. **联调测试** - 7 个端点 e2e 通过
7. **切流量** - 灰度切换(先 10% 流量,再 100%)

### 5.7 业务侧集成清单(其他服务需要做的事)

需要调用 TrackEvent 的服务:

| 服务 | 上报事件 | 集成位置 |
|------|---------|---------|
| **socialService** | `asset.like` | LikeAsset() 写 like_income_log 后 |
| **galleryService** | `exhibition.start`, `exhibition.end` | StartExhibition() / EndExhibition() 后 |
| **taskService** | `exhibition.revenue` | 定时任务派发收益后 |
| **assetService** | `asset.mint`, `asset.level_up` | MintAsset() / LevelUp() 后 |
| **userService** | `crystal.change` | 任何水晶变动后 |

**集成方式:** 各服务加 `statisticClient.TrackEvent()`,fire-and-forget 异步调用,失败 log 但不影响主业务。

### 5.8 灰度发布策略

| 阶段 | 范围 | 验证 |
|------|------|------|
| **Stage 1** | statisticService 内部测试 | 单元测试 + 集成测试 |
| **Stage 2** | 网关联调(后端) | 7 个 RPC 端到端通 |
| **Stage 3** | 前端切 10% 流量 | 监控看板 7 个数据准确性 |
| **Stage 4** | 前端 100% 流量 | 监控稳定性 |
| **Stage 5** | 业务侧集成(其他服务) | TrackEvent 上报,验证物化视图刷新 |
| **Stage 6** | 移除 mock 依赖 | 关闭前端 USE_MOCK_API |

---

## 六、风险、后续与验收

### 6.1 已知风险(16 个)

| # | 风险 | 影响 | 概率 | 缓解措施 |
|---|------|------|------|---------|
| 1 | **粉丝身份越权** | 看到别人数据 | 低 | Gateway 校验 fan_profile |
| 2 | **JSONB 注入** | DB 注入 / XSS | 中 | jsonb_build_object + 前端不直渲 |
| 3 | **MV 刷新阻塞** | 看板延迟 | 低 | REFRESH CONCURRENTLY |
| 4 | **事件表爆炸** | 磁盘满 | 中 | 按日分区 + 30 天清理 |
| 5 | **week_rank 数据延迟** | 用户困惑 | 中 | UI 提示"5 分钟前更新" |
| 6 | **分区缺失** | INSERT 失败 | 低 | Worker 自动创建 |
| 7 | **多服务同时上报** | Channel 满 | 中 | Level 1 监控 + 告警 |
| 8 | **gateway 路由冲突** | 其他路径异常 | 低 | 先查现有路由 |
| 9 | **前端 30 分钟缓存** | 数据新鲜度 | 低 | 强制刷新 + 下拉刷新 |
| 10 | **跨时区错位** | 看板日期/排名错误 | **中-高** | `received_at` 统一存 UTC,查询时 `AT TIME ZONE 'Asia/Shanghai'` |
| 11 | **冷启动缓存穿透** | 启动瞬间 DB 压力大 | **中** | 启动时预热 7 个 RPC 缓存;首屏请求合并 |
| 12 | **慢 SQL 锁表** | 写入阻塞 | **中** | REFRESH CONCURRENTLY 用 SHARE UPDATE EXCLUSIVE 锁;避开业务高峰 |
| 13 | **TrackEvent 失败永久丢失** | 数据缺失 | **中-高** | 业务方本地 retry 队列;statisticService 落库前不返回成功 |
| 14 | **proto 字段升级兼容** | 业务方调用报错 | **中** | 字段一律 optional / 带默认值;废弃字段保留 N 版本 |
| 15 | **单用户大量事件**(脚本/爬虫) | Channel 倾斜 | **中** | 按 user_id 限流(每 user 100 QPS) |
| 16 | **服务启动依赖** | 启动期 TrackEvent 失败 | **低** | 业务方重试;statisticService 启动不依赖其他服务 |

### 6.2 后续可扩展(不在本期范围)

| 扩展项 | 触发条件 | 工作量 | 优先级 |
|--------|---------|--------|--------|
| **多赛季切换** | 赛季结束归档 | 1 周 | P2 |
| **赛季总览 Tab** | 上面完成 + UI | 1 周 | P2 |
| **前端埋点 SDK** | 前端有团队接 | 2-3 周 | P2 |
| **OLAP 双写 ClickHouse** | 事件量 > 1亿/天 | 2 周 | P3 |
| **实时通道**(同步 TrackEvent) | 业务要求实时 | 1 周 | P3 |
| **Channel 满载优化**(Level 2-5) | channel 满载告警频繁 | 1 周 | P3 |
| **数据看板分享海报** | 运营要求 | 1 周 | P4 |
| **7 日曲线交互**(点击柱子弹明细) | UI 要求 | 3 天 | P4 |
| **升级提醒推送** | 业务要求 | 1 周 | P4 |
| **本周 vs 上周对比** | 运营要求 | 1 周 | P4 |
| **业务方自定义事件查询** | 业务方有强需求 | 2 周 | P4 |
| **数据准确性核对工具** | 数据出现问题时 | 3 天 | 工具 |

### 6.3 验收清单(本期)

**功能性:**

- [ ] 7 个看板 RPC 全部联通,数据准确(对照前端 mock)
- [ ] `week_rank` 完整实现,排名准确
- [ ] `ExhibitionIncomeSummary.top5` 排序正确
- [ ] `Get7DayIncomeCurve.points[].is_peak` 标识正确
- [ ] TrackEvent 接收 + 去重 + 批量
- [ ] 物化视图刷新成功(4 个 MV + 3 个 metric 表: 2 个由 Worker 定时刷新 + 1 个由 TrackEvent 同步触发)
- [ ] 预聚合表更新正确(recent_level_ups / upcoming_level_ups)
- [ ] JWT 鉴权 + 粉丝身份校验
- [ ] 跨时区处理(Asia/Shanghai 转换)

**性能:**

- [ ] 看板单 RPC P99 < 200ms
- [ ] 7 RPC 并发 P99 < 500ms
- [ ] TrackEvent P99 < 50ms
- [ ] 物化视图刷新 < 30s/视图
- [ ] 缓存命中率 > 80%
- [ ] 冷启动不雪崩(预热 + 缓存穿透防护)

**可靠性:**

- [ ] 单元测试覆盖率 > 80%
- [ ] 集成测试覆盖 100% RPC
- [ ] Channel 满载不阻塞业务
- [ ] MV 刷新失败有告警
- [ ] partition 自动创建/清理
- [ ] 服务异常时不丢关键看板数据
- [ ] TrackEvent 失败业务方有 retry

**可观测性:**

- [ ] Prometheus 指标完整(20+ 指标)
- [ ] 健康检查端点
- [ ] refresh_log 完整记录
- [ ] 关键告警规则配置(10 条)

**集成:**

- [ ] Gateway 路由注册正确(7 个 dashboard 路由)
- [ ] 前端 `USE_MOCK_API = false` 切换
- [ ] 业务侧 5 个服务集成(TrackEvent 上报)
- [ ] Dubbo 服务注册成功(20009)
- [ ] 数据库迁移脚本可重放(10 个 SQL)

**安全:**

- [ ] 粉丝身份越权防护
- [ ] JSONB 注入防护
- [ ] 限流配置生效
- [ ] CORS 配置(预留 SDK 时)

### 6.4 文档维护

| 文档 | 位置 | 维护人 |
|------|------|--------|
| **本设计文档** | `docs/superpowers/specs/2026-06-04-statistic-service-design.md` | 后端主程 |
| **API 文档(Swagger)** | `http://gateway:8080/swagger/index.html` | 自动生成 |
| **事件类型注册表** | `backend/services/statisticService/docs/EVENT_TYPES.md` | 后端 + 业务方 |
| **运维手册** | `backend/services/statisticService/docs/RUNBOOK.md` | 运维 |
| **常见问题 FAQ** | `backend/services/statisticService/docs/FAQ.md` | 后端 |
| **更新日志 CHANGELOG** | `backend/services/statisticService/CHANGELOG.md` | 后端 |

**事件类型新增流程:**

1. 业务方提 PR 修改 `EVENT_TYPES.md`
2. 后端 review
3. 合并后业务方按规范上报

### 6.5 不在本期范围(明确排除)

- 多赛季历史数据
- 数据看板分享海报
- 7 日曲线点击弹窗
- 升级提醒推送
- 本周 vs 上周对比
- 前端埋点 SDK 实现(只预留后端 HTTP 端点)
- 业务方自定义事件查询 API
- ClickHouse 集成(只预留开关和 events 表设计)
- BI 报表工具集成
- 实时数据流(Flink/Kafka)

---

**文档结束。**