🎨 UI / 界面

组件 / 布局 / Drawer / 列表 / Chip / 国旗

⚙️ 本文件由 pnpm docs:rebuild 自动生成 — 修改无效。

涉及文档（39 个）

📐 架构 / 知识沉淀（1）

• Popup 认证状态机
• 浏览器扩展 popup 的登录态机制 — 4 态状态机 + 2 秒超时兜底 + 多重登录入口

🎯 功能规格（1）

• SPEC-000 — v2 UI 改版说明（v0.8.58 → v0.9.x → v0.10.x） · done
• 早期整体界面改版历史档案；dist/ 与 dist-v2/ 双轨阶段进度记录

🔧 已知问题 + 修复（22）

• [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 漏改 + 嵌套滚动条（部分修） · in-progress
• 用户反馈 matsudental.com "失败" 实为 mstage:success 视觉误导；同时反馈嵌套滚动条 + 要求建立可持续迭代文档
• 状态列「待采集」与 HTTP 列「✓已采」视觉矛盾 — row 维度 vs URL 维度 · fixed
• 连锁店共享 URL 时一行采过其他行 status=0；状态列看 row 自己，HTTP 列看 URL 历史 → 视觉冲突

📋 工作流规则（6）

• 扫描类计数 — 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；同一行视觉上必然矛盾
• 用户反馈前置查询 — 先查 INDEX 再动代码 · stable
• 用户报 bug / 提需求时，按反馈类型给具体 grep 命令清单，防直接读代码错过历史

🗒️ 原始素材（8）

• 反馈 — 地图实开 (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 / 新协作者的建议阅读顺序

1. 先读 wiki（了解架构）
2. 再读 specs（了解需求 / 设计决策）
3. 遇到 bug 查 issues（避免重蹈覆辙）
4. 追溯起源看 raw（用户原话）