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