技能介绍

痛点：课时对账与反人类的 API 设计

在教培场景中，每月的课时统计和账单结算是一项繁琐且易错的工作。小麦助教（xiaomai5.com）的后台数据虽然齐全，但依赖手动导出和 Excel 拼凑不仅耗时，还极易因口径理解偏差导致算错钱。此外，其底层 API 设计对开发者极不友好：前端默认的 API 域名是内网地址，公网根本无法解析；登录密码采用 MD5 而非 RSA 加密；认证不仅需要 query 参数，还必须携带一系列静态 HTTP 头，稍有不慎就会返回“请重新登录”。本技能旨在将这些反人类的对接细节和繁琐的统计逻辑彻底固化，让课时账单一键生成。

核心实现与统计口径

技能的核心在于精准还原平台后端的数据流转逻辑，并严格定义了统计口径。

数据源与时间维度：以点课记录（rollCall）为数据源，时间维度严格采用 classStartDate（上课时间），而非点课或课消时间，确保与页面默认导出逻辑一致。
课时字段辨析：点课记录中存在“扣课时”（planCheckedClassHour）与“实际扣课时”（checkedClassHour）两个极易混淆的字段。技能默认采用“扣课时”口径（当学员到课或实际扣课时大于 0 时计入），并支持通过参数切换。由于会话级的课时不能直接相加，脚本会按 signId 调取接口逐学员累加。
分类与账单生成：根据班级名称自动识别 C++（含集训/csp/信奥等）或 Python，并结合内置单价和换算系数（如 Python 的 0.75 系数）自动生成账单。支持通过 --extra 参数手工追加营地等非点课课时。

适用边界与工程细节

归属过滤：默认仅统计登录教师本人点名的课时（rollCallTeacherId 匹配）。若需统计带班他人点名的课时（如查询特定 OJ 班学员），需绕过此过滤逻辑。
异常与限流：API 登录存在限流风险，脚本内置了 5 次重试与 8 秒退避机制。多机构账号默认取第一个机构，跨机构统计需显式传入 teacherId。
凭据安全：所有账号密码仅通过环境变量读取，脚本不落盘、不打日志，避免敏感信息泄露到共享面。