Add captive portal setup AP as P1 feature (4.11)

Hotel/airport WiFi requires web-based captive portal authentication,
which is impossible on a headless device without this feature.

- New P1 feature 4.11: Setup AP + Captive Portal proxy
  - Box auto-enters setup mode when no network is available
  - Phone connects to temporary AP, completes portal auth via proxy
  - Requires WiFi AP+STA concurrent mode
- Fallback options: USB tethering, mobile hotspot, ethernet, MAC clone
- New CLI commands: warpgate setup-wifi, warpgate clone-mac
- New config section for setup AP parameters
- Updated hardware requirements: WiFi module must support AP+STA
- Updated roadmap v1.5 to include setup AP
- Added risk entry and glossary terms
- Renumbered 4.12-4.23 accordingly

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

warpgate-prd-v3.md

@@ -200,13 +200,46 @@ TM 回写策略：
 
 **TIMEMACHINE_PATH 与 NAS_REMOTE_PATH 的关系**：两者是 NAS 上的不同目录，互不关联。NAS_REMOTE_PATH 是用户的照片/文件目录（如 `/volume1/photos`），TIMEMACHINE_PATH 是 TM 备份专用目录（如 `/volume1/timemachine`）。TM 回写通过独立的 SFTP 连接直接传输到 TIMEMACHINE_PATH，不经过 rclone VFS。
 
-#### 4.11 缓存预热（Warm-up）
+#### 4.11 配网模式 + Captive Portal 代理（Setup AP）
+
+盒子是 Headless 设备（无屏幕），而绝大多数酒店/机场 WiFi 需要网页认证（Captive Portal）。没有这个功能，旅途场景直接不可用。
+
+**核心流程**：
+
+```
+① 盒子开机，检测到未配置 WiFi 或无法联网
+   → 自动进入「配网模式」，WiFi 模块启动临时 AP（SSID: Warpgate-Setup）
+
+② 用户手机连接 Warpgate-Setup 热点
+   → 自动弹出配网页面（或手动访问 http://192.168.4.1）
+
+③ 配网页面显示周围可用 WiFi 列表，用户选择酒店 WiFi
+
+④ 盒子连接酒店 WiFi（WiFi 模块切换为 AP+STA 并发模式）
+   → 检测到 Captive Portal 重定向
+
+⑤ 盒子将 Captive Portal 认证页面代理到配网页面
+   → 用户在手机上完成酒店 WiFi 的网页认证（输入房号/姓名等）
+
+⑥ 认证通过，盒子获得互联网访问，Tailscale 自动连接
+   → 配网模式关闭，临时 AP 关闭（或保持为管理入口）
+```
+
+**硬件要求**：WiFi 模块必须支持 **AP+STA 并发模式**（同时作为热点和连接外部 WiFi），这是配网模式的前提。大多数支持 AP 模式的 WiFi 芯片均支持此功能。
+
+**Fallback 方案**（不需要额外开发，文档中列出即可）：
+- **USB 网络共享**：手机 USB 连接盒子，共享手机网络（tethering），绕过酒店 WiFi
+- **手机热点**：盒子直连手机 4G/5G 热点
+- **有线以太网**：部分酒店有网口，直插通常无需认证
+- **MAC 克隆**：`warpgate clone-mac <MAC>` 克隆已认证设备的 MAC 地址（高级用户）
+
+#### 4.12 缓存预热（Warm-up）
 - 命令行手动预热指定目录
 - 按时间范围预热（如"最近 7 天新增的文件"）
 - 定时预热任务（如每天凌晨自动拉取最新数据）
 - 预热进度显示
 
-#### 4.12 管理工具（CLI）
+#### 4.13 管理工具（CLI）
 - `warpgate status` — 查看服务状态、缓存命中率、回写队列、冲突文件数
 - `warpgate cache-list` — 列出缓存中的文件
 - `warpgate cache-clean` — 清理缓存
@@ -217,28 +250,30 @@ TM 回写策略：
 - `warpgate verify` — 双卡校验
 - `warpgate log` — 查看实时日志
 - `warpgate speed-test` — 链路速度测试
+- `warpgate setup-wifi` — 手动进入配网模式
+- `warpgate clone-mac <MAC>` — 克隆指定设备的 MAC 地址
 
-#### 4.13 带宽管理
+#### 4.14 带宽管理
 - 支持上传/下载分别限速
 - 运行时动态调整限速（不重启服务）
 - 回写带宽不影响读取体验
 
-#### 4.14 连接容错
+#### 4.15 连接容错
 - Tailscale 断连时自动重试
 - 已缓存的文件在离线时仍可正常读取
 - 写回队列在恢复连接后自动续传
 - 连接超时参数可配置
 
-#### 4.15 写冲突通知
+#### 4.16 写冲突通知
 - 冲突发生时通知用户（CLI 提示 / 日志 / 可选 Webhook）
 - 冲突文件清单管理
 - 手动解决冲突工具
 
 ### P2（后续迭代）
 
-#### 4.16 WiFi AP 现场共享
+#### 4.17 WiFi AP 现场共享
 
-盒子内置 WiFi 模块开启热点，现场团队设备连上即可通过 SMB/WebDAV 访问缓存目录。
+盒子内置 WiFi 模块开启持久热点，现场团队设备连上即可通过 SMB/WebDAV 访问缓存目录。与 4.11 配网模式的区别：配网 AP 是临时的（完成配网后关闭），本功能是持久的团队共享热点。
 
 - 支持 AP 模式，复用已有的 SMB/WebDAV 多协议服务
 - AP 网络与 Tailscale/WAN 网络隔离（安全考虑）
@@ -246,24 +281,24 @@ TM 回写策略：
 - **硬件要求**：需要两个独立网络接口——WiFi 模块用于 AP 热点，有线/USB 4G 网卡用于 WAN/Tailscale 连接。一体机硬件设计需预留双网卡
 - 典型场景：婚礼现场摄影师导入 SD 卡后，助理 iPad 连上 WiFi 即可浏览选片
 
-#### 4.17 Web 管理界面
+#### 4.18 Web 管理界面
 - 缓存状态仪表盘（大小、命中率、回写队列、冲突文件、带宽趋势图）
 - 缓存文件浏览器（查看/手动清除/手动预热）
 - 配置修改界面（参数调整无需编辑配置文件）
 - 冲突文件可视化处理
 - 实时日志查看器
 
-#### 4.18 NAS 侧 Agent 推送（可选增强）
+#### 4.19 NAS 侧 Agent 推送（可选增强）
 - 在 NAS 上运行轻量 Agent（Docker 容器），监听文件变化主动推送给 Proxy
 - 实现秒级远程变更感知（替代分钟级轮询）
 - 不依赖品牌 API，基于 inotify 通用方案
 
-#### 4.19 多 NAS / 多目录支持
+#### 4.20 多 NAS / 多目录支持
 - 同时连接多个远程 NAS（如家里 + 工作室）
 - 每个 NAS 独立共享名，独立缓存策略
 - 每个共享可配置不同的缓存大小和保留时间
 
-#### 4.20 智能缓存策略
+#### 4.21 智能缓存策略
 - 根据文件类型自动调整策略：
   - `.lrcat` / `.xmp`（Lightroom catalog/sidecar）→ 高优先级回写，短写回延迟
   - `.CR3` / `.ARW` / `.NEF`（RAW 照片）→ 大块预读，长缓存保留
@@ -271,12 +306,12 @@ TM 回写策略：
   - `.psd` / `.ai`（设计文件）→ 完整缓存，避免分块导致的兼容问题
 - 基于访问频率自动调整缓存优先级（热数据不被淘汰）
 
-#### 4.21 Docker 镜像
+#### 4.22 Docker 镜像
 - 一行命令启动：`docker run -v /mnt/ssd:/cache warpgate`
 - docker-compose 配置
 - 支持环境变量或挂载配置文件
 
-#### 4.22 通知机制
+#### 4.23 通知机制
 - 回写失败告警（Webhook / Telegram / 邮件）
 - 缓存空间不足告警
 - NAS 离线告警
@@ -1237,6 +1272,16 @@ for dir in watched_directories:
 | `INGEST_PRIORITY` | 导入文件的回写优先级 | `high` | 高于普通编辑文件 |
 | `INGEST_IO_CLASS` | 导入时的 I/O 调度优先级 | `best-effort:4` | 使用 ionice 设置，避免导入阻塞缓存读取 |
 
+### 配网模式配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `SETUP_AP_SSID` | 配网热点名称 | `Warpgate-Setup` | - |
+| `SETUP_AP_PASSWORD` | 配网热点密码（空=开放） | 空 | 首次配网建议开放，降低门槛 |
+| `SETUP_AP_AUTO` | 无网络时自动进入配网模式 | `yes` | `yes` |
+| `SETUP_AP_TIMEOUT` | 配网完成后临时 AP 保持时间 | `5m` | 认证成功后自动关闭 |
+| `SETUP_PORTAL_LISTEN` | 配网 Web 服务监听地址 | `192.168.4.1:80` | - |
+
 ### WiFi AP 配置
 
 | 参数 | 说明 | 默认值 | 建议值 |
@@ -1333,7 +1378,7 @@ for dir in watched_directories:
 | SD 卡槽 | SD / microSD，覆盖大多数相机 |
 | CFexpress 槽（可选） | CFexpress Type-B，高端相机用户 |
 | USB-A/C 口 | 至少 2 个，用于外接读卡器（XQD 等）或移动硬盘 |
-| WiFi 模块 | 支持 AP 模式，建议 WiFi 6 |
+| WiFi 模块 | 支持 **AP+STA 并发模式**（配网必须），建议 WiFi 6 |
 | 物理按钮 | 触发 SD 卡导入 / 确认操作 |
 | LED 状态指示 | 导入进度 / 完成 / 错误 / 回写状态 |
 | 内置电池 | 支持断电保护 + 便携使用 |
@@ -1386,6 +1431,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate
 | 缓存空间耗尽 | 中 | dirty 文件（导入+TM）撑满 SSD | 导入前空间预检；TM 硬配额；缓存空间告警（7.3.1） |
 | 中转服务带宽成本 | 中 | DERP 中继带宽随用户增长上升 | 大部分连接走 P2P 直连；按流量分级限速/计费；初期节点少按需扩容 |
 | 云备份存储成本 | 低 | 用户数据增长导致存储费用上升 | 接低价对象存储（B2/R2）；按量计费传导成本；增量备份减少传输量 |
+| 酒店 Captive Portal | 中 | Headless 设备无法完成网页认证，旅途场景不可用 | 配网 AP + Portal 代理（4.11）；fallback：USB tethering / 手机热点 / MAC 克隆 |
 
 ---
 
@@ -1394,7 +1440,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate
 | 阶段 | 内容 | 重点 |
 |------|------|------|
 | **v1.0 — MVP** | 配置文件 + 部署脚本 + CLI 管理 + 基础一致性 + Time Machine 支持 | SMB + 读写缓存 + 三时间戳 + 精简 metadata（两表）+ 分层轮询 + TM 备份目标（几乎零 Samba 配置成本） |
-| **v1.5 — 硬件原型** | SD 卡导入 + 自动归档 + 双卡校验 + LED/按钮交互 + 缓存预热 + 带宽管理 + 连接容错 + 写冲突通知 | 外拍现场核心场景 + P1 功能补全，验证硬件形态 |
+| **v1.5 — 硬件原型** | SD 卡导入 + 自动归档 + 双卡校验 + **配网模式 + Captive Portal 代理** + LED/按钮交互 + 缓存预热 + 带宽管理 + 连接容错 + 写冲突通知 | 外拍现场核心场景 + P1 功能补全，验证硬件形态 |
 | **v2.0 — 组网服务** | 内置 Headscale + 高速 DERP 节点 + WiFi AP 共享 | 开箱即连 + 现场团队协作 |
 | **v2.5 — 容灾 + 附加** | 云端异地备份 + Docker 镜像 + 多协议（NFS/WebDAV）+ NAS 侧 Agent 推送 | 数据安全闭环 + 降低部署门槛 |
 | **v3.0 — 硬件产品** | 定制硬件（SSD + 电池 + SD 槽 + WiFi），工业设计，开箱即用 | 产品化，面向非技术用户 |
@@ -1510,7 +1556,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate
 | 程序员场景（Git 缓存、Docker 镜像等） | 痛点不够强，已有成熟方案（Git 天然分布式、Codespaces 等） |
 | 公网文件分享链接 | 法律风险 + 需求不明确 |
 | 多设备 SaaS 管理面板 | 需求不明确，过早 |
-| Docker 开放运行环境 | 产品定位发散（注：这里指的是允许用户在盒子上运行任意 Docker 容器，而非 4.21 的"将本产品打包为 Docker 镜像部署"） |
+| Docker 开放运行环境 | 产品定位发散（注：这里指的是允许用户在盒子上运行任意 Docker 容器，而非 4.22 的"将本产品打包为 Docker 镜像部署"） |
 
 ---
 
@@ -1535,3 +1581,5 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate
 | **DERP** | Tailscale 的中继服务器（Designated Encrypted Relay for Packets），在无法直连时中转流量 |
 | **Ingest / 导入** | SD 卡文件导入到缓存并自动归档到 NAS 的过程 |
 | **WAL** | SQLite 的写前日志模式（Write-Ahead Logging），允许并发读写 |
+| **Captive Portal** | 强制门户认证，酒店/机场等 WiFi 连接后重定向到网页要求登录的机制 |
+| **AP+STA 并发** | WiFi 模块同时作为热点（AP）和连接外部网络（STA）的工作模式 |