143 lines
6.5 KiB
Markdown
143 lines
6.5 KiB
Markdown
# chat-history 页面数据来源排查
|
||
|
||
> 排查日期：2026-03-18
|
||
> 页面路径：pages/chat-history/chat-history
|
||
> 排查范围：chat-history.ts / .wxml / .wxss / .json + 引用的 mock-data.ts / sort.ts / time.ts
|
||
|
||
## 概览
|
||
|
||
| 分类 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| A. Mock 数据 | 5 字段 | 全部列表数据来自 `mockChatHistory`，无真实 API |
|
||
| B. 硬编码数据 | 5 处 | `ICON_GRADIENTS` 配色、延迟常量、回退值、跳转路径 |
|
||
| C. 已对接 API | 0 | 页面尚未对接任何后端接口 |
|
||
| D. 前端计算/派生 | 4 字段 | `timeLabel`、`iconGradient`、`pageState`、`statusBarHeight` |
|
||
| E. 路由参数 | 0 | 本页无接收路由参数（跳转时传出 `historyId`） |
|
||
| F. WXML 硬编码文案 | 6 处 | 加载/错误/空态/底部提示等 UI 文案 |
|
||
|
||
---
|
||
|
||
## 一、Mock 数据（来自 mock-data.ts）
|
||
|
||
数据源：`import { mockChatHistory } from '../../utils/mock-data'`
|
||
类型定义：`ChatHistoryItem`
|
||
|
||
| # | 字段 | 类型 | Mock 值示例 | 说明 |
|
||
|---|------|------|-------------|------|
|
||
| 1 | `id` | `string` | `'chat-001'` | 对话记录唯一 ID |
|
||
| 2 | `title` | `string` | `'张伟消费分析'` | 对话标题 |
|
||
| 3 | `lastMessage` | `string` | `'已记录。下次回访张伟时...'` | 最后一条消息摘要 |
|
||
| 4 | `timestamp` | `string` | `'2026-03-05T14:02:03+08:00'` | ISO 8601 时间戳 |
|
||
| 5 | `customerName` | `string?` | `'张伟'` / `undefined` | 可选，关联客户名 |
|
||
|
||
Mock 数据条数：4 条（`mockChatHistory` 数组长度）
|
||
|
||
---
|
||
|
||
## 二、硬编码数据
|
||
|
||
| # | 位置 | 值 | 说明 |
|
||
|---|------|-----|------|
|
||
| 1 | `chat-history.ts` 顶部常量 `ICON_GRADIENTS` | 6 组 CSS 渐变色 | VI 规范 §6.2 AI 图标配色系统（indigo/purple/red/orange/yellow/blue） |
|
||
| 2 | `chat-history.ts` → `loadData()` | `setTimeout(..., 400)` | 模拟网络延迟 400ms，联调时需替换为真实异步调用 |
|
||
| 3 | `chat-history.ts` → `onPullDownRefresh()` | `setTimeout(() => wx.stopPullDownRefresh(), 600)` | 下拉刷新 600ms 后停止，联调时需与真实请求回调绑定 |
|
||
| 4 | `chat-history.ts` → `onLoad()` | `sysInfo.statusBarHeight \|\| 44` | 状态栏高度回退值 44（当前 WXML 中未消费该值） |
|
||
| 5 | `chat-history.ts` → `onItemTap()` | `'/pages/chat/chat?historyId=' + id` | 跳转路径硬编码 |
|
||
|
||
---
|
||
|
||
## 三、已对接 API
|
||
|
||
**无。** 页面当前 0 个真实 API 调用。
|
||
|
||
代码中有明确 TODO 注释：
|
||
```typescript
|
||
// TODO: 替换为真实 API 调用
|
||
const sorted = sortByTimestamp(mockChatHistory)
|
||
```
|
||
|
||
---
|
||
|
||
## 四、前端计算/派生数据
|
||
|
||
| # | 字段 | 计算逻辑 | 依赖 |
|
||
|---|------|----------|------|
|
||
| 1 | `timeLabel` | `formatRelativeTime(item.timestamp)` | `time.ts` → 将 ISO 时间戳转为「刚刚/N分钟前/N小时前/N天前/MM-DD/YYYY-MM-DD」 |
|
||
| 2 | `iconGradient` | `ICON_GRADIENTS[Math.floor(Math.random() * ICON_GRADIENTS.length)]` | 从 6 色渐变数组中随机取一个（每次渲染结果不同） |
|
||
| 3 | `pageState` | 状态机：`'loading'` → `'normal'` / `'empty'` / `'error'` | 根据 `list.length === 0` 判断空态，`catch` 进入错误态 |
|
||
| 4 | `statusBarHeight` | `wx.getWindowInfo().statusBarHeight \|\| 44` | 系统 API 获取（当前 WXML 未消费此值） |
|
||
|
||
---
|
||
|
||
## 五、路由参数
|
||
|
||
**本页无接收路由参数。** `onLoad()` 未读取 `options` 参数。
|
||
|
||
传出参数（跳转时）：
|
||
|
||
| 目标页 | 参数 | 来源 |
|
||
|--------|------|------|
|
||
| `/pages/chat/chat` | `historyId={item.id}` | 列表项的 `id` 字段（当前为 Mock） |
|
||
|
||
---
|
||
|
||
## 六、WXML 硬编码文案
|
||
|
||
| # | 位置 | 文案 | 说明 |
|
||
|---|------|------|------|
|
||
| 1 | 加载态 toast | `加载中...` | loading 浮层文案 |
|
||
| 2 | 错误态 emoji | `😵` | 错误图标（emoji） |
|
||
| 3 | 错误态文案 | `加载失败，请重试` | 错误提示 |
|
||
| 4 | 错误态按钮 | `重新加载` | 重试按钮文案 |
|
||
| 5 | 空态描述 | `暂无对话记录` | `<t-empty description="暂无对话记录" />` |
|
||
| 6 | 底部提示 | `— 已加载全部记录 —` | 列表底部 footer |
|
||
|
||
---
|
||
|
||
## 七、联调 TODO
|
||
|
||
### 7.1 必须替换的 Mock 数据
|
||
|
||
| 优先级 | 改动项 | 当前状态 | 联调目标 |
|
||
|--------|--------|----------|----------|
|
||
| P0 | `mockChatHistory` → 真实 API | `loadData()` 中直接引用 mock 数组 | 调用后端 `GET /api/chat/history` 或类似接口，返回 `ChatHistoryItem[]` |
|
||
| P0 | 移除 `setTimeout(…, 400)` 模拟延迟 | 硬编码 400ms | 替换为 `wx.request` / 封装的 `http.get()` 异步调用 |
|
||
| P1 | 下拉刷新绑定真实请求 | `onPullDownRefresh` 中 600ms 后固定停止 | 在 API 回调中调用 `wx.stopPullDownRefresh()` |
|
||
|
||
### 7.2 需确认的接口契约
|
||
|
||
| 字段 | 问题 | 建议 |
|
||
|------|------|------|
|
||
| `id` | Mock 为 `chat-001` 格式，后端实际 ID 格式？ | 确认是 UUID / 自增 ID / 其他 |
|
||
| `title` | 对话标题由谁生成？后端还是前端？ | 确认接口是否返回 `title` |
|
||
| `lastMessage` | 是否需要截断？最大长度？ | 确认接口返回的是完整消息还是摘要 |
|
||
| `timestamp` | 后端返回格式？ISO 8601 / Unix ms？ | `formatRelativeTime` 两种都支持 |
|
||
| `customerName` | 可选字段，后端是否一定返回？ | 确认接口契约中该字段的 nullable 语义 |
|
||
|
||
### 7.3 需关注的前端逻辑
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| `iconGradient` 随机分配 | 每次渲染/刷新颜色会变，是否需要按 `id` 哈希固定？ |
|
||
| `statusBarHeight` 未使用 | `data.statusBarHeight` 已计算但 WXML 中无消费，可能是自定义导航栏残留代码 |
|
||
| 分页/无限滚动 | 当前一次性加载全部，数据量大时需要分页 |
|
||
| 错误态重试 | `onRetry` 调用 `loadData()`，联调后需确认错误处理（网络超时/401/500 等） |
|
||
| `import { mockChatHistory }` | 联调完成后需删除此 import 及 `mock-data.ts` 中对应导出 |
|
||
|
||
### 7.4 引用的工具函数（无需改动）
|
||
|
||
| 函数 | 文件 | 用途 | 联调影响 |
|
||
|------|------|------|----------|
|
||
| `sortByTimestamp()` | `utils/sort.ts` | 按 `timestamp` 降序排列 | 纯函数，无需改动 |
|
||
| `formatRelativeTime()` | `utils/time.ts` | 时间戳 → 相对时间文案 | 纯函数，无需改动 |
|
||
|
||
### 7.5 引用的组件
|
||
|
||
| 组件 | 路径 | 数据依赖 |
|
||
|------|------|----------|
|
||
| `ai-float-button` | `/components/ai-float-button/` | 无 props 传入，组件内部自治 |
|
||
| `dev-fab` | `/components/dev-fab/` | 开发调试用浮动按钮，上线前移除 |
|
||
| `t-loading` | TDesign | 无数据依赖 |
|
||
| `t-icon` | TDesign | `name`/`size`/`color` 硬编码 |
|
||
| `t-empty` | TDesign | `description` 硬编码 |
|