jacy
53e0db6a98
Add log_promo_event for scan/attribution/register/order with IP; admin metrics APIs and ECharts on promo detail page. Co-authored-by: Cursor <cursoragent@cursor.com>
147 lines
7.5 KiB
Markdown
147 lines
7.5 KiB
Markdown
# 杜康好客 · v3.4.13 体验优化开发文档
|
||
|
||
> 版本：**v3.4.13** · 日期：2026-08-05
|
||
> 需求源：20 条 ST 工单（体验优化 / Bug / 客户端验证）
|
||
|
||
## 1. 范围
|
||
|
||
| 模块 | 内容 |
|
||
|------|------|
|
||
| admin-web | 推广码 attributionCount + **指标事件日志/ECharts 趋势**；核销记录用户信息；技术支持工单优先级；**大图上传前压缩** |
|
||
| mini-user | 门店电话脱敏+拨打埋点；门头/套餐展示；商品去分享+首图 preview；提货确认弹框；版本更新提示；**物流增强（签收照/拨号/时间线/ETA）**；**头像超 10MB 压缩** |
|
||
| h5-partner / h5-shop / h5-user | 登录 phone/code 前端校验；**OSS 图片超 10MB 自动 canvas 压缩后上传** |
|
||
| 后端 | 工单 priority；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器**；**log_promo_event 推广码指标日志** |
|
||
|
||
## 2. ST 映射
|
||
|
||
| ST | 标题 | 状态 |
|
||
|----|------|------|
|
||
| ST1785925037781309 | 总部端-推广码数据跟踪优化 | ✅ attributionCount + **事件日志 + ECharts 趋势** |
|
||
| ST1785924286682833 | 用户端-门店电话加密+拨打埋点 | ✅ maskPhone + store_phone_call |
|
||
| ST1785921693982470 | 技术支持-工单优先级 | ✅ priority 枚举 + HQ UI |
|
||
| ST1785921585900725 | 门店端扫一扫授权异常 | ✅ 已有（v3.4.12 前） |
|
||
| ST1785907536648201 | 版本不对提示更新 | ✅ UpdateManager + minClientVersion |
|
||
| ST1785906800359657 | 合伙人暂停后禁登 | ✅ loginPartnerWechat status |
|
||
| ST1785906592340255 | PARTNER_H5 login 校验 | ✅ 前端空字段拦截 |
|
||
| ST1785906390321653 | 现场提货提交确认弹框 | ✅ showModal |
|
||
| ST1785905773501871 | 核销记录用户信息 | ✅ 列表+详情 |
|
||
| ST1785904849234806 | 工单中心 | ✅ 已有 |
|
||
| ST1785904076632841 | 门店列表开城合伙人 | ✅ 已有 |
|
||
| ST1785902173093977 | 去掉商品详情分享按钮 | ✅ 移除 ShareNavButton |
|
||
| ST1785902141731113 | 商品首图大图 | ✅ previewable |
|
||
| ST1785901870913349 | 门店列表营业时间 | ✅ 已有 |
|
||
| ST1785901838948572 | SHOP 未绑定门店 | ✅ 已有 |
|
||
| ST1785901775231811 | 门店套餐遮挡 | ✅ 折叠/行数限制 |
|
||
| ST1785901711627824 | SHOP login 校验 | ✅ 前端空字段拦截 |
|
||
| ST1785901314893145 | 门头照裁剪 | ✅ aspectFit + preview |
|
||
| ST1785939375449985 | 订单物流追踪页 | ✅ 签收照 + 拨号 + 时间线 + ETA + 路由回调 |
|
||
| — | 上传图片超 10MB 先压缩 | ✅ `@dukang/shared-ui/compressImage` + 各端 upload |
|
||
|
||
## 3. 后端 API / 配置
|
||
|
||
| 方法 | 路径 / 配置 | 说明 |
|
||
|------|-------------|------|
|
||
| GET | `/common/client-config` | 新增 `minClientVersion`（env `MINI_USER_MIN_VERSION`） |
|
||
| — | `CommonSupportTicket.priority` | `LOW \| NORMAL \| HIGH \| URGENT`，默认 NORMAL |
|
||
| — | `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）
|
||
|
||
### 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`
|
||
- `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`。
|
||
|
||
## 7. 验收 ACC
|
||
|
||
- [ ] 推广码详情展示 attributionCount；**四指标事件日志 + ECharts 按日/按时趋势 + 高峰标注**
|
||
- [ ] 推广码 SCAN/ATTRIBUTION/REGISTER/ORDER 事件含 time + IP；幂等（重复 touch 不计 SCAN）
|
||
- [ ] 核销记录含 userNo/nickname/phone
|
||
- [ ] 技术支持可创建/筛选/编辑优先级
|
||
- [ ] 合伙人/门店登录空字段前端提示；暂停合伙人微信登录被拒
|
||
- [ ] mini-user：电话脱敏、拨打埋点、提货确认、无分享按钮、首图 preview、门头/套餐正常
|
||
- [ ] mini-user：配送中物流摘要 + 签收照预览 + 电话拨号 + 时间线旧→新全点亮 + 预估送达
|
||
- [ ] 小飞侠路由回调 `POST /callbacks/courier/xfx/track`：status=5 或 statusName 已签收 → 订单 **COMPLETED**；重复回调幂等
|
||
- [ ] 各端上传 >10MB 图片自动压缩后可上传；仍超限有明确报错
|
||
- [ ] `pnpm lint` 无新增错误
|