# 客户端流程与 MVP

## 1. 目标接口配置与回滚策略

### 1.1 配置流程

1. 客户端调用 `validate`
2. 校验通过后调用 `apply`
3. Server 备份当前稳定配置
4. 写入新的 `netplan`
5. 执行 `netplan apply`
6. 验证目标接口地址是否生效
7. 可选验证网关连通性
8. 成功则标记为稳定配置
9. 失败则自动回滚

### 1.2 回滚原则

1. 仅回滚目标接口的业务配置
2. `LAN2` 控制口固定维护地址不受影响
3. 即使目标接口配错，仍可通过 `LAN2` 恢复

## 2. Windows 客户端流程

### 当前实现状态

当前实现已经收敛为以下结构：

1. 主窗口：负责本机网卡选择、密码输入、直连探测、切换到维护网络、发现并连接
2. 设备详情弹窗：负责设备信息、目标接口选择、当前配置读取、新配置填写、校验、应用、任务轮询

当前实现与早期设计相比有以下变化：

1. 密码默认自动保存到注册表，不再提供“记住密码”复选框
2. 密码框提供显示/隐藏切换
3. 设备信息与 Linux 接口不再常驻主窗口，改为连接成功后弹窗显示
4. 配置区的 `1/2/3` 步骤已直接放到按钮文案里

### 2.0 页面结构建议

早期设计建议采用 4 个主界面：

1. 连接页
2. 设备页
3. 配置页
4. 结果页

当前实现已收敛为：

1. 连接主窗口
2. 设备详情与配置弹窗

### 2.0.1 连接页

页面目标：

1. 选择 Windows 本机有线网卡
2. 切换到维护网络
3. 输入或自动带出密码
4. 发现设备并建立连接

页面元素建议：

1. 本机网卡下拉框
2. 网卡当前状态：
   - 网卡名称
   - 链路状态
   - 当前 IPv4
3. 密码输入框
4. 密码显示/隐藏切换
5. 按钮：`切换到维护网络`
6. 按钮：`发现并连接`
7. 运行日志区域

交互规则：

1. 若本地已保存密码，页面打开时自动填充
2. 用户可修改密码后重新保存
3. 发现成功后自动弹出设备详情与配置窗口

#### 连接页详细交互

建议按以下顺序执行：

1. 用户选择本机有线网卡
2. 客户端立即读取并展示该网卡状态：
   - 网卡名称
   - 真实系统名称
   - 是否已插网线
   - 当前 IPv4
3. 客户端自动从注册表读取已保存密码并填充到密码框
4. 用户可手动修改密码
5. 用户点击 `切换到维护网络`
6. 客户端记录该网卡原始配置
7. 客户端将该网卡设置为 `169.254.100.1/16`
8. 切换成功后，允许点击 `发现并连接`
9. 用户点击 `发现并连接`
10. 客户端通过 UDP 广播发现设备
11. 发现设备后，客户端使用当前密码调用 HTTP 接口进行连接验证
12. 若连接成功，进入设备页

#### 连接页状态提示建议

建议至少覆盖以下状态提示：

1. `请选择一块有线网卡。`
2. `当前网卡未检测到链路，请检查网线连接。`
3. `正在切换到维护网络，请稍候。`
4. `已切换到维护网络。`
5. `正在发现设备，请稍候。`
6. `已发现设备，正在验证连接。`
7. `连接成功。`
8. `未发现设备，请确认 Windows 已连接到设备的管理口。`
9. `密码错误，请检查后重试。`
10. `连接失败，请稍后重试。`

#### 连接页按钮状态建议

1. 未选择网卡时：
   - `切换到维护网络` 禁用
   - `发现并连接` 禁用
2. 已选择网卡但未切换维护网络时：
   - `切换到维护网络` 可用
   - `发现并连接` 禁用
3. 已成功切换维护网络后：
   - `切换到维护网络` 可重复执行
   - `发现并连接` 可用
4. 正在执行切换或发现时：
   - 两个按钮都禁用

#### 注册表存储建议

当前阶段建议使用当前用户范围注册表：

1. 路径：`HKEY_CURRENT_USER\Software\NetTool`
2. 值名：`SavedPassword`
3. 仅在用户勾选 `记住密码` 且连接成功后写入
4. 用户点击 `清除已保存密码` 时删除该值

### 2.0.2 设备详情弹窗

页面目标：

1. 展示设备基本信息
2. 展示当前管理接口
3. 展示目标接口候选列表
4. 确定本次要配置的真实接口名

页面内容建议：

1. 设备信息：
   - 设备 ID
   - 主机名
   - Ubuntu 版本
   - Server 版本
2. 管理接口信息：
   - 逻辑标识 `LAN2`
   - 真实接口名
   - 当前地址列表
3. 目标接口列表：
   - 逻辑标识
   - 真实接口名
   - MAC 地址
   - 链路状态
   - 当前 IPv4

交互规则：

1. 若 `requires_target_selection=false`，默认选中建议目标接口
2. 若 `requires_target_selection=true`，用户必须先选择目标接口才能继续

#### 设备页详细交互

页面建议分为两个区域：

1. 设备信息区
2. 接口识别区

#### 设备信息区建议字段

1. 设备 ID
2. 主机名
3. Ubuntu 版本
4. Server 版本

#### 接口识别区建议字段

接口列表建议使用表格展示，列如下：

1. 逻辑标识
2. 真实接口名
3. MAC 地址
4. 链路状态
5. IPv4 地址
6. 当前角色说明

其中：

1. 当前管理接口显示为 `LAN2`
2. 当前建议目标接口显示为 `LAN1`
3. 如果超过两个物理有线接口，其余接口显示为候选接口

#### 设备页选择规则

1. 若接口总数为 2：
   - 自动将当前管理接口标记为 `LAN2`
   - 自动将另一个接口标记为 `LAN1`
   - 默认选中该接口作为本次配置目标
2. 若接口总数超过 2：
   - 自动标记当前管理接口为 `LAN2`
   - 其余接口都列为候选目标接口
   - 用户必须显式选择一个真实接口名作为本次配置目标

#### 设备页操作按钮建议

1. `刷新接口状态`
2. `下一步`
3. `返回连接页`

#### 设备页按钮状态建议

1. 未确定目标接口时：
   - `下一步` 禁用
2. 已确定目标接口时：
   - `下一步` 可用
3. 正在刷新接口状态时：
   - `刷新接口状态` 禁用
   - `下一步` 禁用

#### 设备页状态提示建议

建议至少覆盖以下提示：

1. `正在读取设备信息，请稍候。`
2. `设备信息读取成功。`
3. `正在读取接口状态，请稍候。`
4. `已自动识别当前管理接口。`
5. `已自动识别建议目标接口。`
6. `检测到多个候选接口，请选择本次要配置的目标接口。`
7. `请选择一个目标接口后继续。`

#### 设备页跳转规则

1. 进入页面时自动调用：
   - `GET /api/device/info`
   - `GET /api/network/interfaces`
2. 若已有建议目标接口，客户端自动读取该接口当前配置
3. 点击 `下一步` 后进入配置页，并携带当前选中的真实接口名

### 2.0.3 配置页

页面目标：

1. 编辑目标接口网络参数
2. 先校验，再应用
3. 明确提示当前操作对象的真实接口名

页面表单建议：

1. 目标接口：只读显示当前选中的真实接口名
2. IP
3. 子网掩码
4. 网关
5. 首选 DNS
6. 备用 DNS

页面按钮建议：

1. `读取当前配置`
2. `校验配置`
3. `应用配置`
4. `返回上一步`

交互规则：

1. 配置页中始终显示 `当前操作对象：<真实接口名>`
2. `校验配置` 通过后才允许执行 `应用配置`
3. 若目标 IP 为 `169.254.x.x`，即时显示提示，不阻止提交

#### 配置页详细交互

页面建议分为三个区域：

1. 当前目标接口信息区
2. 网络参数编辑区
3. 操作按钮区

#### 当前目标接口信息区

建议展示：

1. 逻辑标识
2. 真实接口名
3. 当前链路状态
4. 当前 IPv4 地址
5. 当前网关
6. 当前 DNS

建议固定提示：

`当前操作对象：<真实接口名>`

#### 网络参数编辑区

建议字段：

1. IP 地址：文本框
2. 子网掩码：优先使用下拉框，也允许手动输入
3. 网关：文本框，选填
4. 首选 DNS：文本框，选填
5. 备用 DNS：文本框，选填

#### 输入建议

1. IP、网关、DNS 使用普通文本框
2. 子网掩码建议提供常用选项：
   - `255.255.255.0`
   - `255.255.0.0`
   - `255.0.0.0`
   - `255.255.255.128`
   - `255.255.255.192`
   - `255.255.255.252`
3. 子网掩码允许用户手工输入其他合法值

#### 校验策略建议

采用“两段校验”方式：

1. 本地即时校验
2. 服务端点击校验

本地即时校验只处理基础格式问题：

1. IP 是否为合法 IPv4
2. 网关格式是否正确
3. DNS 格式是否正确
4. 子网掩码是否为合法掩码

服务端点击校验处理业务规则：

1. 接口是否有效
2. 网关是否与目标 IP 同子网
3. 是否存在链路本地地址警告
4. 是否可正常写入目标接口配置

#### 配置页操作按钮建议

1. `读取当前配置`
2. `校验配置`
3. `应用配置`
4. `返回上一步`

#### 配置页按钮状态建议

1. 页面初始加载完成后：
   - `读取当前配置` 可用
   - `校验配置` 可用
   - `应用配置` 禁用
2. 服务端校验通过后：
   - `应用配置` 可用
3. 表单被再次修改后：
   - `应用配置` 重新禁用
   - 需要重新执行 `校验配置`
4. 正在读取、校验或应用过程中：
   - 所有按钮禁用

#### 配置页提示建议

建议至少覆盖以下提示：

1. `请输入目标接口的 IP 地址。`
2. `子网掩码格式不正确。`
3. `网关格式不正确。`
4. `DNS 格式不正确。`
5. `正在校验配置，请稍候。`
6. `校验通过。`
7. `配置校验失败，请检查输入内容。`
8. `目标接口使用的是链路本地地址，通常仅适合同链路通信。`
9. `正在提交配置，请稍候。`

#### 应用前确认建议

点击 `应用配置` 前建议弹出确认框。

确认框内容建议包含：

1. 目标接口真实接口名
2. IP 地址
3. 子网掩码
4. 网关
5. DNS

确认文案建议：

`请确认是否将以上配置应用到目标接口。`

### 2.0.4 结果页

页面目标：

1. 展示配置结果
2. 说明是否已回滚
3. 提供后续操作入口

状态建议：

1. 配置成功
2. 配置失败，已回滚
3. 配置失败，回滚失败

页面按钮建议：

1. `返回配置页`
2. `重新读取接口状态`
3. `重启设备`
4. `关机设备`

#### 结果页详细交互

结果页应清晰区分以下三种结果：

1. 配置成功
2. 配置失败，已自动回滚
3. 配置失败，回滚失败

#### 结果页建议展示字段

1. 目标接口真实接口名
2. 任务状态
3. 当前步骤
4. 结果说明
5. 是否已回滚

#### 结果页提示建议

建议至少覆盖以下提示：

1. `目标接口配置已成功应用。`
2. `配置失败，已自动回滚到上一次稳定配置。`
3. `配置失败，且回滚失败，请立即通过管理口检查设备状态。`
4. `正在读取最新接口状态，请稍候。`

#### 结果页后续操作建议

1. 配置成功后：
   - 自动刷新一次接口状态
   - 允许用户返回配置页继续调整
2. 配置失败且已回滚：
   - 默认引导用户返回配置页重新修改
3. 配置失败且回滚失败：
   - 重点提示用户继续通过 `LAN2` 管理口处理

### 2.1 设备发现

1. 用户选择本机有线网卡
2. 客户端检查链路状态
3. 客户端将本机网卡切换为 `169.254.100.1/16`
4. 用户输入密码或使用已记住的密码
5. 客户端发送 UDP 广播
6. 发现 `169.254.100.2`

### 2.2 读取状态

1. 调用 `GET /api/health`
2. 调用 `GET /api/device/info`
3. 调用 `GET /api/network/interfaces`
4. 调用 `GET /api/network/configs` 一次性读取全部网口配置

### 2.3 配置目标接口

1. 用户填写：
   - 目标接口
   - IP
   - 子网掩码
   - 网关
   - 首选 DNS
   - 备用 DNS
2. 客户端将子网掩码转换为前缀长度
3. 先调用 `validate`
4. 再调用 `apply`
5. 轮询任务状态
6. 展示成功、失败或已回滚结果

### 2.4 系统操作

1. 用户可执行重启
2. 用户可执行关机
3. 所有操作都必须携带密码 Header

## 3. 日志建议

1. 记录接口名、来源 IP、结果、耗时
2. 不记录密码 Header
3. 不在日志中明文暴露敏感信息
4. 网络配置变更建议记录：
   - 变更时间
   - 原配置
   - 新配置
   - 是否成功
   - 是否发生回滚

## 4. 记住密码策略

### 4.1 目标

允许客户端记住固定初始化密码，下次打开后可直接连接设备。

### 4.2 建议实现

1. 客户端默认自动保存密码到 Windows 本机
2. 下次打开客户端时自动读取并填充
3. 用户修改密码后，新值自动覆盖旧值

### 4.3 存储方式

当前阶段按简单实现处理，密码明文写入 Windows 注册表。

建议：

1. 将密码保存到当前用户范围的注册表项
2. 客户端启动时自动读取该值并填充
3. 当前不提供界面内删除密码按钮
4. 后续如需提升安全性，再升级为受保护存储方式

### 4.4 交互规则

1. 若已保存密码，连接页自动带出
2. 用户仍可修改密码
3. 新密码在连接或配置动作发生时自动覆盖旧密码
4. 若连续出现密码错误，应提示用户检查当前密码是否与 Server 启动参数一致
5. 需在文档和实现中明确：当前阶段密码保存在注册表中，为便捷优先方案

## 5. MVP 范围

第一版建议仅覆盖以下范围：

1. Ubuntu 24
2. netplan
3. `LAN1`、`LAN2` 仅作为逻辑展示标识
4. `LAN2` 固定 `169.254.100.2/16`
5. `LAN2` 支持 DHCP 获取 4G 地址
6. `LAN2` 支持 DHCP 获取网关与外联网参数
7. UDP 发现
8. HTTP 管理接口
9. Header 固定密码校验（当前阶段密码写死在代码中）
10. 基于真实接口名的静态 IP 配置
11. 自动回滚
12. 关机、重启
13. 以新机器初始化场景为主

## 6. 后续可扩展项

1. 每台设备唯一初始化密码
2. HTTPS 或双向认证
3. 多语言返回
4. 批量配置
5. 配置导入导出
6. 更细的审计日志
7. 设备升级和远程维护能力