shishengliang/ln-bi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7d8bff46608d78256424585235518721c3049b5a
ln-bi/docs/ui-optimization-checklist.md
T

16 KiB
Raw Blame History

LN-BI UI 优化待办清单

生成日期：2026-09-20 来源：全局外壳/导航、数据看板与图表、业务操作页面三路 UI/UX 审查汇总 用法：- [ ] 为未完成，- [x] 为已完成；每条附 文件:行号 证据，完成后建议连同代码一起提交。 关联文档：../LN-BI-项目分析报告.md §11.4、../LN-BI-重构方案.md 阶段 5/6

P0 可用性与数据信任（最优先）

可访问性：下拉组件

  • SearchSelect 键盘/读屏不可用：补 role="combobox" + aria-expanded + listbox/option 语义、↑↓/Enter/Escape，或直接替换 Headless UI / Radix Combobox — src/components/SearchSelect.tsx:47-68
  • MultiSearchSelect 同上，且焦点环颜色与单选版不一致（emerald vs blue）— src/components/MultiSearchSelect.tsx:59-85
  • mileage SearchableSelect 选项为裸 div，键盘不可达 — src/modules/mileage/monitoring/components/SearchableSelect.tsx:60-72
  • 排序表头补 aria-sort；三张 div 模拟表格中期换成真 <table> — src/modules/mileage/daily-report/VehicleTable.tsx:220-271、GroupRow.tsx:86-132、ElectricDaily.tsx:124-186、HydrogenDaily.tsx:192-272

可访问性：弹窗/全屏

  • 抽共用 Modal/BottomSheet 壳：统一 role="dialog" aria-modal、Escape 关闭、遮罩点击关闭、焦点圈禁与还原、滚动锁定、移动端安全区 — 参考 src/components/feedback/FeedbackModal.tsx:59-66、FeedbackHistoryDrawer.tsx:67-83
  • 全屏监控/全屏表格补 aria-label + Escape 关闭 + 打开时焦点移到关闭按钮 — src/modules/mileage/monitoring/components/FullscreenMonitoring.tsx:111-119、src/modules/mileage/statistics/FullscreenTargetTable.tsx:49-60
  • 抽 useScrollLock hook，统一锁定 body 滚动（VehicleDetailModal/FlowDetailModal/NotificationHistory 目前未锁）— src/modules/assets/components/VehicleDetailModal.tsx:47、FlowDetailModal.tsx:33、src/modules/scheduling/NotificationHistory.tsx:122
  • 移动端底栏分组弹层：修溢出屏幕（定位约束）、加遮罩点击关闭、活动项补 aria-current — src/components/Shell.tsx:194-206
  • 全部图标按钮补 aria-label/title（监控工具栏等）— src/modules/mileage/monitoring/components/MonitoringToolbar.tsx:88-93
  • 移动端卡片用 span 冒充可点击元素：改 <button type="button"> + 稳定业务 key — src/modules/assets/components/overview/AssetSummaryMobileCards.tsx:60-63、InventoryMobileList.tsx:50,93

数据可信

  • 全屏监控筛选口径与普通视图静默不一致：全屏复用同一 monitoringQuery，或在全屏头部明示"以下筛选未生效：项目/主体/里程区间" — src/modules/mileage/monitoring/query-model.ts:92-96、MonitoringView.tsx:108-110
  • 热力图刷新期间旧数据无标识：请求期间地图区加半透明遮罩 + spinner，或 KPI/热力层 opacity-50 过渡（两个热力图文件同步改）— src/modules/vehicle-heatmap/VehicleHeatmapModule.tsx:73-92,143-147、src/modules/hydrogen-heatmap/HydrogenHeatmapModule.tsx
  • 洞察卡片"月度动能"对进行中当月做按天折算或加"本月未完整"标注；正收益改用 TrendingUp/CheckCircle 图标 — src/modules/energy/hydrogen-overview/model.ts:64-66、components/InsightCards.tsx:77-79
  • 区分"无数据"与"数据未就绪"两种空态文案；未就绪时隐藏 KPI 行 — src/modules/energy/ElectricDaily.tsx:62,101-119、HydrogenDaily.tsx:91-109

写操作防错与反馈

  • 「登记干预」加二次确认弹层（复用 BatchConfirmModal 底部弹模式，展示 原车牌→候选车牌+客户）— src/modules/scheduling/SwapPreview.tsx:33-40,155-163
  • 批量干预成功后保持 resp.message 可见（弹窗延迟关闭或页面 Toast），失败才留在弹窗内 — src/modules/scheduling/SchedulingModule.tsx:142-144、scheduling-module/BatchConfirmModal.tsx:59-61
  • 替换全部原生 alert/confirm 为统一 Toast/内联错误 — src/modules/scheduling/SwapPreview.tsx:44-47、NotificationHistory.tsx:109-110

上传/导入工作流

  • UploadDropzone 前置校验扩展名/大小并内联报错；uploading 期间禁用点击/拖入防并发 — src/modules/ele/import-page/UploadDropzone.tsx:42-58、EleImportPage.tsx:77-95
  • 大文件上传给进度反馈（XMLHttpRequest 进度），成功后状态改"✓ 已导入，点击重新上传" — src/modules/ele/EleImportPage.tsx:77-95
  • 导入记录表分页或"加载更多"，修 total 与可见 50 条脱节；搜索改防抖即时生效或显式搜索按钮；输入框加清除按钮 — src/modules/ele/EleImportPage.tsx:58、import-page/RecordFilters.tsx:30
  • 空态区分"无记录"与"筛选无结果" — src/modules/ele/import-page/RecordTable.tsx:46

P1 明显体验缺陷

加载/刷新范式统一（目标：氢能总览为模板）

  • 日报已有数据时改顶部进度条 + 内容淡化（去掉全屏遮罩），取消或缩短 280ms 强制延迟；全屏遮罩仅留首次加载 — src/modules/mileage/DailyReportView.tsx:24,134-136、MileageLoadingOverlay.tsx:13
  • 统计报表补骨架屏 + ErrorState + 重试，不再静默吞错 — src/modules/mileage/StatisticsView.tsx:39-100
  • 电能/氢能"每日"页补首屏骨架屏 — src/modules/energy/ElectricDaily.tsx:131-132、HydrogenDaily.tsx:208-209
  • 电能总览 LoadingState 单卡片升级为骨架屏 — src/modules/energy/ElectricOverview.tsx:31

布局错位与遮挡

  • 监控 KPI 吸顶条按断点修正 sticky 偏移（导航 62px + 顶栏 48px），375px 与 1440px 实机滚动验证 — src/modules/mileage/monitoring/components/MonitoringSummary.tsx:27、src/modules/mileage/MileageModule.tsx:33
  • 面包屑遮罩与页面内容重叠：<main> 加 md:pt-12 或 PageFrame 桌面顶距提至 ≥56px — src/components/Shell.tsx:159-164、src/components/ui/surface.tsx:34
  • 面包屑纳入子 tab（如 羚牛氢能 BI / 里程管理 / 统计报表），结构化 breadcrumb 标记；移动端补子 tab 位置指示 — src/components/Shell.tsx:160-163、src/modules/energy/useHashSubTab.ts:30-35

移动端专项

  • 热力图移动端图例不直接隐藏：折叠为渐变条按钮，点击展开 — src/modules/vehicle-heatmap/VehicleHeatmapModule.tsx:220、src/modules/hydrogen-heatmap/HydrogenHeatmapModule.tsx:206
  • VehicleDetailModal 客户视图 13 列在移动端改卡片列表（借鉴 FlowDetailModal 模式）— src/modules/assets/components/VehicleDetailModal.tsx:194-236
  • 库存统计筛选弹层加遮罩点击关闭或改底部弹层 — src/modules/assets/components/overview/InventoryStatisticsSection.tsx:85
  • 地图点击查询打临时 Marker 或二次确认，避免误点覆盖概览 — src/modules/vehicle-heatmap/VehicleHeatmapModule.tsx:94-103
  • 热力图 ToolBar/Scale 避免与底部详情面板重叠（改左上或随面板状态调整）— src/modules/vehicle-heatmap/AmapHeatmapCanvas.tsx:88-89

视觉一致性

  • 次级文字对比度整改：定义对比度达标的语义色 token（slate-500 起步），全站替换 9–12px 的 text-slate-400/300 关键文字 — src/components/ui/surface.tsx:137,181,269、src/components/Shell.tsx:122,154,186
  • 全站字号下限 10–11px，清掉 7–8px — src/modules/mileage/monitoring/components/VehicleList.tsx:77-126、FullscreenMonitoring.tsx:159-318、MonitoringSummary.tsx:30-44
  • SearchSelect/MultiSearchSelect 统一到 slate 系 + rounded-xl + 统一 focus ring，尺寸默认值移入组件内部 — src/components/SearchSelect.tsx:34,48、MultiSearchSelect.tsx:46
  • 资产域表格数字列统一右对齐 + tabular-nums，表头随列对齐 — src/modules/assets/components/overview/AssetSummaryDesktopTable.tsx:22-34,87-192、InventoryDesktopTable.tsx:36,76（对齐标准：src/modules/ele/import-page/BatchTable.tsx:27-47）
  • 分组大表表头 sticky + 容器右缘渐变阴影提示可横滑 — src/modules/assets/components/overview/AssetSummaryDesktopTable.tsx:16-17

筛选/标签交互

  • ActiveFilterTags 默认日期区间不进"已选条件"标签（区间降级为统计周期信息条）— src/modules/mileage/monitoring/components/ActiveFilterTags.tsx:90-97、MonitoringView.tsx:68-69
  • searchTerm 死筛选：工具栏补搜索框，或删除该状态 — src/modules/mileage/MonitoringView.tsx:43、query-model.ts:44
  • 筛选统一即时生效（防抖），删除 filterMileageRange/appliedMileageRange 双状态 — src/modules/mileage/monitoring/components/FilterPanel.tsx:259-267、MonitoringView.tsx:64-65
  • 筛选 tag 清除热区扩至 24px+，tag 整片可点清除 — src/modules/scheduling/scheduling-module/ActiveFilterTags.tsx:15-20
  • 多选模式补"全选当前筛选结果"；不可选项加 title="已干预，不可重复登记" — src/modules/scheduling/SuggestionList.tsx:85-103
  • 监控工具栏快速区间补"近7天" — src/modules/mileage/monitoring/components/MonitoringToolbar.tsx:149-155

小 Bug 集群（改动极小，顺手修）

  • TargetDetailPanel：徽标硬编码"在线"改随 isOnline；ChevronDown 条件旋转；非法类名 bg-slate-50/50/50 — src/modules/mileage/statistics/TargetDetailPanel.tsx:90-95,213,216-218
  • 图表车型长名截断加 title 悬浮完整名，复用 shortTargetName 缩写规则 — src/modules/mileage/daily-report/ReportCharts.tsx:111、GroupRow.tsx:94
  • 热力图默认日期兜底改为"近 30 天"由当前日期推导 — src/modules/vehicle-heatmap/VehicleHeatmapModule.tsx:9-10、src/modules/hydrogen-heatmap/HydrogenHeatmapModule.tsx:9-10
  • 堆叠柱 radius 接缝缺口 — src/modules/mileage/daily-report/ReportCharts.tsx:114-115
  • ReportDatePicker 补点击外部/Esc 关闭；日期加业务下界 — src/modules/mileage/daily-report/ReportDatePicker.tsx:56-110、ReportHeader.tsx:45-53
  • FullscreenTargetTable 行 key 改业务值、补空态、刷新按钮转动反馈 — src/modules/mileage/statistics/FullscreenTargetTable.tsx:49-54,86
  • 电能每日表月份分组行环比列留空问题；氢能每日图 Y 轴 k 与 Kg 混淆 — src/modules/energy/ElectricDaily.tsx:124-153、HydrogenDaily.tsx:155
  • forceLandscape 监听 resize/orientationchange — src/modules/mileage/MonitoringView.tsx:298-308
  • ReportInsights key 撞车改 index 或 id — src/modules/mileage/daily-report/ReportInsights.tsx:26
  • DailyRangeControls 去掉 onChange+onInput 重复触发、加 max 限制未来日期 — src/modules/energy/daily-range/DailyRangeControls.tsx:56-72
  • ETC 占位页里程碑与 meta 文案矛盾统一 — src/modules/energy/EtcModule.tsx:12、ETCView.tsx:50
  • FeedbackHistoryDrawer 死 prop onBack 移除；截图链接补 aria-label；状态文案"已忽略"改"暂不处理" — src/components/FeedbackHistoryDrawer.tsx:44,135-136、FeedbackFab.tsx:169
  • MultiSearchSelect 标签移除按钮补 aria-label — src/components/MultiSearchSelect.tsx:40
  • SearchSelect 容器 onClick 与 input onFocus 双触发误关问题；清理不可达的 placeholder 分支 — src/components/SearchSelect.tsx:35,40,45
  • FeedbackAdminPage 反馈列表 limit=200 静默截断：加分页或溢出说明；tab 计数改后端聚合 — src/modules/admin/FeedbackAdminPage.tsx:79,124-171
  • VehicleDetailModal 周明细表补空态行；footer 计数口径区分"本周流转 n 台/共 n 台" — src/modules/assets/components/VehicleDetailModal.tsx:158-178,267
  • BatchTable 补空态占位；上传成功后最新批次高亮或加"新"徽标 — src/modules/ele/import-page/BatchTable.tsx:12
  • FlowDateRangePicker 超出 370 天日期直接置灰，而非事后报错 — src/modules/assets/components/overview/FlowDateRangePicker.tsx:18-19,110
  • NotificationHistory 增加相对时间（x 小时/天前）；待执行超 48h 加"滞留"警示徽标；"近7天"过滤改后端参数化 — src/modules/scheduling/NotificationHistory.tsx:67-72,222-228
  • SuggestionDetail 当前车摘要 sticky；保留滚动条或滚动阴影 — src/modules/scheduling/SuggestionDetail.tsx:145-169
  • FeedbackFab 改走统一 api-client（401 触发全局登出）— src/components/FeedbackFab.tsx:16-25（同类：EleImportPage.tsx:23-33、FeedbackAdminPage.tsx:52-53）
  • 全局补 :focus-visible 兜底样式 — 目前仅 4 处模块组件有
  • SegmentedNav 的 layoutId 加 useId() 前缀防同页撞车 — src/components/ui/surface.tsx:202-243

P2 体系化改进（对应重构方案阶段 5/6）

  • 设计令牌化：index.css 用 Tailwind 4 @theme 定义语义 token（--color-ink-secondary、--shadow-card、--shadow-nav、--color-surface-bg），替换散落 arbitrary value；删除无人引用的 --panel-bg/--hairline — src/index.css:3-7、src/components/ui/surface.tsx:41、src/App.tsx:49、src/components/Shell.tsx:103
  • 统一格式化层：fmtKm 三套实现合并到 shared；TrendBadge 环比小数位统一 — src/modules/mileage/daily-report/utils.ts:54、src/modules/mileage/statistics/model.ts:48、src/modules/energy/TrendBadge.tsx:21
  • 统一"今天"定义与日期区间预设：日报按上海自然日 / 监控按本地 05:00 / 电能按本地自然日，收敛为一套 — src/modules/mileage/daily-report/utils.ts:13-24、monitoring/date-range.ts:11-15、energy/daily-range/model.ts:22-39
  • 配置化硬编码：高里程告警规则（写死车型名+800km）挪后端或配置常量 — src/modules/mileage/MonitoringView.tsx:36-40；站点横幅硬编码 — src/modules/energy/ElectricOverview.tsx:50-52
  • z-index 分层约定：定义 z-modal/z-overlay 等 token，替换 z-[1000]/z-[80]/z-[60] 随意值 — src/modules/assets/components/FlowDetailModal.tsx:33、VehicleDetailModal.tsx:47、src/modules/scheduling/SwapPreview.tsx:58、NotificationHistory.tsx:122,262
  • 错误呈现统一：表单内联错误用统一 FormError 组件 + role="alert"，对齐 ErrorState — src/components/feedback/FeedbackFormStep.tsx:145、FeedbackHistoryDrawer.tsx:107
  • 深色模式显式决策：短期写进设计约定；中期按 令牌化 → Shell/surface → 图表 palette → 地图底图 顺序评估
  • 导航扩容策略：一级模块超过 5 个时收口为"更多"抽屉；分组首点直达第一个子模块 — src/components/Shell.tsx:117,173,183
  • PageFrame 拆分：hideHeader/compactInfo 布尔分叉拆成 PageHeader 与 CompactHeader 两个组合 — src/components/ui/surface.tsx:46-110
  • 死代码清理：移除 69 处 no-op <Blur> 包裹与 DemoModeProvider enabled={false} — src/components/Blur.tsx:13-16、Shell.tsx:93
  • 杂项：cn.ts 换 clsx + tailwind-merge — src/lib/cn.ts；RotatingFooterHint keyframes 移入 index.css — src/components/RotatingFooterHint.tsx:43-48；UnauthorizedPage 英文 eyebrow 中文化 — src/auth/UnauthorizedPage.tsx:10；简化 index.css 双层滚动容器 — src/index.css:9-26；相对时间 relativeNow 5s 整表重渲染优化 — src/modules/mileage/MonitoringView.tsx:131-134；Top5 榜 Y 轴刻度与 width 解耦 — src/modules/energy/hydrogen-overview/components/DistributionCharts.tsx:31-36,62；饼图 >9 区域颜色循环失真 — 同文件 :15-19,109；水印时间戳随会话刷新 — src/components/Shell.tsx:86-90

已确认的正面实践（保持，勿回退）

  • 氢能总览：骨架屏 + 非打断 RefreshOverlay（全站推广模板）
  • VehicleTable 可点行：role/tabIndex/aria-pressed/键盘支持、吸顶首列 + 右侧阴影
  • GroupRow 的 aria-expanded；日报日期写回 URL 可刷新恢复
  • BatchTable 数字右对齐 + tabular-nums（资产域对齐目标）
  • FlowDetailModal 移动端卡片模式（VehicleDetailModal 降级参考）
  • 动效克制（layoutId 弹簧/FadeIn/shimmer 均为 transform/opacity 级）

建议实施顺序

阶段 内容
第 1 周 P0 写操作反馈 / 上传工作流 / 数据可信 / 小 Bug 集群
第 2 周 P0 可访问性（Modal 壳 + useScrollLock + 下拉组件）+ 加载范式统一 + 布局错位
第 3 周 P1 移动端专项 + 视觉一致性
持续 P2 令牌化 → 格式化/日期层 → 配置化（重构方案阶段 5/6）
Reference in New Issue View Git Blame Copy Permalink