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 注释：
四、前端计算/派生数据
| # |
字段 |
计算逻辑 |
依赖 |
| 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 硬编码 |
