# Skill Cloud Specification

## ADDED 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` 中返回筛选条件和技能列表