# report-service 统计报表服务

## 服务定位

`report-service` 是总后台统计报表只读服务。第一阶段提供内存 repository 模拟数仓读取，面向 `admin-gateway` 和 `admin-web` 输出经营统计数据，不参与下注、扣款、派彩、结算和注单状态变更。

## 本地命令

```bash
cd /Users/amumu/Desktop/beifen/golang新架构/数据服务/report-service
go test ./...
go build ./cmd/report-service
PORT=8111 go run ./cmd/report-service
```

健康检查：

```bash
curl http://127.0.0.1:8111/health
curl http://127.0.0.1:8111/ready
```

## 第一阶段接口

所有业务接口返回统一结构：

```json
{
  "code": "OK",
  "message": "success",
  "request_id": "req_xxx",
  "data": {}
}
```

### GET /reports/overview

总览统计，支持 `merchant_id`、`game_id`、`start_at`、`end_at`。

```bash
curl "http://127.0.0.1:8111/reports/overview?merchant_id=MERCHANT_DEMO&start_at=2026-06-01T00:00:00Z&end_at=2026-06-02T00:00:00Z"
```

返回字段包含：

- `total_bet_amount`：投注额
- `total_payout`：派彩金额
- `ggr`：平台毛收入，等于投注额减派彩金额
- `bet_count`：注单数
- `player_count`：去重玩家数
- `cache_key` / `cache_status`：缓存命中信息

### GET /reports/merchant

商户维度统计，支持 `start_at`、`end_at`、`limit`、`offset`。结果按 `ggr` 倒序排列后分页。

```bash
curl "http://127.0.0.1:8111/reports/merchant?start_at=2026-06-01T00:00:00Z&end_at=2026-06-02T00:00:00Z&limit=20&offset=0"
```

### GET /reports/games

游戏维度统计，支持 `merchant_id`、`start_at`、`end_at`、`limit`、`offset`。结果按 `ggr` 倒序排列后分页。

```bash
curl "http://127.0.0.1:8111/reports/games?merchant_id=MERCHANT_DEMO&start_at=2026-06-01T00:00:00Z&end_at=2026-06-02T00:00:00Z&limit=20&offset=0"
```

### GET /reports/realtime

实时窗口统计，支持 `merchant_id`、`game_id`、可选 `start_at`、`end_at`。缺省窗口为当前 UTC 时间向前 5 分钟。

```bash
curl "http://127.0.0.1:8111/reports/realtime?merchant_id=MERCHANT_DEMO"
```

## 参数约束

- `start_at` / `end_at` 使用 RFC3339 UTC 时间，例如 `2026-06-01T00:00:00Z`。
- 查询窗口必须满足 `start_at < end_at`。
- 第一阶段单次查询窗口最大 31 天，避免后台大范围查询拖垮服务。
- `limit` 缺省 50，最大 1000。
- `offset` 必须大于等于 0。

## 数仓读取建议

第一阶段代码中的 `internal/repository/memory` 只模拟从数仓读取事实数据。生产建议由 `warehouse-writer` 写入 ClickHouse 后，`report-service` 读取以下类型的只读表：

- 注单事实明细表：按 `merchant_id`、`game_id`、`player_id`、`bet_order_id`、`occurred_at` 保留投注额、派彩金额、注单状态。
- 分钟级聚合表：用于 `/reports/realtime` 和短时间窗总览。
- 小时/天级聚合表：用于总后台常规经营报表。
- 维表快照：商户名称、游戏名称、币种、渠道等展示字段由配置库或维表补齐。

服务边界要求：

- 只读 ClickHouse 或数仓聚合表。
- 不直接读写钱包库、交易库核心余额字段。
- 不修改注单状态，不补写结算结果。
- 跨服务展示字段通过 admin-gateway 聚合或配置维表补齐。

## 缓存策略

第一阶段服务层内置进程内缓存：

- 缓存 key 由报表类型、`merchant_id`、`game_id`、`start_at`、`end_at`、`limit`、`offset` 组成。
- 缓存 TTL 缺省 30 秒，适合总后台高并发重复查询。
- 实时接口建议生产独立设置更短 TTL，例如 3 到 5 秒。
- 分页参数进入 key，避免不同页码误命中。
- 缓存只保存查询结果，不保存任何交易写入意图。

生产建议升级为 Redis/KeyDB 分布式缓存，并按时间窗口粗粒度设置失效策略：实时分钟窗短 TTL，历史小时/天窗长 TTL。

## 与 admin-web / admin-gateway 的关系

`admin-web` 不建议直接访问 `report-service`。推荐链路：

```text
admin-web -> admin-gateway -> report-service -> ClickHouse/数仓
```

`admin-gateway` 负责后台登录态、权限、菜单和操作审计；`report-service` 只负责已授权请求下的统计计算与只读查询。后续 admin-gateway 可按页面权限转发 `/reports/*`，并在网关层补充租户范围、管理员角色和审计日志。