REST API 规范 (Frontend/Backend)

1. 基本约定

• Base URL: /api/v1
• Content-Type: application/json
• 认证：Authorization: Bearer <token>
• 分页：page、page_size

2. 通用响应结构

{ "code": 0, "message": "ok", "data": {}, "request_id": "r-123" }

3. 通用错误码

• 40001 参数错误
• 40101 未认证/Token 失效
• 40301 权限不足
• 40401 资源不存在
• 50001 服务错误

4. 认证 Auth

POST /auth/login

Request:

{ "username": "user", "password": "***" }

Response:

{ "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:

{
  "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:

{ "org_id": "o-1", "org_name": "XX建设集团", "win_rate": 0.23 }

7. 分析 Analytics

GET /analytics/summary

Response:

{ "tender_count": 12000, "total_amount": 980000000 }

GET /analytics/region-heatmap

Response:

[ {"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:

{ "keywords": ["轨道交通"], "regions": ["110000"], "channels": ["email"] }

GET /subscriptions

9. 数据源 Sources (Admin)

GET /sources

POST /sources

PATCH /sources/{id}

10. 导出 Export

POST /exports

Request:

{ "type": "projects", "filters": {"region": "110000"} }