qingsongping-AIDevelop/specs/learning-path/spec.md

learning path Specification

Purpose

定义基于缺失 TOP10 技能的确定性学习路径生成行为。

Requirements

Requirement: Learning path consumes unmatched TOP10 skills

学习路径接口 MUST 复用个人技能匹配结果，并只包含当前 TOP10 中未命中的技能；不得包含已命中技能或 TOP10 之外的技能。

Scenario: Student has skill gaps

• WHEN 当前 TOP10 中部分技能未命中
• THEN 学习路径 MUST 包含全部未命中技能且不含已命中技能

Scenario: Student has no skill gaps

• WHEN 当前 TOP10 全部命中
• THEN 学习路径 MUST 返回空列表和总数 0

Scenario: Student has no matching skill evidence

• WHEN 学生没有技能数据
• THEN 学习路径 MUST 包含当前 TOP10 的全部技能

Requirement: Learning priority follows heat order

学习路径项 MUST 按与 TOP10 相同的热度顺序排列，并从 1 开始连续编号；空热度技能继续遵守词云的末位排序规则。

Scenario: Multiple missing skills are ordered

• WHEN 缺失技能包含多个热度不同的技能
• THEN 热度最高的技能 MUST 获得优先级 1，后续技能依次编号

Scenario: Missing skills have equal heat

• WHEN 缺失技能热度相同
• THEN 优先级 MUST 沿用词云的稳定次级排序，重复请求结果一致

Scenario: Only one skill is missing

• WHEN 当前 TOP10 只有一项未命中
• THEN 该技能 MUST 返回优先级 1

Requirement: Learning suggestions are deterministic and industry-neutral

每项学习建议 MUST 由后端按技能分类的通用模板生成，不调用 AI、知识库问答或外部课程服务；建议不得包含课程链接、讲师、价格、学习时长或完成度。

Scenario: Programming language gap is returned

• WHEN 缺失技能属于编程语言分类
• THEN 建议 MUST 描述基础语法学习和编码练习方向

Scenario: Framework gap is returned

• WHEN 缺失技能属于框架分类
• THEN 建议 MUST 描述核心概念学习和小型项目实践方向

Scenario: Tool gap is returned

• WHEN 缺失技能属于工具分类
• THEN 建议 MUST 描述安装配置和工程实践方向

Scenario: Unknown category is returned

• WHEN 缺失技能无法匹配特定模板分类
• THEN 系统 MUST 返回一条行业无关的通用学习建议

Requirement: Learning path response is actionable and minimal

每个学习路径项 MUST 返回技能 ID、技能名称、技能分类、优先级和简化学习建议；响应 MUST 不包含个人隐私、简历原文或模型推理内容。

Scenario: A learning item is generated

• WHEN 存在未命中技能
• THEN 每个路径项 MUST 同时具备技能身份、分类、连续优先级和建议文本

Scenario: Repeated request is made

• WHEN 学生资料、词库数据和筛选条件均未变化
• THEN 接口 MUST 返回相同顺序、相同优先级和相同建议

Scenario: Response contains no private profile data

• WHEN 学习路径成功返回
• THEN 响应 MUST 不含手机号、邮箱、简历文件、原始 skills_json 或其他无关个人数据