附录 A 案例集
具体故障和记录按章归类,正文只留规律并指向这里。
A.4 第 4 章 页面交互
A.4.1 动态选择题:AI 正文已有“1/2/3”时,不要再叠一套按钮
选择题只有一个权威展示源:结构化选项卡与 AI 正文的“1/2/3”不能重复渲染。应隐藏卡片的重复提问,而非删掉模型正文;选择/刷新后旧按钮要失效,且始终允许用户自定义输入。
A.4.2 语音解析出了文字,点击“批量加入”却消失:三种成功不能混淆
语音识别到文字、保存接口成功、列表能按正确日期查到是三种不同成功。保存失败不能先清空口述草稿;跨午夜必须显式保留 recordDate,刷新页面后仍能回查数据。
A.4.3 点击日历日期却被强制滚走:不要为展示详情牺牲阅读位置
点击日历里的普通日期,应更新选中态和详情,不要默认强制页面滚走。只有用户从逾期提示主动跳转时才考虑最小必要滚动;先确认滚动的是 window 还是内部 main 容器。
A.4.4 验证“工具正在准备”有多慢:计时起点必须与测试目标对应
测“工具正在准备”显示慢,要从收到首个工具事件到 UI 状态出现计时,不能直接从用户点击发送计时。端到端首响应、工具事件显示、真实工具执行应分别打点,否则会把模型决定调用工具的时间错算成前端卡顿。
A.6 第 6 章 移动端与实现
A.6.1 考试答题页在手机上只剩约 130px:响应式“其他页正常”不代表整个产品适配
移动端试卷不能保留挤占主体的 PC 双栏:220px 固定答题卡可能把手机题目压成约 130px。把题目/输入作为主区域,答题卡收进抽屉,并在 320/375/390/414px 验证完整答题到交卷流程。
A.6.2 插件有描述却在面板里完全看不到:核对数据链路每一层
插件 package.json 已有 description、界面却不展示,可能是后端 API 没透传字段。按“元数据源→服务响应→前端组件→浏览器版本”追踪;先确认数据在哪一层丢了,再谈是否重新写描述。
A.6.3 任务包在测试浏览器可见、用户新浏览器却看不到:currentRequestId 不能当“显示最新结果”的唯一门禁
前端用 localStorage 的 currentRequestId 识别“本次刷新”,不能用它当唯一条件决定“可否读取服务器上最新成功快照”。另一设备没有本地 ID,却仍应看见已完成的结果;本次进度状态与全局最新可读状态要分离。
A.6.4 Pi 终端滚动突然跳顶:渲染指令本身可以成为根因
终端自动跳顶不一定是业务状态变化:转义序列如 ESC[3J 清屏、终端全量重绘和滚动容器会带来不同结果。只拦清屏控制码不能证明跳顶修好了;要抓实际输出、复现滚动位置并分别验收。
A.6.5 PWA 安装入口:浏览器环境不同,不一定能一键添加主屏幕
PWA manifest 和 service worker 使网页具备安装条件,但 iPhone Safari、iOS Chrome 与桌面 Chromium 的安装入口不同。页面只能在浏览器支持的条件下调用安装提示,否则展示与当前设备一致的手动引导。
A.6.6 SPA 页面一打开就白屏:服务器返回 HTML 不代表 JavaScript 资源正确
SPA 返回 index.html 为 200,不保证 JS 资源正确。若错误的 base path 使静态 JS 请求也被重写成 HTML,浏览器仍会白屏;应查 script URL、Content-Type、实际响应体及控制台,再修部署入口/路由。