xiaoshu-app/docs/qa/store-credit-phase-one-2026-10-15.md

门店额度第一阶段验收（2026-10-15）

交付范围

总部为门店增加 30 分钟课时、60 分钟课时、体验次数、陪练小时；门店独立登录及数据隔离属于后续阶段。

• 门店列表增加「充值额度」入口，详情页顶部显示四个账户的余额、预留和可用额度。
• 单次填写四项增量，零值不提交；服务器先计算变动预览，再统一入账。课时及体验次数为整数，陪练小时最多两位小数。
• 超级管理员可操作，运营管理员须单独授权；授权与撤销必须填写原因并记录审计。其他角色不能充值。
• 四项余额、凭据及操作日志在同一事务保存。请求编号防重复，余额发生变化后必须重新预览。
• 流水支持账户、业务和日期筛选、分页与 Excel 导出。纠错关联原总部入账凭据，累计不得超过原入账，且不能扣回已经划拨或预留的额度。
• 学生开课、充值划拨、排课预留与结课扣减规则保持原有行为。
• 旧单账户客户端仍能使用原接口；发布前已经提交成功的请求跨版本重试时返回原凭据，不再次入账。

验证结果

1. node --test scripts/tests/store-credit.test.mjs scripts/tests/member-credit-ledger.test.mjs scripts/tests/member-enrollment.test.mjs scripts/tests/member-enrollment-gateway.test.mjs：44 项通过。
2. 管理端门店相关 Angular 测试：11 项通过。覆盖四项预览、提交、重复点击、超时重试、输入变化、授权与既有门店页面。
3. npm run build:admin：成功；现有样式预算和 CommonJS 警告不影响构建。
4. npm run cloud:validate：11 个云函数定义通过。
5. Chrome 本地管理端连接线上接口验收：门店列表充值入口、四项真实服务端预览、权限名单、详情顶部账户、流水读取、Excel 下载均成功；1440px 与 390px 视口无弹窗横向溢出；无页面运行错误。
6. 浏览器验收主动拦截充值和授权写入接口，实际写入次数为 0。选择的门店现有流水为空，验证了空结果及 Excel 下载；有数据的流水筛选与归并由数据库及组件回归覆盖，未伪造历史流水。
7. 真实数据库事务验证：四项入账、凭据数量和幂等重试通过，事务主动回滚。验证结束后测试凭据、正式充值操作及授权记录均未新增，部署前后门店余额摘要一致。
8. 发布后线上回读：账户四项、充值资格、流水及可授权运营管理员名单接口正常。流水与权限读取单次约 1.4–1.5 秒，仅为本次回读结果，不代表性能基准。

PGlite 的并发请求测试验证请求防重，但其串行执行不等同于真实多连接压力测试。本次不包含实际生产充值、真实账号授权、手机或微信 WebView 验收。

发布与迁移

• scripts/sql/store-credit.sql 为增量迁移，新增授权、授权审计、幂等操作表及数据库函数；不重写存量余额、课时或历史凭据。
• SQL 和两个现有运营网关已发布。发布先保存真实线上函数及 SQL 基线，以哈希核对基线后定点替换，发布后再次回读。
• 旧客户端账户接口保留 transactions；新账户概览使用 summaryOnly:true 减少不必要明细读取。
• 前端在本地 http://127.0.0.1:4300/admin/stores 可用，生产构建已验证；本轮未部署独立的生产前端站点。
• 发布证据及受保护基线保存在本机 /Users/mac/.local/state/xiaoshu/cloud-releases/2026-10-15-store-credit/，不提交凭据或线上完整函数快照到 Git。

回滚

前端可回退此次组件及入口改动；后端应依据发布目录保存的实际基线恢复本次修改的函数段，先核对线上哈希，避免覆盖后续他人发布。保留新增表、收入/额度凭据、授权审计和幂等约束，不以删除数据的方式回滚。若已经发生正式充值，余额和原凭据必须保留，纠正通过关联原单的调整操作完成。旧网关如不包含新权限校验，应暂停门店充值写入后再恢复，防止撤销本次授权限制。