NetworkTool/docs/04-客户端流程与MVP.md

客户端流程与 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\NetworkTool
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/config?interface=<真实接口名>

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. 设备升级和远程维护能力