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

杜康好客 · v3.5.14 修复文档

2026-08-26 · API / 生产数据
主题：C 端「提交订单 / 支付成功」用户日志 client_app 误标为 H5，改为真实端（小程序）

---

1. 版本目标

1. 修复后端埋点：order_submit、pay_success 不再写死 USER_H5。
2. 回填线上 log_user_analytics：这两类事件里所有 USER_H5 改为 USER_MINI。

不做：核销埋点（benefit_redeem_*）；未登录 POST /analytics/events 的 H5 回退；H5 预览（TARO_ENV=h5）仍报 USER_H5。

---

2. 根因

TradeService.createOrder / payOrder（Mock 支付成功）/ handlePaySuccess（微信支付回调）调用 analyticsService.trackOneSafe 时把 clientApp 写死为 'USER_H5'。

当前生产 C 端是 apps/mini-user 小程序，请求头为 X-Client-App: USER_MINI（写入 JWT）。同链路的 pay_fail 已使用 JWT 的 clientApp，故 HQ「用户日志」里提交订单显示「C 端 H5」，支付失败却可能显示「C 端小程序」。

---

3. 代码规则

写入点	事件	clientApp
POST /trade/orders → createOrder	order_submit	JWT user.clientApp（缺省 USER_H5）
POST /trade/orders/:id/pay Mock 成功	pay_success	入参 clientApp（缺省 USER_H5）
微信支付回调 handlePaySuccess	pay_success	该订单已有 order_submit / pay_fail；没有则默认 USER_MINI

小程序原生：USER_MINI。mini-user H5 预览：仍为 USER_H5（公众号 JSAPI，见 apps/mini-user/src/lib/api.ts）。

---

4. 线上数据回填

表：log_user_analytics
范围：event_name IN ('order_submit', 'pay_success') AND client_app = 'USER_H5'
动作：client_app → USER_MINI

SELECT event_name, client_app, COUNT(*) AS cnt
FROM log_user_analytics
WHERE event_name IN ('order_submit', 'pay_success')
GROUP BY event_name, client_app;

UPDATE log_user_analytics
SET client_app = 'USER_MINI'
WHERE event_name IN ('order_submit', 'pay_success')
  AND client_app = 'USER_H5';

回填结果（生产，2026-08-26）：

事件	回填前 USER_H5	回填后 USER_MINI
order_submit	55	55
pay_success	28	28

共更新 83 行。回填后这两类事件已无 USER_H5。

不改其它事件名，不改 common_event。

---

5. 关键路径

域	路径
建单 / 支付埋点	server/dukang-api/src/modules/trade/trade.service.ts
建单入参	server/dukang-api/src/modules/trade/trade.controller.ts
HQ 展示	order_submit → 提交订单；USER_MINI → C 端小程序

无 Prisma 迁移。

---

6. 发版步骤

步骤	动作
1	生产已执行上述 UPDATE（历史行）
2	发 dukang-api（新单按 JWT 写端）；--skip-db

---

7. 验收清单

• 历史 order_submit / pay_success 在 HQ 不再显示「C 端 H5」（已回填 83 行）
• 小程序提交订单后，HQ 用户日志「提交订单」端为「C 端小程序」（需发 dukang-api）
• 小程序支付成功后，「支付成功」端为「C 端小程序」（需发 dukang-api）
• mini-user H5 预览下单仍为「C 端 H5」
• 浏览类埋点（home_view 等）端字段不变