门店课消
教培机构数字化运营管理平台
「门店课消」是一套面向教培机构的数字化运营管理工具，将门店、员工、学员（会员）、充值项目（课包 / 储值卡 / 独立产品）、进账流水、消账记录、销售沟通、体验预约、督学规划、我的班级、课程排课、学员出勤与三种签到通道（手工 / 刷脸 / NFC）、门店账本、提醒与标签等核心业务全量数字化。其最大的设计特点是类微信对话式交互——所有业务操作（充值、课消、督学、出勤打卡、备注）都以消息形式沉淀在学员对话流中，大幅降低使用门槛。销售沟通更进一步：把"记录跟进"这件事交给语音与 AI——打完电话说一段，转写、结论、跟进标签全部自动生成。
从线索到续费、再到门店经营记账，全链路闭环管理，每个环节的数据自动回流到学员对话流。
销售沟通跟进线索（AI 语音录入 → 自动结论与跟进标签 → 加微 → 诺访 → 到店 → 体验课 → 转化），体验课预约到店转化，一键转为正式学员。
购买课包 / 储值卡 / 独立产品，自动生成实例与价格快照，实时累加累计充值。
按日期排课（课程×时段×地点×老师×学员），一键按课包分组批量扣消，缺勤不扣；亦可单笔课消/核销，支持退费标记。
三种通道共用一条打卡链路：手工打卡（按门店配置图片 / 文字）、刷脸签到（本地/服务器识别、命中即签）、NFC 刷卡签到（App / H5 / 小程序）。缺勤填原因，日历热力图 + 按月次数统计，超管可补打卡。
按周督学计划 + 编组矩阵 + 我的班级，到期 / 剩余课时 / 长时未课消自动提醒，促进续费。
门店账本记录日常收支，经营看板看净利润与支出构成；收入可按消账 / 按进账口径切换。
同一套后端，同时驱动 Web 管理后台（完整业务 + 复核 + 导出）与员工移动端小程序（对话式交互），数据实时互通。后端 Spring Boot 3.x + Java 21，20 个业务 REST 控制器，菜单扁平化为一级业务菜单由后端动态下发，门店账本更以「按用户可见」过滤器实现细粒度裁剪。
Vue 3 + Vite + Naive UI。12 个业务菜单（门店 / 充值项目 / 学员 / 进账 / 消账 / 销售沟通 / 体验课 / 督学 / 我的班级 / 课程排课·日历式 / 数据统计 / 门店账本）+ 员工管理、系统日志与隐藏的角色管理。菜单与路由由后端动态下发并已扁平化为一级，支持 Excel 批量导入导出、复核列、绩效表导出、多维统计看板、出勤弹窗（含超管补打卡）、进账/消账的辅导老师纠错（仅超管）。
UniApp + TDesign，一套代码编译 H5 / 微信小程序 / 安卓 App 三端。4 个 Tab（记录 / 学员 / 发现 / 我），以类微信对话流承载充值、课消、督学、出勤、我的班级、课程排课、门店账本等业务操作；发现页提供人脸签到（App 专属）与NFC 签到（全端）入口，支持增量同步、微信级消息分页与实时刷新。
20 个业务 REST 控制器，MyBatis-Plus + MapStruct 持久层，Liquibase 自动建表与种子数据，Spring Security + JWT 鉴权，Redis 缓存与分布式锁，WebSocket 实时通知，/biz/sync 增量同步接口覆盖 8 个业务域；人脸签到双形态——App 端只提供底库、打卡落库与照片存储（识别全链路在设备本地完成），Web 后台实时签到由服务端对上传帧完成检测识别后落库。
到店签到的真实性，直接决定课消与出勤统计的可信度。系统提供手工打卡（按门店配置图片水印 / 文字模板）、刷脸签到（本地/服务器 1:N 识别、命中即签）与 NFC 刷卡签到（App / H5 / 微信小程序）等通道，全部复用同一条出勤链路：每日一次校验、角色数据隔离、聊天系统消息留痕、签到明细可撤销。
按门店出勤配置执行：图片打卡（后端统一压缩并叠加门店水印文字与时间）或文字打卡（模板支持学员姓名变量）。缺勤填写原因；超管可补打卡、可取消打卡。
App 端在设备本地完成检测 → 对齐 → 128 维向量 → 1:N 比对，命中即提示「XX 签到成功」并震动，人脸原图不上云；Web 后台门店管理页「实时签到」弹窗则将摄像头帧流上传，由服务端检测识别后直接落打卡——两形态共用同一底库与判定阈值。
学员持卡贴读卡设备完成签到，后端按卡号定位学员并走同一打卡链路（文案追加「（NFC刷卡）」）。App / H5 / 小程序读 NFC 卡 UID；Web 后台另支持键盘口（HID）ID 读卡器——十进制卡号自动识别转换为十六进制 UID。一卡一学员，重复绑卡当场提示对方学员。
先读本地底库缓存立即可用，同时后台拉最新底库（向量 + 各学员门店的打卡方式一并下发，打卡前不再串行查接口）。
页面挂载即初始化检测 / 识别引擎，与摄像头启动并行，压缩首帧识别前的空白期；不满足条件（无权限、底库为空）直接给明确遮罩文案。
逐帧检测人脸框与关键点，多脸按面积取最大；脸太小提示「请靠近一点」。状态位常驻刷新，绝不让操作者面对"什么都没发生"。
关键点对齐 112×112 取 128 维向量，限频 + 命中退避 + 只吃新鲜快照，识别绝不阻塞检测。
余弦相似度 ≥ 0.50 且领先第二名 ≥ 0.08 才判同一人；立即提示「XX 签到成功」+ 震动 + 记入本次签到列表（零网络等待）。
打卡请求（含命中帧编码落盘）后台异步提交；任何后端错误不上屏，但会静默撤回乐观展示，考勤以后端落库为准。
进页默认展示本次会话（人脸与同步 NFC 记录混排，可搜索、可取消签到）；点「历史」切换为全量签到记录——人脸（附照片与相似度）、NFC（蓝标签）、手动（灰标签）按日期分组、分页加载。取消签到联动清理人脸 / NFC 两个签到页的本次列表。
添加学员 / 学员信息页拍照 → 本地检测对齐取向量 → 与底库查重（相似度过高提示「疑似重复录入」）→ 向量随学员新增 / 修改落库。人脸签到页的底库人数卡点一下即可重载底库，无需退出页面。
教培机构的线索大半活在电话和微信里，最容易丢的不是客户，而是「这次到底聊了什么、下一步该谁做什么」。销售沟通模块把这段链路做成录进去就有结论：电话、录音、上传、手打四个入口，点下去立刻生成一条沟通明细；语音边说边转成文字，随即 AI 边想边写，输出【沟通要点 / 客户意向 / 异议与顾虑 / 跟进建议】四段结论，并自动打上四档跟进标签——列表上只看得到最近一次的标签。
电话（拨号后回来补传通话录音）、录音（应用内直接录）、上传（本地音频，≤200MB 且走格式白名单）、输入（手打一段话，≤4000 字）。四者殊途同归：都写同一条沟通明细，后续转写、分析、标签完全一致。
转写完成自动进入分析：先流式输出思考过程，再逐段写正文——沟通要点、客户意向、异议与顾虑、跟进建议。提示词带着「已到店 / 已参与体验课」这些阶段信息，不会把老客户按陌拜口吻来写。
AI 在【跟进建议】段必须给出一个类别，后端把它原样存成中文（不存码），列表、详情、归档三页直接显示，颜色语义统一。只取最近一次沟通的标签，最新那次没结论就留空，不往前回落——宁可没有，也不给过期的判断。
点电话 / 录音 / 上传 / 输入，立刻生成一条明细并展开在该线索下，不必等转写完成。
录音走实时通道逐字上屏；上传与通话录音走后台整段转写。状态标「转写中」。
边想边显示思考过程，用户看得见 AI 正在做什么，长内容也不会以为卡住了。
四段正文逐段写入；同时把主表的「最近沟通结果 / 汇总时长」一并刷新。
从建议段抽出四档类别写入线索主表，列表立刻可见，只显示最新一次。
超管复核锁定；销售按标签排优先级；统计页看加微 → 诺访 → 到店 → 体验 → 转化漏斗。
家长问了暑期班的课时和价格，说孩子现在二年级，担心跟不上；约好周六上午来试听……
关注暑期班课时安排与价格，孩子二年级、担心跟不上进度。
意向明确，已接受试听邀约，属近期可成交客户。
担心班级节奏与孩子基础不匹配，需要看到分层教学证据。
快速跟进：48 小时内发一期同龄班课堂视频，并确认周六试听到店。
正文逐段流式写入，思考过程单独可见；同一屏里既有原话也有结论，不用再靠回忆补记录。
48 小时内再联系一次。
一周内跟进一次，按常规节奏。
按月回访，不占用日常精力。
AI 只给建议，归档仍是人工动作。
标签的抽取规则是工程化的：只读【跟进建议】段的段首 60 字，取出现位置最靠前的类别词，不按固定优先级硬套——"快速跟进：先发资料，两周无回应再建议归档"这种句子里两个类别词同时出现，按优先级匹配就会把档判错。
销售主管在 Web 后台 Excel 导入成批线索进「线索池」，再按数量分配给多名销售——按选择顺序轮询发牌，可留空表示全量分配。每次分配都写分配记录，谁在什么时候拿了多少条，事后可查，避免"好线索都进了同一个人手里"的争议。
四个录入入口的显隐由后端配置决定，用于按门店能力裁剪，例如没配通话录音就只留「录音 / 上传 / 输入」。开关只控制按钮显示，不拦接口——历史数据与其它端不会因此失效。
在 Web 后台与员工小程序之外，门店课消提供 AI 自然语言操作入口：用户用日常语言下达指令，AI 解析意图后调用现有后端接口完成教务操作，或生成经营分析与话术建议。把"点十几下菜单"变成"说一句话"。
在 AI 对话框中用自然语言描述诉求，AI 自动识别学员、金额、课包等要素，并经确认后执行——全程复用既有鉴权与角色隔离，超管/销售/辅导老师各按权限行事。
AI 智能端接入 workbuddy 的 Skills 能力，将各教务动作封装为可调用的 skill，由 AI 在对话中按需编排组合调用，对应系统已有的 REST 接口与业务规则（价格快照、退费标记、督学联动等）。
"给张小明充 60 课时秋季班课包 ¥4200"
"给李雷消 2 课时，辅导老师王老师"
"王芳还剩多少有效课时？"
"给赵同学约本周六试听课"
"给陈思远排下周数学督学计划"
"给张小明补昨天的到店打卡"
"今天刷脸和 NFC 签到都有谁？"
"把王小二的卡换绑成 A1B2C3D4"
"把 7 天内到期、剩余≤3 课时的学员加入提醒"
"给王老师周一 19:00 排一节数学课，带上 3 名学员"
"记一笔支出：房租 ¥8000，微信支付"
"生成本周门店流水与转化概览"
"哪些学员 30 天没课消了？"
"给很久没续费的 VIP 写条跟进话术"
"起草一份期末复习督学内容"
"解读本周销售漏斗哪个环节掉量"
"总结刘洋这学期的课消与续费情况"
M1–M21 全部已交付，覆盖教务运营的完整业务面：M1–M19 后端 / Web 后台 / 小程序双端对齐，M20 人脸签到提供 App 端（本地识别）与 Web 后台实时签到（服务端识别），M21 NFC 签到覆盖 App / H5 / 微信小程序并另有 Web 后台键盘口读卡。
机构门店基础信息，启停与删除关联校验，门店出勤配置入口。
✅ 已交付并入用户管理，累计客户/累计耗课课时自动统计。
✅ 已交付核心对象，聚合课包/充值/消费/提醒/标签；支持学员批量迁移。
✅ 已交付三类：课包 COURSE / 储值卡 CARD / 独立产品 SQUIRREL，字段随类型切换。
✅ 已交付新签/续费流水，自动建实例 + 价格快照 + 聊天系统消息；辅导老师可由超管在编辑弹窗改写（须已绑定该学员，已复核锁定）。
✅ 已交付课消流水，支持小数课时、退费标记，按三类项目分别描述；超管行内编辑可改辅导老师与备注（改老师时累计耗课按差值平移）。
✅ 已交付门店流水/销售漏斗/充消/签单/续费率/学员增长/出勤等 30+ 个聚合接口，支持导出 Excel 与绩效表。
✅ 已交付线索 + 沟通明细两层模型；电话 / 录音 / 上传 / 输入四条 AI 录入链路，语音实时逐字转写，AI 输出四段结论并打四档跟进标签；含线索池导入与轮询分配、复核锁定、独立归档页。
✅ 已交付线索与到店转化，转为正式学员，同名同手机号冲突拦截。
✅ 已交付按周计划 + 自定义编组 + 学员×周次矩阵 + 批量状态。
✅ 已交付会话列表 + 共享时间线（备注/图片/系统消息），微信级分页加载。
✅ 已交付到期档 + 剩余课时档（≤3/≤6/≤10）+ 未课消三档区间，个人状态管理。
✅ 已交付流失/次卡/月卡/年卡预置，打标与筛选，标签增长统计。
✅ 已交付账号/姓名/角色切换/改密/头像。
✅ 已交付到店打卡/缺勤（图片或文字），日历热力图 + 按月次数 + 超管补打卡；手工 / 刷脸 / NFC 三种签到共用同一链路与「每日一次」校验。
✅ 已交付免登录 /query，手机号 + 图形验证码查本人项目明细。
复用督学编组表 + 成员课包；班级/学员/课包管理。仅超管与辅导老师可见，销售不可读。
✅ 已交付按日期排课（课程×时段×地点×老师×一组学员，各绑课包）；一键按课包分组批量扣消、缺勤不扣，全部已复核 / 全部撤回（仅超管）；删除排课仅未扣消可删，修改排课为覆盖式通知。
✅ 已交付门店日常收支记账 + 按月经营看板 + 收入口径切换；全局唯一按「用户」鉴权（店主 id=1 恒可见并可邀请超管），销售 / 老师不可访问。
✅ 已交付App 端：端上 YuNet + SFace 本地 1:N 识别、乐观打卡（错误静默、失败撤回）、会话内防重；Web 后台实时签到弹窗：摄像头帧流上传服务端识别，与 App 共用底库与阈值，人脸原图不上云。
✅ 已交付全端（App / H5 / 小程序）+ Web 后台键盘口（HID）读卡器：走 M15 同一打卡链路（文案留「（NFC刷卡）」、卡号留痕）；绑卡随添加学员完成。
✅ 已交付后端 Service 层行级过滤（requireOwnStudent / requireMyPlan 等）+ 前端按角色隐藏入口，双层防护。同一账号可多角色，登录后随时切换。门店账本是全局唯一「按用户而非角色」鉴权的模块；刷脸 / NFC 签到只增加打卡入口，不放大任何数据范围——仍按角色限定到本人客户 / 本人负责学员。
在性能、安全与体验上做了多项工程化设计，支撑真实经营场景下的高并发与数据可信。
/biz/sync 以 since 游标增量拉取，覆盖 8 个业务域；WebSocket /ws/sync 仅传"有变化"轻通知，断线退化为 60s 轮询。实测增量 avg 22ms。
后端 requireOwnStudent / requireMyPlan 等方法级 + 行级过滤，前端 v-permission 隐藏按钮。196 项断言回归 0 失败。
充值/消费/沟通/体验课/督学/聊天系统消息支持"已复核"，已复核记录禁止编辑/删除/撤回，业务记录与聊天消息复核状态双向同步，保证数据可信。
录音时把 16k PCM 以纯 JS 编码实时上行（WebSocket /ws/asr-realtime，先连通道再开麦，避免开头几句话被吞），识别文本逐字回写到明细；暂停时当前这句即定稿，断开前先取快照再决定「收尾定稿」还是「整段落盘转写」。同一条明细只允许一路桥接，后来者会被明确拒绝。
AI 的思考与正文不在请求里干等：服务端把生成快照存进内存流仓库，前端按字符偏移只取增量（r/t/c），800ms 一跳，断网重进也能接着看。相比 SSE 不怕移动端代理截断，也不占长连接；服务重启后未完成的生成改判失败并保留原文，可一键重跑。
安卓微信 / X5 在 hash 路由页选文件后会整页重载，tel: 拨号本身就是一次导航——两者都会冲掉页面内存里的状态。做法是：选文件用单例 input（只降透明度、不重建）并在前后写本地标记，重载后主动补问；拨号改由隐藏 iframe 承载（仅安卓，iOS 仍用 location）；「是否补传录音」的标记应答后才清。
成批线索从 Excel 进池后按数量分配给多名销售，按选择顺序轮询发牌，可留空表示全量；每次分配写分配记录，来源文件与分配去向都可回查。线索从"谁先看到归谁"变成可审计的分配动作。
充值/课消/体验课转正等关键路径用 Redisson 锁串行化，持锁至事务提交后释放，防止并发累计值错乱与超扣课时。
长按系统消息可撤回，在事务内回滚业务影响（删除课包实例、恢复课时、删计划、撤回出勤打卡）；撤回与复核状态互斥，数据始终自洽。
充值/课消/督学/出勤等自动生成系统消息（角标区分充值/消费/退费/计划/到店/缺勤），自动把学员加入销售/辅导/超管会话列表，经营过程一目了然。
进入会话瞬时定位底部、触顶提前预加载并以高度差校正保持视野不抖动；图片按真实宽高预留气泡高度、上传路径 30 天长缓存，头像图片二次进入秒开。
按门店配置图片/文字打卡，图片由后端统一压缩落盘并叠加地址与时间水印；出勤记录以日历热力图 + 按月出勤次数呈现，超管可补打卡、点格取消。
变更集带 preConditions 可重复启动；角色/菜单/演示用户/预置标签种子自举；业务账号由 demo_data.py 运行时自动创建。
门店/课包/标签下拉缓存；验证码、限流、登录防爆破跨实例共享，支持 caffeine 降级回退，支撑水平扩展。
松鼠AI / 培训机构 / 通用三套映射，仅切换界面文案与 tabBar 文字（学员↔会员、课包↔服务包、课时→次），后端接口与字段完全一致。
按日期排课，学员逐人绑定课包、出勤可切换；一键扣消按课包分组批量写消账（复用既有消费流水线），缺勤不扣、余量不足整批拦截；状态显示即将开始、进行中、已扣消、已复核，超管可全部复核与全部撤回。
全系统唯一按用户维度的菜单鉴权（MenuPermissionTreeFilter）：门店账本菜单不绑角色，仅店主与被邀请超管可见，未受邀者菜单不出现且路由不注册，另有接口层兜底拦截。
日常收支手工记账 + 经营看板（净利润/营收/支出 + 支出构成 Top5）；本月营收可按「消账收入 / 进账收入」口径切换——按月份把课消/进账逐条转成收入行在页面复合展示，不落库、不写聊天、不参与复核。
班级/学员/课包一体化管理；辅导老师仅本人班级、超管按老师分栏看全部，销售不可见，与后端行级隔离一致。
YuNet 检测 + SFace 128 维嵌入全部在设备本地（WASM）完成，底库向量随接口下发、本地缓存秒开；识别限频 + 命中退避 + 只吃新鲜快照，避免同步推理饿死检测循环；判定要求「最高分 ≥0.50 且领先第二名 ≥0.08」，把陌生人误签压到最低。
刷脸命中即刻上屏「签到成功」（与已打卡回显同速），打卡请求与照片落盘全部后台异步；任何后端错误不上屏，但必须撤回乐观展示。会话内防重标记不回退，从根上避免「成功→撤回→再识别」死循环。
App 用 Native.js 反射系统 NfcAdapter（不依赖打包时的 NFC 原生模块）、H5 走 Web NFC、小程序走 NFCAdapter、Web 后台支持键盘口（HID）读卡器；卡号按同一规则归一化（去分隔符转大写 HEX），一张卡只能绑一位学员，读卡预查 + 后端兜底双保险。
| 层 | 技术选型 |
|---|---|
| 后端框架 | Spring Boot 3.x + Java 21 |
| ORM / 持久层 | MyBatis-Plus 3.5 + MapStruct（DTO/VO 转换） |
| 数据库 | MySQL 8（生产）/ H2 内存库（开发）；Liquibase 变更集驱动建表与种子 |
| 缓存 / 锁 | Redis（门店/课包下拉缓存 + 分布式锁）+ Caffeine 降级 |
| 实时通知 | Spring WebSocket（/ws/sync 轻通知）+ HTTP 增量同步（/biz/sync） |
| 安全 | Spring Security + JWT（自定义 adminAuthz 方法级鉴权）；免登录查询走图形验证码 + 一次性校验 |
| Web 前端 | Vue 3 + Vite + Naive UI（vue_naive_admin 脚手架） |
| 小程序 | UniApp + @tdesign/uniapp（H5 / 微信小程序 / 安卓 App 三端；人脸签到为 App 专属，NFC 读卡三端均仅 Android） |
| 端侧 AI（人脸） | onnxruntime-web（WASM）+ YuNet 检测 320px / SFace 128 维量化识别；renderjs 视图层取流与推理、逻辑层负责底库与打卡；模型仅打进 App 产物 |
| NFC 读卡 | App：Native.js 反射 Android NfcAdapter（前台分发 + newintent）；H5：Web NFC（NDEFReader，需 HTTPS）；小程序：wx.getNFCAdapter；Web 后台：键盘口（HID）读卡器捕获 + 十进制卡号自动识别（大端 / 字节序反转双候选） |
| 语音识别（ASR） | 阿里云百炼「千问 ASR」，按音频长短自动三档路由：qwen3-asr-flash（同步，短音频）→ qwen3-asr-flash-filetrans（超限转异步长音频，最长 12 小时）→ qwen3-asr-flash-realtime（WebSocket 双向流逐字识别）；开逆文本标准化（「三千八」→「3800」），能同时捕获说话人情感 |