llm-intelligence/docs/API_REFERENCE.md

# API 参考

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

## 通用约定

- 基础地址：`http://<host>:<port>`
- 默认端口：`8080`
- 返回格式：成功接口统一返回 `{ "data": ... }`
- 失败格式：当前直接返回纯文本错误信息，不是统一 JSON 错误结构
- 鉴权：当前仓库未内建认证、鉴权与限流；公网暴露前应由网关或反向代理补齐

## `GET /health`

检查数据库连通性。

### 成功

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

### 失败

- `503 database not configured`：未配置 `DATABASE_URL`
- `503 database unavailable`：数据库 Ping 失败

### 示例

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

## `GET /api/v1/models`

返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing` 当前最新价格快照。

### 返回体

```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`

## `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`

## `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`

## `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`：元数据存在，但落盘文件缺失

## `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`

## 冒烟检查命令

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

## 生产暴露建议

- 在 Nginx / 网关上补齐访问控制、速率限制和超时配置
- `/health` 仅暴露给负载均衡器和监控系统
- 如果前端与 API 同域部署，优先由 Nginx 转发 `/api/` 和 `/health`
- 如果需要公网访问，建议至少加一层 Basic Auth、OIDC 或内网入口限制