🎨 UI / 界面¶
组件 / 布局 / Drawer / 列表 / Chip / 国旗
⚙️ 本文件由
pnpm docs:rebuild自动生成 — 修改无效。
涉及文档(89 个)¶
🧭 产品使用文档(1)¶
- 这一批更新你会看到什么(v0.10.180 → 194) · stable
- 设置页重排、两个会误导你的提示被修掉、两个安全问题、导入导出
📐 架构 / 知识沉淀(2)¶
- 电话来源三态持久化协议 · stable
- 地图、官网与来源未知的写入、兼容解码和证据计数规则
- Popup 认证状态机
- 浏览器扩展 popup 的登录态机制 — 4 态状态机 + 2 秒超时兜底 + 多重登录入口
🎯 功能规格(2)¶
- SPEC-000 — v2 UI 改版说明(v0.8.58 → v0.9.x → v0.10.x) · done
- 早期整体界面改版历史档案;dist/ 与 dist-v2/ 双轨阶段进度记录
- SPEC-026 把快速筛选做成内置视图 · done
- 消灭 quickFilter 这个平行维度;内置视图默认固定、可取消固定、不占配额
🔧 已知问题 + 修复(65)¶
- [ISSUE-0006]「有邮箱」chip 选中但表格未过滤 · fixed
- 选有邮箱,但是这边还是所有的,其他是不是也是呢?
- 设置页右侧出现两个滚动条 · fixed
- 设置的右侧两个滑动的??
- 商家列表单行高度过大 · fixed
- 商家列表,单个商家的高度继续压缩,上下空白有点大
- 国家标识用文字「US」而非 SVG 国旗 · fixed
- 国旗标识最好是用 svg
- 拖动表格列宽后被自动重置 · fixed
- 字段拖动宽度会被自动重置
- 商家详情 Drawer 视觉平淡 · fixed
- 美化下详情页面
- taskId + hasEmailOnly 同时启用时分页错乱 · fixed
- taskId + 有邮箱 chip 时分页错乱(先分页再过滤数学不等价)
- 列宽 fix 的 useMemo 形同虚设(v0.10.19 修复不彻底) · fixed
- v0.10.19 列宽 fix 没修到根 — useMemo deps 含不稳定数组引用
- RatingStars 对异常 rating 输入不稳健 · fixed
- RatingStars 对 NaN / 字符串 / 越界 rating 输入不稳健
- hasEmailOnly 全表 50k 上限静默截断 · fixed
- hasEmailOnly 全表 50k 上限超过后静默截断(观察项)
- 商家列表「已完善」状态 chip 参差不齐 · fixed
- 状态:已完善 参差不齐,建议靠右
- Google 验证拦截后用户感知 + 恢复体验差 · fixed
- 拦截已被检测+任务已暂停,但 UI 看不到状态、要逐个点继续、新开 maps tab 多余
- 任务暂停/继续/停止/删除 按钮失败时用户无反馈 · fixed
- task-view control() 用 sendMessage(...).catch(() => {}) 静默吞错;与 ISSUE-0036 同源
- 用户截图 v0.10.52 集中反馈:缩放 / 按钮色 / 排序 / 分页 / 顶部 CTA / 文案 · fixed
- 5 张截图 6 项 UX 痛点 — 字小、CTA 黑色不显眼、popup 文案错、质量分排序失效、分页 dropdown 没用、右上 CTA 不常显
- 质量分可配置 — 3 预设 + 5 维度权重 + 阈值 + 等级门槛 · fixed
- 用户问"质量分如何计算?能设置吗" — 加 Settings UI(默认/邮件营销/电销/高端市场 4 预设 + 完全自定义)
- 商家列表 chip count 截断 50k + 加载慢(22w 数据时) · fixed
- 22w 数据 chip "全部" 显示 50k;merchant-stats 每 10s select 50k 行
- 第 10 轮 agent — v0.10.73 A2 hybrid 6 处真 bug(数据安全 / 刷新失效 / page race / CTA 失效) · fixed
- A2 只改了读路径,写/refresh/CTA/banner 全路径仍指向旧 server-mode 单源,导致一系列错位
- saveParams 治本:search.ts 接受 taskId/hasEmailOnly,撤销 v0.10.74 短期拦截 · fixed
- ISSUE-0054 #1 数据安全长期重构 — delete/export 现按 UI 筛选范围操作,不再误删全表
- 第 14 轮 agent — polling 闪 + pageSize reset + SW sync error · fixed
- 2 🟠 + 1 🟡 + 1 🟢;agent 自己建议第 14 轮后真停下来用户实测
- dogfood v0.10.87 暴露 4 项 — email 占位符 / phone 从未写库 / probe 403 / 缺 UI toggle · fixed
- 用户截图 advocatehealth.com 抓到 your@email.com 占位符 + 第 2 个手机丢失;同时发现 v0.10.87 缺 settings UI toggle
- data-view HTTP 列 mstage 漏改 + 嵌套滚动条(部分修) · fixed
- 用户反馈 matsudental.com "失败" 实为 mstage:success 视觉误导;同时反馈嵌套滚动条 + 要求建立可持续迭代文档
- KPI/sidebar 计数 0 邮箱 — 50k 窗口家族 bug 复发 · fixed
- 用户 187k 商家 / 实际采到 660 邮箱,但 KPI 显示 0;data-counts.ts + data-view.tsx 都用 50k 窗口按 id desc 派生计数
- 状态列「待采集」与 HTTP 列「✓已采」视觉矛盾 — row 维度 vs URL 维度 · fixed
- 连锁店共享 URL 时一行采过其他行 status=0;状态列看 row 自己,HTTP 列看 URL 历史 → 视觉冲突
- 官网列表「邮箱」列 chip 右对齐显示错位 · fixed
- type:'number' 让 MUI 数字列默认右对齐,但 renderCell 渲染的是 chip 文字 → 视觉错位
- 官网/邮箱/电话 tab 右侧嵌套滚动条 · fixed
- 外层 Box overflow:'auto' + DataGrid 内置滚动 = 两层嵌套滚动条,用户视觉混乱
- DataGrid 底部分页器被裁掉看不见 · fixed
- v0.10.117 改外层 overflow:'hidden' 后 + tableContainer 固定 height 让超出的分页器被裁
- 官网列表电话列未接 RenderPhone — 多号码被截断显示 · fixed
- v0.10.117 邮箱列改 RenderEmail 但电话列漏改;tooltip 4 条 UI 只显 1 条引发 ISSUE-0080 般用户疑问
- 官网列表 HTTP 列对已采行显示 "-" 让用户误以为未采 · fixed
- page-log 5000 条环形 buffer 淘汰后老行 HTTP 列空;但 row.scrape_status=2 表明真采过 — UI 该兜底
- HTTP 列 tooltip 误导 — 把"批量复用"说成"日志被淘汰 · fixed
- v0.10.120 ISSUE-0083 修复时假定只有环形淘汰一种原因,实际还有 batchDedupeByUrl 复用 / ContactPool pool-hit 两种
- 一轮五项并行实施 —— Tier3 三刀 / 池 merge / 列表勾选 / 来源网站 · fixed
- 四路并行 + 独立复核;含两条待 Tony 拍板的产品判断
- 邮箱一锅端 —— 正向徽章,因为否定判据假阳性 85% · fixed
- 页面上所有邮箱无差别入库;朴素域名判据实测误杀 85%,改单向证明
- 手机列表一格塞三种写法 —— 去重 key 是美式假设 · fixed
- 「取后 10 位」只对国内号恰好 10 位的国家成立,德/法全失效
- sourceInferred 随来源处理顺序变化 —— 行级布尔压不住 per-source 的语义 · observing
- 同一个号 ['social','maps'] 与 ['maps','social'] 得到相反的 sourceInferred
- 防抖的依赖里吃了每次刷新都换的引用 —— 定时器被饿死,表现是「功能整个消失」 · fixed
- 同一个 P0 换了三种机制复发三次,根因都是"让功能消失的条件"没被识别
- 手机来源无标记被批量误判官网,重采还会反向误标地图 · fixed
- 用可往返三态标记修复电话来源丢失与反向误标
- 「采样提示」在任何采集进行时都误报 —— truncated 量的是状态差不是截断 · fixed
- scrape_status 四态而窗口只装两态,total 减不平就被当成采样截断;129 条数据也弹 10 万条采样提示
- 设置页信息密度 —— 四处占地方或没说清的东西 · fixed
- 云端保存按钮没人解释、显示比例占一整张卡、预设按钮五行高、危险提示 245 字
- 标签下拉撑破窗口 —— portal 浮层拿了未缩放的 CSS 像素 · fixed
- zoom 下移到 #root 后,clientWidth 与浮层坐标系分家;80% 下浮层宽出 25%
- AI 界面尺寸漂移:8 种字号 + 5 种 Chip 高度 · fixed
- 十几个版本一次一处加出来的尺寸不一致;收敛到 3 档字号 + 2 档 Chip 高度并立闸
- 顶部数据条把一条转化链平铺成了五个等权重卡片 · fixed
- 商家→官网→邮箱本是转化链,被平铺成五格五色;用户得自己心算才能发现 21% 的瓶颈
- 用 ellipsis 当自适应 —— 数据条把数字截没了,任务行把自己压重叠 · fixed
- 6格等分790px的数据条把数字截成「17.9…」;任务行两个写死的260px把左侧压到负宽度导致内容重叠
- 焦点守卫装了三个版本,一直在监听一个不会发生的事件 · fixed
- aria-hidden 报错第四次复发——真实场景是「焦点不动、属性变」,而守卫只监听 focusin
- 模型行只判 testOk 两态——「已失效」被显示成绿勾 · fixed
- modelHealth 写了四态且「stale 压过 testOk」,而模型行没用它;账号行四态、模型行两态,同一语义两套实现
- AI 入口对小白不可见,而真正的障碍是「我卖什么」≠「客户是什么店」 · fixed
- 推演入口是右上角一个小按钮;没配 Key 点进去才报错;输入框没说清要填什么性质的词
- 拿 Key 没有入口、余额看不见,而余额是厂商特例 · fixed
- 创建 Key/充值链接进厂商配置;DeepSeek 查余额用 is_available 不自己算;GLM 没有余额接口就不显示
- 新增账号的空表单里挂着上一次的余额 · fixed
- 常驻挂载的对话框 state 跨两次打开存活;靠手写 reset 清单兜不住,改用 key 强制重挂
- 拿 Key 的示意图 —— 远程图不解决「过期」,结构才解决 · fixed
- 三次要求的创建 Key 截图;反对的是打包不是截图,但远程图也没解决过期;靠「图不是唯一出路」兜住
- 把余额当成了状态指示灯 —— 它其实是用户主动要看的一个数字 · fixed
- 金额被降成灰色小字不醒目;位置和强度是两个诉求;充值挪到余额旁,骑缝只管拿 Key
- 四十万条组合打开详情直接卡死 · fixed
- 卡的不是渲染(早就截断了)是构造;笛卡尔积全量展开 × 每 2 秒 polling
- 详情页从没读过组合表,城市级组合永远显示「待采集」 · fixed
- P2 只做了降级路径的分页;降级路径的匹配是裸拼接,URL 形式对不上搜索框形式
- 详情页每 2 秒在 3 万行的表上查 5 次 + guard 漏了同步错误 + 三列没对齐 · fixed
- 任务停着也轮询;拿数据库当计算器求和;context guard 只监听了 unhandledrejection
- 商家列表顶部三条带吃掉近半屏 —— 压成一行,并顺带根治一个入口消失的 P0 · fixed
- 模式切换并进标题行 / 采样说明收进问号(警告不藏)/ 快速筛选并进视图行
- 实测七条 —— 「有邮箱 29」是 ISSUE-0074 家族只修了一半,外加五处界面缺陷 · fixed
- hasEmailOnly 扫描窗口按 id desc 撞满新行;补搜操作栏被挤出可视区;四处空态/密度问题
- 把 chips 塞进固定 48px 的视图行 —— 窄窗口整排塌掉,工具条浮到表格上 · fixed
- v0.16.14 的界面翻车;固定高度的行 + 会换行的内容 = 必然溢出
- 为「固定高度 × 会换行的内容」立机器闸 —— 并在建闸时第四次犯了同类错 · fixed
- ISSUE-0197 的沉淀;闸的第一版判据命中了我自己写的注释
- 82,437 条数据显示「还没有任何数据」—— 「没查出来」被当成了「没有」 · fixed
- 空状态判据依赖一个初值为 0 的 state,而首屏守卫只看行数据、不看统计查询
- DataGrid 内部 Uncaught TypeError 会白屏整个数据页 —— 加边界,根因待复现 · fixed
- 不猜测性修复;没有边界时第三方组件一抛,用户只能重开扩展
- 任务还在跑时「净增商家」恒为 0,而界面告诉用户「多半是之前采过了」 · fixed
- resultCount 只在 onBatchDone 写一次;跑不完就永远是 0,而解释文案在这种场景下是假的
- 清空对话框卡在「正在统计条数…」——它只要一个毫秒级 count,却在等两次 5 万行搬运 · fixed
- 删全库的确认数依赖含采样聚合的慢查询;且按任务筛选时显示任务条数而清的是全库
- 官网 tab 下显示的是地图 tab 的组合数 —— footer 在 Tabs 之外 · fixed
- 结果区移到 footer 时没按 tab 分流,两个 tab 共用一份
- 设置页 tab CJK 逐字断行错位 — 收缩无防护 + 无 nowrap · fixed
- AI 账号弹窗 API Key 标题没骑缝 — 弹窗字段形态不一致 · fixed
- AI 配置同步挱云端 tab + 开关形态重做 — 命名撞车与隐身开关 · fixed
- brand.tsx 漏入库——.gitignore Icon? 模式第三案误伤 src/components/icons/ 目录 · fixed
- 表格尾页越界 clamp——行数收缩后停在深页显空表+页脚越界文案;totalRows=0 分页器消失 · fixed
📋 工作流规则(7)¶
- 扫描类计数 — countByQuery 优先 / 警惕 50k 窗口家族 bug · stable
- 任何 selectByQuery({limit, order:id desc}) + 循环计数 都是隐性 bug;4 次复发的家族
- 分组聚合取代表 — 必须按 score,不能取"第一个 · stable
- useMemo / Map.set 分组去重时取"第一遇到的"是隐性 bug;要按价值 score 选最佳代表
- 抓取 pipeline 决策表 / mstage 标签速查 · stable
- SPEC-004 多阶段抓取 — 每种 mstage 标签的含义、UI 颜色、DB 行为速查;改 UI 或逻辑前必看
- UI 改动前置自查清单 · stable
- 改 UI 文案 / 颜色 / chip / 渲染逻辑前,必跑的"扫描所有重复渲染点"清单 — 防"改了 A 漏了 B
- UI 列维度一致性 — 同一行各列必须看同一对象 · stable
- 列 A 看 row 字段、列 B 看 URL/全局聚合 是隐性 bug;同一行视觉上必然矛盾
- UI/原型改动必须实测 —— 证据三档与四道锁 · stable
- 前端与原型改动禁止只凭推理收工 —— jsdom 不算实测;布局链要真浏览器 harness 断言,视觉级要真加载截图
- 用户反馈前置查询 — 先查 INDEX 再动代码 · stable
- 用户报 bug / 提需求时,按反馈类型给具体 grep 命令清单,防直接读代码错过历史
🗒️ 原始素材(12)¶
- 反馈 — 地图实开 (265) 比 地图请求 (249) 还多,反直觉 · processed
- settings 里讲"实开 1 → 后台翻 14 页",但日志显示实开 > 请求
- 反馈 — Google /sorry/index 验证拦截交互不到位 · spec-ed
- 已检测+暂停但 UI 无横幅、无 toast、要逐个点继续、又开新 tab
- 反馈 — 网络状态点点加光晕 + 放大缩小动画 · processed
- 当前网络状态圆点静态,加呼吸光晕让品牌区更有「在线感」
- 反馈 — StatsBanner 与 QuickFilters chip 信息重复 · processed
- 商家列表上方 5 卡 stats + 下方 6 chip filter 显示几乎相同信息
- 反馈 — 状态 chip 参差不齐 · processed
- 用户截图反馈商家列表的「已完善」chip 位置不齐,建议靠右
- 反馈 — toast 提醒位置 + 网络状态位置 · processed
- 登录成功 toast 太靠下;网络状态点放侧栏底部不显眼,建议移到顶部标题旁
- 反馈 — KPI 任务卡文字截断 + 剩余时间不人性化 · processed
- 顶部"任务进行中/总数"被 ellipsis 截掉 + "剩余 495时18分10秒"用户得心算 ÷ 24
- 嵌套滚动条又出现 — 截图位置未标注,待复现 · unprocessed
- v0.10.91 截图反馈数据列表区有"多个滚动条",但未标注具体位置
- AI 配置「自动同步到云端」归属与形态质疑 · unprocessed
- Tony 三点反馈——同步云端应放云端设置 tab?(对抗分析)好丑;开启开关不明显
- AI 账号弹窗 API Key 掩码圆点骑缝越界 · spec-ed
- Tony 截图报障——API Key 输入框的掩码圆点(●●●)越出输入框右边框约 7% 画面宽,画到框外
- 商家列表头像美化 + 整界面梳理 · spec-ed
- 商家列表 logo 列裸 img+外链占位图的头像美化与整界面梳理(结合已有做增量,不乱优化)
- 设置页 tab 错位到第二行(文字断行) · spec-ed
- Tony 截图报障——设置页三个 tab 在宽度不足/放大比例下文字逐字断行错位成两行高
给 AI / 新协作者的建议阅读顺序¶
- 先看 product(核对当前用户路径和限制)
- 再读 wiki(了解架构)
- 再读 specs(了解需求 / 设计决策)
- 遇到 bug 查 issues(避免重蹈覆辙)
- 追溯起源看 raw(用户原话)