#微信小程序技术说明

核对日期：2026-10-14；代码基线见本轮更新说明。顾客操作、店长工作台和恢复师工作台按实际发布使用。

#页面与调用结构

spa-wxapp 使用原生 JavaScript、CommonJS、WXML、WXSS，无独立 npm 构建。当前 app.json 注册 45 页：主包 16 页，活动 2 页、礼券 4 页、员工 13 页、培训 10 页。

页面通过 utils/api.js → utils/request.js → spa-backend 调用，复用 auth、store、selected-store、booking、payment 及 ui-error 工具。当前 app.js 默认 API 为 https://api.afuspa.com，本地启动同样可能访问线上，不能当作隔离环境。

#身份与门店

微信 code 由后端兑换会话并签发业务令牌。请求层统一处理 Authorization、X-Member-Id 和门店上下文；会员号及客户端选店不构成授权凭证。

顾客选店、员工管理门店及培训角色范围分别管理。多角色账号可切视角，总部或多店店长需显式选择当前管理门店，后端仍按可信角色与授权范围校验。老师、校长、学员由培训绑定识别，不因员工岗位名称自动获得。

请求返回 HTTP 错误或 success=false 时抛出带 code、requestId、statusCode 的错误。现有令牌导致 401 时清会话并重试一次，不把这一分支说成自动重新完成微信登录。页面应区分无权限、加载失败和空数据。

#预约、支付与商城

预约袋当前最多 9 个基础项目，整单额外服务最多 6 项；具体资源、价格、项目可见性及券优惠由后端校验。同项目重复添加须保留明细身份，逐项偏好及存油选择不被合并丢失。

商城提交前等待登录与手机号绑定完成，绑定导致会员合并后重新报价。支付取消、超时和响应丢失沿原订单恢复，最终付款依据服务端查询和回调，不以 wx.requestPayment 回调直接结清。

货架含旧单独订单和合单协议，主支付及子单分摊分别展示；一次付款不代表所有子单已经履约。普通商品提货、货架商品核销、服务使用各有原单与幂等约束。

#项目履约与换项

换项入口为 POST /api/staff/manager/orders/{bookingId}/projects/{projectItemId}/replace。不自动补差、退款、派新师或重排资源；原券失败整笔回滚，不静默弃券。

#结算、券与核销

店长可选方式由本单服务端条件决定：原方式、本人积分、现金、他人代付、团购、平台、产品积分、权益活动或体验完单等。已有付款及扣分不重复处理，商品赠分、服务扣分、库存、存油和券需按正式事务协作。

产品积分结算与权益活动结算保留既有 mall、mall_campaign 编码，名称变化不迁移历史金额。体验单零额完单保留真实权益和钟数，不能按普通单任意撤销返券。

权益活动符合条件时携带可选 redemptionCodeId，服务单与本店未核销码在同一事务保存；重复成功请求不重复核销，冲正保留已用码事实。码不能在已完成单事后补选。

积分在不同接口可能使用分值或百分之一积分单位，以对应 DTO 契约为准；人民币 amountCent 与积分 minor 字段不能混算。存油是商品件数，不是货币余额。

#培训与外部学习

小程序培训详情返回图文投影，不暴露视频播放能力；源教材版本及历史视频证据保留。外部浏览器学习通过 60 秒一次性链接兑换独立会话，原小程序 token 不进入链接，网页会话最长 2 小时且不超过原会话有效期。

学员自己、老师负责关系及校长授权范围在后端校验；心跳记录前台浏览及实际播放，不能自动换学分或考勤。网页协议、迁移和代理需成套发布，详见H5 技术说明。

#检查与发布

专项命令以仓库实际 tools 为准，例如：

node tools/manager-replace-project-check.js
node tools/therapist-no-accept-check.js
node tools/manager-redemption-code-check.js
node tools/wxml-compile-check.js

Node 专项不等同视觉验收。微信工具编译、原生授权、支付、外部浏览器播放、域名及真机需按影响范围单独验证。培训、券、货架及履约变化通常先完成数据库和兼容后端，再发布中台及小程序，保留旧版本窗口。

本次仅重写文档，未执行上述业务回归、真机操作或部署。