qipai/docs/devlogs/2026-06-24-M08-A-顾客端.md

# M08-A 顾客端

## 本次工程增量

- 后端新增顾客端公开门店详情和房间列表接口：`GET /app-api/stores/:storeId`、`GET /app-api/stores/:storeId/rooms`，继续通过 `x-wechat-appid` 与可选 `tenant-id` 解析租户，房间只返回未删除且启用的公开数据。
- 小程序新增登录态封装，所有需登录接口自动携带 `Authorization: Bearer <token>`；首页门店卡片可进入门店详情。
- 门店详情页加载门店资料、公开房间列表和受控 Wi-Fi；Wi-Fi 只在登录后请求 `/app-api/stores/:storeId/wifi`。
- 房间详情页接入报价、预占、测试支付创建和测试支付回调完成，形成顾客端下单链路的本地可验证入口。
- 新增 `scripts/check-miniapp-m08-a.mjs`，检查小程序页面注册、固定生产 API 域名、登录和 M08-A 关键接口调用。

## 验收结果

- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `npm run build`（`backend/`）：PASS。
- `node tests/store-discovery.test.mjs`：PASS。
- `node tests/pricing.test.mjs`：PASS。
- `node tests/payment.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

## 状态

M08-A 仍为 `PARTIAL`。本次完成顾客端第一段工程闭环，但订单列表、开门、续费、取消、换房、分享、余额、优惠券、套餐、个人中心、生产微信支付调起和真机合法域名验证仍未完成，游标继续停留在 M08-A。

## 提交

- 工程提交：`4ac2c96`
- 远端校验：push 后执行 `HEAD == origin/main`。

## 2026-06-24 续接：订单列表与详情

- 后端新增顾客端订单查询服务和路由：`GET /app-api/orders`、`GET /app-api/orders/:orderId`，按本人 `qipai_order_user_access` 与门店管理范围裁剪数据。
- 小程序新增 `pages/orders/list` 与 `pages/orders/detail`，可查看我的订单、订单详情、状态历史、取消测算和取消订单入口；房间预占成功后可直接进入订单详情。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查订单页注册和订单相关真实 API 调用。

验收：

- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；开门、续费、换房、分享、余额、优惠券、套餐、个人中心、真实微信支付调起和真机合法域名验证待继续。

## 2026-06-24 续接：顾客端开门入口

- 后端新增顾客订单开门权限仓储，`GET/POST` 链路只允许本人未撤销订单、订单状态为 `PAID/RESERVED/IN_PROGRESS` 且处于开始前 30 分钟到结束时间之间的订单开门。
- 新增 `POST /app-api/orders/:orderId/open-door`，按订单上下文构造最小 `device.write` 权限并调用现有门控服务；顾客端强制 `holdopen=0`，不暴露后台设备控制接口。
- 小程序订单详情页新增“开门”按钮，调用订单绑定的 app-api 开门入口。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查 `open-door` 调用。

验收：

- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/device-control.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；续费、换房、分享、余额、优惠券、套餐、个人中心、真实微信支付调起和真机合法域名/实物开门验证待继续。

## 2026-06-25 续接：顾客端续费、换房与分享

- 后端新增顾客专用订单调整入口：`POST /app-api/orders/:orderId/renew` 与 `POST /app-api/orders/:orderId/change-room`。
- 顾客续费只允许本人未撤销订单访问，继续复用服务端时段冲突、状态和价格计算；顾客换房额外限制目标房间必须属于原订单门店，避免跨门店改单。
- 小程序订单详情页新增续费分钟、换房目标房间 ID、分享有效期输入；续费/换房调用真实 app-api 并显示差价，分享调用 `POST /app-api/orders/:orderId/shares` 生成临时口令。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查 `/renew`、`/change-room` 和 `/shares` 调用。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/order-management.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；余额、优惠券、套餐、个人中心、生产微信支付调起、真机合法域名和实物开门验证待继续。

提交：

- 工程提交：`874b9b8`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：顾客端个人中心

- 后端新增 `MemberProfileService.getMyProfile`，按当前登录顾客读取本人资料、余额、优惠券/套餐汇总、充值消费摘要和最近钱包账单。
- 新增 `GET /app-api/profile`，校验登录态与 `profile.read` 权限，只返回当前用户本人数据；同时补上生产 `server.ts` 中的会员路由注册。
- 新增 `backend/tests/member-profile-route.test.mjs`，覆盖正常读取、未登录拒绝和缺少 `profile.read` 拒绝。
- 小程序新增 `pages/profile/index` 个人中心页，展示总余额、现金/赠送余额、可用券、套餐、套餐分钟、充值消费摘要和最近账单；首页新增个人中心入口。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查个人中心页面注册、`/profile` 调用和余额/权益/账单绑定。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/member-profile-route.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；优惠券/套餐明细页、充值入口、生产微信支付调起、真机合法域名和实物开门验证待继续。

提交：

- 工程提交：`7446852`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：顾客端充值入口

- `RechargeService` 新增可用充值计划查询，按租户、有效期、启用状态和可选门店过滤。
- 后端新增 `GET /app-api/recharge/plans` 与 `POST /app-api/recharge/orders`，顾客登录后可查看充值计划并创建幂等充值单。
- 生产 `server.ts` 接入 `RechargeService` 与 `WalletLedgerService`，充值路由随真实后端启动注册。
- 新增 `backend/tests/recharge-route.test.mjs`，覆盖充值计划查询、顾客充值单创建和非法请求拒绝。
- 小程序新增 `pages/recharge/index`，个人中心新增充值入口，可展示实付/赠送/到账金额并创建待支付充值单。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查充值页面注册、`/recharge/plans` 与 `/recharge/orders` 调用。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/recharge-route.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；优惠券/套餐明细页、充值微信支付调起、订单生产微信支付调起、真机合法域名和实物开门验证待继续。

提交：

- 工程提交：`dbdfe3d`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：顾客端权益明细与微信支付调起

- 后端 `MemberProfileService` 新增 `getMyBenefits`，按当前登录顾客读取本人优惠券和套餐持有明细，返回状态、金额、分钟、剩余次数、有效期、适用范围和冻结订单，不暴露其他用户权益。
- 新增 `GET /app-api/profile/benefits`，复用登录态和 `profile.read` 权限校验，只允许读取当前用户本人权益。
- `backend/tests/member-profile-service.test.mjs` 与 `backend/tests/member-profile-route.test.mjs` 扩展覆盖权益明细查询和本人鉴权。
- 小程序新增 `pages/benefits/index` 权益明细页，个人中心新增入口，可展示优惠券和套餐的可用/锁定/已用尽状态、金额、分钟、有效期和适用范围。
- 小程序 `utils/api.js` 新增 `requestWechatPayment`，房间下单页新增“微信支付”按钮：先创建 `WECHAT` 支付单，再调用 `/pay/wechat/prepay`，仅在后端返回真实预支付参数后调用 `wx.requestPayment`；测试支付路径保留。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查权益页注册、`/profile/benefits`、`/pay/wechat/prepay` 和 `wx.requestPayment`。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/member-profile-service.test.mjs`：PASS。
- `node tests/member-profile-route.test.mjs`：PASS。
- `node tests/marketing-benefit-service.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。
- `powershell -ExecutionPolicy Bypass -File scripts\dev\windows\test-all.ps1`：PASS。

状态：

- M08-A 仍为 `PARTIAL`；充值微信支付调起、余额/套餐/优惠券下单抵扣深度集成、真机合法域名、真实微信支付和实物开门验证待继续。

提交：

- 工程提交：`e24920c`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：顾客端充值微信支付调起

- 数据库新增 `2026062524_m08a_recharge_wechat` 迁移，为 `qipai_recharge_orders` 增加微信预支付 ID、微信交易号、回调幂等 ID 和脱敏通知 JSON，避免把充值单伪造成订单支付。
- `RechargeService` 新增 `createWechatPrepay` 和 `processWechatNotification`，充值预支付复用微信支付配置、顾客 openid 和 JSAPI 参数生成；微信通知验签解密后按充值单号入账，重复通知不重复加余额。
- `POST /app-api/recharge/orders/:rechargeOrderId/wechat-prepay` 暴露给小程序，校验当前登录顾客只能为本人充值单调起支付。
- `POST /app-api/recharge/wechat/notify` 新增充值微信支付通知入口，通知 payload 入库前移除 `payer`。
- 小程序充值页新增“微信支付”按钮，创建充值单后可调起微信支付；到账结果以后端通知和个人中心余额为准。
- 迁移 runner 白名单纳入新迁移，并补充 API/DB changelog。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `node tests/recharge-service.test.mjs`：PASS。
- `node tests/recharge-route.test.mjs`：PASS。
- `node tests/migration-contract.test.mjs`：PASS。
- `node tests/migration-runner.test.mjs`：PASS。
- `node tests/wechat-pay.test.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；余额/套餐/优惠券下单抵扣深度集成、真机合法域名、真实微信支付和实物开门验证待继续。

提交：

- 工程提交：`53f5d67`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：顾客端权益与余额下单抵扣

- `PricingRepository.reserve` 接入优惠券/套餐权益冻结：顾客预占订单时可传入优惠券发放 ID、套餐持有 ID、套餐分钟和套餐金额抵扣，后端先按服务端价格创建预占，再在同一数据库事务中冻结权益、重算价格快照和订单应付金额。
- `MarketingBenefitService` 与 `WalletLedgerService` 新增事务内复用方法，供订单预占、支付成功和取消释放共享同一事务边界。
- `PaymentRepository` 新增余额支付闭环：顾客创建 `BALANCE` 支付单时跳过外部支付配置，按门店钱包先赠送后现金扣款，支付单立即成功并推进订单；测试支付与微信支付成功回调统一确认冻结权益。
- `OrderStateRepository` 在订单取消、关闭、退款完成等释放预占/撤销权限的状态路径中释放仍处于冻结状态的优惠券和套餐。
- 微信支付通知成功路径复用统一支付成功结算，避免测试支付和微信支付两条路径对权益确认逻辑分叉。
- 小程序房间页新增优惠券 ID、套餐 ID、套餐分钟、套餐抵扣金额输入和“余额支付”按钮；预占时携带权益参数，支付后可直接进入订单详情。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查权益下单字段和余额支付入口。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；真机合法域名、真实微信支付、实物开门验证，以及权益选择器的可视化列表仍待继续。

提交：

- 工程提交：`dda2b3c`
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

## 2026-06-25 续接：权益可视化选择器

- 小程序房间页进入时读取 `GET /app-api/profile/benefits`，按当前门店和房间过滤可用优惠券与套餐，展示为可点选卡片，替代手工输入权益 ID。
- 优惠券选择支持再次点击取消；套餐选择后自动填入可用分钟和可用金额，仍允许顾客调整本次使用分钟与抵扣金额。
- 小程序下单 payload 继续只提交权益 ID、套餐使用量和幂等请求号，不接受客户端自报价格。
- 后端预占重算时补充时长券折价：`TIME` 优惠券按当前锁价单价和券分钟折算为订单折扣，满减券、套餐金额抵扣继续走服务端 clamp。
- `scripts/check-miniapp-m08-a.mjs` 扩展检查权益列表、选择事件、`/profile/benefits` 和余额支付入口。

验收：

- `npm run build`（`backend/`）：PASS。
- `node scripts/check-miniapp-m08-a.mjs`：PASS。
- `npm test`（`backend/`）：PASS。

状态：

- M08-A 仍为 `PARTIAL`；真机合法域名、真实微信支付和实物开门验证待继续。

提交：

- 工程提交：`4701674`。
- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。