# Photo Review — 需求文档

> 项目路径：`260619_Photo_Review`  
> 版本：0.2 · 2026-06-19  
> 页面：`index.html`（Tag 规范）· `review.html`（评图）

---

## 1. 背景与目标

将 AE/AWB 类客观评图从「语义表征驱动」（人脸/天空/灯牌…）重构为 **Tag × Global/Local** 正交体系，并提供：

1. **Tag 规范页** — 评图者查阅可用 Tag
2. **评图页** — 对比样张 + 分步标注问题

规范依据：石墨文档「AE&AWB评图规范 & bug聚类规则」第三版（合并版 Tag 见 `data/tags.json`）。

---

## 2. 页面一览

| 页面 | 文件 | 用途 |
|---|---|---|
| Tag 规范 | `index.html` | 查看 AE/AWB Tag、G/L 范围、Local 定位说明 |
| 评图 | `review.html` | 对比图 + 新增问题 + 问题列表 |

Demo 样张：`example/` 下三张实拍（Whoopass S2 / V60 / Pixel）。

---

## 3. Tag 体系需求（规范页）

### 3.1 设计原则

- **What / Where 分离**：问题 Tag 与 Global/Local 正交，不以语义对象作为一级分类
- **Local 定位**：bbox 优先；无框时用 tonal（高光/中间调/暗部）或 hue band
- **语义降级**：原「人脸/天空/灯牌…」改为 Local 时的可选 region_hint 或 bbox 推断（框选自动识别设计见 [bbox-region-hint-ml-design.md](./bbox-region-hint-ml-design.md)，待实现）
- **聚类出口**：保留「缺陷维度（第三版）」cluster_tag，由规则推导

### 3.2 Tag 表展示

- AE / AWB 各一张表，**不重复** Global/Local 两套
- 每行：`Tag 名 | G/L 标记 | 参考图（待填）`
- 名含「高光/暗部」的 Tag **仅 L**；整图过曝/压制用「过曝」「压制过度」（G only）

### 3.3 Local 区域定位方式（须保留在规范页）

三种方式可并存：

| 方式 | 说明 |
|---|---|
| 框选 BBox | 归一化 [x,y,w,h]；争议 case / superuser feedback 推荐 |
| 影调分区 Tonal | 高光 / 中间调 / 暗部 |
| 色相分区 Hue band | AWB Local 可选；无 bbox 时描述偏色方向 |

> region_hint 仅影响聚类推导，**不是必选**。

---

## 4. 评图页需求

### 4.1 布局

```
┌─────────────────────────────────────────┐
│ Header（链到 Tag 规范 · Zoom 提示）        │
├─────────────────────────────────────────┤
│ 对比图区（高度 fit，约 30–35vh）          │  ← 紧凑，图片高度适配
│  [图1]    [图2]    [图3]   2~5 张横排     │
├─────────────────────────────────────────┤
│ 评图区（占剩余空间，可滚动）               │  ← 主要交互区
│  · 分类计数 影调(1) 色彩(1)               │
│  · 已添加问题列表                         │
│  · 分步 Wizard / 新增问题按钮             │
└─────────────────────────────────────────┘
```

- 对比图：**2~5 张**横排；Demo 默认 **3 张**
- 预览框 **高度 fit**，把更多垂直空间留给下方评图区
- 默认 **选中第一张**，「新增问题」立即可用

### 4.2 对比图交互

| 操作 | 行为 |
|---|---|
| 点击某张图 | 选中态（蓝框）；后续问题绑定该图 |
| 滚轮 Zoom | **全部图片同步**缩放 |
| ⌘ / Ctrl + 滚轮 | **仅当前鼠标下/选中**那张缩放 |
| 图片显示 | `object-fit: contain`，在固定高度 viewport 内适配 |

### 4.3 新增问题 — 分步流程（逐级展开）

> 原则：**点一级才出现下一级**，避免一次展示过多信息。

#### Step 0：前置

- 须先选中一张对比图（默认第一张已选）
- 点击 **「新增问题」** 进入 Wizard

#### Step 1：大类（三选一）

- **影调**（AE）
- **色彩**（AWB）
- **清晰度**（ISP）

#### Step 2：范围（影调 / 色彩）

- **Global** — 整图问题，无需 Local 定位
- **Local** — 局部问题，进入 Step 4 Local 面板

> 清晰度暂无 G/L，选 Tag 后直接进入 finalize。

#### Step 3：问题 Tag

**影调（AE）**  
过曝 · 偏亮 · 对比低 · 对比高 · 偏暗 · 死黑 · 压制过度  
（Local 额外）高光过曝 · 高光压制过度 · 暗部提亮过度

**色彩（AWB）**  
8 格偏色盘（hover/选中显示短标签，英文无 “cast” 后缀）+ 饱和列（**Sat. High / Sat. Low**，列宽 fit-content）

- 偏色盘 hover/选中：`castBlockLabel`（如 Green、Warm、Yellow-green）
- Issue chip / 路径 pill：`tagLabel`（如 Green cast、Sat. High）
- 选中态：A7 磨砂玻璃 + inset 高光 + 外白 blur
- 饱和列宽随文案收缩（`width: fit-content`）

**清晰度（ISP）**  
清晰度差 · 噪声大 · 锐化高 · 锐化低 · AI 感重

#### Step 4：Local 定位（仅 scope=Local）

可同时多选，不互斥：

| 类别 | 选项 |
|---|---|
| 框选 | **在图中框选** — 可框多个；Enter 完成；Esc 取消 |
| Tonal | 高光 · 中间调 · 暗部 |
| 部位 | face · face亮光 · face局部 · face暗部 · 头发胡子 · 口红腮红 |
| 采样 | 亮度范围 / 色彩范围（矢量吸管 icon，左 padding 4×） |
| 自定义 | Type… 文本输入 |

**框选模式**

- 除当前选中图外，全页 **黑色半透明 mask**
- 当前图 spotlight，可拖拽画框（多个）
- **Enter** 完成框选

**吸管模式**

- 同样 mask + spotlight
- **第一次点击**：采样点
- **移动鼠标**：调整采样范围大小
- **第二次点击**：确认
- Esc 取消

#### Step 5：Finalize（Desktop-3）

展示已选 Tag _chip 行，例如：`[影调][Local][对比高][face]`

| 操作 | 必须？ | 说明 |
|---|---|---|
| **+ OK Ref** | 可选 | 从其余对比图中选一个作为 OK reference device |
| **+ Note** | 可选 | 文本备注 |
| **完成此问题** | — | 写入问题列表，关闭 Wizard |

一条问题 = Step 1~5 全部走完（Ref / Note 可跳过）。

### 4.4 问题列表

- 按**当前选中图**过滤展示
- 每行：`序号 + chip 链`（含 Ref / Note）
- 顶部计数：`影调(n) 色彩(n) 清晰度(n)`

### 4.5 数据（单条问题 JSON 结构）

```json
{
  "imageId": "whoopass",
  "category": "ae",
  "scope": "local",
  "issueTags": [{ "id": "ae_contrast_high", "label": "对比高" }],
  "local": {
    "bboxes": [{ "x": 0.1, "y": 0.2, "w": 0.3, "h": 0.4 }],
    "tonal": ["shadow"],
    "semantic": ["face"],
    "custom": "",
    "brightnessPick": { "x": 0.5, "y": 0.5, "r": 0.1 },
    "huePick": null
  },
  "okRef": { "id": "pixel", "label": "Pixel" },
  "note": "备注文字"
}
```

---

## 5. UI 参考图

原型图存放于 `docs/ui-references/`：

### 5.1 分步 Wizard 流程（影调 Local / 色彩 Local / Finalize）

![Wizard 流程](./ui-references/wireframe-wizard-flow.png)

- 左上：影调 → Local → Tag 列表 → Local 定位区（框选 / tonal / 部位 / 吸管 / Type）
- 左下：色彩 → Local → 3×3 色块 + 饱和 → Local 定位区
- 右上：Finalize — chip 行 + `+ OK Ref` + `+ Note`

### 5.2 问题列表 + 新增问题入口

![问题列表](./ui-references/wireframe-issue-list.png)

- 选中图下方：`影调(1) 色彩(1)` 计数
- 问题行示例：`1  影调 Local 对比高 face Ref: iPhone`
- 底部：**新增问题** 按钮

### 5.4 Figma 分步分支（评图 Wizard）

![分步分支](./ui-references/figma-flow-branch.png)

- 从左到右逐级展开；已选分支只显示 **白色 pill**（可点击回退）
- 影调 Tag 在 **灰色矩形** 内空间排布（过曝/偏亮/对比低·高/偏暗/死黑）
- 偏色在 **8 色矩形** 内 hover 高亮 + 白字标签，点击选中
- Local 选项 **分行** 展示（见下图）

![Local 分行](./ui-references/figma-local-rows.png)

![AE Tag 行](./ui-references/figma-ae-tags-row.png)

- 框选 BBox / 影调 Tonal / 色相 Hue band 三卡片

---

## 6. 实现状态

| 功能 | 状态 |
|---|---|
| Tag 规范页（合并 G/L） | ✅ |
| 评图页三图对比 | ✅ |
| 同步 / ⌘ 单张 Zoom | ✅ |
| 默认选中 + 新增问题可点 | ✅（本次修复） |
| 对比区高度 fit | ✅（本次修复） |
| 分步 Wizard | ✅ |
| Local 框选 + mask | ✅ |
| 亮度 / 色相范围（吸管 icon + 布局 A） | ✅ |
| AWB 偏色盘 8 格 + castBlock / chip 双文案 | ✅ |
| AWB 饱和 Sat. High/Low + fit 列宽 | ✅ |
| OK Ref + Note | ✅ |
| 问题列表 + 计数 | ✅ |
| 框选 region_hint 自动识别（ML 建议） | ⬜ 设计已定，见 [bbox-region-hint-ml-design.md](./bbox-region-hint-ml-design.md) |
| 数据持久化 / 导出 | ⬜ 待做 |
| 清晰度 G/L | ⬜ 待定 |
| 参考图 per Tag | ⬜ 待填 |

---

## 7. 本地运行

```bash
cd 260619_Photo_Review
python3 -m http.server 8765
```

- Tag 规范：<http://localhost:8765/>
- 评图：<http://localhost:8765/review.html>

---

## 8. 变更记录

| 日期 | 内容 |
|---|---|
| 2026-06-19 | 初版：Tag 合并规范 + 评图 Demo |
| 2026-06-19 | 换 example/ 实拍；需求文档 + UI 参考图归档 |
| 2026-06-19 | AWB UI 定稿：8 格偏色、castBlock 短标签、Sat. High/Low、饱和列 fit 宽、A7 选中态、吸管 icon、Local 布局 A |
| 2026-06-19 | 框选 region_hint ML：调研结论与设计文档 `bbox-region-hint-ml-design.md`（P0→P1→P2，正式方案为整图分割+框内投票） |