pwklppg
1 month ago
4 changed files with 1030 additions and 1 deletions
@ -0,0 +1,275 @@ |
|||
# 行业技能词云、个人匹配度与学习路径 API |
|||
|
|||
> 版本：N03 设计锁定版 |
|||
> 状态：已编码实现 |
|||
> 适用范围：学生端只读接口。本文描述 `GET /api/v1/skills/word-cloud`、`GET /api/v1/skills/match`、`GET /api/v1/skills/learning-path`。 |
|||
> Base URL：`http://127.0.0.1:8080/api/v1`（生产环境替换域名，路径不变）。 |
|||
|
|||
## 1. 权限与共同参数 |
|||
|
|||
三个接口均： |
|||
|
|||
- 仅允许 `STUDENT` 访问。 |
|||
- 必须携带 `Authorization: Bearer <accessToken>`，身份只从 JWT/SecurityContext 获取，不接受 `userId`、`studentId` 等身份注入参数。 |
|||
- 使用统一 `ApiResponse` 包装结构。 |
|||
- 只读，不写入学习进度、学生资料或词库数据。 |
|||
|
|||
查询参数： |
|||
|
|||
| 参数 | 类型 | 必填 | 说明 | |
|||
|---|---|---|---| |
|||
| `industryId` | long | 是 | 词库行业 ID，必须为正整数，且必须是真实存在的行业。 | |
|||
| `occupationId` | long | 是 | 词库职位 ID，必须为正整数，且必须属于该行业。 | |
|||
| `categoryId` | long | 否 | 技能分类 ID，必须为正整数；省略时使用该职位下全部技能分类。传入时必须属于目标职位。 | |
|||
|
|||
任一必填参数缺失、非正整数，或行业—职位—分类关系非法时返回 `400`。如果未登录返回 `401`，非 STUDENT 用户返回 `403`。 |
|||
|
|||
## 2. 通用响应与排序 |
|||
|
|||
三个接口的 `data` 都使用 camelCase 字段。词云和 TOP10 使用同一份服务端排序结果： |
|||
|
|||
1. `heat` 从高到低；`heat` 为 `null` 的技能排在所有非空热度之后。 |
|||
2. 热度相同时按 `nameZh` 升序。 |
|||
3. 其余情况按 `skillId` 升序，保证重复请求顺序稳定。 |
|||
4. `rank` 从 1 连续递增。 |
|||
|
|||
`heat` 来自 O*NET Importance。无可靠 O*NET Importance 映射的 ESCO 技能仍返回，但 `heat` 为 `null`。TOP10 不在后端单独存储或单独排序；前端直接取词云 `data.items` 的前 `min(10, data.total)` 项。 |
|||
|
|||
技能身份来源： |
|||
|
|||
- `sourceType`：`ESCO` 或 `O*NET`，表示技能条目的主来源。 |
|||
- `sourceCode`：可追溯来源标识。ESCO 为技能 URI；O*NET 补充技能为 `SOC|Workplace Example|Element ID`。 |
|||
- `heatSourceCode`：热度来源 SOC；没有 O*NET 热度时为 `null`。 |
|||
- `heatElementId`：O*NET Importance 的来源 Element ID；没有时为 `null`。 |
|||
- `heatProxy`：该条热度是否为代理映射。代理值不改变排序规则，但前端可据此展示来源说明。 |
|||
|
|||
## 3. 查询词云 |
|||
|
|||
```http |
|||
GET /api/v1/skills/word-cloud?industryId=1&occupationId=2&categoryId=101 |
|||
Authorization: Bearer <accessToken> |
|||
``` |
|||
|
|||
`categoryId` 可省略： |
|||
|
|||
```http |
|||
GET /api/v1/skills/word-cloud?industryId=1&occupationId=2 |
|||
``` |
|||
|
|||
成功响应为 `ApiResponse<SkillCloudResponse>`。`SkillCloudResponse` 返回筛选节点、总数和当前范围内的完整技能列表： |
|||
|
|||
```json |
|||
{ |
|||
"code": 200, |
|||
"message": "ok", |
|||
"data": { |
|||
"industry": { "id": 1, "code": "INTERNET", "name": "互联网" }, |
|||
"occupation": { "id": 1, "code": "FRONTEND_DEVELOPER", "name": "前端开发工程师" }, |
|||
"category": { "id": 103, "code": "FRONTEND_FRAMEWORK", "name": "前端框架" }, |
|||
"total": 1, |
|||
"items": [ |
|||
{ |
|||
"rank": 1, |
|||
"skillId": 26, |
|||
"skillCode": "REACT", |
|||
"nameZh": "React", |
|||
"nameEn": "React", |
|||
"sourceType": "O*NET", |
|||
"sourceCode": "15-1254.00|React|2.E.7.h", |
|||
"categoryId": 103, |
|||
"categoryName": "前端框架", |
|||
"heat": 4.38, |
|||
"heatSourceCode": "15-1254.00", |
|||
"heatElementId": "2.E.7.h", |
|||
"heatProxy": true |
|||
} |
|||
] |
|||
}, |
|||
"requestId": "req-123", |
|||
"timestamp": "2026-09-15T10:00:00Z" |
|||
} |
|||
``` |
|||
|
|||
`category` 在未传 `categoryId` 时为 `null`。合法范围但暂时没有技能时返回成功、`total=0`、`items=[]`。前端根据 `items` 渲染词云，并截取前十条作为 TOP10。 |
|||
|
|||
## 4. 查询个人技能匹配度 |
|||
|
|||
```http |
|||
GET /api/v1/skills/match?industryId=1&occupationId=2&categoryId=101 |
|||
Authorization: Bearer <accessToken> |
|||
``` |
|||
|
|||
匹配集合严格取当前筛选结果的 TOP10。系统从当前 JWT 学生的 `student_profiles.skills_json` 读取技能，使用标准技能名、英文名、技能代码和别名归一化匹配。大小为 `total` 的筛选范围使用 `min(10, total)` 作为分母： |
|||
|
|||
```text |
|||
matchScore = round(matchedCount * 100 / min(10, total)) |
|||
``` |
|||
|
|||
- `total=0` 时 `matchScore=0`，命中列表和缺失列表为空。 |
|||
- 范围少于 10 项时按实际技能数计算。 |
|||
- 重复技能或指向同一标准技能的多个别名只计一次。 |
|||
- 示例：范围 15 条、命中 5 条，`matchScore=33`。 |
|||
- 原始 `skills_json`、手机号、邮箱和简历内容不会出现在响应中。 |
|||
|
|||
成功响应为 `ApiResponse<SkillMatchResponse>`： |
|||
|
|||
```json |
|||
{ |
|||
"code": 200, |
|||
"message": "ok", |
|||
"data": { |
|||
"matchScore": 50, |
|||
"matchedCount": 1, |
|||
"totalCount": 2, |
|||
"matchedSkills": [ |
|||
{ |
|||
"rank": 1, |
|||
"skillId": 26, |
|||
"skillCode": "REACT", |
|||
"nameZh": "React", |
|||
"nameEn": "React", |
|||
"sourceType": "O*NET", |
|||
"sourceCode": "15-1254.00|React|2.E.7.h", |
|||
"categoryId": 103, |
|||
"categoryName": "前端框架", |
|||
"heat": 4.38, |
|||
"heatSourceCode": "15-1254.00", |
|||
"heatElementId": "2.E.7.h", |
|||
"heatProxy": true |
|||
} |
|||
], |
|||
"missingSkills": [ |
|||
{ |
|||
"rank": 2, |
|||
"skillId": 31, |
|||
"skillCode": "DOCKER", |
|||
"nameZh": "Docker", |
|||
"nameEn": "Docker", |
|||
"sourceType": "O*NET", |
|||
"sourceCode": "15-1299.08|Docker|2.E.7.h", |
|||
"categoryId": 105, |
|||
"categoryName": "工程化工具", |
|||
"heat": 4.12, |
|||
"heatSourceCode": "15-1299.08", |
|||
"heatElementId": "2.E.7.h", |
|||
"heatProxy": true |
|||
} |
|||
] |
|||
}, |
|||
"requestId": "req-456", |
|||
"timestamp": "2026-09-15T10:01:00Z" |
|||
} |
|||
``` |
|||
|
|||
`matchedSkills` 与 `missingSkills` 的并集等于当前 TOP10，两个列表各自保持词云排序；`totalCount` 是实际匹配集合大小。 |
|||
|
|||
## 5. 生成学习路径 |
|||
|
|||
```http |
|||
GET /api/v1/skills/learning-path?industryId=1&occupationId=2&categoryId=101 |
|||
Authorization: Bearer <accessToken> |
|||
``` |
|||
|
|||
学习路径只消费个人匹配结果中的 `missingSkills`： |
|||
|
|||
- 只包含当前 TOP10 中未命中的技能，不包含已命中技能或 TOP10 之外的技能。 |
|||
- 顺序与 `missingSkills` 完全一致，`priority` 从 1 连续递增。 |
|||
- 每项只返回技能 ID、名称、分类、优先级和简化学习建议。 |
|||
- 后端不调用 AI、课程平台或外部知识库；不会返回课程链接、讲师、价格、学习时长或完成度。 |
|||
- 系统不持久化学习进度或完成状态。 |
|||
- 全部命中或合法范围没有技能时返回 `total=0`、`items=[]`。 |
|||
|
|||
建议模板按技能分类确定性生成： |
|||
|
|||
| 模板类别 | 建议方向 | |
|||
|---|---| |
|||
| 编程语言 | 基础语法、常见数据结构、至少一个编码练习。 | |
|||
| 框架 | 核心概念与生命周期、小型项目集成实践。 | |
|||
| 工具 | 安装与基础配置、结合工程完成实际操作。 | |
|||
| 通用 | 核心概念和常见应用场景、简短实践巩固。 | |
|||
|
|||
```json |
|||
{ |
|||
"code": 200, |
|||
"message": "ok", |
|||
"data": { |
|||
"total": 1, |
|||
"items": [ |
|||
{ |
|||
"priority": 1, |
|||
"skillId": 26, |
|||
"skillName": "React", |
|||
"categoryId": 103, |
|||
"categoryName": "前端框架", |
|||
"suggestion": "先理解 React 的核心概念与生命周期，再通过一个小型项目练习集成。" |
|||
} |
|||
] |
|||
}, |
|||
"requestId": "req-789", |
|||
"timestamp": "2026-09-15T10:02:00Z" |
|||
} |
|||
``` |
|||
|
|||
## 6. 错误响应示例 |
|||
|
|||
所有错误也使用统一 `ApiResponse`： |
|||
|
|||
```json |
|||
{ |
|||
"code": 1001, |
|||
"message": "bad request", |
|||
"data": null, |
|||
"requestId": "req-400", |
|||
"timestamp": "2026-09-15T10:03:00Z" |
|||
} |
|||
``` |
|||
|
|||
| HTTP | 场景 | 典型 `code` | |
|||
|---|---|---| |
|||
| `400` | `industryId`/`occupationId` 缺失、非正整数，或节点关系非法 | `1001` | |
|||
| `401` | 未携带有效 JWT 或令牌无效/过期 | `2001` | |
|||
| `403` | 已登录但不是 STUDENT | `2002` | |
|||
|
|||
示例 401： |
|||
|
|||
```json |
|||
{ |
|||
"code": 2001, |
|||
"message": "unauthorized", |
|||
"data": null, |
|||
"requestId": "req-401", |
|||
"timestamp": "2026-09-15T10:04:00Z" |
|||
} |
|||
``` |
|||
|
|||
示例 403： |
|||
|
|||
```json |
|||
{ |
|||
"code": 2002, |
|||
"message": "forbidden", |
|||
"data": null, |
|||
"requestId": "req-403", |
|||
"timestamp": "2026-09-15T10:05:00Z" |
|||
} |
|||
``` |
|||
|
|||
## 7. 字段参考 |
|||
|
|||
### SkillCloudNode |
|||
|
|||
`id`、`code`、`name`。`category` 节点在未指定分类时为 `null`。 |
|||
|
|||
### SkillCloudItem |
|||
|
|||
`rank`、`skillId`、`skillCode`、`nameZh`、`nameEn`、`sourceType`、`sourceCode`、`categoryId`、`categoryName`、`heat`、`heatSourceCode`、`heatElementId`、`heatProxy`。 |
|||
|
|||
### SkillMatchResponse |
|||
|
|||
`matchScore`、`matchedCount`、`totalCount`、`matchedSkills`、`missingSkills`。 |
|||
|
|||
### SkillLearningPathItem / SkillLearningPathResponse |
|||
|
|||
`SkillLearningPathItem`：`priority`、`skillId`、`skillName`、`categoryId`、`categoryName`、`suggestion`。 |
|||
|
|||
`SkillLearningPathResponse`：`total`、`items`。 |
|||
Loading…
Reference in new issue