# OMS Optimization Tracker

## 状态说明

- `已修正`: 已完成代码或数据层调整。
- `待修正`: 已确认问题，后续继续跟进。
- `暂缓`: 已知问题，但当前优先级较低。

## 已修正

### 1. ClickHouse `events` 表增加按月分区

- 状态: `已修正`
- 背景: 原表无 `PARTITION BY`，`done-rate` 按天统计时会扫描超大范围数据，随着数据量增长容易超时。
- 处理:
  - 已完成 `events -> events_v2 -> rename` 的迁移。
  - 新表使用 `PARTITION BY toYYYYMM(time)`。
  - 已补齐迁移过程中缺失的 `202511` 和 `202605` 数据。
- 结果:
  - 分区剪枝可用于按天/按月统计。
  - TTL 清理效率提升。
  - 为后续统计查询优化打下基础。

### 2. `done-rate` 的 ClickHouse 统计查询合并为 1 条聚合查询

- 状态: `已修正`
- 文件: `services/cron-jobs/done-rate.ts`
- 原问题:
  - 原实现分别对 `color_start`、`color_done`、`color_tip` 发 3 次独立查询。
  - 相同时间范围被重复扫描，成本高。
- 处理:
  - 已改为 1 条聚合查询，使用 `uniqIf` 和 `countIf` 一次返回三类统计结果。
  - 时间边界已修正为 `[day_start, next_day_start)`，避免漏掉当天末尾数据。
  - `DoneRate` 每日落库阶段已从逐条 `createOrUpdate` 改为分批 `bulkWrite upsert`（按 `date + res`），减少 Mongo 写入往返。

### 3. `done-rate` 增加 ClickHouse 查询耗时与结果规模日志

- 状态: `已修正`
- 文件: `services/cron-jobs/done-rate.ts`
- 处理:
  - 增加 ClickHouse 聚合查询耗时日志。
  - 增加返回行数、有效作品数、无效行数、开始用户数、完成用户数、道具使用次数统计日志。
- 目标:
  - 便于线上确认分区和聚合查询优化后的实际收益。

### 4. ClickHouse 分区迁移脚本落库

- 状态: `已修正`
- 文件: `scripts/migrate-clickhouse-events-partition.sh`
- 处理:
  - 支持 Docker 容器内执行 `clickhouse-client`。
  - 支持历史分区回填、cutover、校验、reconcile-only 缺口补齐。
  - 修复了若干脚本问题，包括 shell `eval`、Docker stdin、缺口月份补齐逻辑等。
- 备注:
  - 该脚本可作为后续类似数据迁移的基线脚本继续演进。

## 待修正

### 1. `done-rate` 后半段 Mongo 聚合更新

- 状态: `已修正`
- 文件: `services/cron-jobs/done-rate.ts`
- 原问题:
  - ClickHouse 查询优化后，后半段仍逐条 `findByIdAndUpdate` 更新 `TotalDoneRate`，网络往返与写入放大明显。
- 处理:
  - 已改为分批 `bulkWrite`（`TOTAL_DONE_RATE_BULK_SIZE=1000`）覆盖更新 + `upsert`。
  - 增加阶段性日志，拆分为：
    - `DoneRateModel.aggregate` 聚合耗时
    - `TotalDoneRate.bulkWrite` 写入耗时与批次进度
- 结果:
  - 显著减少逐条更新带来的 Mongo 往返开销。
  - 后续可更准确判断瓶颈位于聚合阶段还是写入阶段。

### 2. `ingestor-service` 先 `ack` 后 flush，存在小窗口数据丢失风险

- 状态: `待修正`
- 文件: `services/ingestor-service.ts`
- 现状:
  - 消息进入内存 buffer 后即 `ack`。
  - 如果进程在 flush 到 ClickHouse 或 MongoDB 前崩溃，这批消息会丢失。
- 当前取舍:
  - 业务上允许少量埋点丢失，因此暂不优先处理。
- 后续可选方向:
  - 缩短 flush 间隔。
  - 在关键批次上改为 flush 成功后再 `ack`。
  - 引入失败补偿或轻量级死信策略。

### 3. ClickHouse `raw_json_data` 存储成本较高

- 状态: `待修正`
- 文件: `src/services/clickhouseService.ts`
- 现状:
  - 每条事件完整保存原始 JSON。
  - 同时系统已有 `log-service` 将原始日志写入文件，存在冗余。
- 风险:
  - 长期占用大量磁盘。
  - 增加 merge、备份、迁移成本。
- 后续可选方向:
  - 仅保留结构化字段。
  - 对 `raw_json_data` 做抽样保留。
  - 只在日志文件中保留完整原文。

### 4. `event-api-service` 缺少限流与更明确的背压策略

- 状态: `待修正`
- 文件: `services/event-api-service.ts`
- 现状:
  - 接口没有基础 rate limit。
  - RabbitMQ publish buffer 满时仅返回 `503`，没有更系统的保护策略。
- 风险:
  - 恶意流量或异常流量可能放大队列和下游压力。
- 后续可选方向:
  - 增加基础限流中间件。
  - 区分客户端错误与系统拥塞。
  - 评估本地丢弃、采样或重试策略。

### 6. 消息统计接口超时（Phase 1 执行中）

- 状态: `待修正`
- 阶段: `Phase 1 进行中`
- 文件:
  - `src/controllers/messageRecordController.ts`
  - `src/services/messageRecordService.ts`
  - `src/models/messageRecordModel.ts`
  - `omsapp/src/app/pages/message-dashboard.component.ts`
- 背景:
  - `api/message/statistics/overall`
  - `api/message/statistics/daily-trends`
  - `api/message/statistics/by-strategy`
  - 等接口在大时间窗口下易超时。
- 当前阶段目标:
  - 核心统计接口 p95 <= 2 秒。
  - 首屏加载不触发所有重接口。
  - 预聚合放在 Phase 1.5。
- 本轮已落地:
  - 聚合查询统一增加 `allowDiskUse(true)`。
  - 维度统计接口新增分页参数（page/limit）并启用安全上限。
  - controller 增加日期范围上限校验和统一错误响应（`RANGE_TOO_LARGE`）。
  - controller 增加结构化统计日志（请求范围、耗时、结果规模、错误信息）。
  - 核心接口（`overall`、`daily-trends`、`by-strategy`）接入 Redis 缓存（TTL 300s）并输出命中日志。
  - 新增汇总接口 `api/message/statistics/summary`，首屏合并返回 overall + daily-trends + by-strategy（默认分页）。
  - 前端首屏加载改为优先请求 `summary`，减少首屏多接口并发重查询。
  - `api/message-records` 列表查询在无筛选场景改为 `estimatedDocumentCount`（替代全量 `countDocuments`），并增加排序白名单与 `lean()` 返回，缓解千万级数据下列表超时。
  - 修复 `summary` 慢查询：将统计去重从 `$addToSet(uid)` 改为分层聚合去重计数（避免大数组内存压力），并为 `summary` 增加默认近7天时间窗与前端同参请求去重。
  - 新增统计接口分层耗时日志：`summary` 子查询耗时（overall/daily-trends/by-strategy）与核心聚合耗时（statistics-by-group/daily-trends/multi-dimensional）及结果规模。
- 下一步:
  - 增加缓存失效策略与命中率监控（Phase 1）。
  - 补充 summary 与各维度接口的基准压测数据（Phase 1）。
  - 预聚合数据源切换（Phase 1.5）。

### 5. 配置与凭证仍混在代码和部署配置中

- 状态: `待修正`
- 文件:
  - `ecosystem.config.js`
  - `docker-compose.yml`
  - `docker-compose.prod.yml`
  - 部分 service 文件中的默认连接串
- 现状:
  - 仓库中仍存在明文凭证和默认连接串。
  - 运行时配置分散，后续维护和切环境成本高。
- 后续可选方向:
  - 统一改为 `.env` 或部署平台环境变量管理。
  - 清理代码中的真实凭证 fallback。
  - 为生产和开发环境建立更清晰的配置边界。

## 暂缓

### 1. `ingestor-service` 的严格不丢数改造

- 状态: `暂缓`
- 原因:
  - 当前业务接受少量埋点丢失。
  - 与 `done-rate` 和 ClickHouse 性能问题相比，优先级较低。

## 下一步建议

1. 先在线上执行一次 `done-rate`，观察新增的 ClickHouse 耗时日志。
2. 如果 ClickHouse 已明显变快，再评估 `TotalDoneRate` 的 Mongo 聚合更新是否成为新瓶颈。
3. 若后续继续做性能治理，优先处理 `done-rate` 的 Mongo 批量更新。
