# bridge

> 风控审核数据桥。把上游 1B 运营后台的订单、账变、下注等原始数据同步到 ClickHouse，并按《风控判断所需数据与后台位置清单》提供用户审核快照。只读，不对上游做任何写操作。除 /api/health 外，所有接口需要请求头 X-Api-Key。

Base URL: https://bridge.ws.balltl.cc
Auth: header `X-Api-Key: <key>` on every endpoint except /api/health.
Machine-readable spec: /openapi.json

## Endpoints

### GET /api/risk/users/{userId}/review-snapshot

需求清单 §三 的统一接口。一次返回 20 类数据源，每类带 status（SUCCESS / EMPTY / FAILED / PARTIAL / NOT_CONFIGURED）、上游来源、后台位置、拉取时间；completeness.recommendation_mode 为 AUTO_ALLOWED 或 MANUAL_REVIEW_ONLY（任一核心数据源 FAILED）。默认先对该用户做一次增量同步（60 秒内做过则跳过）再从 ClickHouse 读；库不可用时回退直连上游，data_source 与 meta.warnings 会说明。手机、卡号、IFSC、IP、邮箱在响应中脱敏。

Parameters:
- userId (path, integer, required): 上游用户 ID
- days (query, integer, default 30): 回溯窗口天数，1..180。订单、账变、下注、游戏分布都按此窗口取。
- rows (query, integer, default 1): 1 含明细行，0 只返回汇总（约 40 KB）
- max_rows (query, integer, default 2000): 每类明细列表的上限，最新在前
- sync (query, integer, default 1): 0 跳过读前的增量同步，直接读库
- source (query, string, default clickhouse): live 强制直连上游，不走库

Responses:
- 200: ReviewSnapshot：snapshot_id, user_id, generated_at, data_source, window, completeness, domains, sources
- 400: userId 不是正整数
- 401: 缺少或错误的 X-Api-Key
- 404: 上游没有这个用户
- 502: 上游接口异常
- 503: 服务未配置密钥，或依赖不可用

Example: curl -H 'X-Api-Key: $KEY' 'https://bridge.ws.balltl.cc/api/risk/users/10974/review-snapshot?days=30&rows=0'

### GET /api/risk/withdraw/orders

需求清单 §一 第 1 行「待审提现订单」。返回窗口内的提现订单，并按用户合并出 order_count 与 total_amount。status 枚举尚未获平台确认，outcome 字段按环境变量推断。

Parameters:
- days (query, integer, default 1): 回溯天数，1..32（上游单次查询上限）
- status (query, integer): 按上游 status 数值本地过滤
- user_id (query, integer): 只看某个用户

Responses:
- 200: window, count, truncated, orders[], by_user[]
- 401: 缺少或错误的 X-Api-Key
- 502: 上游接口异常

Example: curl -H 'X-Api-Key: $KEY' 'https://bridge.ws.balltl.cc/api/risk/withdraw/orders?days=1'

### GET /api/health

进程存活、上游登录、ClickHouse 连通。任一失败返回 503。不需要密钥。

Responses:
- 200: { ok: true, upstream, clickhouse, time }
- 503: { ok: false, ... } 并带 error 说明

Example: curl -H 'X-Api-Key: $KEY' 'https://bridge.ws.balltl.cc/api/health'

### GET /api/sync/global

查看全局订单列表、风控日志、支付风控名单的同步游标与上次同步时间（上游时区 UTC+5:30）。

Responses:
- 200: { states: [{ source, scope, cursor, last_synced_at, rows, note }] }
- 503: ClickHouse 未配置

Example: curl -H 'X-Api-Key: $KEY' 'https://bridge.ws.balltl.cc/api/sync/global'

### POST /api/sync/global

拉取全局订单列表（按创建时间游标增量，72 小时重叠）、风控处理日志、支付风控名单。

Parameters:
- backfillDays (query, integer, default 60): 首次运行的回溯天数
- overlapHours (query, integer, default 72): 重叠回拉小时数
- reset (query, integer): 1 忽略游标，按 backfillDays 全量重拉

Responses:
- 200: { ok: true, results[] }
- 207: 部分失败，results[] 内有 error

### GET /api/sync/users/{userId}

该用户各数据源（账变、Gullak、下注等）的游标与上次同步时间。

Parameters:
- userId (path, integer, required): 上游用户 ID

Responses:
- 200: { user_id, states[] }

Example: curl -H 'X-Api-Key: $KEY' 'https://bridge.ws.balltl.cc/api/sync/users/10974'

### POST /api/sync/users/{userId}

拉取该用户的明细、充提、风控订单、账变、Gullak、下注、下级、标签日志。增量按天切块，1 小时重叠。

Parameters:
- userId (path, integer, required): 上游用户 ID
- backfillDays (query, integer, default 60): 首次同步的回溯天数
- force (query, integer): 1 忽略游标全量重拉该用户

Responses:
- 200: { user_id, skipped, synced_at, sources{}, ms }
- 207: 部分步骤失败
- 404: 上游没有这个用户

## Notes for agents

- The snapshot's `completeness.recommendation_mode` is MANUAL_REVIEW_ONLY whenever a core source FAILED; do not treat missing data as evidence.
- Each entry in `sources` carries `status`, `upstream` (endpoints used), `admin_location` (where a human finds it) and `notes` (caveats such as unconfirmed status enums).
- Timestamps inside data are upstream local time (Asia/Kolkata) without offset; `generated_at` and `fetched_at` are ISO-8601 UTC.
- Sensitive fields are masked (`*_masked`); full values are never returned.