From c90f6e34a18ddf81eb26e6a2cbd5648e7c58f494 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 24 Jun 2026 16:05:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(M07-D):=20=E8=AE=B0=E5=BD=95=E4=BC=9A?= =?UTF-8?q?=E5=91=98=E7=AE=A1=E7=90=86=E9=AA=8C=E6=94=B6=E5=B9=B6=E6=8E=A8?= =?UTF-8?q?=E8=BF=9B=E9=A1=BE=E5=AE=A2=E7=AB=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 7 +++-- .../api-changelog/2026-06-24-M07-D-members.md | 29 +++++++++++++++++++ docs/current-baseline.md | 6 ++-- docs/devlogs/2026-06-24-M07-D-会员管理.md | 25 ++++++++++++++++ docs/feature-status.md | 2 ++ docs/module-status.md | 13 +++++---- 6 files changed, 70 insertions(+), 12 deletions(-) create mode 100644 docs/api-changelog/2026-06-24-M07-D-members.md create mode 100644 docs/devlogs/2026-06-24-M07-D-会员管理.md diff --git a/README.md b/README.md index 90abe3d..6c4e9f0 100644 --- a/README.md +++ b/README.md @@ -120,9 +120,9 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running 项目已开发部分模块。具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。 -- 当前执行游标：`M07-D` -- 最近工程提交：`4ae9296`，完成 M07-C 优惠券和套餐权益底座，支持持券/持套餐、订单冻结、确认核销、退回和重复请求幂等。 -- 下一工程目标：M07-D 会员管理。 +- 当前执行游标：`M08-A` +- 最近工程提交：`ed0d455`，完成会员聚合查询服务和后台会员 API，支持订单、消费、余额、充值、优惠券、套餐和最近流水汇总。 +- 下一工程目标：M08-A 顾客端。 ## 版本递进 @@ -136,3 +136,4 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running ```text 请阅读 V5.4.md，按当前进度继续开发。 ``` + diff --git a/docs/api-changelog/2026-06-24-M07-D-members.md b/docs/api-changelog/2026-06-24-M07-D-members.md new file mode 100644 index 0000000..c7782ee --- /dev/null +++ b/docs/api-changelog/2026-06-24-M07-D-members.md @@ -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`：会员不存在或不在当前访问范围。 + diff --git a/docs/current-baseline.md b/docs/current-baseline.md index 7093f99..1e77ed8 100644 --- a/docs/current-baseline.md +++ b/docs/current-baseline.md @@ -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 和现场实物配线。 diff --git a/docs/devlogs/2026-06-24-M07-D-会员管理.md b/docs/devlogs/2026-06-24-M07-D-会员管理.md new file mode 100644 index 0000000..bafdf82 --- /dev/null +++ b/docs/devlogs/2026-06-24-M07-D-会员管理.md @@ -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 顾客端：基于现有小程序模板接入首页/选店、房间、下单、支付、订单、开门、余额、优惠券、套餐和个人中心。 + diff --git a/docs/feature-status.md b/docs/feature-status.md index cd49eda..3960e15 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -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。 | + diff --git a/docs/module-status.md b/docs/module-status.md index 59cc7f5..f3e2941 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -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 | - | - | - | +