jacy
797b20979d
承运商 HTML 按收货市下发；textarea 回车在 C 端转成换行。含门店去掉分享按钮与小程序企微客服。 Co-authored-by: Cursor <cursoragent@cursor.com>
122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
# 杜康好客 · 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「仓配管理 → 承运商」多行输入，例如：
|
||
|
||
```html
|
||
<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`](../server/dukang-api/prisma/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` |
|