docs(M07-D): 记录会员管理验收并推进顾客端

2026-06-24 16:05:15 +08:00
parent ed0d455083
commit c90f6e34a1
6 changed files with 70 additions and 12 deletions
@@ -0,0 +1,29 @@
+# M07-D members
+
+- 工程 commit：`ed0d455`
+- 数据库迁移：无新增迁移，复用 M02 用户、M03 订单访问、M04 订单、M07 钱包/充值/权益表。
+
+## 新增后台 API
+
+- `GET /admin-api/members`
+  - 权限：有效后台会话，具备 `user.read`、`tenant.manage` 或 `PLATFORM_ADMIN`。
+  - 查询：`page`、`pageSize`、`status`、`search`。
+  - 返回：会员基础信息、脱敏手机号、余额汇总、充值汇总、订单汇总、优惠券和套餐汇总。
+
+- `GET /admin-api/members/:id`
+  - 权限：同会员列表。
+  - 返回：会员聚合档案，并额外返回最近钱包流水。
+
+## 访问范围
+
+- 租户管理员和平台管理员可查看租户内会员。
+- 门店管理员必须具备 `user.read`，且仅能查看在其门店范围内存在钱包账户的会员。
+- 无门店范围的普通员工返回空列表，详情按 `MEMBER_NOT_FOUND` 处理。
+
+## 错误码
+
+- `AUTH_SESSION_INVALID`：会话无效。
+- `MEMBER_READ_FORBIDDEN`：缺少会员查看权限。
+- `INVALID_MEMBER_REQUEST`：参数非法。
+- `MEMBER_NOT_FOUND`：会员不存在或不在当前访问范围。
+
@@ -2,7 +2,7 @@

 > V5.0 首次核验日期：2026-06-16  
 > audited_commit: `4ae9296`
-> next_engineering_target: M07-D 会员管理
+> next_engineering_target: M08-A 顾客端
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。

 ## 总体结论
@@ -35,6 +35,6 @@

 ## 下一步

-1. 进入 M07-D：实现会员画像、注册/最近下单、订单数、消费额、余额、券、套餐和状态聚合。
-2. 继续复用 M07-A 钱包流水、M07-B 充值入账和 M07-C 权益核销状态，会员管理只输出服务端可信聚合。
+1. 进入 M08-A：基于现有微信原生小程序模板接入顾客端首页/选店、门店详情、房间、下单、支付、订单、开门、续费、取消、换房、分享、Wi-Fi、余额、优惠券、套餐和个人中心。
+2. 继续复用 M03 门店发现、M04 订单、M05 支付、M06 设备联动和 M07 会员营销后端能力，不重复初始化小程序。
 3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。
@@ -0,0 +1,25 @@
+# M07-D 会员管理
+
+- 日期：2026-06-24
+- 起始 commit：`239ef4d`
+- 工程 commit：`ed0d455`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE
+
+## 工程增量
+
+- 新增 `MemberProfileService`，聚合会员画像、注册时间、最近登录、订单数、已支付订单数、消费额、最近下单、余额、充值、优惠券和套餐状态。
+- 新增后台会员查询路由 `/admin-api/members` 与 `/admin-api/members/:id`，复用 JWT 会话和 RBAC 访问档案。
+- 门店管理员按 `user.read` 与门店余额账户范围裁剪可见会员；租户管理员和平台管理员可查看租户内会员。
+- 手机号在会员列表和详情中继续脱敏；最近钱包流水只返回业务类型、业务号、金额变化和余额结果，不暴露敏感凭据。
+- 新增 `member-profile-service.test.mjs`，覆盖聚合统计、最近流水、手机号脱敏、租户隔离和门店范围裁剪。
+
+## 验证
+
+- Windows `npm run build`：退出码 0。
+- Windows `node tests/member-profile-service.test.mjs`：退出码 0。
+
+## 后续
+
+游标进入 M08-A 顾客端：基于现有小程序模板接入首页/选店、房间、下单、支付、订单、开门、余额、优惠券、套餐和个人中心。
+
@@ -37,6 +37,7 @@
 | WAL-002 | 门店独立会员余额 | M07-A | DONE | `63711ad` | 已建立租户/门店余额范围策略、现金/赠送双余额账户和不可变流水；充值、赠送、消费、退款、人工调整均预留 entry type；消费按赠送后现金扣款，业务号幂等，余额不足拒绝；Windows 全量后端回归通过。 | - | M07-D 聚合会员余额和权益状态。 |
 | WAL-003 | 余额账单 | M07-A/M08 | PARTIAL | `d9743d3` | 账单底表已包含业务类型、业务号、现金/赠送变动、变动后余额、操作人、trace 和 metadata；M07-B 充值成功后写入真实充值流水。 | 查询 API 和前端账单页面待 M08；优惠券/套餐不直接写钱包流水。 | M08 增加分页查询。 |
 | WAL-004 | 优惠券和套餐权益 | M07-C | PARTIAL | `4ae9296` | 已建立优惠券模板、持券、套餐计划、持有和权益核销流水；支持满减券、时长券、适用门店/房型/房间/星期/节假日、套餐剩余时长/金额，以及订单冻结、确认核销、退回和重复请求幂等；Windows 全量后端回归通过。 | 前端发放/购买/核销入口和订单 API 深度集成待 M08/M04 后续接入。 | M07-D 聚合会员券和套餐状态；M08 接入页面。 |
+| MEM-001 | 会员管理 | M07-D/M08 | PARTIAL | `ed0d455` | 已实现后台会员聚合查询服务和 `/admin-api/members`、`/admin-api/members/:id`；可查看注册/最近登录、订单数、消费额、余额、充值、优惠券、套餐和最近钱包流水，手机号脱敏，租户/门店范围裁剪通过测试。 | 管理员赠券、余额人工调整、禁用、备注和前端页面需在 M08 管理端接入并复用既有审计能力。 | M08-A/C 接入小程序个人中心与后台会员管理页面。 |
 | GRP-001 | 团购券兑换 | M05-C | PARTIAL | `cda640b` | 已实现美团/点评、抖音、快手统一适配器，支持顾客粘贴/扫码值、管理员人工核销、Mock/API 核销、clientRequestId 幂等和券码 SHA-256 存储；重复券不能再次记账，WSL MySQL 8.4.9 实测通过。 | 缺各平台商家 API 授权，未执行真实厂商核销。 | 取得授权后配置 API endpoint/token 并执行真实验券。 |
 | GRP-002 | 美团直订 | M05-C | PARTIAL | `cda640b` | 已实现 HMAC 回调、事件幂等、外部门店/房间映射、未映射人工队列、顾客认领和团购支付订单生成；映射成功订单可进入 PAID。 | 缺美团开放平台授权和真实回调协议确认。 | 取得授权后按厂商协议实现专用签名适配并联调。 |
 | GRP-003 | 管理员验券 | M05-C/M08 | PARTIAL | `cda640b` | 已提供后台人工验券、配置、映射和记录查询 API，门店数据范围校验生效，券码列表只返回脱敏值。 | 管理员小程序扫码界面待 M08，真实平台核销待授权。 | M08 接入扫码界面；授权后切换 API 模式。 |
@@ -52,3 +53,4 @@
 | IOT-004 | Sub-1G 门锁控制 | M06-D | PARTIAL | `d15fd3f` | `CtrlDevice` 开关门、密码/卡片和恢复出厂适配器已实现；危险清空/恢复出厂仅平台管理员加确认短语；record 内容哈希脱敏，低电量及 timeout/full/unconfirm 告警。 | 缺 701C/701G 实物及密码/卡片现场验收。 | M06-G 完成实物控制与故障场景。 |
 | IOT-005 | 智慧插座接入 | M06-E | PARTIAL | `9144fa8` | `basicInfo/workInfo` 查询、`on/off`、`localtask/clearTask` 已通过适配器、命令持久化和后台 API 接入；本地任务限制 20 条；过载、过温、过流、过压/欠压、功率和温度阈值写入设备告警；Windows 全量后端回归通过。 | 缺 4G 智慧插座实物、DeviceID、生产 MQTT 账号/ACL 和现场负载，未执行真实计量与保护断电联调。 | M06-F 接入订单自动联动；M06-G 完成实物计量、开关、本地任务和保护事件矩阵。 |
 | IOT-008 | 设备告警与离线 | M06/M10 | PARTIAL | `d01f771` | `/devicewill/{DeviceID}` 可更新离线状态；低电量、timeout/full/unconfirm、插座过载、过温、过流、过压/欠压、功率和温度阈值可写入开放告警；订单联动任务失败会进入异步任务重试/补偿；真实硬件烟测运行器可等待 ACK 并输出 JSON 报告。 | 缺真实硬件离线、保护断电、任务结束和弱信号事件矩阵。 | 取得实物和生产 MQTT 账号后执行硬件烟测矩阵；当前旁路进入 M07-A。 |
+
@@ -2,12 +2,12 @@

 ```yaml
 execution_cursor:
-  current_module: M07
-  current_stage: M07-D
+  current_module: M08
+  current_stage: M08-A
  stage_status: TODO
-  last_completed_stage: M07-C
-  next_stage: M07-D
-  last_engineering_commit: 4ae9296
+  last_completed_stage: M07-D
+  next_stage: M08-A
+  last_engineering_commit: `ed0d455`
  last_push_verified: true
  base_branch: main
  blocked_reason: "M06-G 真实硬件联调缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线；已完成烟测运行器并按 BLOCKED_EXTERNAL 旁路。"
@@ -23,7 +23,8 @@ execution_cursor:
 | M04 订单、时段锁定、支付闭环 | DONE | `91801fe` | docs/devlogs/2026-06-20-M04-D-订单分享.md | M04-A/B/C/D 已完成可信定价、并发预占、订单状态机、续费取消换房、管理员调整、代下单和最小权限分享；Windows 全量回归与 WSL MySQL 8.4.9 模块回归通过。 |
 | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 |
 | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `d01f771` | docs/devlogs/2026-06-24-M06-G-真实硬件联调.md | M06-A 至 F 已完成 MQTT、拓扑、协议幂等、控制箱、Sub-1G 门锁、智慧插座和订单自动联动任务；M06-G 已补真实硬件烟测运行器，缺生产 MQTT 账号/ACL、DeviceID 和实物配线，保持 BLOCKED_EXTERNAL。 |
-| M07 会员、余额、充值、优惠券和套餐营销 | PARTIAL | `4ae9296` | docs/devlogs/2026-06-24-M07-C-优惠券和套餐.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；继续 M07-D 会员管理。 |
+| M07 会员、余额、充值、优惠券和套餐营销 | DONE | `ed0d455` | docs/devlogs/2026-06-24-M07-D-会员管理.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；M07-D 已完成会员画像、订单、消费、余额、充值、优惠券和套餐聚合查询。 |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |
+