xiaoshu-app/docs/qa/member-credit-ledger-2026-10-14

会员充值与课时流水验收

行为与接口

• ops/users/credit-accounts 返回四类账户、可用/预留、原业务单、trialStatus。
• ops/users/credit-preview 计算成套变动及门店库存，返回 version。
• ops/users/adjust-balance 接收 expectedUpdatedAt=version 和稳定幂等键；direction=add/deduct/adjust。
• 普通 30 分钟按 1:0.5、60 分钟按 1:1 配套充值和原单扣回；旧单据未配套的部分按原单处理。
• 独立调整需要 evidence、adjustSign=add/deduct、adjustMode=paired/single，不调整门店库存。
• ops/users/credit-ledger 按完整历史分组、数据库分页；账户和业务筛选保留同一笔完整明细。导出逐页读取，同一版本和无重复业务单号才生成文件。
• ops/users/import-ledger 仅管理角色可用。服务端从旧 WXAPP 四类账户分页读取，客户端不能提交导入内容。
• 体验资格为 pending/eligible/issued，发放、独立补充、旧入口统一执行数据库限制；退款不重置。旧余额/流水/上课证据存在即视为已发放，缺少完整证据保持待核验。

数据保护

迁移不重算余额或工资。CreditOperation 保存成套业务及请求指纹，子流水保留 CreditTransaction 原有结构；账户和排课使用同一帐套锁。

历史流水以帐套、账户类型、旧 ExpHisID 唯一定位。先写私有服务端原始页备份，再原子导入单个账户并保存回执；原始 score_before 缺失保留 NULL。旧 ScoreType 是原始交易类型，不用于推断账户。旧无时区时间按北京时间解析。不同账户或时间相近的历史条目不合并。

真实余额、课时和工资不因补流水改变；同源内容发生变化时保留现有流水并写冲突。夜间任务新增四类财务分组，成功回执仍须同时验证原九个业务数据集；断点按服务端会员四账户回执恢复。账号身份冲突继续阻止业务同步，单个会员手工核验不能代表整夜成功。

本地验收

• SQL 实例验证成套原子记账、版本过期、原单部分退款、独立调整、预留保护、库存不足、体验一次性、旧入口拒绝重发、重复结课。
• 40 次 30 分钟充值后 40/20；完成一次后 39/19.5；60 分钟及工资/扣费快照一致。
• 历史导入 1,001 条跨页、空前余额、再次导入 0 条、冲突保留、余额不变。
• 管理后台预览后修改内容必须重预览；网络失败保留输入和幂等键。

发布边界

数据库迁移：node scripts/migrate-member-credit-ledger.mjs --apply，凭据通过环境加载，必须设置私有 XIAOSHU_CREDIT_BACKUP_DIR。迁移拒绝仍有有效夜间任务租约的情况；先备份流水、账户、业务单、预留与原函数。

配套发布运营网关、App 网关版本及 direct-v1 财务处理，然后原子更新 Mac LaunchAgent 使用的 worker 文件。学生/老师端和管理后台前端由用户发布。私有备份、真实会员反馈、会话及测试截屏不提交 Git。

生产回读和隔离验收结果见同目录最终记录；任何未通过检查应明确保留，不能以构建通过替代真实验收。

真实发布与回读（2026-10-14）

• 原有任务已退出后暂停本机重试，等待服务端已有租约自然过期；备份后发布数据库迁移、两个运营网关、App 网关与直接同步网关。完成后恢复 LaunchAgent。没有抢占租约或删除有效锁。
• 许诺初中补齐 10 条历史流水（60 分钟、陪练各 5 条，分别 +20、四次 -1）。分账户事务使首次兼容错误只阻止受影响账户；修正旧 Score 大小写差异后补齐剩余 5 条，再次全量读取新增 0。
• 两账户当前余额仍各 16，充值补导前后四账户完全一致；复习工资数量、金额不变。
• 旧陪练流水的 score_before 存在与相邻条目不一致的原始值，原样保留。旧接口没有可靠调整后余额，详情显示“未记录”，没有改写原始证据或倒推余额。
• 修正真实创建会员时空邮箱写入导致 Parse 唯一邮箱冲突的问题；无邮箱时不写邮箱字段。
• 浏览器连接真实后端验证：四账户、10 条历史、60 分钟与陪练各筛选 5 条、明细展开、北京时间排序、Excel 导出 5 行、390 像素窄屏无整页溢出。
• 本地管理端 270 项、移动端 218 项、首次后端全集 195 项通过；新增财务 SQL 和直接同步专项 20 项通过，两个生产构建通过（已有样式预算/CommonJS 警告）。后续真实兼容修正再次通过财务 SQL 测试和云函数语法校验。
• 隔离真实账号验证成套充值、40/20 → 39/19.5、退款与预留并发、充值与完课并发、独立调整、并发体验发放、退回后不能再次领取、流水余额一致和事务审计。测试账号及业务数据执行清理。

私有证据位于 ~/.local/state/xiaoshu/cloud-releases/2026-10-14-member-credit-ledger/，不提交 Git。前端没有代用户发布。夜间全量仍受既有身份冲突阻塞，未宣称完成当晚同步。

• 最终补充真实验收：体验并发预约只成功一次，取消后恢复不消耗体验，结课仅扣 1 次体验、普通账户不变；重复结课不重复扣减；学生端可读取体验充值与消费流水。
• 财务范围仅限已核实旧来源的会员，新系统创建的会员不会凭同名字段被送往旧系统核验。专项测试覆盖财务回执缺失、校验和被修改时拒绝全量完成；保留九个业务数据集原有核验。
• 发布回读：三个网关、直接同步函数与本地代码一致，Mac 独立执行文件一致，LaunchAgent 已加载。最新本机报告仍为 legacy_account_identity_conflict，没有生成虚假的成功回执。
• 统一流水接口实际数据库分页测试：1,001 条记录连续 11 页，业务 ID 无重复无遗漏；账户、日期筛选在分页前生效。