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

杜康好客 · v3.5.10 开发文档

2026-08-25 · mini-user / API
主题：门店详情去掉分享按钮；同城配送提示 24 小时内送到；小程序客服接通企业微信

---

1. 版本目标

#	任务	类型	交付
1	DPT-20260824-896	BUG	C 端门店详情去掉顶栏「分享」按钮
2	DPT-20260824-601	优化	同城送提示改承运商「配送信息提示」（HTML）；C 端 GET /catalog/local-deliveries
3	DPT-20260822-651	需求	小程序在线客服调起企业微信「微信客服」

不做：改配送规则 / 改 SLA 计算；合伙人/门店端客服；禁用微信右上角「···」分享菜单。

---

2. 门店详情去掉分享按钮

pages/store-detail 顶栏不再渲染 ShareNavButton。

右上角微信原生菜单仍可分享（enableShareAppMessage / WechatShareReady 保留）。只要去掉页面上的分享按钮。

---

3. 同城送提示（承运商 HTML）

不再写死文案。以用户收货地址城市为准：该市 common_city.status=ACTIVE（已开城）→ 同城，展示对应仓配承运商的「配送信息提示」；未开城 → 跨城，只展示「总部物流、运费到付」。

收货市 → 开城仓库（ACTIVE，优先 API_AUTO 且已绑承运商）→ 承运商.delivery_hint_html

空字段时 C 端回退纯文本 同城配送，预计24小时内送到。不改下单 / 推单 / 起购。

3.1 承运商字段

common_fulfillment_provider.delivery_hint_html TEXT NULL。允许 span/p/br/b/strong/i/em/font，style 仅 color / font-weight / font-size / font-style。保存与下发前消毒。HQ 文本框里的回车在 C 端转成换行（不必手写 <br/>）。

HQ「仓配管理 → 承运商」多行输入，例如：

<span style="color:#A61D24;font-weight:700;font-size:13px">同城配送，预计24小时内送到</span>

3.2 API

GET /catalog/local-deliveries（公开）。可选 cityCode / cityName。

每项：city · warehouse · provider · hintHtml。未开城 / 无仓 / 无承运商返回空列表或 hintHtml=null，不报错。

3.3 C 端

页面	何时展示
商品详情	可线上购；用当前选城预览
确认订单	收货市已开城且地址校验通过；RichText
订单详情	deliveryType === LOCAL；按收货市匹配

---

---

4. 小程序客服接通企业微信

原先 open-type=contact 进入小程序原生客服。本版在已配置企微参数时改为 wx.openCustomerServiceChat，进入企业微信「微信客服」（与 H5 kfid 同一套）。

配置（HQ → 系统设置 → 微信小程序配置）

键	说明
CUSTOMER_SERVICE_WECOM_URL	微信客服 kfid 链接；缺省用代码常量
WECOM_CORP_ID	企业 ID（ww 开头）。企微「我的企业」可查

GET /common/client-config 下发 customerServiceWecomUrl、wecomCorpId。

行为

环境	条件	行为
小程序	链接 + CorpID 都有	openCustomerServiceChat；订单详情可带订单卡片
小程序	未填 CorpID	回退 open-type=contact
H5	有 kfid 链接	打开企微客服网页

企微侧前置（运营）

1. 开通企业微信「微信客服」，拿到 kfid 链接。
2. 把 C 端小程序关联到该企业的微信客服。
3. 把 CorpID 填进系统设置。未填则用户仍走小程序原生客服。

---

4.1 Prisma

common_fulfillment_provider.delivery_hint_html TEXT NULL。脚本：migrate-fulfillment-delivery-hint-v3510.sql。

5. 验收清单

• 门店详情顶栏没有分享按钮；返回/导航/拨打不受影响
• HQ 承运商可编辑「配送信息提示」HTML（颜色/粗细/字号）；非法标签被去掉
• GET /catalog/local-deliveries 按开城列出仓库+承运商+hintHtml；cityName 可筛收货市
• 商品详情（可线上购）按当前选城展示承运商提示（空则回退「同城配送，预计24小时内送到」）
• 确认订单：收货市已开城显示 HTML 提示；未开城只显示「总部物流、运费到付」
• 同城订单详情「配送时效」为该市承运商提示
• 系统设置可改客服链接与 CorpID；保存后 client-config 立即带出
• 小程序已填 CorpID：联系客服进入企微微信客服（非小程序原生客服后台）
• 未填 CorpID：小程序仍能打开原生客服，不白屏

---

6. 关键路径

域	路径
门店详情	apps/mini-user/src/pages/store-detail/index.tsx
同城提示	fulfillment-provider.service.ts · GET /catalog/local-deliveries · DeliveryHintHtml
客服按钮	apps/mini-user/src/components/ContactCsButton.tsx · lib/wecom-cs.ts
下发	client-config.controller.ts · packages/shared-types config.ts / wechat.ts
HQ 配置	system-config.registry.ts