201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
# 杜康好客 · v3.5.3 版本更新
|
||
|
||
> **2026-08-20** · admin-web / mini-user / h5-partner / h5-shop / API
|
||
> 目标：门店封面/环境图体验、企微门店审核通知、总部抽屉内审套餐、小程序分享用业务标题主图、系统设置分享配置按场景折叠；**补修核销金额为 0 / 无法提现、测试流水计结算、核销浮动提示、好客权益金额图标**；**企微业务通知可编辑模板 + 处理快链**。
|
||
|
||
## 范围
|
||
|
||
| # | 项 | 交付 |
|
||
|---|----|------|
|
||
| 1 | 合伙人改封面/环境图 | **现状已具备**（`PUT /partner/stores/:id/media`）；本版不改接口 |
|
||
| 1a | 小程序店内环境预览 | 页面内竖排展示；点击调用 `previewImage`，相册内可左右滑 |
|
||
| 1b | 录入/编辑页环境图上传 UI | 去掉独立「批量上传 / 重新上传照片」大按钮；九宫格「+」选图；编辑页「提交变更」同时提交门头照/环境图 |
|
||
| 2 | 客服改企微 | **暂不处理** |
|
||
| 3 | 门店提交审核企微通知 | `wecom_message_push` 条件 `store.audit_pending`；群名「门店审核通知群」 |
|
||
| 4 | 套餐审核同步 + 通知 | 门店详情抽屉内对比并通过/驳回；`store.package_audit_pending` 同群通知 |
|
||
| 5 | 商品/门店微信分享 | title/主图固定用业务字段（不被 HQ 场景配置覆盖） |
|
||
| 6 | 系统设置分享分组 | 「小程序分享」内按场景子组 Collapse，可展开收起 |
|
||
| 7 | 核销金额序列化 / 门店提现 | Prisma Decimal → JSON 数字；结算比例兜底；提现摘要补建缺失 `store_payout` |
|
||
| 8 | 测试流水计结算 | **取消**「测试流水不计结算」；核销一律建 payout；账单/佣金不再因 `isTest` 跳过 |
|
||
| 9 | 核销校验浮动提示 | 门店 H5 / 小程序：超可用余额等提示改为页面中上部浮动气泡 |
|
||
| 10 | 好客权益金额图标 | 小程序权益金额前去掉 ¥，改为门店核销语义图标（商品售价/实付仍用 ¥） |
|
||
| 11 | 企微业务通知扩展 | 订单支付/核销成功/信息变更/提现/发票；`wecom_push_template` 可编辑；处理快链 |
|
||
|
||
**配置进库**：`wecom_message_push` upsert「门店审核通知群 / 业务待办通知群 / 成交播报群」（无 webhook 时占位 URL + `enabled=false`）。**新表** `wecom_push_template`（发版不可 skip-db）。
|
||
|
||
---
|
||
|
||
## 1. 封面 / 环境图
|
||
|
||
### 合伙人端（已有）
|
||
|
||
- 创建：`StoreCreatePage` 门头照 + 环境照（≥3）
|
||
- 修改：`StoreDetailPage` → `PUT /partner/stores/:id/media`
|
||
- 限制：`CLOSED` / `auditStatus=PENDING` 不可改；`REJECTED` 改照片会重提审核
|
||
|
||
### 小程序门店详情
|
||
|
||
- 顶部：仅 `coverUrl`（不混环境图）
|
||
- 「店内环境」：竖排长图列表；点击 `Taro.previewImage`，预览相册为**封面 + 环境图**（可左右滑）；点封面预览同相册
|
||
|
||
### 录入/编辑页环境图 UI
|
||
|
||
- `MultiOssUploadField` 支持九宫格模式：缩略图 + 末尾「+」，去掉全宽虚线大按钮
|
||
- **已营业门店**：门头照/环境图变更并入「信息变更」审核（`coverUrl` / `envPhotoUrls`）；总部「审核通知 → 信息变更」通过后才覆盖线上图；`PUT .../media` 对 APPROVED 门店已禁用
|
||
- **入驻驳回**：仍走 `PUT .../media` / `basic` 重提门店审核
|
||
- 签约合同本条不改
|
||
|
||
---
|
||
|
||
## 3 / 4. 企微「门店审核通知群」
|
||
|
||
| 条件 key | 触发 |
|
||
|----------|------|
|
||
| `store.audit_pending` | 新建门店进 PENDING；驳回后基本信息/照片重提 |
|
||
| `store.package_audit_pending` | 合伙人/门店提交套餐变更 PENDING |
|
||
|
||
- HQ `/wecom/pushes` 可改 webhook、启停、条件
|
||
- API 启动按名称 upsert 默认行；可选 env `WECOM_STORE_AUDIT_WEBHOOK_URL`
|
||
|
||
### 总部抽屉内审套餐
|
||
|
||
- 共享组件 `StorePackageAuditPanel`（对比 + 通过/驳回）
|
||
- `StoresPage` 详情抽屉「套餐」Tab 内嵌；列表「审核套餐」打开抽屉并切 Tab
|
||
- 原「审核通知」页保留
|
||
|
||
---
|
||
|
||
## 5. 小程序分享
|
||
|
||
| 场景 | title | imageUrl |
|
||
|------|-------|----------|
|
||
| 商品详情 | `product.name` | `mainImageUrl` → `carouselUrls[0]` |
|
||
| 门店详情 | `store.name` | `coverUrl` → 首张环境图 |
|
||
|
||
`buildSceneSharePayload`：上述两场景 title/image 优先业务字段；其它场景仍场景配置优先。
|
||
|
||
---
|
||
|
||
## 6. 系统设置分享子组
|
||
|
||
`SystemConfigFieldMeta.subgroup`；`wechat_mini_share` 内层 Collapse：全局 / 首页 / 门店列表 / 门店详情 / 权益 / 我的 / 商品详情 / 订单详情。
|
||
|
||
---
|
||
|
||
## 7. 核销金额序列化与门店提现补修
|
||
|
||
**现象**：线上偶发核销后金额显示为 `0.00`、门店「结算提现」可用余额为 0。
|
||
|
||
| 根因 | 处理 |
|
||
|------|------|
|
||
| Prisma `Decimal` 经 `serializeBigInt` 未转成数字，前端 `Number` → `NaN` → 显示 0 | `convertForJson`：`Decimal` → `number`，`bigint` → `string`，`Date` → ISO |
|
||
| `settlementRate` 非法/为空导致结算额为 0 | `packages/domain`：`DEFAULT_STORE_SETTLEMENT_RATE = 0.6`、`resolveSettlementRate()`；核销建 payout 使用兜底比例 |
|
||
| 历史核销无 `store_payout`（含曾跳过测试流水） | `settlement.service`：提现摘要 `backfillMissingStorePayouts(storeId)`（最多补 200 条孤儿核销） |
|
||
| 前端弱网/对象形态金额 | `h5-shop` / `mini-user` `formatMoney` / `toMoneyNumber` 统一解析 |
|
||
|
||
**发版后**：门店打开一次「结算提现」即可触发补建；无需手工 SQL。
|
||
|
||
| 位置 | 说明 |
|
||
|------|------|
|
||
| `common/decorators/current-user.decorator.ts` | 响应序列化 |
|
||
| `packages/domain` | `resolveSettlementRate` / `validateRedeemAmount` 拒 `NaN` |
|
||
| `redeem.service` / `settlement.service` | 兜底比例 + 补建 payout |
|
||
| `apps/h5-shop/src/lib/money.ts`、`apps/mini-user/src/lib/money.ts` | 金额展示 |
|
||
|
||
---
|
||
|
||
## 8. 测试流水计入结算（规则变更）
|
||
|
||
相对 v3.4.14「测试打标」保留，**结算口径对齐正式流水**：
|
||
|
||
- 核销：一律 `createStorePayout`（记录仍可带 `isTest` 供 HQ `excludeTest` 列表过滤）
|
||
- 提现补建：不再跳过测试门店 / `isTest` 核销
|
||
- 合伙人账单、酒厂 T+3、物流账单：不再因 `isTest` 排除或零佣金
|
||
|
||
**仍保留**：HQ 列表「过滤测试账号」；测试账号 JWT 状态旁路；待支付 30 分钟取消仍只处理非测试单（非结算链路）。
|
||
|
||
---
|
||
|
||
## 9. 核销校验浮动提示
|
||
|
||
「核销金额不能超过可用余额」等校验/接口错误，改为页面**中上部**固定定位气泡（约 2.5～2.8s 消失），不再贴在表单底部（易滚出屏外）。
|
||
|
||
| 端 | 实现 |
|
||
|----|------|
|
||
| 门店 H5 | `ShopToastProvider` + `toastError` / `toastSuccess`；手机号核销、扫码确认、弱网兜底 |
|
||
| 小程序 | `FloatingToastHost`（挂 `PageShell`）；`toast(icon≠success)` 走浮动层；成功仍用原生 `showToast` |
|
||
|
||
「门店休息中」等需持续可见的说明仍保留内联 banner。
|
||
|
||
---
|
||
|
||
## 10. 好客权益金额图标（mini-user）
|
||
|
||
权益额度前去掉人民币符号，改用红色圆角方块 + 白色店铺剪影图标，语义为「可到店核销」。
|
||
|
||
- 组件：`BenefitFigure`（`assets/icons/store-benefit.png`）
|
||
- 覆盖：首页角标、商品详情礼遇额、下单「好客权益」行、我的资产、权益页余额/券面、核销页/码/成功页金额
|
||
- **不改**：商品售价、订单实付、套餐价、人均价等现金口径（仍用 ¥）
|
||
|
||
---
|
||
|
||
## 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 除外）
|
||
- [ ] 录入门店环境图无独立「批量上传」大按钮，九宫格「+」可多选
|
||
- [ ] 小程序门店详情「店内环境」竖排；点开预览后可左右滑看多图
|
||
- [ ] 关自动通过后，新建/重提门店推企微；提交套餐同样推
|
||
- [ ] 门店详情抽屉可审套餐，不必跳页
|
||
- [ ] 商品/门店分享卡片为该实体名称 + 主图
|
||
- [ ] 系统设置「小程序分享」按场景可展开/收起
|
||
- [ ] 核销接口返回的 `amount` / `settleAmount` 为数字；门店记录/成功页不再显示 `0.00`（真实有额时）
|
||
- [ ] 历史无 payout 的核销：打开「结算提现」后可用余额出现；测试核销同样计结算
|
||
- [ ] 门店 H5 / 小程序超额核销提示为中上部浮动气泡
|
||
- [ ] 小程序好客权益金额前为店铺图标，商品价仍为 ¥
|
||
- [ ] HQ 可编辑企微通知模板；勾选条件 + 配置 webhook 后订单/核销/提现/发票/审核有推送
|
||
- [ ] 企微消息「去处理」可打开 HQ 对应列表并尽量定位到该单（需登录）
|
||
- [ ] 测试订单/核销不推成交播报；发票申请测试单不推
|
||
- [ ] 发版含 `wecom_push_template` 表与 `HQ_ADMIN_PUBLIC_URL`
|