diff --git a/README.md b/README.md index 41ce490..86d2a37 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` 为准。 -- 当前执行游标：`M05-D` -- 最近工程提交：`cda640b`，完成 M05-C 团购验券、第三方直订和人工处理队列。 -- 下一工程目标：M05-D 分账和门店收款配置。 +- 当前执行游标：`M06-A` +- 最近工程提交：`1680d73`，完成 M05-D 收款账户、接收方、比例策略和幂等分账。 +- 下一工程目标：M06-A Broker 与 MQTT 基础。 ## 版本递进 diff --git a/docs/api-changelog/2026-06-22-M05-D-profit-sharing.md b/docs/api-changelog/2026-06-22-M05-D-profit-sharing.md new file mode 100644 index 0000000..d3c2725 --- /dev/null +++ b/docs/api-changelog/2026-06-22-M05-D-profit-sharing.md @@ -0,0 +1,9 @@ +# M05-D 分账与收款配置 API + +- `PUT /admin-api/pay/collection-account`：维护租户/门店收款账户和授权状态。 +- `PUT /admin-api/pay/profit-share-receiver`：维护脱敏分账接收方及环境引用。 +- `PUT /admin-api/pay/profit-share-policy`：维护全局或门店比例策略。 +- `POST /admin-api/pay/profit-shares`：对成功微信支付发起幂等分账。 +- `GET /admin-api/pay/profit-shares`：查询账户、接收方、策略和分账记录。 + +以上接口只允许租户管理员或平台管理员调用。 diff --git a/docs/configuration.md b/docs/configuration.md index 4a20bf9..9f9cfa4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -69,6 +69,9 @@ MYSQL_DATABASE=<以项目实际数据库名为准> - 真实值只写入 `/etc/qipai/qipai.secrets` 或本地 Git 忽略配置，权限 `600`；商户私钥、APIv3 Key 和平台证书正文不得进入 Git、日志或前端包。 - 支付配置 `settings` 可登记 `description`、`paymentNotifyUrl`、`refundNotifyUrl`；未登记时固定回调地址为 `https://api.txyundm.cn/app-api/pay/wechat/notify` 和 `https://api.txyundm.cn/app-api/pay/wechat/refund-notify`。 - 当前仓库未登记真实微信支付凭据；真实预支付、退款、通知和账单下载联调仍为外部阻塞。 +- `profitShareReceivers` 可在每个微信凭据项中按 `receiver:*` 引用登记真实分账接收方账号；数据库仅保存该引用、SHA-256 和脱敏值。 +- `QIPAI_PROFIT_SHARE_MOCK_ENABLED=true` 仅允许非生产测试环境启用；生产环境始终强制关闭。 +- 收款账户只有 `authorizationStatus=AUTHORIZED` 时才能开启分账；接收方也必须单独标记授权。 ## 团购与第三方平台 @@ -99,3 +102,4 @@ MYSQL_DATABASE=<以项目实际数据库名为准> - 2026-06-18：总纲升级为 V5.4；登记 WSL MySQL `root/root123` 与生产 MySQL `root/Da@Shuai!6y8c..XT`，增加 `/etc/qipai/mysql-client.cnf`、特殊字符处理和真实登录检测规则。 - 2026-06-22：M05-B 增加 `QIPAI_WECHAT_PAY_CREDENTIALS` 凭据映射、微信支付/退款回调地址和私钥证书隔离规则。 - 2026-06-22：M05-C 增加 `QIPAI_THIRD_PARTY_CREDENTIALS`、人工/Mock/API 模式、回调 HMAC 和券码哈希规则。 +- 2026-06-22：M05-D 增加门店收款账户、`profitShareReceivers` 环境映射、分账授权状态和非生产 Mock 门禁。 diff --git a/docs/db-changelog/2026-06-22-M05-D-profit-sharing.md b/docs/db-changelog/2026-06-22-M05-D-profit-sharing.md new file mode 100644 index 0000000..ccff983 --- /dev/null +++ b/docs/db-changelog/2026-06-22-M05-D-profit-sharing.md @@ -0,0 +1,7 @@ +# M05-D 分账与收款配置数据库变更 + +- 迁移版本：`2026062218` +- 新增 `qipai_collection_accounts`、`qipai_profit_share_receivers`、`qipai_profit_share_policies`。 +- 扩展 `qipai_profit_shares`：账户、接收方、批次/单项幂等键、比例、失败码和脱敏响应。 +- 收款账户和全局/门店策略使用显式 scope key，避免 NULL 唯一索引绕过。 +- 接收方真实账号不入库，只保存 SHA-256、脱敏值和环境引用。 diff --git a/docs/devlogs/2026-06-22-M05-D-分账与收款配置.md b/docs/devlogs/2026-06-22-M05-D-分账与收款配置.md new file mode 100644 index 0000000..f85c195 --- /dev/null +++ b/docs/devlogs/2026-06-22-M05-D-分账与收款配置.md @@ -0,0 +1,33 @@ +# M05-D 分账和门店收款配置 + +- 日期：2026-06-22 +- 起始 commit：`52edf24` +- 工程 commit：`1680d73` +- ENGINEERING_DELTA=YES +- 子阶段状态：DONE，工程 commit 已 push 且 `HEAD == origin/main` + +## 工程增量 + +- 支持按租户、小程序和门店配置微信收款商户号、环境凭据引用、启用状态与分账授权状态。 +- 分账接收方只保存 SHA-256、脱敏值和 `receiver:*` 环境引用。 +- 支持全局/门店比例策略，同一范围比例总和不得超过 10000 bps。 +- 只有成功且具有微信交易号的支付允许分账；未授权账户或接收方被拒绝。 +- 分账批次使用 clientRequestId 幂等，每个支付/接收方有唯一约束。 +- 接入微信支付 v3 `/v3/profitsharing/orders` 请求签名；API 失败记录 `MANUAL_REVIEW`，不伪造成功。 +- Mock 分账仅非生产显式开启后可用，生产环境强制关闭。 +- 后台 API 可维护账户、接收方、策略并查询账户、策略、脱敏接收方与分账明细。 + +## 验证 + +- Windows 全量测试及仓库门禁通过。 +- WSL MySQL 8.4.9 临时库执行 `up → verify → down → up → verify` 通过。 +- 迁移语句：up 89、verify 65、down 83。 +- 实测未授权开启被拒绝、比例超限被拒绝、接收方不落明文、两接收方金额正确、重复批次不重复分账。 + +## 外部阻塞 + +缺微信支付服务商/分账权限和已授权接收方，真实分账标记 `BLOCKED_EXTERNAL`。 + +## 模块回归与后续 + +M05-A/B/C/D Windows 全量回归与 WSL MySQL 全迁移往返通过。执行游标进入 M06-A：Broker 与 MQTT 基础。 diff --git a/docs/feature-status.md b/docs/feature-status.md index fc32162..9d67610 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -36,3 +36,5 @@ | 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 模式。 | +| FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `1680d73` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | M10/M08 补加盟流程与界面；取得权限后执行真实分账与对账。 | +| BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `1680d73` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；私钥、APIv3 Key 和接收方真实标识只使用环境引用，查询仅返回脱敏信息。 | Vue 后台页面待 M08；真实商户与服务商授权未提供。 | M08 接入响应式配置页面；授权后完成生产验收。 | diff --git a/docs/module-status.md b/docs/module-status.md index b795353..8cffb02 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -2,16 +2,16 @@ ```yaml execution_cursor: - current_module: M05 - current_stage: M05-D + current_module: M06 + current_stage: M06-A stage_status: TODO - last_completed_stage: M05-C - next_stage: M05-D - last_engineering_commit: cda640b + last_completed_stage: M05-D + next_stage: M06-A + last_engineering_commit: 1680d73 last_push_verified: true base_branch: main blocked_reason: "" - updated_at: 2026-06-22T18:30:00+08:00 + updated_at: 2026-06-22T19:30:00+08:00 ``` | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 | @@ -21,7 +21,7 @@ execution_cursor: | M02 登录、租户、权限 | DONE | `5a300a8` | docs/devlogs/2026-06-18-M02-D-用户与员工管理.md | M02-A/B/C/D 已完成租户、身份、可撤销会话、RBAC、门店数据范围、员工管理、禁用、会话重置和审计；Windows 全量测试与 WSL MySQL 8.4.9 往返迁移通过。 | | M03 门店、房间、价格、营业时间 | DONE | `d563078` | docs/devlogs/2026-06-18-M03-D-场景码NFC与WiFi.md | M03-A/B/C/D 已完成门店房间、装修广告、媒体、地图选店、场景码/NFC 页面导航和受控 Wi-Fi；真实微信小程序码图片生成留待 M08 真机联调。 | | M04 订单、时段锁定、支付闭环 | DONE | `91801fe` | docs/devlogs/2026-06-20-M04-D-订单分享.md | M04-A/B/C/D 已完成可信定价、并发预占、订单状态机、续费取消换房、管理员调整、代下单和最小权限分享；Windows 全量回归与 WSL MySQL 8.4.9 模块回归通过。 | -| M05 会员、余额、套餐、优惠券 | PARTIAL | `cda640b` | docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md | M05-A/B/C 已完成统一支付、微信支付退款、团购券核销和第三方直订：支持人工/Mock/API 适配器、券码哈希脱敏、重复核销幂等、HMAC 回调、门店房间映射、待处理队列及顾客认领成已支付订单；真实平台授权仍受阻，下一阶段 M05-D 分账和收款配置。 | +| M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 | | M06 设备、MQTT 与真实硬件联动 | TODO | - | - | - | | M07 保洁、通知、任务和语音播报 | TODO | - | - | - | | M08 微信原生小程序完整业务 | TODO | - | - | - | diff --git a/docs/unresolved-issues.md b/docs/unresolved-issues.md index 0796ce1..e9fdd7f 100644 --- a/docs/unresolved-issues.md +++ b/docs/unresolved-issues.md @@ -12,3 +12,4 @@ | ISSUE-008 | 2026-06-18 | M03-D/QR-001 | 真实微信小程序码图片生成尚未联调。 | 中 | sceneCode 生命周期、重建失效、扫码统计、二维码/NFC 页面解析和测试全链路已完成。 | 缺少可用于微信接口的 AppSecret 与真机联调环境。 | M08 配置真实 AppSecret 后调用微信小程序码接口并完成真机扫描验收。 | BLOCKED_EXTERNAL | | ISSUE-009 | 2026-06-22 | M05-B/ORD-001 | 微信支付 v3 真实预支付、通知、退款和账单下载尚未联调。 | 高 | 已完成请求签名、JSAPI 参数、原始通知体验签、AES-GCM 解密、幂等记账、全额/部分退款、退款状态推进、人工处理失败状态和对账记录；使用生成密钥与可控传输完成协议测试。 | 缺真实商户号、APIv3 Key、商户私钥、平台证书及可用商户环境。 | 用户提供凭据后写入 `/etc/qipai/qipai.secrets`，在生产回调域名完成小额支付、重复通知、部分退款、全额退款和账单下载验收。 | BLOCKED_EXTERNAL | | ISSUE-010 | 2026-06-22 | M05-C/GRP-001/GRP-002 | 美团/点评、抖音等团购核销与直订未完成真实平台联调。 | 高 | 已完成统一适配器、人工/Mock/API 核销、券码哈希、重复核销幂等、HMAC 回调、映射、人工队列和认领成单；后台配置与记录 API 已具备。 | 缺平台商家授权、Token、正式签名协议和回调测试环境。 | 获取授权后新增厂商专用适配器并执行验券、重复推送、取消和异常重试验收。 | BLOCKED_EXTERNAL | +| ISSUE-011 | 2026-06-22 | M05-D/FRN-001 | 微信支付真实分账尚未联调。 | 高 | 已完成收款账户、接收方、比例策略、授权门禁、成功支付校验、API 请求签名、幂等批次、失败人工处理和查询；Mock 仅限非生产。 | 缺微信支付服务商/分账权限、已授权接收方和生产商户凭据。 | 取得权限后登记环境接收方映射，执行小额支付后多接收方分账、重复请求和失败对账验收。 | BLOCKED_EXTERNAL |