math_cms/.planning/PROJECT.md

Math CMS — Difficulty Calibration & Intelligent Exam

What This Is

K12 数学智能提分系统的难度分级优化项目。系统已有题库管理、知识点匹配、组卷、答题分析、掌握度计算等核心能力，现需解决题目难度值不准确和组卷难度匹配不佳两个核心问题，形成"答题 → 校准 → 精准组卷 → 再答题"的闭环。

Core Value

让题目难度趋于真实，让组卷精准匹配学生水平。 校准算法准确性是一切的前提，未经验证不进入生产链路。

Requirements

Validated

• ✓ 题库管理（CRUD、导入、AI生成题目）
• ✓ 知识点体系与章节匹配
• ✓ 智能组卷（按知识点、章节、错题等多种策略）
• ✓ 答题分析与评分
• ✓ 掌握度计算（MasteryCalculator，按知识点追踪学生水平）
• ✓ 难度分级基础架构（questions.difficulty、DifficultyDistributionService、5级分类）
• ✓ 校准算法框架（QuestionDifficultyCalibrationService，stratified_residual_eb_v2 算法）
• ✓ 校准数据表（question_difficulty_calibrations）
• ✓ 难度校准命令行报告工具（AnalyzeQuestionDifficultyCalibrationCommand）

Active

• 校准算法（stratified_residual_eb_v2）准确性验证 — 历史数据回测
• 难度标准统一（消除 0-1 和 0-5 双标准混用问题）
• 校准值接入组卷全链路（所有组卷路径优先使用校准值）
• 难度分布策略默认启用（enable_difficulty_distribution 全路径生效）
• 基于学生掌握度自动推荐 difficulty_category
• 后续产品方向规划（学习路径、更精准的提分策略等）

Out of Scope

• 回写 questions.difficulty — 原始难度作为初始值永久不变，校准值存在独立表
• 重新设计校准算法 — 当前先用 stratified_residual_eb_v2，验证后决定是否调整
• 改造掌握度计算权重体系 — MasteryCalculator 的 overshoot/match/undershoot 权重暂不动

Context

现有系统架构

• 技术栈: Laravel (PHP)，MySQL，异步任务队列
• 难度存储: questions.difficulty（原始值）+ question_difficulty_calibrations（校准值）
• 组卷流程: IntelligentExamController → AssembleExamTaskJob → LearningAnalyticsService → DifficultyDistributionService
• 掌握度: MasteryCalculator 按知识点追踪，0-1 连续值
• 难度分类: 5 级（零基础/筑基/进阶/培优/竞赛），对应 0-4

已识别的 6 个关键问题

难度不准：

1. 校准值存在独立表，但智能组卷主流程未启用校准值，多条路径仍用原始值
2. 原始难度有 0-1 和 0-5 两套标准混用，导致分布计算可能出错
3. （设计如此）校准结果不回写 questions.difficulty，原始值保持静态

组卷匹配差：

1. enable_difficulty_distribution 默认关闭，API 主链路未使用难度分布策略
2. 无根据学生掌握度自动推荐 difficulty_category 的逻辑
3. LearningAnalyticsService 的组卷路径未调用校准难度

校准算法（stratified_residual_eb_v2）

• 分层基线残差 + 贝叶斯收缩 + 时间衰减
• 按题目类型 + 试卷难度分层计算全局基线错误率
• 残差 = 观测错误率 - 期望错误率
• 自适应增益/收缩随样本量和信号强度调整
• 45 天半衰期时间衰减
• 校准值范围 [0.01, 0.99]
• 健康监控：近期 Brier score/log-loss 恶化时缩小调整幅度

关键原则

• questions.difficulty = 初始值，永不改变
• question_difficulty_calibrations.calibrated_difficulty = 实时校准值，持续更新
• 验证通过前，校准值不进入生产组卷链路

Constraints

• Tech Stack: Laravel PHP 后端，不改技术栈
• 数据完整性: 历史答题数据必须可用于回测验证
• 向前兼容: 校准值接入链路不能破坏现有组卷功能
• 渐进式: 验证 → 打通 → 智能匹配，分阶段推进

Key Decisions

Decision	Rationale	Outcome
questions.difficulty 保持不变	作为初始参考值，便于审计和问题追溯	✓ Good
校准值存在独立表	解耦原始值与校准值，独立演进	✓ Good
先验证再接入生产	校准算法未经验证就用于组卷会引入更大误差	— Pending
历史数据回测验证	有大量历史答题数据可用于评估校准效果	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-04-16 after initialization