api-endpoint-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Endpoint Design

REST API design specifications for vehicle insurance data analysis platform.

**Key Files**:
- [backend/api_server.py](../../backend/api_server.py) - Flask API server
- [frontend/src/services/api.js](../../frontend/src/services/api.js) - Frontend API client

**Related Docs**:
- See [TESTING_TEMPLATE.md](../testing-and-debugging/TESTING_TEMPLATE.md) for unit test templates
- See [COMMON_ISSUES.md](../testing-and-debugging/COMMON_ISSUES.md) for troubleshooting

---

## 📚 一、API 端点清单

### 概览表格

| 端点 | 方法 | 功能 | 优先级 |
|------|------|------|--------|
| `/api/health` | GET | 健康检查 | P0 |
| `/api/latest-date` | GET | 获取最新日期 | P0 |
| `/api/refresh` | POST | 刷新数据 | P0 |
| `/api/filter-options` | GET | 获取筛选选项 | P0 |
| `/api/kpi-windows` | POST | KPI 三口径数据 | P0 |
| `/api/week-comparison` | POST | 周对比图表数据 | P0 |
| `/api/insurance-type-distribution` | POST | 险别组合占比 | P0 |
| `/api/premium-range-distribution` | POST | 业务员保费区间占比 | P0 |
| `/api/renewal-type-distribution` | POST | 新转续占比 | P0 |
| `/api/policy-mapping` | GET | 保单映射信息 | P1 |
| `/api/staff-performance-distribution` | POST | 业务员业绩分布 | P1 |

---

### 1.1 `/api/health` - 健康检查

**位置**: [api_server.py:114-120](../../backend/api_server.py#L114-L120)

**请求**:
```http
GET /api/health
```

**响应**:
```json
{
  "status": "healthy",
  "message": "API服务运行正常"
}
```

**测试示例**:
```bash
curl http://localhost:5001/api/health
```

---

### 1.2 `/api/latest-date` - 获取最新日期

**位置**: [api_server.py:96-111](../../backend/api_server.py#L96-L111)

**响应**:
```json
{
  "success": true,
  "latest_date": "2025-11-08"
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "获取最新日期失败: 未找到数据文件"
}
```

**测试示例**:
```bash
curl http://localhost:5001/api/latest-date
```

---

### 1.3 `/api/refresh` - 刷新数据

**位置**: [api_server.py:21-37](../../backend/api_server.py#L21-L37)

**请求**: `POST /api/refresh`

**响应**:
```json
{
  "success": true,
  "message": "数据刷新成功",
  "latest_date": "2025-11-08"
}
```

**注意事项**:
- ⚠️ 此操作较耗时(大文件可能 10-30 秒)
- ⚠️ 前端应显示加载状态
- ⚠️ 建议设置 60 秒超时

**测试示例**:
```bash
curl -X POST http://localhost:5001/api/refresh
```

---

### 1.4 `/api/filter-options` - 获取筛选选项

**位置**: [api_server.py:123-138](../../backend/api_server.py#L123-L138)

**响应**:
```json
{

From FDU-INS/Insurance-Skills, Apache-2.0.

More from FDU-INS/Insurance-Skills