feat: update clustering implementation and docs

docs/02_接口设计文档.md

@@ -64,7 +64,7 @@
 
 - URL：`/api/analysis/importance`
 - 方法：`GET`
-- 参数：`model`，可选
+- 参数：`model`，可选，默认 `random_forest`
 - 说明：返回模型特征重要性排序
 
 ### 3.2 获取相关性矩阵
@@ -88,9 +88,42 @@
 - `marital_status`
 - `chronic_disease`
 
-## 4. 缺勤预测接口
+## 4. `JD-R` 理论分析接口
 
-### 4.1 单次预测
+### 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`
@@ -113,7 +146,10 @@
   "chronic_disease_flag": 0,
   "children_count": 1,
   "industry": "制造业",
-  "marital_status": "已婚"
+  "marital_status": "已婚",
+  "work_autonomy": 3.2,
+  "supervisor_support": 3.5,
+  "self_efficacy": 3.4
 }
 ```
 
@@ -122,50 +158,94 @@
 - `predicted_hours`
 - `risk_level`
 - `risk_label`
+- `risk_probability`
 - `confidence`
 - `model_used`
 - `model_name_cn`
 
-### 4.2 模型对比
+### 5.2 模型对比
 
 - URL：`/api/predict/compare`
 - 方法：`POST`
 - 说明：返回多个模型在同一输入下的预测对比结果
 
-### 4.3 获取模型列表
+### 5.3 获取模型列表
 
 - URL：`/api/predict/models`
 - 方法：`GET`
-- 说明：返回可用模型及其性能指标，包含传统模型与 `LSTM+MLP` 深度学习模型
+- 说明：返回当前可用模型及其性能指标。当前模型接口名包括 `random_forest`、`gradient_boosting`、`extra_trees`、`xgboost` 与 `lstm_mlp`
 
-### 4.4 获取模型信息
+### 5.4 获取模型信息
 
 - URL：`/api/predict/model-info`
 - 方法：`GET`
-- 说明：返回训练样本量、特征数量、训练日期以及深度学习窗口信息
+- 说明：返回训练样本量、特征数量、训练日期和深度学习窗口信息
 
-新增返回字段示例：
+返回字段示例：
 
+- `train_samples`
+- `test_samples`
+- `feature_count`
+- `training_date`
 - `sequence_window_size`
 - `deep_learning_available`
 
-## 5. 员工画像接口
+### 5.5 风险分类
 
-### 5.1 获取聚类结果
+- 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`
 - 说明：返回聚类后的群体列表
 
-### 5.2 获取聚类画像
+### 7.2 获取聚类画像
 
 - URL：`/api/cluster/profile`
 - 方法：`GET`
 - 参数：`n_clusters`
 - 说明：返回雷达图所需的群体画像数据
 
-### 5.3 获取散点数据
+### 7.3 获取散点数据
 
 - URL：`/api/cluster/scatter`
 - 方法：`GET`
@@ -174,9 +254,10 @@
   - `x_axis`
   - `y_axis`
 
-## 6. 错误处理
+## 8. 错误处理
 
 - `400`：请求参数错误
+- `404`：资源或分类模型不可用
 - `500`：服务器内部错误
 
 常见错误场景：
@@ -184,4 +265,5 @@
 - 请求体为空
 - 维度参数非法
 - 模型文件缺失或加载失败
+- `SHAP` 依赖未安装
 - 后端依赖未正确安装