commit 540935ed47637a324b35b0599e0a5d4a289e7aca Author: bid-docs <bid-docs@localhost> Date: 2026-01-21T11:08:50+08:00 Initialize docs and viewer diff --git a/docs/10-rest-api-spec.md b/docs/10-rest-api-spec.md new file mode 100644 index 0000000..a2214be --- /dev/null +++ b/docs/10-rest-api-spec.md @@ -0,0 +1,105 @@ +# REST API 规范 (Frontend/Backend) + +## 1. 基本约定 +- Base URL: `/api/v1` +- Content-Type: `application/json` +- 认证：`Authorization: Bearer <token>` +- 分页：`page`、`page_size` + +## 2. 通用响应结构 +```json +{ "code": 0, "message": "ok", "data": {}, "request_id": "r-123" } +``` + +## 3. 通用错误码 +- `40001` 参数错误 +- `40101` 未认证/Token 失效 +- `40301` 权限不足 +- `40401` 资源不存在 +- `50001` 服务错误 + +## 4. 认证 Auth +### POST /auth/login +Request: +```json +{ "username": "user", "password": "***" } +``` +Response: +```json +{ "token": "jwt-token", "expires_in": 3600 } +``` + +## 5. 项目与公告 Projects/Notices +### GET /projects +Query: `keyword, region, industry, min_amount, max_amount, date_from, date_to, sort` + +### GET /projects/{id} +Response: +```json +{ + "project_id": "p-123", + "project_name": "某市轨道交通项目", + "stage": "award", + "region_code": "110000", + "notices": ["n-1", "n-2"], + "tenders": ["t-1"] +} +``` + +### GET /notices +Query: `type, source, region, date_from, date_to` + +### GET /tenders +### GET /awards +### GET /contracts + +## 6. 组织与企业 Organizations +### GET /organizations +Query: `keyword, org_type, region` + +### GET /organizations/{id}/profile +Response: +```json +{ "org_id": "o-1", "org_name": "XX建设集团", "win_rate": 0.23 } +``` + +## 7. 分析 Analytics +### GET /analytics/summary +Response: +```json +{ "tender_count": 12000, "total_amount": 980000000 } +``` + +### GET /analytics/region-heatmap +Response: +```json +[ {"region_code":"110000","count":1200} ] +``` + +### GET /analytics/competitors +Query: `org_id, industry, date_from, date_to` + +### GET /analytics/trends +Query: `dimension=industry|region, interval=month|quarter` + +## 8. 订阅 Subscriptions +### POST /subscriptions +Request: +```json +{ "keywords": ["轨道交通"], "regions": ["110000"], "channels": ["email"] } +``` + +### GET /subscriptions + +## 9. 数据源 Sources (Admin) +### GET /sources +### POST /sources +### PATCH /sources/{id} + +## 10. 导出 Export +### POST /exports +Request: +```json +{ "type": "projects", "filters": {"region": "110000"} } +``` +