qingsongping-AIDevelop/specs/skill-cloud/spec.md

skill cloud Specification

Purpose

定义行业技能词云查询、筛选、热度排序与来源追溯行为。

Requirements

Requirement: STUDENT-only skill cloud access

系统 MUST 只允许已登录 STUDENT 调用技能词云接口，并从 JWT 解析当前用户，不接受客户端传入学生身份参数。

Scenario: Anonymous request is rejected

• WHEN 未携带有效 JWT 请求 GET /api/v1/skills/word-cloud
• THEN 系统 MUST 返回 401，且不得返回任何词库数据

Scenario: Company or administrator request is rejected

• WHEN COMPANY 或 ADMIN 用户携带有效 JWT 请求技能词云
• THEN 系统 MUST 返回 403，且不得返回任何词库数据

Scenario: Student request is accepted

• WHEN STUDENT 用户携带有效 JWT 请求技能词云
• THEN 系统 MUST 按筛选条件返回词库数据

Requirement: Skill cloud filter validation

接口 MUST 要求 industryId 和 occupationId 为必填正整数，categoryId 为可选正整数；行业与职位必须存在且互为关联，技能分类存在时必须属于该职位。

Scenario: Required filters are missing

• WHEN 请求未传 industryId 或 occupationId
• THEN 系统 MUST 返回 400，并说明缺失的筛选参数

Scenario: Occupation does not belong to industry

• WHEN 请求传入存在但不属于目标行业的职位
• THEN 系统 MUST 返回 400，且不得返回技能数据

Scenario: Category does not belong to occupation

• WHEN 请求传入存在但不属于目标职位的技能分类
• THEN 系统 MUST 返回 400，且不得返回技能数据

Scenario: Category is omitted

• WHEN 请求只传行业和职位
• THEN 系统 MUST 返回该职位下所有技能分类的技能

Requirement: Complete ranked skill cloud

系统 MUST 返回当前筛选范围内全部技能，并按 heat 降序排列；heat 为空时排在非空值之后。同 heat 或同为空值时，系统 MUST 使用稳定的中文技能名称和技能 ID 作为次级排序条件。

Scenario: Skills are ordered by heat

• WHEN 筛选结果存在多个带 O*NET Importance 的技能
• THEN 返回列表 MUST 按数值从高到低排列

Scenario: Skills without heat are retained

• WHEN 筛选结果包含无 O*NET Importance 的 ESCO 技能
• THEN 这些技能 MUST 保留在列表中，heat 为 null，并排在所有非 null 热度技能之后

Scenario: Equal heat has deterministic order

• WHEN 两个技能具有相同 heat
• THEN 系统 MUST 按稳定次级规则返回一致顺序，重复请求不得随机变化

Scenario: Empty scope returns empty list

• WHEN 合法筛选范围内没有技能
• THEN 系统 MUST 返回成功响应、空技能列表和总数 0

Requirement: TOP10 is derived from the skill cloud

系统 MUST NOT 为 TOP10 维护独立排序或独立数据源；前端必须能够直接使用词云返回列表的前十条得到 TOP10。

Scenario: Scope has at least ten skills

• WHEN 词云结果包含至少十条技能
• THEN 前十条 MUST 与同一筛选条件下的热门技能 TOP10 一致

Scenario: Scope has fewer than ten skills

• WHEN 词云结果少于十条技能
• THEN 全部结果 MUST 构成实际 TOP10 集合

Requirement: Skill cloud response exposes source-linked metadata

每个技能项 MUST 至少返回技能 ID、中文名称、技能分类 ID、技能分类名称、heat 和稳定排名。技能仍可通过 ID 追溯至 ESCO/O*NET 来源。

Scenario: Skill item is returned

• WHEN 查询返回任一技能
• THEN 响应 MUST 包含该技能的身份、分类、热度和排名字段

Scenario: Response is wrapped consistently

• WHEN 请求成功
• THEN 响应 MUST 使用项目统一 ApiResponse 结构，并在 data 中返回筛选条件和技能列表