# 杜康好客 · 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`

```sql
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. 验收清单

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