ks-app-employment-service/docs/职业图谱接口说明.md

# 职业图谱功能接口说明

## 📋 目录
- [一、职业路径相关接口](#一职业路径相关接口)
- [二、职业技能相关接口](#二职业技能相关接口)
- [三、职业推荐相关接口](#三职业推荐相关接口)
- [四、接口使用场景](#四接口使用场景)

---

## 一、职业路径相关接口

### 1. `getJobPathPage` - 根据职业名称获取路径列表
- **接口路径**: `/jobPath/getJobPathPage`
- **请求方法**: `GET`
- **接口类型**: `zytp`
- **参数**:
  - `jobName` (可选): 职业名称，用于搜索
  - `pageNo`: 页码
  - `pageSize`: 每页数量
- **返回数据**: 
  ```json
  {
    "code": 0,
    "data": {
      "list": [
        {
          "id": 1,
          "startJobId": 1,
          "startJob": "AI产品经理",
          "endJobId": 1,
          "endJob": "推荐算法",
          "jobOrder": "AI产品经理，AI训练师，图像识别，导航算法，推荐算法",
          "jobCount": 5
        }
      ],
      "total": 16
    }
  }
  ```
- **使用场景**:
  - ✅ **CareerPath.vue**: 获取目标职业选项列表（下拉选择器）
  - ✅ **CareerRecommend.vue**: 通过 `jobName` 查询获取 `jobId`（当缺少 jobId 时）
  - ✅ **CareerPath.vue**: 查询时如果没有 jobPathId，通过 jobName 查找

---

### 2. ``getJobPathById`- 根据职业路径ID获取详情
- **接口路径**: `/jobPath/getJobPathById`
- **请求方法**: `GET`
- **接口类型**: `zytp`
- **参数**:
  - `jobPathId`: 职业路径ID
- **返回数据**: 
  ```json
  {
    "data": [
      {
        "name": "职位名称",
        "skillNameList": "技能1,技能2,技能3"
      }
    ]
  }
  ```
- **使用场景**:
  - ✅ **CareerPath.vue**: 获取职业路径的详细信息（起点、中间步骤、终点及每个职位的技能列表）
  - 用于显示完整的职业发展路径时间线

---

### 3. `getJobPathNum` - 获取职业路径数量
- **接口路径**: `/jobPath/getJobPathNum`
- **请求方法**: `GET`
- **接口类型**: `zytp`
- **参数**: 无
- **返回数据**: 
  ```json
  {
    "data": 16  // 路径总数
  }
  ```
- **使用场景**:
  - ✅ **CareerPath.vue**: 显示"系统已收录 X 条职业路径"

---

## 二、职业技能相关接口

### 4. `getJobSkillDetail` - 获取职位技能详情
- **接口路径**: `/jobSkillDet/getJobSkillDet`
- **请求方法**: `GET`
- **接口类型**: `zytp`
- **参数**:
  - `jobId` (必需): 职位ID
  - `jobName` (可选): 职位名称
- **返回数据**: 
  ```json
  {
    "data": [
      {
        "skillName": "技能名称",
        "skillScore": "技能分数"
      }
    ]
  }
  ```
- **使用场景**:
  - ✅ **career-planning.vue**: 点击推荐职位卡片时，获取该职位的技能详情（用于技能详情弹窗 `SkillDetailPopup`）
  - **调用位置**: `handleJobCardClick` 函数中

---

### 5. `getJobPathSkill` - 获取职业路径技能（已隐藏，暂未使用）
- **接口路径**: `/jobSkillDet/getJobPathSkill`
- **请求方法**: `POST`
- **接口类型**: `zytp`
- **参数**:
  - `pathId`: 路径ID
  - `currentJobName`: 当前职位名称
- **返回数据**: `List<JobSkillDetVO>` (包含技能分数、类型等详细信息)
- **使用场景**: 
  - ❌ 暂未在代码中使用
  - 💡 **潜在使用场景**: 在 `CareerPath.vue` 中，如果用户点击路径中的某个职位，需要查看该职位在路径中的详细技能信息（包含技能分数、类型等）时，可以使用此接口
  - **当前状态**: 接口已注释隐藏，如需使用请取消注释

---

## 三、职业推荐相关接口

### 8. `recommendJob` - 推荐职位
- **接口路径**: `/job/recommendJobByJobName`
- **请求方法**: `GET`
- **接口类型**: `zytp`
- **参数**:
  - `jobName` (必需): 当前职位名称（从缓存中获取），通过 URL 参数传递，格式：`/job/recommendJobByJobName?jobName=职位名称`
- **返回数据**: 
  ```json
  {
    "data": [
      {
        "jobId": 123,
        "jobName": "推荐职位名称",
        "skillList": [
          {
            "skillName": "技能名称"
          }
        ]
      }
    ]
  }
  ```
- **使用场景**:
  - ✅ **CareerRecommend.vue**: 根据当前职位名称（从缓存中获取），获取相似推荐职位列表（显示在"相似推荐职位"区域）

---

## 四、接口使用场景

### 📍 页面结构
```
career-planning.vue (主页面)
├── Tab 0: 职业推荐 (CareerRecommend.vue)
├── Tab 1: 职业路径 (CareerPath.vue)
└── Tab 2: 技能发展 (SkillDevelopment.vue)
```

### 📍 职业推荐 Tab (CareerRecommend.vue)
1. **进入页面时**:
   - `getJobSkillDetail` - 获取当前职位的技能标签（需要 `jobId`，如果没有 `jobId` 则跳过）
   - `recommendJob` - 获取相似推荐职位（需要 `jobId`）

2. **点击职位卡片时**:
   - `getJobSkillDetail` - 获取该职位的技能详情（显示在技能详情弹窗中）

**注意**: `getJobPathPage` 接口**只在职业路径流程中使用**，不在职业推荐流程中使用。

### 📍 职业路径 Tab (CareerPath.vue)
1. **进入页面时**:
   - `getJobPathPage` - 获取所有职业路径列表（填充目标职业下拉选择器）
   - `getJobPathNum` - 获取职业路径总数（显示"系统已收录 X 条职业路径"）

2. **选择目标职业并点击查询时**:
   - `getJobPathPage` - 如果没有 `jobPathId`，通过 `jobName` 查找
   - `getJobPathDetail` (实际: `getJobPathById`) - 获取职业路径详情（显示完整路径时间线）

### 📍 技能发展 Tab (SkillDevelopment.vue)
1. **进入页面时**:
   - 暂无接口调用

---

## 🔑 关键接口调用流程

### 流程1: 获取当前职位技能
```
CareerRecommend.vue
└── getJobSkillDetail(jobId, jobName) → 获取技能列表
    （如果没有 jobId，则跳过获取技能）
```

### 流程2: 查询职业路径
```
CareerPath.vue
├── getJobPathPage() → 获取路径列表（填充下拉选择器）
├── 用户选择目标职业
└── getJobPathById(jobPathId) → 获取路径详情（显示时间线）
```

### 流程3: 获取推荐职位
```
CareerRecommend.vue
└── recommendJob(jobId) → 获取相似推荐职位列表
```

---

## ⚠️ 注意事项

1. **接口返回码**: 
   - `code: 0` 和 `code: 200` 都表示成功
   - 已在 `request.js` 中处理

2. **参数要求**:
   - `getJobSkillDetail` 必须提供 `jobId`，如果没有 `jobId` 则跳过获取技能
   - `getJobPathPage` **只在职业路径流程中使用**，不在职业推荐流程中使用

3. **数据格式**:
   - `getJobPathPage` 返回的 `list` 在 `response.data.list` 中
   - `getJobPathById` 返回的详情在 `response.data` 中（数组格式）

4. **接口使用范围**:
   - `getJobPathPage` **只在职业路径流程（CareerPath.vue）中使用**
   - 职业推荐流程（CareerRecommend.vue）**不使用** `getJobPathPage` 接口

5. **接口前缀**:
   - 所有 `zytp` 类型的接口使用: `http://ks.zhaopinzao8dian.com/api/ks_zytp/admin-api/zytp`