270 lines
5.5 KiB
Markdown
270 lines
5.5 KiB
Markdown
# 接口设计文档
|
||
|
||
## 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`，可选，默认 `random_forest`
|
||
- 说明：返回模型特征重要性排序
|
||
|
||
### 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. `JD-R` 理论分析接口
|
||
|
||
### 4.1 获取三维度分布
|
||
|
||
- URL：`/api/jdr/dimensions`
|
||
- 方法：`GET`
|
||
- 说明：返回工作要求、工作资源、个人资源与 `JD-R` 平衡度统计结果
|
||
|
||
### 4.2 获取倦怠与投入分析
|
||
|
||
- URL：`/api/jdr/burnout-engagement`
|
||
- 方法：`GET`
|
||
- 说明：返回工作倦怠、工作投入分布及其与缺勤时长的关联指标
|
||
|
||
### 4.3 获取双路径分析
|
||
|
||
- URL：`/api/jdr/path-analysis`
|
||
- 方法：`GET`
|
||
- 说明：返回健康损伤路径与激励路径的相关分析结果
|
||
|
||
### 4.4 获取分组画像
|
||
|
||
- URL：`/api/jdr/profile`
|
||
- 方法：`GET`
|
||
- 参数：`dimension`，可选，默认 `所属行业`
|
||
- 说明：返回按指定维度分组后的 `JD-R` 画像
|
||
|
||
### 4.5 获取风险分布
|
||
|
||
- URL：`/api/jdr/risk-distribution`
|
||
- 方法：`GET`
|
||
- 说明：返回低、中、高风险事件分布
|
||
|
||
## 5. 缺勤预测接口
|
||
|
||
### 5.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": "已婚",
|
||
"work_autonomy": 3.2,
|
||
"supervisor_support": 3.5,
|
||
"self_efficacy": 3.4
|
||
}
|
||
```
|
||
|
||
返回字段：
|
||
|
||
- `predicted_hours`
|
||
- `risk_level`
|
||
- `risk_label`
|
||
- `risk_probability`
|
||
- `confidence`
|
||
- `model_used`
|
||
- `model_name_cn`
|
||
|
||
### 5.2 模型对比
|
||
|
||
- URL：`/api/predict/compare`
|
||
- 方法：`POST`
|
||
- 说明：返回多个模型在同一输入下的预测对比结果
|
||
|
||
### 5.3 获取模型列表
|
||
|
||
- URL：`/api/predict/models`
|
||
- 方法：`GET`
|
||
- 说明：返回当前可用模型及其性能指标。当前模型接口名包括 `random_forest`、`gradient_boosting`、`extra_trees`、`xgboost` 与 `lstm_mlp`
|
||
|
||
### 5.4 获取模型信息
|
||
|
||
- URL：`/api/predict/model-info`
|
||
- 方法：`GET`
|
||
- 说明：返回训练样本量、特征数量、训练日期和深度学习窗口信息
|
||
|
||
返回字段示例：
|
||
|
||
- `train_samples`
|
||
- `test_samples`
|
||
- `feature_count`
|
||
- `training_date`
|
||
- `sequence_window_size`
|
||
- `deep_learning_available`
|
||
|
||
### 5.5 风险分类
|
||
|
||
- URL：`/api/predict/risk-classify`
|
||
- 方法：`POST`
|
||
- 说明：使用分类器直接返回风险等级与概率分布
|
||
|
||
## 6. `SHAP` 可解释分析接口
|
||
|
||
### 6.1 获取全局解释
|
||
|
||
- URL：`/api/shap/global`
|
||
- 方法：`GET`
|
||
- 参数：`model`，可选，默认 `random_forest`
|
||
- 说明：返回全局特征重要性及其在 `JD-R` 维度上的聚合结果
|
||
|
||
### 6.2 获取局部解释
|
||
|
||
- URL：`/api/shap/local`
|
||
- 方法：`POST`
|
||
- 说明：返回单次预测样本的局部特征贡献及维度贡献
|
||
|
||
### 6.3 获取交互强度
|
||
|
||
- URL：`/api/shap/interaction`
|
||
- 方法：`GET`
|
||
- 参数：
|
||
- `model`
|
||
- `top_n`
|
||
- 说明：返回近似特征交互强度前 `N` 项
|
||
|
||
### 6.4 获取依赖关系
|
||
|
||
- URL：`/api/shap/dependence`
|
||
- 方法：`GET`
|
||
- 参数：
|
||
- `feature`
|
||
- `model`
|
||
- 说明：返回指定特征的取值与 `SHAP` 值关系
|
||
|
||
## 7. 员工画像接口
|
||
|
||
### 7.1 获取聚类结果
|
||
|
||
- URL：`/api/cluster/result`
|
||
- 方法：`GET`
|
||
- 参数：`n_clusters`
|
||
- 说明：返回聚类后的群体列表
|
||
|
||
### 7.2 获取聚类画像
|
||
|
||
- URL：`/api/cluster/profile`
|
||
- 方法：`GET`
|
||
- 参数：`n_clusters`
|
||
- 说明：返回雷达图所需的群体画像数据
|
||
|
||
### 7.3 获取散点数据
|
||
|
||
- URL：`/api/cluster/scatter`
|
||
- 方法：`GET`
|
||
- 参数：
|
||
- `n_clusters`
|
||
- `x_axis`
|
||
- `y_axis`
|
||
|
||
## 8. 错误处理
|
||
|
||
- `400`：请求参数错误
|
||
- `404`：资源或分类模型不可用
|
||
- `500`：服务器内部错误
|
||
|
||
常见错误场景：
|
||
|
||
- 请求体为空
|
||
- 维度参数非法
|
||
- 模型文件缺失或加载失败
|
||
- `SHAP` 依赖未安装
|
||
- 后端依赖未正确安装
|