lxq/changes/n03-skill-cloud/specs/skill-match/spec.md

Skill Match Specification

ADDED Requirements

Requirement: Personal matching uses the current ranked TOP10

个人技能匹配接口 MUST 复用技能词云相同的筛选参数、数据范围和热度排序；匹配集合 MUST 是当前筛选结果的前 min(10, 实际技能数) 项。

Scenario: Filtered result has at least ten skills

• WHEN 当前筛选返回十条或更多技能
• THEN 匹配集合 MUST 恰好包含热度最高的十条技能

Scenario: Filtered result has fewer than ten skills

• WHEN 当前筛选返回六条技能
• THEN 匹配集合 MUST 包含全部六条技能，分母 MUST 为 6

Scenario: Filtered result is empty

• WHEN 当前合法筛选范围内没有技能
• THEN 匹配度 MUST 返回 0，命中和缺失列表 MUST 均为空

Requirement: Student skills are read from the authenticated profile

系统 MUST 从当前登录 STUDENT 的 student_profiles.skills_json 读取技能；不得接受客户端另行提交的技能列表作为个人匹配依据。

Scenario: Student profile has valid skills

• WHEN 当前学生存在合法技能数组
• THEN 系统 MUST 使用该数组计算匹配结果

Scenario: Student profile is absent or has no skills

• WHEN 当前学生没有资料记录、技能字段为空或技能数组为空
• THEN 匹配度 MUST 返回 0，命中列表为空，缺失列表为当前 TOP10

Scenario: Skills JSON is malformed

• WHEN 当前学生技能字段无法解析为字符串数组
• THEN 系统 MUST 按无技能处理，不得导致 500 响应或泄露原始字段内容

Requirement: Skill matching normalizes aliases

系统 MUST 使用技能标准和别名进行匹配，归一化至少覆盖首尾空白、大小写、连续空格和常见标点差异；每个标准技能命中一次即可。

Scenario: Alias matches canonical skill

• WHEN 学生技能为 SpringBoot，TOP10 标准技能为 Spring Boot 且存在对应别名
• THEN 系统 MUST 将该技能计为命中

Scenario: Case and spacing differ

• WHEN 学生技能与标准技能的字母大小写或空格数量不同
• THEN 系统 MUST 在归一化后判断为同一技能

Scenario: Duplicate student skills exist

• WHEN 学生技能数组包含多个指向同一标准技能的别名
• THEN 系统 MUST 只计一次命中

Requirement: Match score uses the actual TOP10 size

匹配度 MUST 使用公式 round(命中数 × 100 / min(10, 实际技能数)) 计算，并返回 0 到 100 的整数。实际技能数为 0 时，匹配度 MUST 为 0。

Scenario: All skills match

• WHEN 当前 TOP10 有 8 项，学生命中全部 8 项
• THEN 匹配度 MUST 返回 100

Scenario: Partial match is rounded

• WHEN 当前 TOP10 有 3 项，学生命中 1 项
• THEN 匹配度 MUST 返回 33

Scenario: No skill matches

• WHEN 当前 TOP10 非空且学生没有命中任何技能
• THEN 匹配度 MUST 返回 0

Requirement: Match response separates matched and missing skills

响应 MUST 返回匹配度、命中数量、实际匹配集合大小、命中技能列表和缺失技能列表；缺失技能 MUST 保持 TOP10 的热度排序。

Scenario: Some skills are matched

• WHEN 学生命中 TOP10 的部分技能
• THEN 命中列表和缺失列表 MUST 分别返回对应技能，且并集等于 TOP10

Scenario: All skills are matched

• WHEN 学生命中 TOP10 的全部技能
• THEN 缺失技能列表 MUST 为空，匹配度 MUST 为 100

Scenario: No skills are matched

• WHEN 学生没有命中 TOP10 的任何技能
• THEN 命中技能列表 MUST 为空，缺失列表 MUST 等于 TOP10