dukang/杜康好客-v3.4.13-体验优化开发文档.md

杜康好客 · v3.4.13 体验优化开发文档

版本：v3.4.13 · 日期：2026-08-05
需求源：20 条 ST 工单（体验优化 / Bug / 客户端验证）

1. 范围

模块	内容
admin-web	推广码 attributionCount + 指标事件日志/ECharts 趋势；权益券详情加宽；核销记录详情增强（对齐权益券内核销详情）；技术支持工单优先级；版本发布联动任务/工单已发布；大图上传前压缩
mini-user	门店电话脱敏+拨打埋点；门店列表展示两段营业时间；门店详情门头 aspectFill 铺满无留白；门店套餐页签切换；商品去分享+首图 preview；提货确认弹框；我的页版本号 v3.4.x；低于 minClientVersion 强制更新/点我知道了退出；物流增强（签收照/拨号/时间线/ETA）；头像超 10MB 压缩
h5-partner / h5-shop / h5-user	登录 phone/code 前端校验；门店端 iOS 首次扫码 OAuth 单例 + JSSDK 预热重试；OSS 图片超 10MB 自动 canvas 压缩后上传
后端	工单 priority；工单 PUBLISHED + releasedVersionNo；版本 RELEASED 联动任务/工单；client-config minClientVersion；合伙人微信暂停禁登；Courier 适配器；log_promo_event 推广码指标日志

2. ST 映射

ST	标题	状态
ST1785925037781309	总部端-推广码数据跟踪优化	✅ attributionCount + 事件日志 + ECharts 趋势
ST1785924286682833	用户端-门店电话加密+拨打埋点	✅ maskPhone + store_phone_call
ST1785921693982470	技术支持-工单优先级	✅ priority 枚举 + HQ UI
ST1785921585900725	门店端扫一扫授权异常	✅ OAuth 单例回调 + iOS JSSDK 预热/重试 + 授权后续扫
ST1785907536648201	版本不对提示更新	✅ 我的页 v3.4.x + UpdateManager + 低于 min 强制更新/退出
ST1785906800359657	合伙人暂停后禁登	✅ 发码前 phone/check + 微信/SMS 登录均拒 DISABLED
ST1785906592340255	PARTNER_H5 login 校验	✅ 前端空字段拦截
ST1785906390321653	现场提货提交确认弹框	✅ showModal
ST1785905773501871	核销记录用户信息	✅ 列表+详情；详情含门店/合伙人/券分摊/结算/评价
ST1785904849234806	工单中心	✅ 已有
ST1785904076632841	门店列表开城合伙人	✅ 列表展示 companyName/name/phone（同 partnerOptionLabel）
ST1785902173093977	去掉商品详情分享按钮	✅ 移除 ShareNavButton
ST1785902141731113	商品首图大图	✅ previewable
ST1785901870913349	门店列表营业时间	✅ 列表展示两段营业时间
ST1785901838948572	SHOP 未绑定门店	✅ 已有
ST1785901775231811	门店套餐遮挡	✅ 页签切换（可横滑）+ 紧凑内容区
ST1785901711627824	SHOP login 校验	✅ 前端空字段拦截
ST1785901314893145	门头照裁剪	✅ aspectFill 铺满无留白 + preview
ST1785939375449985	订单物流追踪页	✅ 签收照 + 拨号 + 时间线 + ETA + 路由回调
—	上传图片超 10MB 先压缩	✅ @dukang/shared-ui/compressImage + 各端 upload

3. 后端 API / 配置

方法	路径 / 配置	说明
GET	/common/client-config	minClientVersion（MINI_USER_MIN_VERSION）；客户端 semver 比对，低于则强制更新或退出
—	CommonSupportTicket.priority	LOW | NORMAL | HIGH | URGENT，默认 NORMAL
—	CommonSupportTicket.status	新增 PUBLISHED（已发布）；releasedVersionNo + publishedAt
—	DevPlanVersion → RELEASED	关联任务 → RELEASED；关联工单 → PUBLISHED 并写入版本号
—	loginPartnerWechat	非 ACTIVE 账号抛出「合伙人账号已停用」
GET	/trade/orders/:id/track	聚合：nodes（旧→新）、signPhotoUrls、estimatedArrival；经 CourierService 适配小飞侠 cmd 100102/100108/100301
POST	/callbacks/courier/xfx/track	小飞侠路由变化回调（适配器入口）
POST	/callbacks/courier/logistics/track	跨城物流回调占位（记录日志，后续接入）
POST	/callbacks/delivery/track	兼容旧路径，等同 xfx
GET	/admin/promo-codes/:id/metrics/timeline	推广码四指标时间序列（按日/按时 + peak）
GET	/admin/promo-codes/:id/metrics/events	推广码指标事件分页日志（时间/ID/IP/地点）

3.1 推广码指标日志（ST1785925037781309）

表 log_promo_event

event_type	统计卡	写入时机	ID
SCAN	扫码进入数	POST /promo/touch 且 countScan !== false	userId / sessionId
ATTRIBUTION	归因用户数	首次写入 user_promo_attribution	userId
REGISTER	扫码注册用户数	applyPromoSourceToUser 成功	userId
ORDER	订单数	带推广码下单 orderCount++	orderId + userId

每条日志含 created_at、可选 ID、client_ip、ip_province/ip_city。仅统计上线后新事件；累计 Statistic 卡逻辑不变。

HQ UI：推广码详情页 → 数据趋势 Card（DatePicker + 按日/按时 + ECharts 四曲线 + 事件 Table）

3.2 mini-user 版本门控（ST1785907536648201）

项	行为
我的页	左下角展示 杜康好客 v3.4.x（与 APP_VERSION / package.json 同步）
启动校验	GET /common/client-config → minClientVersion；APP_VERSION 低于最低版本时拦截
微信有新包	UpdateManager 弹「立即更新」→ applyUpdate()
无新包 / 仍过低	弹「版本过低」→ 点「我知道了」→ Taro.exitMiniProgram() 退出小程序

4. mini-user 物流（ST1785939375449985）

页面	行为
订单详情	配送中展示最新路由摘要 + 「物流详情」；物流未到时展示 预估送达（100301）
物流详情	物流信息；签收照片（有则展示，previewImage 放大）；物流动态旧→新、节点全红点亮、最新在底部
电话拨号	物流文案中手机号可点击 makePhoneCall
接口	GET /trade/orders/:id/track（OrderTrackDto）；C 端禁止直连小飞侠
公共模块	order-logistics.ts + LogisticsRichText 组件

4.1 对外回调 URL（提供给小飞侠）

生产

POST https://api.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
Content-Type: application/json

测试

POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track

请求体：

字段	说明
outNumber	商户单号
number	运单号
status	1下单 2取件 3中转 4派件 5签收 7取消
statusName	中文状态
trackInfo	路由描述
createTime	路由时间

成功响应：{"code":"100000","message":"success"}

4.2 Courier 适配器（integrations/courier）

cmd	能力	Provider 方法
100102	路由查询	getTrack
100108	签收照片	getSignPhotos → OSS → signPhotoUrls
100301	预估送达	checkDeliveryCoverage → estimatedArrival
回调	路由推送	parseTrackCallback + mapTrackStatus（status=5 / statusName 含「签收」→ 订单 COMPLETED）

路由回调状态映射（小飞侠）

小飞侠 status / statusName	系统订单状态
1 下单	OUT_WAREHOUSE
2 取件 / 3 中转	SHIPPING
4 派件	SHIPPING
5 签收 / statusName 已签收	COMPLETED（已完成）
7 取消	仅记录日志，不改订单

5. 数据表

• common_support_ticket.priority ENUM，默认 NORMAL
• common_support_ticket.status 新增 PUBLISHED；released_version_no、published_at
• log_promo_event：推广码指标事件（promo_code_id, event_type, user_id, order_id, session_id, client_ip, 地点, created_at）

6. HQ 开发计划

在 admin-web 开发计划 → 版本列表 创建 v3.4.13（状态 IN_PROGRESS），审批 ST 后关联 dev_plan_task。版本标记为「已发布」后，该版本下任务自动 RELEASED，关联技术支持工单自动 PUBLISHED 并写入 releasedVersionNo。

7. 验收 ACC

• 推广码详情展示 attributionCount；四指标事件日志 + ECharts 按日/按时趋势 + 高峰标注
• 推广码 SCAN/ATTRIBUTION/REGISTER/ORDER 事件含 time + IP；幂等（重复 touch 不计 SCAN）
• 核销记录含 userNo/nickname/phone；详情抽屉展示门店/地址/合伙人/权益券号/关联订单/券分摊/结算单/评价
• 权益券详情抽屉加宽（980px），内嵌核销列表无横向滚动条
• 技术支持可创建/筛选/编辑优先级；版本 RELEASED 后关联工单为「已发布」并带版本号
• 门店列表「开城合伙人」列展示 companyName / name / phone（与下拉选项一致）
• 合伙人/门店登录空字段前端提示；暂停合伙人发码前即拦截，短信/微信登录均禁止
• mini-user：我的页左下角显示 杜康好客 v3.4.x；低于 minClientVersion 时强制更新，无新包则点「我知道了」退出小程序
• mini-user：电话脱敏、拨打埋点、提货确认、无分享按钮、首图 preview、门店列表两段营业时间、门店详情门头铺满无留白、门店套餐页签切换
• mini-user：配送中物流摘要 + 签收照预览 + 电话拨号 + 时间线旧→新全点亮 + 预估送达
• 小飞侠路由回调 POST /callbacks/courier/xfx/track：status=5 或 statusName 已签收 → 订单 COMPLETED；重复回调幂等
• 各端上传 >10MB 图片自动压缩后可上传；仍超限有明确报错
• 门店 H5（iPhone 微信）：首次扫码 OAuth 后自动续扫；offline verifying 时提示再点一次扫码
• pnpm lint 无新增错误