报读与课时台账

课时台账是一本只增不改的流水账：报读、期初、调整都是往里面追加一行，学生当前还剩多少课时是把这些行加总算出来的，不是某个能被直接改写的字段。

入口

台账挂在学生本人身上，不是一张独立的菜单页。

1. 左侧图标栏 档案 → 二级 tab 学生 → 进入学生列表。
2. 找到目标学生那一行，点右侧 详情 → 进入这个学生的详情页。
3. 详情页里有一张卡片，标题是 报读 / 课时台账：上面是一张按学科分桶的余额列表，下面是完整的流水表（时间 / 学科 / 类型 / 课时变动 / 金额 / 备注），卡片右上角是 报读 和 课时调整 两个按钮。

这张卡片只有账号带着「报读登记/课时调整/期初导入」权限（enrollment.manage）且机构开通了「点名与课消」这块积木，才会出现；不满足条件的账号看不到它。

期初课时批量导入不在这张卡片里，入口在学生列表页顶部，跟「+ 新建学生」同一排的 期初课时导入 按钮——见下面「期初课时批量导入」一节。

三种入账

台账里每一行都有一个类型（kind），一共四种：报读、期初、调整、课消。前三种是人手工写的，写口都是同一个接口；第四种课消只能由点名产生，点名工作台点完名之后自动写一行，页面上任何地方都没有让你手工插入一条课消记录的入口——想改课消，只能回去重新点名，台账这一层不提供入口。

• 报读——给学生新增课时。数量必须大于 0；学科可以选一个（决定进哪个课时桶），也可以留空、走「通用课时」。报读模式的表单上有一个「金额（元，选填）」输入框，挂的是这次收了多少学费，选填，不填也能提交。
• 期初——语义上跟报读很像（都是新增课时、都能挂金额），区别是它专门用来把从旧系统迁进来的历史余额搬进来，标准做法是走后面说的批量导入，而不是逐条手填。
• 调整——用来冲正，课时变动可以是负数（比如订正一笔录错的期初）。调整模式的表单没有金额输入框：服务端对调整行挂金额会直接拒绝，「金额只能挂在报读或期初记录上」。调整不论正负都必须填备注，说明这次改动的原因——不填会被服务端拦下，提示「调整记录必须填写备注，说明本次修正的原因」。负数调整最容易被人想起要写清楚为什么扣，但这条规则对正数调整同样成立，不是负数专属。

演示数据里可以看到的真实例子（demo 站上就是这几笔，都是种子数据）：

• 报读初一数学A班 20 课时，挂了 ¥2000.00 学费 → 数学桶 +20.00
• 同一名学生又走了一笔通用课时充值，没选学科、没挂金额 → 通用课时桶 +5.00 ——这一行的类型同样是「报读」，区别只在没选学科、没填金额，不是另一种入账类型
• 另一名学生（试听生）是期初导入进来的：数学桶 +10.00，备注「期初导入课时余额」
• 同一名试听生后来发现期初录多了，冲了一笔调整：数学桶 -3.00，备注「核销期初录入错误，冲减 3 课时」

课时是分桶的

台账每一行都挂着一个学科；算余额时按「这个学生 + 这个学科」分组求和，数学桶和英语桶是分开算的，互不冲抵。

学科留空的那一桶，界面上显示为「通用课时」——它不是某一门具体学科，就是字面意思：没有挂学科的课时，比如机构卖的是不限学科的课时包，或者充值时压根不想按学科拆分。分桶余额列表里，「通用课时」这一行对应的就是这一类行的汇总。

期初课时批量导入

入口：学生列表页顶部的 期初课时导入 按钮（与「+ 新建学生」同一排）。

用来解决什么：机构从外部教务系统迁移过来，一批学生手里还剩多少课时需要一次性搬进来，不是一个个学生点进详情页手工报读。

怎么做，两段式：

1. 粘贴——打开对话框先是一个多行文本框，每行填一名学生，用 Tab 或逗号分隔「姓名、学科（可留空）、课时、金额（可留空）」，点 预览。
2. 预览——服务端按姓名在当前校区范围内匹配在读学生，返回一张可编辑的表：行号 / 姓名 / 学科 / 课时 / 金额 / 匹配结果。姓名重复或匹配不到的行，最后一列会标红说明原因，不会替你猜一个学生出来。
3. 在表格里直接改某一格，那一行的匹配结果会变成「待重新预览」——必须点一次 重新预览，让服务端按改过的内容重新匹配一遍；光在表格里编辑不会自动生效，界面会提示「表里的内容改过了，先点『重新预览』重新匹配一遍，才能确认导入」。
4. 等所有行的匹配结果都变成「已匹配」，确认导入 按钮才会可点，点下去逐行写入「期初」台账行。

重复提交不会重复入账：这份对话框在打开时会生成一个幂等键，整个对话框生命周期内复用同一个键；同一个键第二次确认，服务端一行都不会再插，只会照原样告诉你「这批期初课时此前已经导入过」。所以就算网络超时让你以为提交失败又点了一次，也不会出现课时翻倍。

台账为什么只增不改

hour_ledger 这张表在设计上就没有「改」和「删」的通道——所有写口都只做新增一行，没有对应的修改或删除接口。想撤销或纠正一笔历史记录，标准做法不是把那一行改掉，而是再写一笔调整，用符号相反的数字冲平多算或少算的部分（前面数学桶那笔 -3.00 就是这么来的）。

这样设计的好处：

1. 台账即审计轨迹——机构收了多少钱、扣了多少课时、谁在什么时间点操作的，一条不少地留着，不会因为「顺手改一下」被抹掉痕迹。
2. 余额永远是算出来的——某个学生在某个学科上还剩多少课时，是把这个学生这个学科下的全部台账行加总得到的，不存在一个可以被直接改写、从而跟台账加总结果对不上的独立字段。
3. 重复提交可以安全去重——如果台账允许改或删，「同一个幂等键第二次提交不会导致重复入账」这条承诺就没法简单靠一次插入判重来实现。

台账只解决入账这一头。课时怎么被扣掉，见点名与课消；账面上现在还剩多少、低于多少该去催续费，见课时余额与预警。

常见问题

报读的表单里怎么没有金额输入框？ 说明打开的是「课时调整」模式，不是「报读」。调整这个动作设计上就不允许挂金额，收费只发生在报读或期初的时候；要登记一笔收费，用 报读 按钮，不要用 课时调整。

通用课时是哪一门学科？ 它不是学科，是「没挂学科」的意思。分桶余额列表里「通用课时」那一行，对应的就是学科字段留空的那些台账行的加总，跟某一门具体学科无关。

调整填了负数但没填备注，提交失败？ 见上面「三种入账」——调整不论正负都必须填备注，不是负数专属的规则。

台账里那些「课消」是怎么冒出来的？ 点名之后自动生成的，页面上没有手工增加一条课消记录的入口。点名点错了，正确的改法是回到点名工作台重新点，而不是来这张台账里改动或删除那一行。

期初导入确认之后，怀疑没生效又点了一次「确认导入」？ 不会重复入账；界面会提示这批此前已经导入过、这次没有产生任何新行。如果刚才在预览表里改过内容，那些修改也不会生效——按提示关闭对话框重新走一遍完整流程，或者到对应学生的台账里用课时调整修正，不要指望改完直接点确认导入就能覆盖上一次的结果。