llm-intelligence/docs/API_REFERENCE.md

# API 参考

当前服务端入口位于 `cmd/server/main.go`，只暴露只读查询接口与健康检查接口。

## 通用约定

- 基础地址：`http://<host>:<port>`
- 默认端口：`8080`
- 返回格式：成功接口统一返回 `{ "data": ... }`
- 失败格式：失败接口统一返回 `{ "error": { "code": "...", "message": "..." } }`
- 访问控制：`/health` 仅允许本机或私网访问；`/api/*` 对外访问默认要求 `Authorization: Bearer <token>` 或 Basic Auth，详见下文
- 限流：`/api/*` 默认按来源 IP 做窗口限流；可通过 `API_RATE_LIMIT_PER_WINDOW` 与 `API_RATE_LIMIT_WINDOW_SEC` 调整


## `GET /health`

检查数据库连通性。

### 成功

```json
{
  "status": "ok"
}
```

### 失败

```json
{
  "error": {
    "code": "database_not_configured",
    "message": "database not configured"
  }
}
```

- `503 database_not_configured`：未配置 `DATABASE_URL`
- `503 database_unavailable`：数据库 Ping 失败
### 示例

```bash
curl -fsS http://127.0.0.1:8080/health
```

### 访问控制
- 仅允许本机或私网请求；外部地址返回 `403 health_endpoint_internal_only`


## `GET /api/v1/models`

返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing`；当同一模型存在多条价格记录时，API 按“`global` 区域优先、`official` > `reseller` > `free_tier`、再按 `effective_date`/`id` 倒序”的规则选取主价格。

### 返回体

```json
{
  "data": [
    {
      "id": "openai/gpt-4o",
      "name": "gpt-4o",
      "provider": "OpenAI",
      "providerCN": "OpenAI",
      "modality": "text",
      "contextLength": 128000,
      "pricingMode": "input_output",
      "priceUnit": "million_tokens",
      "inputPrice": 2.5,
      "outputPrice": 10,
      "currency": "USD",
      "isFree": false,
      "stale": false,
      "dataConfidence": "official"
    }
  ]
}
```

### 字段说明

| 字段 | 说明 |
|------|------|
| `id` | 模型外部 ID，通常是 `provider/model` |
| `name` | 模型名称；为空时回退为 `external_id` |
| `provider` | 英文厂商名 |
| `providerCN` | 中文厂商名；缺失时回退为英文名或 `external_id` 前缀 |
| `modality` | 模态类型 |
| `contextLength` | 上下文窗口 |
| `pricingMode` | 定价模式：`input_output`（默认，按输入/输出 token）或 `flat`（按字符/秒等单一单位） |
| `priceUnit` | 价格单位；默认 `million_tokens`，语音类可能是 `10k_characters` / `second` |
| `flatPrice` | `pricingMode=flat` 时的统一单价 |
| `inputPrice` | 输入价格，单位与 `currency` 配套，默认按每百万 token |
| `outputPrice` | 输出价格 |
| `currency` | 币种 |
| `isFree` | 是否免费 |
| `stale` | 是否陈旧数据，当前由 `dataConfidence == "stale"` 推导 |
| `dataConfidence` | 数据置信度 |

### 失败

- `503 database_not_configured`
- `500 query_failed`
- `401 auth_required`
- `429 rate_limited`

## `GET /api/v1/subscription-plans`

返回订阅型套餐列表，当前主要对应腾讯云套餐数据。

### 返回体

```json
{
  "data": [
    {
      "planFamily": "token_plan",
      "planCode": "token-plan-lite",
      "planName": "通用 Token Plan Lite",
      "tier": "Lite",
      "provider": "Tencent",
      "providerCN": "腾讯",
      "operator": "Tencent Cloud",
      "operatorCN": "腾讯云",
      "currency": "CNY",
      "listPrice": 39,
      "priceUnit": "CNY/month",
      "quotaValue": 35000000,
      "quotaUnit": "tokens/month",
      "contextWindow": 0,
      "modelScope": ["tc-code-latest", "glm-5", "glm-5.1"],
      "sourceUrl": "https://cloud.tencent.com/document/product/1823/130060",
      "publishedAt": "2026-04-27T00:00:00",
      "effectiveDate": "2026-04-27"
    }
  ]
}
```

### 失败

- `503 database_not_configured`
- `500 query_failed`
- `401 auth_required`
- `429 rate_limited`

## `GET /api/v1/reports/latest`

返回最新“正式日报”元数据。查询条件来自 `daily_report`：

- `status = 'generated'`
- `output_path` 非空
- `is_official_daily = true`

### 返回体

```json
{
  "data": {
    "reportDate": "2026-05-13",
    "status": "generated",
    "modelCount": 504,
    "summaryMD": "runtime_audit ...",
    "markdownPath": "reports/daily/daily_report_2026-05-13.md",
    "htmlPath": "reports/daily/html/daily_report_2026-05-13.html",
    "archiveMarkdownPath": "reports/daily/2026/05/daily_report_2026-05-13.md",
    "archiveHtmlPath": "reports/daily/2026/05/daily_report_2026-05-13.html",
    "markdownUrl": "/api/v1/reports/latest/markdown",
    "htmlUrl": "/api/v1/reports/latest/html",
    "updatedAt": "2026-05-13T08:00:00"
  }
}
```

### 失败

- `503 database_not_configured`
- `404 latest_report_not_found`
- `500 query_failed`
- `401 auth_required`
- `429 rate_limited`


## `GET /api/v1/reports/latest/markdown`

直接返回最新正式日报的 Markdown 文件内容。

### 成功

- `200`
- `Content-Type: text/markdown; charset=utf-8`

### 失败

- `404 latest_report_not_found`：数据库中没有符合条件的正式日报
- `404 report_artifact_not_found`：元数据存在，但落盘文件缺失
- `401 auth_required`
- `429 rate_limited`

## `GET /api/v1/reports/latest/html`

直接返回最新正式日报 HTML 文件内容。

### 成功

- `200`
- `Content-Type: text/html; charset=utf-8`

### 失败

- `404 latest_report_not_found`
- `404 report_artifact_not_found`
- `401 auth_required`
- `429 rate_limited`


## 冒烟检查命令

```bash
curl -fsS http://127.0.0.1:8080/health
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/models | jq '.data | length'
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html
```


- 在公网暴露时至少配置 `API_AUTH_TOKEN` 或 `API_BASIC_AUTH_USER` / `API_BASIC_AUTH_PASS`
- `/health` 仅暴露给负载均衡器、监控系统或私网来源
- 如果前端与 API 同域部署，优先由 Nginx 转发 `/api/` 和 `/health`
- 如需更强控制，继续在 Nginx / 网关上补齐 CIDR 白名单、OIDC、WAF 与更细粒度限流