# 文档 REST API (Docs REST API)

> 说明：API 用于标准化获取文档列表、内容、历史与迭代信息。

## 1. 认证
- Header：`Authorization: Bearer <BID_API_TOKEN>`
- 备用 Header：`X-API-Key: <BID_API_TOKEN>`
## 1.1 Token 来源
- `.env` 文件中的 `BID_API_TOKEN`
## 1.2 登录获取 Token
`POST /api/auth/login`

Body:
```json
{ "username": "admin", "password": "whoami139" }
```

Response:
```json
{ "code": 0, "message": "ok", "data": { "username": "admin", "token": "<BID_API_TOKEN>" } }
```

`GET /api/auth/me`（需要 Token）

## 2. 基础路径
- 线上：`https://bid.hao.work/docs/api/`
- 本地：`http://127.0.0.1:8090/api/`
- 时间：所有时间字段均为 UTC+8（如 `2026-01-21 10:49:28 +08:00` 或 RFC3339）

## 3. 接口清单
### 3.1 获取文档列表
`GET /api/docs`（需要 Token）

Response:
```json
{ "code": 0, "message": "ok", "data": [{"path":"01-product-requirements.md","updated_time":"2026-01-21 10:45:00 +08:00"}] }
```

### 3.2 获取文档内容
`GET /api/docs/content?path=01-product-requirements.md`

可选渲染 HTML：`render=1`

### 3.3 获取文档历史
`GET /api/docs/history?path=01-product-requirements.md`

### 3.4 获取文档差异
`GET /api/docs/diff?path=01-product-requirements.md&hash=<commit>`

### 3.4.1 文档增删改（需要 Token）
- `POST /api/docs`
- `PUT /api/docs`
- `DELETE /api/docs?path=<file>`

POST/PUT Body 示例：
```json
{ "path": "99-new-doc.md", "content": "# New Doc\n\n内容..." }
```

### 3.5 迭代信息
- `GET /api/iterations`
- `POST /api/iterations`

POST Body 示例：
```json
{
  "version": "v0.1.1",
  "title": "需求完善",
  "summary": "补充数据源与API说明",
  "docs": ["04-data-sources-catalog.md", "10-rest-api-spec.md"],
  "author": "admin"
}
```

### 3.6 创意笔记 (Notes)（需要 Token）
- `GET /api/notes`
- `POST /api/notes`
- `DELETE /api/notes?id=<note_id>`

POST Body 示例：
```json
{
  "title": "竞品分析新方向",
  "content": "考虑增加区域热力与胜率联动分析。",
  "tags": ["analysis", "idea"],
  "author": "admin"
}
```

### 3.7 自动化监控
- `GET /api/automation/status`

## 4. 错误码
- `40101` 未认证或 Token 错误
- `40001` 参数错误
- `40901` 资源冲突（已存在）
- `40401` 资源不存在
- `50001` 服务错误