jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions 8 Packages Projects Releases Wiki Activity
Files
3004a65b3517ec61ef080fca24b5719ec04b851e
dukang/docs/杜康好客-v3.5.3-开发文档.md
T
jacy 26334ed072
CI / verify (pull_request) Has been cancelled
Details
v3.5.3版本更新2
2026-08-20 20:09:05 +08:00

10 KiB
Raw Blame History

杜康好客 · 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
Reference in New Issue View Git Blame Copy Permalink