门店课消
教培机构数字化运营管理平台
「门店课消」是一套面向教培机构的数字化运营管理工具，将门店、员工、学员（会员）、充值项目（课包 / 储值卡 / 独立产品）、进账流水、消账记录、销售沟通、体验预约、督学规划、我的班级、课程排课、学员出勤与三种签到通道（手工 / 刷脸 / NFC）、门店账本、提醒与标签等核心业务全量数字化。其最大的设计特点是类微信对话式交互——所有业务操作（充值、课消、督学、出勤打卡、备注）都以消息形式沉淀在学员对话流中，大幅降低使用门槛。
从线索到续费、再到门店经营记账，全链路闭环管理，每个环节的数据自动回流到学员对话流。
销售沟通跟进线索（加微 → 诺访 → 到店 → 体验课 → 转化），体验课预约到店转化，一键转为正式学员。
购买课包 / 储值卡 / 独立产品，自动生成实例与价格快照，实时累加累计充值。
按日期排课（课程×时段×地点×老师×学员），一键按课包分组批量扣消，缺勤不扣；亦可单笔课消/核销，支持退费标记。
三种通道共用一条打卡链路：手工打卡（按门店配置图片 / 文字）、App 端刷脸签到（本地识别、命中即签）、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 端刷脸签到（本地 1:N 识别、命中即签）、NFC 刷卡签到（App / H5 / 微信小程序三端）三条通道，全部复用同一条出勤链路：每日一次校验、角色数据隔离、聊天系统消息留痕、签到明细可撤销。
按门店出勤配置执行：图片打卡（后端统一压缩并叠加门店水印文字与时间）或文字打卡（模板支持学员姓名变量）。缺勤填写原因；超管可补打卡、可取消打卡。
前台设备对准摄像头持续检测，端上完成检测 → 对齐 → 128 维向量 → 1:N 比对，命中即提示「XX 签到成功」并震动。识别全链路在设备本地完成，人脸原图不上云。
学员持 IC 卡贴读卡设备完成签到，后端按卡号定位学员并走同一打卡链路（文案追加「（NFC刷卡）」）。一卡一学员，重复绑卡当场提示对方学员；绑定随添加学员完成，换绑在学员信息页。
先读本地底库缓存立即可用，同时后台拉最新底库（向量 + 各学员门店的打卡方式一并下发，打卡前不再串行查接口）。
页面挂载即初始化检测 / 识别引擎，与摄像头启动并行，压缩首帧识别前的空白期；不满足条件（无权限、底库为空）直接给明确遮罩文案。
逐帧检测人脸框与关键点，多脸按面积取最大；脸太小提示「请靠近一点」。状态位常驻刷新，绝不让操作者面对"什么都没发生"。
关键点对齐 112×112 取 128 维向量，限频 + 命中退避 + 只吃新鲜快照，识别绝不阻塞检测。
余弦相似度 ≥ 0.50 且领先第二名 ≥ 0.08 才判同一人；立即提示「XX 签到成功」+ 震动 + 记入本次签到列表（零网络等待）。
打卡请求（含命中帧编码落盘）后台异步提交；任何后端错误不上屏，但会静默撤回乐观展示，考勤以后端落库为准。
进页默认展示本次会话（人脸与同步 NFC 记录混排，可搜索、可取消签到）；点「历史」切换为全量签到记录——人脸（附照片与相似度）、NFC（蓝标签）、手动（灰标签）按日期分组、分页加载。取消签到联动清理人脸 / NFC 两个签到页的本次列表。
添加学员 / 学员信息页拍照 → 本地检测对齐取向量 → 与底库查重（相似度过高提示「疑似重复录入」）→ 向量随学员新增 / 修改落库。人脸签到页的底库人数卡点一下即可重载底库，无需退出页面。
在 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 端专属，M21 NFC 签到覆盖 App / H5 / 微信小程序。
机构门店基础信息，启停与删除关联校验，门店出勤配置入口。
✅ 已交付并入用户管理，累计客户/累计耗课课时自动统计。
✅ 已交付核心对象，聚合课包/充值/消费/提醒/标签；支持学员批量迁移。
✅ 已交付三类：课包 COURSE / 储值卡 CARD / 独立产品 SQUIRREL，字段随类型切换。
✅ 已交付新签/续费流水，自动建实例 + 价格快照 + 聊天系统消息；辅导老师可由超管在编辑弹窗改写（须已绑定该学员，已复核锁定）。
✅ 已交付课消流水，支持小数课时、退费标记，按三类项目分别描述；超管行内编辑可改辅导老师与备注（改老师时累计耗课按差值平移）。
✅ 已交付门店流水/销售漏斗/充消/签单/续费率/学员增长/出勤等 30+ 个聚合接口，支持导出 Excel 与绩效表。
✅ 已交付销售跟进过程记录，加微/诺访/到店/体验/转化标记，自动计序号。
✅ 已交付线索与到店转化，转为正式学员，同名同手机号冲突拦截。
✅ 已交付按周计划 + 自定义编组 + 学员×周次矩阵 + 批量状态。
✅ 已交付会话列表 + 共享时间线（备注/图片/系统消息），微信级分页加载。
✅ 已交付到期档 + 剩余课时档（≤3/≤6/≤10）+ 未课消三档区间，个人状态管理。
✅ 已交付流失/次卡/月卡/年卡预置，打标与筛选，标签增长统计。
✅ 已交付账号/姓名/角色切换/改密/头像。
✅ 已交付到店打卡/缺勤（图片或文字），日历热力图 + 按月次数 + 超管补打卡；手工 / 刷脸 / NFC 三种签到共用同一链路与「每日一次」校验。
✅ 已交付免登录 /query，手机号 + 图形验证码查本人项目明细。
复用督学编组表 + 成员课包；班级/学员/课包管理。仅超管与辅导老师可见，销售不可读。
✅ 已交付按日期排课（课程×时段×地点×老师×一组学员，各绑课包）；一键按课包分组批量扣消、缺勤不扣，全部已复核 / 全部撤回（仅超管）；删除排课仅未扣消可删，修改排课为覆盖式通知。
✅ 已交付门店日常收支记账 + 按月经营看板 + 收入口径切换；全局唯一按「用户」鉴权（店主 id=1 恒可见并可邀请超管），销售 / 老师不可访问。
✅ 已交付App 端专属：端上 YuNet + SFace 本地 1:N 识别、命中即签的乐观打卡（错误静默、失败撤回）、会话内防重；底库随接口下发秒开，人脸原图不上云。
✅ 已交付 · 仅 App全端：学员持卡贴设备即签到，走 M15 同一打卡链路（文案留「（NFC刷卡）」、卡号留痕）；绑卡随添加学员完成，换绑在学员信息页编辑弹层。
✅ 已交付 · 全端后端 Service 层行级过滤（requireOwnStudent / requireMyPlan 等）+ 前端按角色隐藏入口，双层防护。同一账号可多角色，登录后随时切换。门店账本是全局唯一「按用户而非角色」鉴权的模块；刷脸 / NFC 签到只增加打卡入口，不放大任何数据范围——仍按角色限定到本人客户 / 本人负责学员。
在性能、安全与体验上做了多项工程化设计，支撑真实经营场景下的高并发与数据可信。
/biz/sync 以 since 游标增量拉取，覆盖 8 个业务域；WebSocket /ws/sync 仅传"有变化"轻通知，断线退化为 60s 轮询。实测增量 avg 22ms。
后端 requireOwnStudent / requireMyPlan 等方法级 + 行级过滤，前端 v-permission 隐藏按钮。196 项断言回归 0 失败。
充值/消费/沟通/体验课/督学/聊天系统消息支持"已复核"，已复核记录禁止编辑/删除/撤回，业务记录与聊天消息复核状态双向同步，保证数据可信。
充值/课消/体验课转正等关键路径用 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；卡号按同一规则归一化（去分隔符转大写 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 |