docs(iteration): 归档项目迭代 V0.4.2 - 路由模式与 TUI 完善

meta/ARCHITECTURE.md

@@ -25,7 +25,8 @@
 
 - 下载并审阅 Tailscale 官方安装器后执行安装。
 - 检查 `tailscaled`、登录状态和当前 advertised routes。
-- 发布或移除 `192.168.11.0/24`、`192.168.22.0/24`，同时保留设备上其他 advertised routes。
+- 管理互斥的“仅 4via6”和“仅旧 IPv4”模式。4via6 模式保存全 Tailnet 唯一的 Site ID，为两个维护地址生成路由；旧 IPv4 模式用于历史兼容。
+- 启用任一模式时移除另一模式的受管路由，同时保留设备上其他 advertised routes。
 - 在启用子网路由时配置 IP forwarding，在禁用时恢复脚本执行前的状态。
 - 通过 `whiptail`、`dialog` 或普通终端提供中文单出口 TUI。
 - 从 `/opt/armaster/data/hw.json` 只读获取 `sn` 作为设备名默认前缀，收集用户补充名称和标签选择，并调用 helper 完成 OAuth 自动注册；配置缺失或无效时回退到系统 hostname。
@@ -36,6 +37,7 @@
 
 - `/etc/sysctl.d/99-tailscale-routes.conf`：仅在脚本需要开启 forwarding 时创建，包含管理标记。
 - `/var/lib/tailscale-route-manager.state`：记录 IPv4/IPv6 forwarding 的原始状态，不保存凭证。
+- `/var/lib/tailscale-route-manager.site`：保存路由模式和可选的 Site ID，带管理标记且不保存凭证；旧配置缺少模式字段时默认为 4via6。
 - OAuth Secret、Access Token 和 Auth Key：只在进程内或权限为 `0600` 的短期文件中存在，不属于持久状态。
 
 主要执行流：
@@ -44,13 +46,17 @@
 主页面
   -> 安装/检查 Tailscale
   -> OAuth 注册（设备名称 + 在线标签多选）或浏览器登录
+  -> 选择互斥路由模式
+  -> 4via6：配置唯一 Site ID 并生成两个 IPv4 /32 对应的 routes
+  -> 旧 IPv4：使用两个历史 IPv4 /24 routes
   -> 读取并合并 advertised routes
+  -> 移除非当前模式的受管 routes
   -> 记录并开启 forwarding
-  -> 发布受管子网
+  -> 发布当前模式的受管 routes
   -> 返回主页面
 
 禁用受管路由
-  -> 从当前路由集合移除受管子网
+  -> 从当前路由集合移除受管 4via6 和旧版 IPv4 routes
   -> 保留其他 advertised routes
   -> 恢复 forwarding 原状态
   -> 返回主页面

meta/FEATURES.md

@@ -4,5 +4,5 @@
 | --- | --- | --- |
 | Agent 治理骨架 | Done | AGENTS、workflow、rule、skill 与多 Agent 适配层已初始化 |
 | 脚本安全约束 | Done | 已定义敏感信息、幂等、权限、危险操作与验证边界 |
-| Tailscale Route Manager | Done (V0.3.2) | 支持 OAuth 批量注册、在线标签多选、短期密钥安全清理及基于 `hw.json` SN 的设备命名前缀；成功入网和多设备批量验收待现场复验 |
+| Tailscale Route Manager | Done (V0.4.2) | 支持 OAuth 批量注册、默认 QArm 标签、SN 设备名前缀、登录/退出、网络检测，以及互斥的 4via6 与旧 IPv4 路由模式；多设备批量注册与 TUI 视觉效果仍待现场复验 |
 | 其他 QArm 业务配置脚本 | Pending | 等待后续按真实目标平台和配置需求添加 |

meta/ITERATIONS.md

 # 迭代记录
 
+## [V0.4.2] 4via6 路由模式与 TUI 完善 (Route Modes and TUI Polish)
+
+- **功能**: 增加网页登录与 OAuth 登录选择、退出登录、默认 `tag:qarm`、Tailscale 网络名称和独立 `netcheck`；将重复 IPv4 维护地址升级为 Site ID 驱动的 4via6 路由，并保留互斥的旧 IPv4 兼容模式；为 TUI 分支增加处理中界面，减少操作间露出底层终端。
+- **改动文件**:
+  - `scripts/tailscale/tailscale-route-manager.sh`: 实现登录状态操作、网络诊断、Site ID、路由模式互斥、受管路由保护、中文状态和 TUI 过渡。
+  - `tests/tailscale/test-route-manager.sh`: 覆盖路由模式切换、旧配置兼容、路由集合保护、登录状态、默认标签、网络名称、netcheck 与 TUI 过渡。
+  - `docs/tailscale/README.md`: 补充 4via6、旧 IPv4 模式、登录/退出、网络检测、TUI 行为、系统影响和人工验收说明。
+  - `meta/ARCHITECTURE.md`: 更新路由模式、Site ID 持久状态及启用/禁用数据流。
+  - `meta/REGRESSION.md`: 增加路由模式、网络诊断、登录状态和 TUI 过渡回归项。
+- **影响**: 多台具有重复局域网地址的 QArm 可通过唯一 Site ID 提供独立维护入口，同时允许单设备继续使用旧 IPv4 subnet。`0.4.2` 已部署到 `192.168.81.118`，只读复验确认原 Site ID、4via6 routes 和 forwarding 保持不变；真实 TUI 视觉效果及多设备端到端访问仍需现场验收。
+
 ## [V0.3.2] OAuth 批量注册与设备命名 (OAuth Provisioning and Device Naming)
 
 - **功能**: 新增 OAuth Client 自动注册链路，在线读取 Provisioner 可直接分配的标签，在中文 TUI 中输入设备名称并多选标签；动态创建短期一次性 Auth Key，安全清理临时凭证，并使用 `/opt/armaster/data/hw.json` 的 `sn` 作为设备名称默认前缀。

meta/PROJECT_MANIFEST.json

 {
   "project_name": "qarm_setup_scripts",
-  "version": "0.3.2",
-  "iteration_count": 4,
-  "last_update": "2026-10-23",
+  "version": "0.4.2",
+  "iteration_count": 5,
+  "last_update": "2026-10-25",
   "stack_summary": [
     "PowerShell",
     "Shell",
@@ -40,6 +40,11 @@
     "tailscale_whiptail_width_safe": true,
     "tailscale_dialog_color_ready": true,
     "tailscale_oauth_registration_ready": true,
-    "tailscale_hardware_sn_prefix_ready": true
+    "tailscale_hardware_sn_prefix_ready": true,
+    "tailscale_login_logout_ready": true,
+    "tailscale_default_qarm_tag_ready": true,
+    "tailscale_network_diagnostics_ready": true,
+    "tailscale_route_modes_ready": true,
+    "tailscale_tui_transition_ready": true
   }
 }

meta/REGRESSION.md

@@ -14,12 +14,22 @@
 | 敏感信息检查 | 检查凭证、私钥、token、生产地址和未脱敏日志 | Ready |
 | Tailscale 脚本 Bash 语法 | `bash -n scripts/tailscale/tailscale-route-manager.sh` | Ready |
 | Tailscale 只读命令 | `tailscale-route-manager.sh help` 与 `status` 不修改系统 | Ready |
-| 路由集合保护 | 启用时合并、禁用时仅移除两个 managed routes | Ready |
+| 路由集合保护 | 启用时合并当前模式并移除另一模式；禁用时仅移除已知 4via6 与旧版受管 IPv4 routes | Ready |
+| 路由模式互斥 | 仅支持 `4via6` 或 `legacy`；当前模式路由仍发布时拒绝切换；无模式字段的旧配置默认为 4via6 | Ready |
+| 4via6 Site ID | 仅接受 `1-65535`；配置持久化；当前编号路由仍发布时拒绝换号 | Ready |
+| 4via6 路由生成 | Site ID 与两个 IPv4 `/32` 生成稳定的独立路由；生成失败时不修改 forwarding 或 advertised routes | Ready |
+| 旧版路由兼容 | legacy 模式无需 Site ID；发布两个 IPv4 `/24` 并移除已知 4via6 路由，同时保留无关路由 | Ready |
 | Forwarding 恢复 | IPv4/IPv6 原始状态均能独立记录和恢复 | Pending |
 | 目标设备端到端路由 | 从 tailnet 客户端访问两个 QArm 局域网 | Pending |
 | Tailscale 状态颜色 | `dialog` 与交互终端显示彩色圆点和中文状态，`whiptail` 仅显示中文状态，重定向或 `NO_COLOR` 时为纯文本 | Ready |
+| Tailscale 网络名称 | 已连接时状态页显示 `Self.HostName`；未连接时显示“未连接”，字段缺失时显示“未知” | Ready |
+| Tailscale 网络检测 | 主菜单和 `netcheck` 命令显示完整检测输出；失败信息可见且 TUI 返回主页面 | Ready |
+| Tailscale TUI 操作过渡 | `dialog`/`whiptail` 菜单分支在执行前显示处理中界面；窗口间不主动清屏暴露底层终端 | Ready |
 | Whiptail 边框宽度 | 状态文本不得包含双列 emoji；右侧边框不因状态行发生错位 | Ready |
 | Tailscale TUI 单出口 | 分支完成、取消、Esc 或失败后返回主页面；仅主页面“退出”结束 TUI | Ready |
+| Tailscale 登录 | 未登录设备可执行 `tailscale login`；已登录设备不重复操作；完成后返回主页面 | Ready |
+| Tailscale 登录方式 | TUI 可选择网页登录或 OAuth 自动注册；取消选择返回主页面；OAuth 快捷入口继续保留 | Ready |
+| Tailscale 退出登录 | TUI 退出前二次确认；已退出设备不重复操作；不隐式修改子网路由或 forwarding | Ready |
 | 未登录时取消启用 | `tailscale up` 确认框选择 No 后不退出脚本，直接返回主页面 | Ready |
 | OAuth 凭证不持久化 | 检查仓库、状态文件和输出不包含 Client Secret、Access Token 或 Auth Key | Ready |
 | OAuth 标签权限过滤 | Policy 中仅由 Provisioner 直接拥有的标签进入 TUI 列表 | Ready |
@@ -27,5 +37,6 @@
 | OAuth 注册失败恢复 | 取消或失败后删除临时 Key 文件并返回主页面 | Ready |
 | OAuth Auth Key 描述 | 描述只包含 API 接受的 ASCII 字母数字和连字符，且不超过 50 字符 | Ready |
 | OAuth 标签大小写 | Provisioner 与设备标签统一使用小写，Auth Key 标签和 `tailscale up` 请求必须一致 | Ready |
+| OAuth 默认 QArm 标签 | `tag:qarm` 可用时自动包含它，用户可增加其他标签；不存在时保持普通多选 | Ready |
 | 硬件 SN 名称前缀 | 有效 `hw.json.sn` 生成 `<sn>-` 默认值；缺失、损坏、非法或过长时回退 hostname | Ready |
 | OAuth 批量真实注册 | 在至少两台新设备连续运行并核对名称、标签和连接状态 | Pending |