# 接口设计文档

## 1. 接口说明

- 接口风格：REST 风格
- 数据格式：JSON
- 公共前缀：`/api`

统一返回结构：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

## 2. 数据概览接口

### 2.1 获取基础统计

- URL：`/api/overview/stats`
- 方法：`GET`
- 说明：返回缺勤事件总量、员工覆盖数、平均缺勤时长等指标

返回字段示例：

- `total_records`
- `total_employees`
- `avg_absent_hours`
- `max_absent_hours`
- `min_absent_hours`
- `high_risk_ratio`
- `industries_covered`

### 2.2 获取月度趋势

- URL：`/api/overview/trend`
- 方法：`GET`
- 说明：返回月度总缺勤时长、平均时长和记录数

### 2.3 获取星期分布

- URL：`/api/overview/weekday`
- 方法：`GET`
- 说明：返回星期维度分布统计

### 2.4 获取原因分布

- URL：`/api/overview/reasons`
- 方法：`GET`
- 说明：返回请假原因大类分布

### 2.5 获取季节分布

- URL：`/api/overview/seasons`
- 方法：`GET`
- 说明：返回季节维度缺勤统计

## 3. 影响因素分析接口

### 3.1 获取特征重要性

- URL：`/api/analysis/importance`
- 方法：`GET`
- 参数：`model`，可选
- 说明：返回模型特征重要性排序

### 3.2 获取相关性矩阵

- URL：`/api/analysis/correlation`
- 方法：`GET`
- 说明：返回关键变量相关性矩阵

### 3.3 获取群体对比

- URL：`/api/analysis/compare`
- 方法：`GET`
- 参数：`dimension`
- 说明：返回指定维度下的群体平均缺勤时长对比

支持维度：

- `industry`
- `shift_type`
- `job_family`
- `marital_status`
- `chronic_disease`

## 4. 缺勤预测接口

### 4.1 单次预测

- URL：`/api/predict/single`
- 方法：`POST`
- 说明：输入核心字段，返回预测缺勤时长与风险等级

请求体示例：

```json
{
  "leave_type": "病假",
  "leave_reason_category": "身体不适",
  "absence_month": 5,
  "weekday": 2,
  "near_holiday_flag": 0,
  "medical_certificate_flag": 1,
  "shift_type": "标准白班",
  "is_night_shift": 0,
  "monthly_overtime_hours": 26,
  "commute_minutes": 42,
  "chronic_disease_flag": 0,
  "children_count": 1,
  "industry": "制造业",
  "marital_status": "已婚"
}
```

返回字段：

- `predicted_hours`
- `risk_level`
- `risk_label`
- `confidence`
- `model_used`
- `model_name_cn`

### 4.2 模型对比

- URL：`/api/predict/compare`
- 方法：`POST`
- 说明：返回多个模型在同一输入下的预测对比结果

### 4.3 获取模型列表

- URL：`/api/predict/models`
- 方法：`GET`
- 说明：返回可用模型及其性能指标

### 4.4 获取模型信息

- URL：`/api/predict/model-info`
- 方法：`GET`
- 说明：返回训练样本量、特征数量和训练日期

## 5. 员工画像接口

### 5.1 获取聚类结果

- URL：`/api/cluster/result`
- 方法：`GET`
- 参数：`n_clusters`
- 说明：返回聚类后的群体列表

### 5.2 获取聚类画像

- URL：`/api/cluster/profile`
- 方法：`GET`
- 参数：`n_clusters`
- 说明：返回雷达图所需的群体画像数据

### 5.3 获取散点数据

- URL：`/api/cluster/scatter`
- 方法：`GET`
- 参数：
  - `n_clusters`
  - `x_axis`
  - `y_axis`

## 6. 错误处理

- `400`：请求参数错误
- `500`：服务器内部错误

常见错误场景：

- 请求体为空
- 维度参数非法
- 模型文件缺失或加载失败
- 后端依赖未正确安装