UI_review / TECH_STATUS.md
Hnnnhn
Claude Fable 5
看板版上线:seg_preview_server 单服务(走查入口+board+导出HTML报告含dev模式交互),度量衡统一figma px,槽位口径字号/间距,卡片序号吸附,弃用代码归档 deprecated/
9c351ab
|
Raw History Blame Contribute Delete
10.9 kB

UI 走查工具 · 技术现状总结

更新时间:2026-05-25 分支:feature/local-measure 服务:主 5050 / 实验 5051


一、架构总览

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Figma API  │     │  截图 (PNG)  │     │  PaddleOCR    │
│  节点树     │     │  impl_input  │     │  文字识别     │
└──────┬──────┘     └──────┬───────┘     └───────┬───────┘
       │                   │                     │
       ▼                   ▼                     ▼
┌──────────────────────────────────────────────────────┐
│         alignment.py — 截图对齐到设计画布             │
│         (OCR 锚点平移 / ORB warpAffine)              │
└──────────────────────────┬───────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
   ┌──────────────┐ ┌────────────┐ ┌──────────────┐
   │ 颜色走查     │ │ 模块内部   │ │ 手动对比     │
   │ figma_color_ │ │ 测量 V3    │ │ manual_      │
   │ check.py     │ │ local_     │ │ compare      │
   │              │ │ measure.py │ │ (webapp.py)  │
   └──────┬───────┘ └─────┬──────┘ └──────┬───────┘
          │               │               │
          ▼               ▼               ▼
   ┌──────────────────────────────────────────────┐
   │         visualize_icar.py — HTML 报告生成     │
   │         webapp.py — Flask 服务 (5050/5051)    │
   └──────────────────────────────────────────────┘

核心文件

文件 行数 职责
src/local_measure.py 1428 模块内部测量(V1 + V3),层级分片、聚合
visualize_icar.py 2513 HTML 报告生成,crop 标注,findings 表
src/figma_color_check.py 1135 OCR 封装、颜色对比、填充/描边/圆角走查
webapp.py 722 Flask 服务、手动对比接口、运行管理
src/alignment.py 216 截图 → 设计画布对齐

关键常量

常量 值 含义
EXPORT_SCALE 2 Figma 导出倍率,Figma px × 2 = canvas px
DIFF_TOL_FIG 5.0 差异容忍阈值(Figma px)
ANCHOR_FUZZY_RATIO 0.85 OCR 文字匹配相似度阈值
PAIR_MAX_NORM_DIST 0.25 归一化位置配对最大距离

二、已完成能力

2.1 基础设施

能力 文件 说明
Figma 节点树获取 figma_client.py API 拉取 + figma_root.json 持久化
设计稿导出 @2× figma_client.py PNG 导出,EXPORT_SCALE=2
截图对齐 alignment.py OCR 锚点平移 或 ORB warpAffine
OCR 文字检测 figma_color_check.py PaddleOCR → {text, bbox_canvas, height_fig}
颜色走查 figma_color_check.py 填充色 / 描边 / 圆角逐节点对比
HTML 报告 visualize_icar.py 模块卡片 + crop 标注 + findings 表
实验环境隔离 webapp_lab.py 5051 端口 + runs_lab/ 独立历史

2.2 模块内部测量(V3 — 当前版本)

三层审计架构,入口 run_local_measure_v2():

层 ① 字号审计 — _audit_font_sizes()

  • 从 Figma 树提取所有 fontSize 声明
  • 从截图 OCR 提取字高分布
  • 对比:Figma 声明的字号在截图里有没有对应高度的文字
  • 粒度:全局

层 ② 间距审计 — _audit_container_spacing() → 分派

  • 有 ≥2 个子容器 → _audit_card_container()(层级分片)
  • 无子容器 → _audit_flat_container()(扁平 OCR)
  • 粒度:每个 Figma auto-layout 容器

层 ③ 锚点精确对比 — _audit_anchors()

  • 找 Figma 里的短文本 UI 标签("查看全部"、"进店"等)
  • 在截图 OCR 里找内容一致的,逐个比字高
  • 粒度:单个文案

2.3 层级分片(核心创新点)

解决的问题:内容不同时的模块匹配(设计稿"好想来" vs 截图"鸿潮汕")

容器 (HORIZONTAL, gap=8)
  ├── 卡片1 (INSTANCE)          ← Figma 子节点 bbox 作为分割线
  │   ├── 标题 TEXT "好想来"
  │   ├── 价格 TEXT "¥268"
  │   └── 按钮 TEXT "进店"
  ├── 卡片2 (INSTANCE)
  │   ├── 标题 TEXT "鸿潮汕"    ← 内容不同但位置结构相同
  │   └── ...
  └── 卡片3 ...

实现流程:

  1. _extract_design_spec() 遍历 Figma 树,为每个容器收集 children_containers(直接子 FRAME/INSTANCE/COMPONENT,含 bbox + TEXT 后代)

  2. _audit_card_container() 对每张卡片:

    • 用子节点 bbox_canvas 从截图 OCR 里分片(只取落在该卡片区域的 OCR 项)
    • _match_by_relative_position() 归一化位置贪婪配对(不看文字内容)
    • 逐配对比:字号(fontSize vs OCR 高度)、内部间距(TEXT 间 gap)
    • 卡片间:Figma bbox 边缘间距 vs OCR 极值间距
  3. _aggregate_card_findings() 聚合同类:

    • 按 design_fig(字号规格)分组字号 findings
    • 按 _pair_idx(间距位置)分组间距 findings
    • N 张卡片同一问题 → 合并为 1 条 "14px 字号偏差(3/4张卡片)"
  4. _audit() 中 covered_bboxes 去重,避免子容器被父级和自身双重审计

2.4 手动框选对比

入口:POST /r/<run_id>/manual_compare

设计稿和截图各框一个区域 → 摘要级对比(不逐 OCR 碎片配对):

指标 来源 说明
选区尺寸 框选坐标 宽×高 对比
文字行数 OCR 按 Y 聚行 行数是否一致
主要字高 OCR bbox 高度中位数 整体字号偏差
字高分布 OCR 去重字高列表 用了哪些字号
行间距 相邻行 bbox 间距中位数 排版松紧
Figma 参考 覆盖该选区的 Figma 节点 gap + 字号规范

三、当前难点

难点 1:内容不同时的模块匹配 ⭐ 核心

阶段 方案 结果
V1 文字内容匹配 (match_anchor_in_impl) ❌ 内容不同时完全失效
V2 空间最近邻 ❌ 对齐偏差 20-30px 导致全部错配
V2 模板匹配 (Canny + matchTemplate) ❌ 内容不同时边缘也不同
V3 扁平 OCR 间距审计 ⚠️ 不分卡片,混入噪声,间距 -39px 等垃圾数据
V3+ 层级分片 + 归一化位置配对 ✅ 按 Figma 子 bbox 分割,位置配对不看内容

当前状态:基本解决。对有 ≥2 个子容器的 auto-layout 容器有效。

残留限制:

  • 非 auto-layout 容器或只有 1 个子容器 → 退回扁平模式
  • 嵌套子容器(卡片内的卡片)未递归处理
  • 归一化配对在卡片内只有 1 个 TEXT 时退化

难点 2:OCR 噪声

问题:食物图片水印/装饰文字被 OCR 误检。

当前缓解:

  • 层级分片把 OCR 限制在子容器 bbox 内
  • 归一化配对跳过距离 >0.35 的噪声项

残留:卡片内图片区域的 OCR 误检仍可能与 Figma TEXT 位置接近时误配。

难点 3:非文字元素

问题:icon、图片、分割线等不被 OCR 检测,但影响间距测量。

当前状态:未处理。_collect_text_descendants 只收 TEXT 类型。

可行方案:把 VECTOR / RECTANGLE / 小 FRAME 也纳入 Figma 侧配对,用 bbox 位置匹配截图色块。不需要 ML。

难点 4:对齐精度

问题:全局对齐误差 20-30px。

当前缓解:V3 只比相对值(卡片内间距、字号),不依赖绝对坐标。

难点 5:输出可读性

问题:几十行碎片 findings。

已解决:

  • ✅ 卡片容器聚合:"14px 字号偏差(3/4张卡片)" 替代 3 条碎片
  • ✅ 扁平容器聚合:"间距整体偏差(5/7处)" 替代 7 条碎片
  • ✅ 手动对比重写:7 行摘要替代 15+ 行 OCR 碎片配对

四、版本演进

V1 · 内容锚定
  文字内容匹配 design↔impl → 模块内 4 边距 + 文字间距
  ✅ 内容一致时精确
  ❌ 内容不同时完全失效

V2 · 空间 / 模板匹配(已废弃)
  最近邻 + Canny 模板匹配
  ❌ 对齐偏差 + 内容差异双重打击

V3 · 规范审计
  三层审计:字号 / 间距 / 锚点
  ⚠️ 间距层扁平 OCR 不分卡片,噪声大

V3+ · 层级分片(当前)
  Figma 子节点 bbox 分割 → 归一化位置配对 → 聚合输出
  ✅ 内容无关,结构驱动
  ✅ 输出简洁,按角色聚合

五、下一步优先级

优先级 方向 预估 价值
P0 真实项目测试 + 调参 1-2h 验证层级分片效果,调整配对阈值
P1 非 TEXT 元素纳入 3-4h icon/图片参与间距,覆盖面 +30%
P1 清理 V1/V2 死代码 1h run_local_measure / measure_local 等
P2 嵌套子容器递归 2-3h 卡片内的卡片
P2 对齐质量检测 2h 对齐差时自动降级到纯 spec 审计
P3 多模态 LLM 兜底 4-6h 可疑区域 crop → Claude Vision 二次确认

六、关键函数索引

函数 行号 用途
run_local_measure_v2() L737 V3 主入口
_extract_design_spec() L766 提取 Figma 设计规范(含子容器层级)
_audit() L886 三层审计调度
_audit_font_sizes() L968 层① 字号审计
_audit_container_spacing() L1013 层② 间距分派(card / flat)
_match_by_relative_position() L1027 归一化位置配对(内容无关)
_audit_card_container() L1076 卡片容器层级分片审计
_aggregate_card_findings() L1226 同类 findings 跨卡片聚合
_audit_flat_container() L1289 扁平容器 OCR 间距审计
_audit_anchors() L1364 层③ 固定文案锚点对比
manual_compare() webapp L358 手动框选摘要级对比