5.5 KiB
5.5 KiB
接口设计文档
1. 接口说明
- 接口风格：REST 风格
- 数据格式：JSON
- 公共前缀：
/api
统一返回结构：
{
"code": 200,
"message": "success",
"data": {}
}
2. 数据概览接口
2.1 获取基础统计
- URL：
/api/overview/stats - 方法：
GET - 说明：返回缺勤事件总量、员工覆盖数、平均缺勤时长等指标
返回字段示例：
total_recordstotal_employeesavg_absent_hoursmax_absent_hoursmin_absent_hourshigh_risk_ratioindustries_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 - 说明：返回指定维度下的群体平均缺勤时长对比
支持维度：
industryshift_typejob_familymarital_statuschronic_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 - 说明：输入核心字段，返回预测缺勤时长与风险等级
请求体示例：
{
"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_hoursrisk_levelrisk_labelrisk_probabilityconfidencemodel_usedmodel_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_samplestest_samplesfeature_counttraining_datesequence_window_sizedeep_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 - 参数：
modeltop_n
- 说明：返回近似特征交互强度前
N项
6.4 获取依赖关系
- URL：
/api/shap/dependence - 方法：
GET - 参数：
featuremodel
- 说明：返回指定特征的取值与
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_clustersx_axisy_axis
8. 错误处理
400：请求参数错误404：资源或分类模型不可用500：服务器内部错误
常见错误场景：
- 请求体为空
- 维度参数非法
- 模型文件缺失或加载失败
SHAP依赖未安装- 后端依赖未正确安装