Files
lingniu-vehicle-ingest/vehicle-data-platform/design-qa.md
2026-07-20 03:49:28 +08:00

252 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 单车详情移动端 Semi UI Design QA
- source visual truth: 生产版本 `f59148e2``/vehicles/LB9A32A26R0LS1489`
- source screenshots:
- directory desktop: `/tmp/semi-goal-audit-20260719-next/01-vehicle-directory-desktop.png`
- detail desktop: `/tmp/semi-goal-audit-20260719-next/02-vehicle-detail-desktop.png`
- detail mobile: `/tmp/semi-goal-audit-20260719-next/03-vehicle-detail-mobile.png`
- implementation screenshots:
- detail mobile: `/tmp/semi-goal-audit-20260719-next/04-vehicle-detail-mobile-after.png`
- detail desktop: `/tmp/semi-goal-audit-20260719-next/05-vehicle-detail-desktop-after.png`
- comparison evidence:
- mobile before/after: `/tmp/semi-goal-audit-20260719-next/vehicle-detail-mobile-comparison.png`
- viewport and state:
- desktop `1440 × 900`
- mobile `390 × 844`
- 使用管理员生产数据与同一辆车 `粤AGP3506`
## Fidelity Ledger
| Surface | Required fidelity | Implementation evidence | Result |
| --- | --- | --- | --- |
| Vehicle identity | 车牌、在线状态、VIN、品牌车型和三类协议来源必须完整。 | 保留原任务栏结构;车型允许两行且提供完整 `title`,协议标签保持 Semi Tag 色彩语义。 | Improved. |
| Live evidence | 速度、SOC、总里程和当日里程不能被截断或隐藏。 | 修正移动端带上下文指标轨道的网格优先级;四项指标获得完整宽度,实测全部 `clipped=false`。 | Fixed. |
| First viewport | 首屏必须尽快进入地图,不能被重复卡片和过高操作区占满。 | 身份、动作、位置、来源入口和章节导航收敛;地图顶部由 `652px` 提前至 `569px`。 | Improved. |
| Location workflow | 当前坐标、按需地址解析和车辆实时跟随必须保留。 | 坐标与解析按钮合并成一行;未增加自动逆地理编码,地图和实时轮询逻辑未改。 | Preserved. |
| Source evidence | 总里程、当日里程和“查看全部来源”仍需打开同一证据面板。 | 实测总里程按钮打开 Semi Bottom SideSheet日期和来源证据可见关闭后恢复页面。 | Passed. |
| Section navigation | 实时位置、最近事件、实时遥测和车辆主档必须可达。 | 四个 Semi Button 保留可访问名称;点击实时位置后目标区域获得焦点。 | Passed. |
| Desktop stability | 移动端收敛不能造成桌面布局回退。 | `1440 × 900` 桌面截图保持原信息结构,横向溢出 `0px`。 | Preserved. |
| Asset fidelity | 品牌、地图和图标不得由临时资产代替。 | 继续使用生产 Logo、高德地图、Semi Icon、Card、Button、Tag 与 SideSheet。 | Preserved. |
## Interaction And Accessibility Checks
- 页面根节点保留“车牌 + 车辆档案”的可访问标签;
- 总里程和当日里程继续以有名称的按钮进入来源证据;
- 来源证据 SideSheet 可打开、读取并通过“关闭来源证据”退出;
- 章节导航点击后执行平滑滚动并将焦点交给目标区域;
- `390px``1440px` 视口横向溢出均为 `0px`
- 生产数据下总里程、当日里程、速度和 SOC 均无视觉裁切;
- 控制台未发现本次改动产生的运行时异常。
## Comparison History
### Pass 1 — fixed
- 原移动端指标轨道仍被通用 `has-context` 网格分成两列,隐藏的来源上下文占用一半宽度,导致总里程显示为 `80,27…`
- 当前修复将四项实时指标恢复到完整宽度的 `2 × 2` 网格,并压缩重复的纵向间距。
- 同视口并排对比确认地图在首屏获得约 `83px` 的额外可见空间,车型和里程信息完整。
- 未发现 P0、P1 或 P2 视觉与交互问题。
## 全站移动导航 Semi UI Design QA
- source visual truth: ECS 生产端 `/monitor?mode=list`
- source screenshots:
- shell baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/before-monitor-mobile.png`
- more baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/before-more-sheet.png`
- help baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/before-help-sheet.png`
- statistics filter baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/before-statistics-filter.png`
- implementation screenshots:
- more launcher: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/after-more-sheet-local.png`
- active module: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/after-more-active-fixed-local.png`
- comparison evidence:
- before/after: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-ui-shell/compare-more-before-after.png`
- viewport and state:
- mobile `390 × 844`
- 管理员权限、全局监控列表模式
### Fidelity Ledger
| Surface | Required fidelity | Implementation evidence | Result |
| --- | --- | --- | --- |
| Permission model | 客户与管理员仍只能看到已授权菜单。 | 继续使用 `hasMenu()` 过滤主导航和更多功能分组,未新增绕过入口。 | Preserved. |
| Navigation hierarchy | 高频任务保留底栏,低频任务必须有清晰业务分组。 | 全局监控、车辆查询、轨迹回放、里程查询仍在底栏;历史/告警与平台治理维持两组。 | Passed. |
| Module recognition | 更多功能不能只靠小图标和短标签辨认。 | 每个模块增加真实任务说明、独立 Semi 图标容器和进入指示。 | Improved. |
| Current state | 位于二级模块时,重新打开更多功能必须识别当前位置。 | 当前模块使用蓝色边框、浅蓝底色和图标强调,未叠加重复装饰线。 | Passed. |
| Touch density | 入口需要适合移动端点击,同时单屏展示完整模块集合。 | 模块卡片最小高度 `68px`,两列布局在 `390 × 844` 下完整显示五个入口。 | Passed. |
| Shared shell | 帮助、筛选与更多功能应属于同一 Semi UI 工作台体系。 | 继续复用 `WorkspaceSideSheet` 的标题、徽标、遮罩、圆角和滚动边界。 | Preserved. |
| Asset fidelity | 不使用临时图形或自制 SVG。 | 全部使用 `@douyinfe/semi-icons` 与 Semi UI `SideSheet``Tag``Button`。 | Preserved. |
### Interaction And Accessibility Checks
- 底栏仍为命名为“主导航”的可访问导航区域;
- 更多按钮继续暴露 `aria-expanded``aria-controls`
- 两个业务分组均为独立命名导航;
- 五个模块入口保留链接语义与预加载行为;
- 当前模块继续由 React Router 输出 `aria-current="page"`
- 关闭按钮仍使用“关闭更多功能”的可访问名称;
- `390 × 844` 同视口前后对照未出现横向溢出、裁切或不可达入口;
- 页面帮助和里程筛选基线检查未发现本次共享样式导致的回退。
### Comparison History
#### Pass 1 — fixed
- 旧版入口卡片依赖小图标和短标签,任务意图不够明确,分组又被大面积边框切割。
- 新版保持原路由与权限边界,用两列 Semi UI 模块卡片展示任务说明,并减弱分组容器噪声。
- 首次视觉复核发现当前模块仍继承底栏的底部装饰线;已在更多功能作用域内移除,保留单一高亮语义。
- 同尺寸并排对比确认五个入口均可见,层级更清晰,未发现 P0、P1 或 P2 视觉与交互问题。
## 查询工作台 Semi UI Design QA
- source visual truth: ECS 生产端车辆查询、轨迹回放、历史数据
- source screenshots:
- vehicle page: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-vehicles-mobile.png`
- vehicle filter: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-vehicle-filter-mobile.png`
- track page: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-tracks-mobile.png`
- track workbench: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-track-filter-mobile.png`
- history page: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-history-mobile.png`
- history filter: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/before-history-filter-mobile.png`
- implementation screenshots:
- vehicle filter: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/after-vehicle-filter-mobile-settled.png`
- history filter: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/after-history-filter-mobile.png`
- history draft state: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/after-history-filter-draft-mobile.png`
- desktop history: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/after-history-desktop.png`
- comparison evidence:
- vehicle mobile: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/compare-vehicle-filter-mobile.png`
- history mobile: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/compare-history-filter-mobile.png`
- history desktop: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-query-workspaces/compare-history-desktop.png`
- viewport and state:
- mobile `390 × 844`
- desktop `1440 × 900`
- 管理员权限、未提交查询的初始状态
### Fidelity Ledger
| Surface | Required fidelity | Implementation evidence | Result |
| --- | --- | --- | --- |
| Shared filter anatomy | 车辆与历史筛选应与轨迹查询使用同一标题、摘要、内容和确认边界。 | `MobileFilterSheet` 新增共享 `summaryItems`,继续复用 `WorkspaceSideSheet`。 | Improved. |
| Draft visibility | 用户修改条件时必须知道尚未应用的车辆、时间和数据范围。 | 摘要直接读取草稿状态;输入 `沪A01559F` 后车辆范围立即由“待选择”更新为“1 辆”。 | Passed. |
| Vehicle discovery | 查车面板必须同时说明账号授权范围、当前关键词和快速结果状态。 | 生产数据下显示 `1,024 辆``全部车辆``待输入`,输入后同步更新当前条件和匹配状态。 | Passed. |
| History scope | 历史查询必须同时呈现车辆上限、日期区间、数据类型和协议来源。 | 三段摘要对应车辆范围、时间范围和数据范围,并保留上海时区说明。 | Passed. |
| Track consistency | 轨迹查询现有行程摘要和查询状态不能被新共享组件破坏。 | 轨迹仍使用同一个 `WorkspaceSideSheet` 摘要模型,页面与查询明细交互未修改。 | Preserved. |
| Desktop stability | 移动端工作台迁移不得改变桌面查询布局和密度。 | `1440 × 900` 同状态前后截图一致,桌面继续使用 `WorkspaceFilterPanel`。 | Preserved. |
| Action boundary | 草稿不应在关闭弹层时意外应用。 | 关闭、重置、应用三类动作保持独立,原测试继续覆盖草稿回滚和显式提交。 | Preserved. |
### Interaction And Accessibility Checks
- 摘要区域使用命名列表,并继承“车辆搜索摘要”“历史查询范围摘要”等可访问名称;
- 车辆筛选输入后,摘要与候选列表同时更新;
- 历史筛选输入后,车辆数量实时更新,应用按钮恢复可用;
- 筛选弹层关闭、重置与应用按钮保持完整可见;
- `390 × 844` 下内容由共享滚动区承载,无横向溢出;
- `1440 × 900` 桌面历史查询前后布局一致;
- 轨迹回放原有摘要、地图、播放轴与查询明细未发生行为回退。
### Comparison History
#### Pass 1 — fixed
- 原车辆和历史筛选只有标题与表单,用户需要进入字段后才能理解当前授权范围和草稿状态;轨迹查询已经具备摘要层,三页层级不统一。
- 当前将摘要能力下沉到 `MobileFilterSheet`,车辆和历史页通过真实查询状态填充,不复制新的弹层组件。
- 首次截图在 SideSheet 进入动画期间截到不完整底栏;等待动画稳定后复核,重置与应用按钮完整可见。
- 同视口对比确认新增摘要没有压缩关键输入、日期范围和来源选择,未发现 P0、P1 或 P2 问题。
## 共享数据面板标题 Semi UI Design QA
- source visual truth: ECS 生产端里程查询、告警中心、接入管理与运维质量结果面板
- source screenshots:
- statistics baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/desktop-statistics-after.png`
- mobile statistics baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/mobile-statistics-after.png`
- implementation screenshots:
- statistics desktop: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/desktop-statistics-fixed.png`
- statistics mobile: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/mobile-statistics-fixed.png`
- alert center desktop: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/desktop-alerts-fixed.png`
- access center desktop: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/desktop-access-fixed.png`
- operations desktop: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-panel-hierarchy-20260720/desktop-operations-fixed.png`
- viewport and state:
- mobile `390 × 844`
- desktop `1440 × 900`
- 管理员权限、生产数据、默认查询状态
### Fidelity Ledger
| Surface | Required fidelity | Implementation evidence | Result |
| --- | --- | --- | --- |
| Semantic hierarchy | 高频结果区必须先说明数据语境,再给出当前任务标题。 | 共享 `WorkspacePanelHeader` 新增真实眉题层;里程、告警、接入、历史、对账和运维分别使用“每日统计”“实时队列”“接入差异”等业务语义。 | Improved. |
| Tone consistency | 不同业务状态需要可辨认,但不能形成高饱和装饰色块。 | 使用共享 primary、warning、health 等低对比度语义变量,只在顶部细线、眉题与轻微渐变中表达状态。 | Passed. |
| Data density | 标题升级不能挤压表格、统计条和分页主体。 | `1440 × 900` 下四个生产结果页保留原表格行数、筛选条件、分页和滚动边界。 | Preserved. |
| Mobile hierarchy | 眉题、结果标题、车辆数量和操作不能在窄屏互相遮挡。 | 里程结果头在 `390px` 下缩短描述并收敛文本轨道;车辆数量、刷新和导出仍完整可见。 | Passed. |
| Action continuity | 刷新、导出和结果计数仍需保持原按钮语义与点击范围。 | 共享组件只调整标题结构,原 Semi Button、Tag、事件处理器和可访问名称均未替换。 | Preserved. |
| Shared implementation | 页面不能各自复制标题视觉规则。 | 六个页面复用同一 `WorkspacePanelHeader` 与统一 tone 类型,样式集中在 `workspace.css`。 | Passed. |
| Desktop stability | 共享视觉层不得产生横向溢出、截断或固定列错位。 | 里程、告警、接入和运维生产截图均无标题裁切,列表滚动条、固定列及分页位置正常。 | Passed. |
### Interaction And Accessibility Checks
- 结果标题继续输出正确的 Heading 层级,眉题使用 Semi Typography 文本而不是模拟标题;
- 里程查询的“刷新里程数据”和“导出 Excel”保留完整可访问名称
- 告警、接入和运维结果列表保留原筛选、刷新、分页与纵向滚动交互;
- `390 × 844` 下里程矩阵车牌列与区间总里程列继续固定,日期列可横向浏览;
- `1440 × 900` 下四个重点页面没有出现标题折断、操作区覆盖或列表主体缩水;
- 生产发布版本 `semi-panel-hierarchy-20260720031800` 完成资源烟测与登录态复核。
### Comparison History
#### Pass 1 — fixed
- 首轮移动端复核发现新增眉题、结果标题和车辆数量在同一窄轨道内显得拥挤。
- 通过共享标题的移动端两级文本布局和里程结果区专用宽度约束,减少无效描述占位,同时保留结果计数与操作。
- 第二轮同视口截图确认“每日统计—车辆每日里程—20 / 1024 辆”层级可辨,刷新、导出和首屏表格均可达。
- 桌面端里程、告警、接入与运维四个结果面板语义色克制、密度稳定,未发现 P0、P1 或 P2 视觉与交互问题。
## 共享语义状态 Semi UI Design QA
- source visual truth: ECS 生产端车辆目录空结果与运维、轨迹证据状态
- source screenshots:
- vehicle directory normal baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/03-vehicles-mobile-before.png`
- vehicle directory empty baseline: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/04-vehicles-empty-before.png`
- implementation screenshots:
- vehicle directory empty: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/05-vehicles-empty-after.png`
- operations health overview: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/06-operations-health-after.png`
- operations compact success: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/08-operations-health-bottom-after.png`
- track mobile initial state: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/09-track-empty-after.png`
- track desktop initial and evidence state: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/10-track-desktop-empty-after.png`
- alert center regression: `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest/.codex-audit/semi-empty-secondary-20260720/11-alerts-empty-after.png`
- viewport and state:
- mobile `390 × 844`
- desktop `1440 × 900`
- 管理员权限、生产数据、空查询与健康检查通过状态
### Fidelity Ledger
| Surface | Required fidelity | Implementation evidence | Result |
| --- | --- | --- | --- |
| Empty result recognition | 无结果不能只剩大块白色画布,用户应立即识别当前状态。 | 共享 `PanelEmpty` 增加 Semi Icon、标题、说明和轻量语义底色车辆目录空结果获得明确搜索图标。 | Improved. |
| Recovery path | 可恢复的空结果必须给出唯一、直接的下一步。 | 车辆目录提供“清除搜索”,实测点击后恢复 1,024 辆授权目录;对账空结果提供“重置筛选”。 | Passed. |
| Semantic tone | 空结果、通过、提醒和失败不能使用同一种视觉语义。 | primary、success、warning、danger 四类状态共享同一结构,仅使用克制的顶部语义线、图标色和浅背景区分。 | Passed. |
| Compact evidence | 侧栏、时间线和小型证据区不能被完整空状态撑高。 | `compact` 状态在轨迹证据、告警履历、来源证据、遥测和运维容量检查中保持约 104112px 的稳定高度。 | Passed. |
| Functional continuity | 状态迁移不能改变查询、刷新、分页和证据读取逻辑。 | 仅替换呈现组件;车辆清除搜索、运维唯一重试路径和原页面查询键保持不变。 | Preserved. |
| Cross-page reuse | 页面不能继续维护互不相同的 Empty 字号、插图和间距。 | 车辆、监控、轨迹、告警、单车、来源、对账和运维共用 `PanelEmpty` 的 tone、icon、compact 契约。 | Improved. |
| Dense-page stability | 新状态样式不得挤压正常数据页。 | 告警队列、运维健康卡片、车辆正常目录和轨迹工作台生产截图均保持原行数、滚动区与操作位置。 | Passed. |
### Interaction And Accessibility Checks
- 空状态继续使用 Semi Empty并由外层 `role="status"``aria-live="polite"` 公布;
- 失败状态保留 `role="alert"`,运维来源失败只保留一个“重试”按钮,避免重复恢复入口;
- 图标来自 `@douyinfe/semi-icons`,不使用文本符号、临时 SVG 或占位资产;
- 车辆目录“清除搜索”按钮在 `390 × 844` 下可见、可点击,点击后空状态消失且授权目录恢复;
- 轨迹桌面端左侧紧凑状态与中央引导状态互不重复,查询表单和播放控制仍可达;
- 运维健康页容量检查通过状态没有覆盖运行时表格,主滚动区域继续可上下浏览;
- `1440 × 900``390 × 844` 下均未发现横向溢出、文字裁切或不可达操作。
- 生产发布版本 `semi-semantic-states-20260720033333` 完成资源烟测与管理员登录态复核。
### Comparison History
#### Pass 1 — fixed
- 原车辆空结果只有两行居中文字,整张结果卡大面积留白,且没有恢复动作。
- 首轮共享状态实现增加图标、语义背景和恢复按钮,同时发现运维来源失败同时出现两个“重试”入口。
- 删除重复的状态内重试,只保留页面级错误恢复;全量 370 项前端测试恢复通过。
- 第二轮生产截图确认车辆空结果、轨迹紧凑证据和运维成功状态遵循同一套 Semi UI 结构,未发现 P0、P1 或 P2 视觉与交互问题。
final result: passed