@@ -0,0 +1,153 @@
|
||||
# 杜康好客 · 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 | 好客权益金额图标 | 小程序权益金额前去掉 ¥，改为门店核销语义图标（商品售价/实付仍用 ¥） |
|
||||
|
||||
**配置进库**：`wecom_message_push` upsert「门店审核通知群」（无 webhook 时占位 URL + `enabled=false`）。无新 Prisma 表。
|
||||
|
||||
---
|
||||
|
||||
## 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`）
|
||||
- 覆盖：首页角标、商品详情礼遇额、下单「好客权益」行、我的资产、权益页余额/券面、核销页/码/成功页金额
|
||||
- **不改**：商品售价、订单实付、套餐价、人均价等现金口径（仍用 ¥）
|
||||
|
||||
---
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 合伙人可改门头/环境图（PENDING 除外）
|
||||
- [ ] 录入门店环境图无独立「批量上传」大按钮，九宫格「+」可多选
|
||||
- [ ] 小程序门店详情「店内环境」竖排；点开预览后可左右滑看多图
|
||||
- [ ] 关自动通过后，新建/重提门店推企微；提交套餐同样推
|
||||
- [ ] 门店详情抽屉可审套餐，不必跳页
|
||||
- [ ] 商品/门店分享卡片为该实体名称 + 主图
|
||||
- [ ] 系统设置「小程序分享」按场景可展开/收起
|
||||
- [ ] 核销接口返回的 `amount` / `settleAmount` 为数字；门店记录/成功页不再显示 `0.00`（真实有额时）
|
||||
- [ ] 历史无 payout 的核销：打开「结算提现」后可用余额出现；测试核销同样计结算
|
||||
- [ ] 门店 H5 / 小程序超额核销提示为中上部浮动气泡
|
||||
- [ ] 小程序好客权益金额前为店铺图标，商品价仍为 ¥
|
||||
Reference in New Issue
Block a user