v3.5.3版本更新2

docs/杜康好客-v3.5.3-开发文档.md

@@ -1,7 +1,7 @@
 # 杜康好客 · v3.5.3 版本更新
 
 > **2026-08-20** · admin-web / mini-user / h5-partner / h5-shop / API  
-> 目标：门店封面/环境图体验、企微门店审核通知、总部抽屉内审套餐、小程序分享用业务标题主图、系统设置分享配置按场景折叠；**补修核销金额为 0 / 无法提现、测试流水计结算、核销浮动提示、好客权益金额图标**。
+> 目标：门店封面/环境图体验、企微门店审核通知、总部抽屉内审套餐、小程序分享用业务标题主图、系统设置分享配置按场景折叠；**补修核销金额为 0 / 无法提现、测试流水计结算、核销浮动提示、好客权益金额图标**；**企微业务通知可编辑模板 + 处理快链**。
 
 ## 范围
 
@@ -19,8 +19,9 @@
 | 8 | 测试流水计结算 | **取消**「测试流水不计结算」；核销一律建 payout；账单/佣金不再因 `isTest` 跳过 |
 | 9 | 核销校验浮动提示 | 门店 H5 / 小程序：超可用余额等提示改为页面中上部浮动气泡 |
 | 10 | 好客权益金额图标 | 小程序权益金额前去掉 ¥，改为门店核销语义图标（商品售价/实付仍用 ¥） |
+| 11 | 企微业务通知扩展 | 订单支付/核销成功/信息变更/提现/发票；`wecom_push_template` 可编辑；处理快链 |
 
-**配置进库**：`wecom_message_push` upsert「门店审核通知群」（无 webhook 时占位 URL + `enabled=false`）。无新 Prisma 表。
+**配置进库**：`wecom_message_push` upsert「门店审核通知群 / 业务待办通知群 / 成交播报群」（无 webhook 时占位 URL + `enabled=false`）。**新表** `wecom_push_template`（发版不可 skip-db）。
 
 ---
 
@@ -138,6 +139,48 @@
 
 ---
 
+## 11. 企微业务通知 + 可编辑模板 + 处理快链
+
+### 事件条件 key
+
+| key | 触发 | 测试单 |
+|-----|------|--------|
+| `order.paid` | `afterOrderPaid` | 不推 |
+| `redeem.success` | `executeRedeem` 成功后 | 不推 |
+| `store.audit_pending` | 入驻/重提 PENDING | 推 |
+| `store.package_audit_pending` | 套餐变更 PENDING | 推 |
+| `store.info_change_pending` | 信息变更 PENDING | 推 |
+| `store.withdraw_pending` | 手动提现 PENDING_REVIEW | 推 |
+| `invoice.pending` | 发票申请 PENDING | 不推 |
+
+默认推送行：`业务待办通知群`、`成交播报群`（占位 webhook + 禁用，直至 HQ 配置）。
+
+### 模板表 `wecom_push_template`
+
+- 按 `eventKey` 全站一份；启动 `ensureTemplates` **仅插入缺行**，不覆盖 HQ 已改
+- HQ「企微机器人 → 消息推送 → 通知模板」：编辑 / 恢复默认 / 示例测试推送
+- API：`GET/PUT /admin/wecom-push-templates/:eventKey`，`POST .../reset`，`POST .../test`
+- 渲染：`WecomMessagePushService.dispatchEvent` → `{{var}}` 插值 → 条件路由
+
+### 处理快链
+
+环境变量 `HQ_ADMIN_PUBLIC_URL`（staging `https://admin-test.dukanghaoke.com`，生产 `https://admin.dukanghaoke.com`）。
+未配置时按 `WECOM_ALERT_ENV_LABEL` 回退（prod→生产域名，staging→测试域名，local→`http://localhost:5175`），**禁止**只发相对路径（企微会解析成 `http://orders/...`）。
+
+| 事件 | 路径 |
+|------|------|
+| 订单 | `/orders?orderNo=` |
+| 核销 | `/redeem-records?redeemNo=` |
+| 入驻 | `/stores?auditStatus=PENDING&storeId=` |
+| 套餐 | `/store-package-audits?requestId=` |
+| 信息变更 | `/store-package-audits?tab=info&infoRequestId=` |
+| 提现 | `/finance/store-bills?kind=WITHDRAW&status=PENDING_REVIEW&storeId=` |
+| 发票 | `/invoices?status=PENDING&invoiceNo=` |
+
+提现待审改走 `store.withdraw_pending`，不再误用 `AlertService` `category: finance` → `alert.system`。
+
+---
+
 ## 验收
 
 - [ ] 合伙人可改门头/环境图（PENDING 除外）
@@ -151,3 +194,7 @@
 - [ ] 历史无 payout 的核销：打开「结算提现」后可用余额出现；测试核销同样计结算
 - [ ] 门店 H5 / 小程序超额核销提示为中上部浮动气泡
 - [ ] 小程序好客权益金额前为店铺图标，商品价仍为 ¥
+- [ ] HQ 可编辑企微通知模板；勾选条件 + 配置 webhook 后订单/核销/提现/发票/审核有推送
+- [ ] 企微消息「去处理」可打开 HQ 对应列表并尽量定位到该单（需登录）
+- [ ] 测试订单/核销不推成交播报；发票申请测试单不推
+- [ ] 发版含 `wecom_push_template` 表与 `HQ_ADMIN_PUBLIC_URL`