# 人工确认 Web 界面

服务端口 **3389**，默认监听 `0.0.0.0`。浏览器打开 `http://服务器IP:3389`，输入访问码即可开始。iPhone 推荐使用 Safari，可添加到主屏幕；无须安装 App。

## 使用

1. 直接看目标裁剪；有疑问时切到“整帧定位”，红框标出当前目标。“放大”支持适应屏幕 / 2倍，以及页面双指缩放。
2. 点选 **两腿 / 三腿 / 四腿**，再选择 **无下横梁＝川字 / 有下横梁＝田字**。只统计当前主要叉取面，不重复计算后排、侧面和相邻堆叠层。
3. 选择正确后点 **确认正确 · 下一条**；修改后的值作为人工修正单独保存。如果腿数或横梁看不清，保留相应未知并点 **无法判断**，不强行归类。
4. “跳过”不保存、不标记已审；未保存的选择离开前会提示。保存成功才自动前进，断网时不会假装成功。
5. 右上“筛选”可按审核状态、原22大组、原划分、腿数/横梁、优先复核和440种子集选择队列，也能搜索身份并导出全部目标的 CSV / JSONL。
6. 顶部“上次”可返回修改。“证据”弹窗查看投影、来源和历次记录；可撤回当前审核恢复待审，但不删除历史。

### “上条”与返回修改

“上条”按照**实际看过的目标组历史**返回，不再使用会缩短的待审核队列位置。确认后即使下一组又位于待审队列第1项，也能返回上一条或上一整组，显示当前服务端保存的真实人工标签，修改后再确认；已有确认不重复计数。

可连续返回多组，回看时“跳过”按钮显示为“下一组”，可以前进到刚才所在组；单纯前后查看不写入标签。不保存的修改离开前会提示，取消则留在本组。上一组读取失败时保留当前位置与历史，不跳空、不丢掉可返回记录。

**返回时始终遵循当前拼图设置，不会被历史的3×3等布局改回去。** 例如3×3确认后切换为1×1，再点“上条”，从上一批最后一张开始逐张返回；“下一组”逐张前进。保存修改只处理当前显示的目标，其余八张不变，保存后也能继续查看原批次中后面的图片。回看已确认组时直接切换为单图，会保留该组成员供逐张检查，不跳到新的待审目标。

浏览器保留最近100页的目标身份、顺序及原组成员关系，并绑定本批数据哈希；修改行列数后按当前容量重新分页，刷新同样保持当前设置。旧版历史和“上次已审”引用均兼容恢复。历史不含标签副本，回看时重新请求当前服务端值。真正没有历史或可返回的上一组时，按钮才禁用；处理完当前筛选的最后一组后也能返回最后的确认记录。换域名/设备的浏览器没有原浏览历史，可筛选“已确认”查看服务端标签。

### 多图合一、共用判定

顶部 **“拼图”** 可设置1–3行、1–3列，默认1×1单图，最多3×3九图。按当前筛选队列的顺序取出一组托盘目标，所有图片始终平铺在剩余看图区内，不变成需要滑动的列表。

| 链接参数 | 每组容量 | 展示方式 |
|---|---:|---|
| `?rows=1&cols=1` | 1 | 单图，与原方式相同 |
| `?rows=1&cols=2` | 2 | 横排双图 |
| `?rows=2&cols=1` | 2 | 纵排双图 |
| `?rows=2&cols=2` | 4 | 四宫格 |
| `?rows=2&cols=3` | 6 | 六宫格 |
| `?rows=3&cols=3` | 9 | 九宫格 |

参数会在访问码一键登录后保留；界面设置也会保存在当前浏览器。没有参数和偏好时仍为单图。队列尾部不足一组时只展示和保存实际剩余目标，不凑数、不重复目标。

**一组只共用一套腿数与横梁选择。** 点“确认本组N项”后，同一结果写入当前显示的全部N个目标，成功才切到下一组，进度分子按实际新增确认数增加。跳过则整组不保存。“上次”返回上次保存的目标，同样按当前拼图设置拆分，不强制恢复原布局。图多时可在“放大”弹窗上方选择第几张，逐张查看原图；“证据”也能逐图选择，撤回操作明确只撤回当前所选图。

组内已知建议不一致时，显示“本组不一致”，对应属性不预选，必须先手动明确统一结果；已保存的人工作为未知的属性也不会被其他图的已知建议自动顶替。只有全组该属性都未知、且没有人工保留未知时，才沿用上条成功确认的值。**不同结构不要强行批量统一，应切回单图或重新筛选。**

整组保存使用一个SQLite事务，先核对每个目标的版本；任一冲突或写入失败则整组不写入，避免出现半组成功。逐目标历史保留同一个批次ID、目标列表和组大小，原检测框/大组/算法字段不改。批量修改标签时，未编辑备注则保留每个目标自己的原备注；编辑备注后才整组替换为所填内容。所有图的原强度图成功载入后才允许确认。

### 图像传输压缩与缓存

图像传输自动选择**无损WebP或优化PNG中体积更小的兼容格式**，不降低分辨率、不使用有损JPEG、不模糊薄横梁或改变掩膜像素。iPhone 13支持WebP；未声明支持WebP的客户端仍得到PNG。原始文件和算法掩膜不改写，带透明度的掩膜保留透明度，嵌入的颜色配置也保留。

图像URL包含输入哈希与编码版本；已登录浏览器可私有缓存24小时，重复切换视图、返回已看目标及原分辨率放大复用同一图像。未版本化的旧链接采用ETag重新验证，未变化时返回304而不传图像正文。图像使用 `Vary: Accept` 区分WebP/PNG；缓存是**浏览器私有缓存**，不将受保护图像开放到公共CDN缓存。服务器缓存最多512份图像变体，避免无限占用内存。

首次只加载当前选中的视图；其它强度/阈值/点云视图和放大图按需读取。全部当前目标的原强度图成功载入这一确认保护不变。审核进度、标签接口和页面仍使用 `no-store`，不缓存过时审核结果；服务器对图像请求和304请求均先检查登录。已下载图片可保存在当前设备缓存中，共用设备时应注意浏览器本地数据。

抽样66目标、覆盖22大组的299张图，旧PNG正文共9,896,416字节，优化后5,635,364字节，减少约43.1%。598次解码比对像素与尺寸完全一致，233份来源资产哈希不变。独立浏览器检查证明重复看图与放大没有新增图像传输，刷新新增图像正文0字节。该结果是代表性样本的正文体积，不是全库压缩率或网络延迟保证；证据见 `outputs/pallet_structure_review_web_validation_v6/transfer_validation.json`。

可在顶部“备注”弹窗填写备注和审核人昵称，点“完成”回到标注页，再点“确认”或“无法判断”保存。昵称只保存在本机浏览器中方便下次使用；**所有标签和审核历史保存在服务端数据库**，更换手机也能看到进度。昵称用于溯源，不是个人账号或签名认证。

桌面快捷键（焦点不在表单控件且没有弹窗时）：`2/3/4` 选腿数，`C` 川字，`T` 田字，`Enter` 确认，左右方向键切换。手机采用**顶部集中操作、下方看图**的布局，腿数、横梁、保存、跳过、返回、备注、证据、图像切换和放大均无需滚动页面即可操作。筛选、备注和证据弹窗内部可滚动，关闭按钮固定在弹窗顶部；页面保留安全区和缩放能力。

### 标注进度

顶部只显示全库的 **已确认数 / 固定目标总数12,344**。新确认一条时分子加1，修改已经确认的记录不重复加数；撤回或改成无法判断时，确认数相应减少。无法判断单独计数，不冒充已确认。

筛选或跳过不改变总量与已确认数。“待审剩余”单独显示，会在确认后减少；它不是进度的分母。不再使用随待审队列缩短的“当前位置/剩余队列长度”。刷新页面从真实服务端审核记录恢复进度，不改写已有人工记录。

### 未知项沿用上一条

未审核目标的腿数或横梁为未知时，默认预选**本浏览器上一条成功确认的标签**，两个属性分别处理；原建议已经明确的字段不变。顶部显示“沿用上条”“腿数沿用”或“横梁沿用”，原建议仍单独展示。

这只是本条的输入默认值，**不自动保存、不增加进度、不批量改标签**，仍需看图并点击确认。可以直接点“未知”取消沿用；已保存的人工记录（包括明确保存为未知的待复核记录）不会被默认值替换。未成功保存、无法判断或已撤回的来源不作为新的已确认标签沿用。

浏览器仅保存来源目标的引用并绑定本批数据哈希；刷新时向服务端重新确认该来源仍为已确认，再读取其最新标签。也兼容从旧版界面的“上次已审”引用恢复；首次使用、无有效来源或来源已撤回时，保留原建议与未知。

### iPhone 13 布局

按 **390×844 CSS逻辑屏幕、3倍像素比**（物理1170×2532）适配，而非把网页宽度设成1170。兼顾Safari工具栏下常见的390×664可视区、主屏幕全屏和横屏；实际安全区读取系统 `env(safe-area-inset-*)`，页面高度跟随 `100dvh`。

腿数、横梁、确认和切换按钮保持在顶部，iPhone 13配置下按钮至少44×44 CSS像素；放大显示和备注/筛选/证据弹窗也避开刘海与底部手势区。图像区域占满其余空间，等比例显示，不裁掉原始目标。刷新网页即可使用新版，访问码与已有审核记录不变。

## 启动与存储

推荐用独立守护启动（同时启动Web服务和Cloudflare隧道，子进程退出自动重启）：

```bash
.venv/bin/python scripts/serve_structure_review.py start
.venv/bin/python scripts/serve_structure_review.py status
```

启动器独立于当前终端会话，使用单实例锁；不会替换已占用3389端口的其他进程。进程状态和每次运行的日志保存在 `outputs/pallet_structure_review_managed_v1/`，当前公网地址仍写入 `outputs/pallet_structure_review_tunnel_v1/public_access.json`。已使用此方式运行时，不要再另行启动下面的手动命令。

仅需手动前台运行本地Web时：

```bash
.venv/bin/python -m pallet.structure_review --host 0.0.0.0 --port 3389
```

默认输入为 `outputs/pallet_structure_attributes_v1/`；默认原生图像路径读取 `configs/active_formal_dataset.json`。可指定 `--source`、`--dataset` 和 `--reviews`。

人工记录单独保存在：

```text
outputs/pallet_structure_human_review_v1/
  reviews.sqlite3      # 当前记录 + 不覆盖的逐版本事件历史
  access_key.txt       # 服务访问码，文件权限0600
  runtime.json         # PID、端口及源数据哈希
  server.lock          # 避免同一目录重复启动
```

早期手动启动日志为 `outputs/pallet_structure_review_service_v1.log`，最新守护运行日志以 `outputs/pallet_structure_review_managed_v1/supervisor.json` 中的 `app.log` 为准。恢复时使用相同审核目录即可；数据库绑定源建议文件 SHA-256，禁止误加载到另一批数据。

如需发给手机一键进入，可构造 `http://服务器IP:3389/#key=访问码`。访问码在 URL 片段中，不发送到HTTP访问日志，登录后立即从地址栏清除。服务使用 HttpOnly / SameSite Cookie 和同源写入保护；原图和标注接口需登录。持有访问码的人都可审核，请勿公开分享。

端口必须能从手机网络访问。如果服务位于 Docker 中，应在宿主机映射 TCP 3389；云服务器还需在安全组放行相应来源。**没有更改系统防火墙或其他服务**。当前为 HTTP，建议用于可信局域网/VPN；对公网长期开放时应在前面配置 HTTPS，访问码不替代传输加密。

## Cloudflare Tunnel 公网 HTTPS

已按要求使用 Quick Tunnel 将本地3389转发为公网HTTPS。当前地址以 `outputs/pallet_structure_review_tunnel_v1/public_access.json` 为准；原日志为同目录 `tunnel.log`，最新守护运行的隧道日志见 `outputs/pallet_structure_review_managed_v1/supervisor.json` 中的 `tunnel.log`。仍需页面访问码，标注与原图接口不匿名开放。

```bash
/tmp/opencode/pallet_review_tunnel/cloudflared tunnel --no-autoupdate \
  --url http://127.0.0.1:3389 --protocol http2
```

Quick Tunnel 无须 Cloudflare 账号，不需要打开服务器入站3389，但需要允许隧道进程出站访问Cloudflare。地址为随机的 `https://*.trycloudflare.com`，**停止或重启隧道后可能改变**，适合当前临时审核；它不是已配置固定域名的长期部署。

服务与隧道两个进程均需保持运行。若需要永久域名和开机自启，应另提供Cloudflare命名隧道/域名授权，再配置长期服务；本次没有修改DNS、系统防火墙或其他服务。

### 1033恢复记录

2026-10-16原隧道收到终止信号，本地3389服务也已退出，旧随机域名返回Cloudflare 1033。已恢复并切换为独立守护管理，新的Quick Tunnel地址会变化；截至恢复核验，1,318条人工确认和1,326条审计事件完整保留，公网登录、图片、批量能力和无损压缩均正常，访问码不变。核验见 `outputs/pallet_structure_review_tunnel_recovery_v2/recovery_validation.json`。

新地址使用新的浏览器站点会话，需重新输入原访问码；审核进度由同一服务端数据库恢复。个人浏览器的拼图偏好、昵称和上一条引用是按域名保存的，换域名后可能需要重新设置。

守护器会在Web或隧道**子进程退出**后重启它们，并保留逐次日志；隧道重启可能产生新地址，见当前地址文件。**没有配置整机/容器开机自启，也不保证守护器自身被终止或容器重启后自动恢复。** 若发生这种情况，重新执行上面的 `start` 命令。长期固定公网地址需要Cloudflare命名隧道和域名授权，不是Quick Tunnel能保证的。

隧道HTTPS登录设置 Secure / HttpOnly / SameSite Cookie。已核验公网页面、静态资源、访问码登录、认证数据和目标图像；未登录的数据接口返回401。公网检查不写入真实审核记录。

## 界面验证

最新“当前拼图设置优先”修复验证见 `outputs/pallet_structure_review_web_validation_v8/`；此前“上条”历史修复保留在 `..._v7/`，图像传输版保留在 `..._v6/`，多图合一版保留在 `..._v5/`，未知项沿用版保留在 `..._v4/`，iPhone 13版保留在 `..._v3/`，顶部布局版保留在 `..._v2/`，最初版本保留在 `..._v1/`。使用独立临时审核库验证确认/修改、自动下一条、无法判断、撤回、历史、并发冲突和刷新恢复；生产审核库不写入测试标签。新增3×3确认后切换单图、逐张前后查看、只修改一张而八张不变、回看时切换布局、刷新/旧历史迁移和全部9种行列设置检查。另验证未知字段独立沿用、明确值/人工记录不变、手动取消、来源撤回、刷新恢复及数据哈希隔离；预选本身不写库、不推进进度。

已在Chromium中检查320×460、320×568、375×667、375×812、390×664、390×844、430×932、844×390及1440×1000的DOM布局：全部核心按钮在首屏可见、无阻挡，最小操作尺寸42×44 CSS像素，无横向溢出。临时库验证进度从0/12,344到1/12,344、2/12,344，改变状态、筛选与刷新时分母不变。浏览器会话还通过公网隧道验证登录与刷新。这是iPhone尺寸/触摸配置模拟，**不是实机Safari测试**。本机旧系统的无头合成器无法稳定截屏与执行指针稳定性检查，因此交互验收使用DOM事件，未宣称原生触摸或截图通过。投影使用SVG矢量图，不依赖Canvas/GPU上下文。

iPhone 13另按3倍像素比检查Safari、全屏及横屏共5种配置，显式模拟竖屏顶部47/底部34像素与横屏左右47/底部21像素的安全区边界；核心按钮、图像区域和弹窗关闭操作均在安全区内。

多图模式在上述5种iPhone 13配置下分别检查全部9种行列组合，共45种：控件和每个图格都在可视安全区内，页面无须滑动。临时库验证4图共用保存、整组修改不重复计数、末尾不足一组、混合建议、逐项备注保留、图像失败禁用确认，以及末项版本冲突/模拟写入失败时整组回滚。上线前通过SQLite在线备份保留当时195条真实人工记录，备份仅保存在本地验收目录，不经网页开放。

## 数据边界

- 原结构建议、22大组、检测框、train/val/test、阈值图、点云掩膜均只读，不修改历史交付清单。
- 人工 **approved** 必须同时有明确腿数和横梁类型；**deferred** 可部分已知；**pending** 表示待审或已撤回。
- 每次保存事务同时写入当前值和事件历史，并带审核人、UTC时间和递增版本。两个页面同时修改同一目标时，旧版本返回冲突，不覆盖后一次记录。
- 导出字段 `proposal_*` 为原建议，`human_*` 为人工记录。仅 `human_review_status=approved` 时 `human_confirmed=true`。CSV 对公式前缀做安全转义，JSONL 保留原始文字。
- 所有导出记录仍是 `training_eligible=false`。人工确认不会自动修改正式训练集或启动训练。
- 不批量代替用户确认；开发测试使用独立临时审核库，不把测试点击写入真实人工记录。

在线备份建议使用 SQLite 的 `.backup`/Python `Connection.backup`，或先停止服务再复制目录。不要在运行时只复制主数据库而漏掉 WAL。
