Xiaozhi Teach Schedule Manager

误区① 全靠记性：课排在脑子里，
        学员问"下次课什么时候"答不上来，
        学员冲突了才后知后觉。

误区② 课时台账混乱：学员课时包还剩多少不清楚，
        课时耗尽了才想起续费，
        学员超课时上课但课时没扣。

误区③ 补课调课靠手动：学员请假靠微信沟通，
        调课靠反复确认，
        没有系统记录，靠人脑容易漏。

                ┌──────────────────────────┐
                │ ① 读学员可上课时间段      │
                │  studentCards[].availability│
                └────────────┬─────────────┘
                             ↓
                ┌──────────────────────────┐
                │ ② 周课表草案              │
                │  固定课 + 临时调课        │
                └────────────┬─────────────┘
                             ↓
                ┌──────────────────────────┐
                │ ③ 冲突检测                │
                │  老师时间 × availability  │
                └────────────┬─────────────┘
                             ↓
                ┌──────────────────────────┐
                │ ④ 排课建议 → 老师确认     │
                │  确认后才写 lessonSchedule│
                └────────────┬─────────────┘
                             ↓
                ┌──────────────────────────┐
                │ ⑤ 课时包台账              │
                │  剩余 / 到期 / 待确认条目 │
                └────────────┬─────────────┘
                             ↓
                ┌──────────────────────────┐
                │ ⑥ 补课/请假/调课          │
                │  一律生成待确认建议       │
                └──────────────────────────┘

小A 的 availability：
  { "dayOfWeek": "周三", "startTime": "18:30", "endTime": "20:00" }
  { "dayOfWeek": "周五", "startTime": "18:30", "endTime": "20:00" }

第 1 步：固定学员优先
  · 每周固定时间学员先排
  · 锁定本周的"硬骨架"

第 2 步：临时学员填空
  · 填空固定学员之间的空位
  · 优先安排学习节奏紧急的学员

第 3 步：留缓冲位
  · 留 1-2 个空位处理调课/补课
  · 不满课是健康的课表

■ 老师时间冲突
  · 同时段 workspace.lessonSchedule[] 已有 status=scheduled/makeup 的课
    （比对 startTime 与 durationMinutes 算出的区间是否重叠）
  · 同时段是老师登记的不可用时间

■ 学员时间冲突
  · 拟排时段不落在该学员任何一条 availability[] 区间内
    （判据：同一 dayOfWeek，且 startTime ≤ 拟排开始，
      拟排结束 ≤ endTime）
  · 学员没登记 availability[] → 不猜，先问一次并登记

■ 时段规定
  · 所有学段（面向中小学生的校外培训都适用：国办发〔2018〕80 号；教基厅函〔2021〕11 号）：
    线下课结束晚于 20:30、线上课结束晚于 21:00 → 提前；
    落在工作日白天的学校上课时间 → 不排
  · 小学中段 20:00、小学高段 20:20 前结束（shared/grade-bands.md 三）
  · 面向义务教育阶段学生的学科类培训（"双减"意见；高中学员参照执行，按当地规定）：
    落在周六、周日、法定节假日、寒暑假 → 不排；
    线上每课时超过 30 分钟，或两课时之间不足 10 分钟 →
    拆成每课时不超过 30 分钟、中间休息不少于 10 分钟
  · 处理：说一句依据，给出合规的候选时段或拆法，由老师选；其余照常排

■ 课时包提示
  · remainingUnits ≤ 3
  · expiryDate 距今 ≤ 7 天
  · pendingConfirmations 非空（剩余课时可能虚高）

■ 学员请假
  操作：
    · 课时不扣（对应课节 status=absence，
      课时条目由 lesson-log 生成 units=0 的待确认条目）
    · 记录请假日期；原因只记"已请假"，不记家庭细节
    · 不代排补课；需要补课时按 §7.2 生成待确认的补课建议

■ 补课
  操作：
    · 在老师可用时间 ∩ 该学员 availability[] 中、合乎 §6.1 时段规定的范围里找候选时段
    · 生成"待确认的补课建议"，列出 1-3 个候选：
        「小A 缺的这节课，这两个时间都排得开：
          本周五 18:30-20:00 / 下周五 18:30-20:00。
          选哪个？也可以都不选。」
    · 老师选定并与学员/家长确认后，才写入 lessonSchedule[]（status=makeup）
    · 课时消耗仍由 lesson-log 在课后生成待确认条目

■ 排课优先级（建议顺序，老师可推翻）
  · 同周补 > 下周补
  · 一次排完 > 分散排
  · 尽量贴近该学员原有的上课节奏

■ 调课（双方协商）
  操作：
    · 老师主动调：与学员/家长协商新时间
    · 学员/家长主动调：登记新时间
    · 双方都要确认

⚠️ 调课原则：
  · 一周内完成调课，不留"待定"
  · 新时间同样过 §6.1 时段规定（不占学校上课时间、按时结束；面向义务教育阶段学生的学科类培训不调到周六、周日、法定节假日或寒暑假）
  · 调课记录要可追溯
  · 频繁调课的学员需沟通原因

■ 触发条件（置 coursePackageLedger[].renewalAttention）
  · remainingUnits ≤ 3
  · expiryDate 距今 ≤ 7 天

■ 提示动作
  · 向老师陈述事实：「小A 还剩 3 课时，课时包 11-30 到期，
    另有 1 条待确认（确认后剩 2 课时）。」
  · 不催单、不制造紧迫感、不替老师决定要不要续

■ 续费节点口径
  · 已用 50% / 70%（与 xiaozhi-teach-renewal-report、
    xiaozhi-teach-student-intake 同一套，本 SKILL 不另设节点）

■ 要和家长谈时
  · 话术起草交 xiaozhi-teach-parent-communication
  · 起草前先查 workspace.studentCards[].consent 的
    parentCommunicationAllowed；发送由老师本人完成

■ 登记课时包时（新开或续课）
  · 按这一次收的课时与起止判断，不按累计的 totalUnits：
    这次的课时折成标准课时超过 60（线下 45 分钟、线上 30 分钟为 1 课时，
    如 90 分钟一节算 2 课时，短于标准时长的按 1 课时；每节多长看该学员的
    lessonSchedule[].durationMinutes，没排过课的问老师一句，课时数本身已超过 60 的不用问），
    或这次的起始日到到期日超过 3 个月
    （没填 startDate 时按登记当天算；续课加在原课时包上的，起始日按这次
    续课登记当天算，不用首次的 startDate）→ 提示老师一次：
    「一次收费的时间跨度不超过 3 个月，也不超过 60 课时（教监管函〔2021〕2 号，
    全国性规定；标准课时见发改价格〔2021〕1279 号）。这次 [N] 课时、每节 [N] 分钟，
    折合约 [N] 个标准课时（跨度 [N] 个月），超出了；如果是一次收的费，请核对收费方式。」
  · 折算只用于这一步：totalUnits 照老师给的数写，台账照老师的记法
  · 只提示、不拦截：老师核对后说照登就照登，课时数与日期照老师给的写
  · startDate 可以不填

■ 剩余课时不足却又要排课
  · 生成待确认提示：「小A 只剩 1 课时，这节课排下去会超出课时包。
    照排 / 先跟家长确认 / 暂不排？」
  · 老师选"照排"才写入 lessonSchedule[]
  · 本 SKILL 不代做"允许透支 N 课时"的决定，也不改动课时数字

■ 学员请假不补课
  · 课时不扣；是否另行约定由老师与家长自行商定
  · 本 SKILL 不涉及金额结算

■ 老师取消
  · 课时不扣
  · 生成待确认的补课建议（候选时段 1-3 个），
    由老师选定并与家长确认后写入
  · 不涉及退款：课时包只记数量，金额相关事项请用独立记账工具处理

■ 所有学段
  · 工作日不排在学校上课时间（国办发〔2018〕80 号）；结束时间照 §6.1

■ 面向义务教育阶段学生的学科类培训
  · 周六、周日、法定节假日与寒暑假不排课（双减意见）
  · 老师提出要排时：说一句依据，改在开学后（或下周）的
    工作日放学后排；其余照常排，不长篇解释

■ 面向高中学生
  · 休息日、法定节假日与寒暑假参照执行，按当地规定

■ 本 SKILL 不预设
  · 周末、假期的加课密度
  · 假期课时包

■ 培训进度
  · 不超过学员所在学校的同期进度，不提前教下学期、下学年的内容
  · 放假前最后一节：学期收尾，记下开学后从哪儿接着上

■ 考前 2 周
  · 减少新课
  · 增加复习/测评
  · 学员优先完成学校作业

■ 考试期间
  · 暂停新课
  · 答疑 + 心理支持
  · 考后复盘

■ 考后 1 周
  · 复盘考试结果
  · 调整下阶段计划

■ 触发条件
  · 1 个月内请假 ≥ 3 次
  · 连续 2 周请假

■ 应对
  · 主动了解原因
  · 评估是否需要调整节奏
  · 考虑续费意愿

  老师口述可上课时间 ──→ ┌────────────────────┐
  老师确认排课建议   ──→ │ schedule-manager    │ ──→ 周课表（渲染视图）
                        │ （本 SKILL）         │ ──→ 待确认的补课建议
                        └─────────┬──────────┘
                                  │ 写这两处
                    ┌─────────────┴─────────────┐
                    ↓                           ↓
             lessonSchedule            coursePackageLedger
             （课节）                  （不含 usedUnits 增减）

读：
  workspace.studentCards[].availability[]
      → 学员可上课时间段（dayOfWeek / startTime / endTime）
        这是时间冲突检测的唯一依据
  workspace.studentCards[].alias / .status / .gradeBand
      → 化名、是否在读、学段（学段决定 §6.1 时段规定怎么用：义务教育阶段
        与高中分开，小学中段、高段按 shared/grade-bands.md 一的就寝时间再提前）
  workspace.teacherProfile.deliveryChannels / .serviceModes
      → 线上/线下、一对一/小班，决定单节时长建议
  workspace.coursePackageLedger[].totalUnits / .usedUnits /
      .remainingUnits / .startDate / .expiryDate / .pendingConfirmations[]
      → 课时包台账；pendingConfirmations 非空时剩余课时按"未含 N 条待确认"展示；
        startDate 到 expiryDate 的跨度用于 §8.2 的登记提示（续课加在原课时包上的，起始日按这次续课登记当天算）
  workspace.lessonLogs[].consumeLessonUnits
      → 单节实际消耗（由 lesson-log 写，本 SKILL 只读）

写：
  workspace.lessonSchedule[]（lessonId / studentId / subject /
      startTime / durationMinutes / day_of_week / status / lessonGoal）
      → 排课结果，老师确认后写入
      status 取值：scheduled / completed / rescheduled / makeup /
                  cancelled / absence / trial
  workspace.coursePackageLedger[].totalUnits / .startDate / .expiryDate
      → 新开或续课时登记（startDate 可不填）；超过 60 课时或起止超过
        3 个月时按 §8.2 提示老师核对，不拦截
  workspace.coursePackageLedger[].renewalAttention
      → remainingUnits ≤ 3 或 expiryDate 距今 ≤ 7 天时置为 true

本 SKILL 不写：
  workspace.coursePackageLedger[].usedUnits / .remainingUnits 的增减
      → 由老师在 lesson-log 确认待确认条目后变更

派生视图（非存储字段）：
  · 周课表        ← 由 workspace.lessonSchedule[] 按 day_of_week 渲染
  · 冲突检测报告  ← 由 workspace.lessonSchedule[] 的 startTime/durationMinutes
                    与 workspace.studentCards[].availability[] 实时比对
  · 补课候选时段  ← 老师可用时间 ∩ 该学员 availability[] 的差集

✅ 排课中可使用：化名、availability[] 的时间段、课时包数量
❌ 禁止：学员家庭住址、家长身份、就读学校与班级、联系方式
✅ 写入数据：课节结构、课时包数量
❌ 不写入：学员真实姓名、金额、家长联系方式

✅ availability[] 只记时间：{周三, 18:30, 20:00}
❌ 不记原因："周三要上钢琴课""周日去爷爷家"属于家庭安排，不入档案

✅ 冲突检测：仅时间维度
❌ 不分析：学员家庭事务、学习状态等非时间因素

排课与课时管理
    读 workspace.studentCards[].availability[] ← student-intake 登记
    读 workspace.coursePackageLedger[]         ← 本 SKILL 与 lesson-log 共同维护
    写 workspace.lessonSchedule[]              ← 本 SKILL 唯一写入方
    写 workspace.coursePackageLedger[].totalUnits / .startDate / .expiryDate /
       .renewalAttention

  课时的实际扣减在 xiaozhi-teach-lesson-log（老师确认待确认条目）。
  要和家长谈调课或续费，话术交 xiaozhi-teach-parent-communication，
  发送由老师本人完成。