v3.5.3版本更新1

docs/杜康好客-v3-PRD.md

@@ -19,9 +19,10 @@
 | 3.4.11 | 08-04 | 开发计划 + 企微机器人/消息推送 | [`开发计划`](./杜康好客-开发计划功能开发文档-v3.4.11.md) |
 | 3.4.12 | 08-04 | 退款回滚/财务/批量任务·工单/套餐 imageUrl | [`v3.4.12`](./杜康好客-v3.4.12-工单迭代开发文档.md) |
 | 3.4.13 | 08-05 | metrics/核销详情/版本联动 PUBLISHED/mini 体验/H5 OAuth | [`v3.4.13`](./杜康好客-v3.4.13-体验优化开发文档.md) |
-| 3.4.14 | 08-06 | mini-user 门头/套餐详情；小程序可配置；**统一测试白名单（不计账+限测可见+Mock旁路）** | [`v3.4.14`](./杜康好客-v3.4.14-mini-user门店体验开发文档.md) |
+| 3.4.14 | 08-06 | mini-user 门头/套餐详情；小程序可配置；**统一测试白名单（限测可见+Mock旁路；测试流水计入结算）** | [`v3.4.14`](./杜康好客-v3.4.14-mini-user门店体验开发文档.md) |
 | 3.4.15 | 08-07 | mini-user 门店列表卡片；HQ 门店照片替换/删除；套餐多图上限 20 | [`v3.4.15`](./杜康好客-v3.4.15-mini-user门店列表优化.md) |
 | 3.4.16 | 08-09 | 联系电话分离；取消自动 ST；套餐 UI；合伙人列表/入驻客服门槛；HQ 门店列表表格 | [`v3.4.16`](./杜康好客-v3.4.16-门店联系电话与体验优化.md) |
+| 3.5.3 | 08-20 | 门店照片/企微审核/分享；核销金额序列化与提现补建；测试流水计结算；核销浮动提示；权益金额门店图标 | [`v3.5.3`](./杜康好客-v3.5.3-开发文档.md) |
 
 ---
 

docs/杜康好客-v3-现状对照.md

@@ -9,7 +9,7 @@
 |------|------|
 | 主链路 | 登录→下单支付→权益→扫码核销→payout→HQ 打款 **可跑通** |
 | C 端 | `mini-user` 小程序 + h5-user；v3.4.13 版本门控/门店/物流已上 |
-| 近期版本 | … · v3.4.15 · **v3.4.16 联系电话/套餐 UI/合伙人列表与入驻客服门槛/HQ 门店列表表格** |
+| 近期版本 | … · v3.4.16 · **v3.5.3 门店照片/企微审核/分享 + 核销金额/提现补修 + 权益图标** |
 | 冒烟 | `scripts/smoke-v3.mjs` 窄路径 ≠ 全量 ACC |
 | REQ 明细 | PRD §4 + `.cursor/skills/dukang-v3/reference-req-index.md` |
 
@@ -57,14 +57,14 @@
 | 3.4.13 | [`体验优化`](./杜康好客-v3.4.13-体验优化开发文档.md) | ✅ 生产 |
 | 3.4.14 | [`mini-user 门店体验 + 小程序可配置 + 测试白名单`](./杜康好客-v3.4.14-mini-user门店体验开发文档.md) | ✅ 生产 |
 | 3.4.15 | [`mini-user 门店列表 + HQ 照片/套餐多图`](./杜康好客-v3.4.15-mini-user门店列表优化.md) | ✅ 生产 |
-
-| 2026-08-08 | v3.4.14 / v3.4.15 已发生产，更新状态
+| 3.5.3 | [`门店照片/企微审核/分享 + 核销金额与提现补修`](./杜康好客-v3.5.3-开发文档.md) | 🔶 开发中 |
 
 | 日期 | 说明 |
 |------|------|
-| 2026-08-07 | v3.4.14 增补统一测试白名单（不计账 / 限测可见 / Mock 旁路） |
+| 2026-08-20 | v3.5.3 增补：Decimal 序列化/提现补建、测试流水计结算、核销浮动提示、好客权益金额图标 |
+| 2026-08-08 | v3.4.14 / v3.4.15 已发生产，更新状态 |
+| 2026-08-07 | v3.4.14 增补统一测试白名单（限测可见 / Mock 旁路；测试流水计入结算） |
 | 2026-08-07 | v3.4.15 增补：HQ 门店照片替换/删除、套餐多图上限 20 |
-
 | 2026-08-05 | v3.4.13 |
 | 2026-08-04 | v3.4.11 / v3.4.12 |
 | 2026-07-11 | 首版对照表 |

docs/杜康好客-v3.4.14-mini-user门店体验开发文档.md

@@ -10,7 +10,7 @@
 | 门店详情·套餐 | 仅完整标题纵向列表；点击进入详情 |
 | 套餐详情页 | 实底导航让出胶囊区；内容区顶/左右留白；有图在门店名下；无图直接菜品 |
 | **系统设置·微信小程序** | Logo / 资质图 / 客服电话 / C 端 H5 / Mock 验证码 **可配置**，经 `client-config` 下发 |
-| **测试白名单** | 全局手机号名单；账号/门店/订单/核销打标；不计四条结算；合并商品/门店可见性手机号；HQ 独立管理模块 |
+| **测试白名单** | 全局手机号名单；账号/门店/订单/核销打标（计入结算）；合并商品/门店可见性手机号；HQ 独立管理模块 |
 
 ## 页面路由
 
@@ -46,8 +46,8 @@ HQ → 系统设置 → **微信小程序配置**。启动时空缺键用 shared
 |------|------|
 | 源真相 | HQ「白名单管理」维护 `common_test_whitelist_phone`；名单内手机号 = 测试账号 |
 | 可见性 | 商品/门店 `visibilityWhitelistEnabled` 开启后，C 端仅当观众手机号 ∈ 全局名单可见/可购（不再用分实体 `*_visibility_phone`） |
-| 打标 | `User` / `StoreAccount` / `PartnerAccount` / `Store` / `Order` / `RedeemRecord` 的 `isTest` |
-| 不计账 | 测试核销不产生 `StorePayout`；酒厂/物流/合伙人账单排除 `isTest` 流水 |
+| 打标 | `User` / `StoreAccount` / `PartnerAccount` / `Store` / `Order` / `RedeemRecord` 的 `isTest`（HQ 列表可过滤；**计入结算**） |
+| 结算 | 测试核销同样产生 `StorePayout`；酒厂/物流/合伙人账单**包含** `isTest` 流水 |
 | 验证旁路 | 页顶 Checkbox ↔ `MOCK_SMS` / `MOCK_WECHAT` / `MOCK_PAY`（勾选 = 不做真实验证） |
 
 ### API
@@ -80,7 +80,7 @@ HQ → 系统设置 → **微信小程序配置**。启动时空缺键用 shared
 - [ ] 页顶三 Checkbox 控制短信/微信/支付跳过真实验证，与 `MOCK_*` 同源立即生效
 - [ ] 业务列表「过滤测试账号」勾选后不含测试数据
 - [ ] 旧可见性手机号已导入；限测商品/门店仅全局名单可见
-- [ ] 测试流水不进四条账单与门店打款
+- [ ] 测试流水进入四条账单与门店打款（与正式流水相同）
 
 ## HQ 开发计划
 

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

@@ -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 / 小程序超额核销提示为中上部浮动气泡
+- [ ] 小程序好客权益金额前为店铺图标，商品价仍为 ¥