# Server 首阶段实现清单

## 1. 目标

定义 Linux Server 从零开始时，第一阶段应该优先完成的模块、接口、数据结构和验证顺序。

第一阶段目标不是立即改 IP，而是先把“发现 + 连接 + 读取状态”整条只读链路打通。

## 2. 第一阶段范围

第一阶段只实现以下能力：

1. Server 启动
2. 读取固定运行配置
3. 启动前为管理接口挂载维护地址
4. UDP 广播发现
5. HTTP 服务启动
6. 固定密码鉴权
7. 设备信息读取
8. 真实接口枚举与识别
9. 返回接口列表

第一阶段暂不实现：

1. `netplan` 写入
2. 配置校验
3. 配置应用
4. 自动回滚
5. 重启与关机

## 3. 第一阶段必须完成的 HTTP 接口

### 3.1 `GET /api/health`

用途：

1. 客户端探活
2. 判断 Server 是否运行

最低返回：

1. 运行状态
2. Server 版本

### 3.2 `GET /api/device/info`

用途：

1. 展示设备基础信息
2. 确认设备身份

最低返回：

1. 设备 ID
2. 主机名
3. Ubuntu 版本
4. Server 版本
5. 运行时长

### 3.3 `GET /api/network/interfaces`

用途：

1. 返回真实接口列表
2. 返回当前管理接口
3. 返回建议目标接口
4. 为设备页提供数据

最低返回：

1. `management_interface`
2. `suggested_target_interface`
3. `requires_target_selection`
4. `interfaces[]`

## 4. 第一阶段必须完成的 UDP 能力

### 4.1 UDP 广播监听

要求：

1. 监听固定发现端口
2. 能接收 Windows 广播报文
3. 能正确解析 `discover` 请求

### 4.2 UDP 发现响应

要求：

1. 回传 `request_id`
2. 返回设备基础信息
3. 返回维护地址 `169.254.100.2`
4. 返回 `auth_required=true`

## 5. 第一阶段建议模块顺序

### 5.1 `config`

先完成一个最小配置模块，至少输出：

1. HTTP 端口
2. UDP 端口
3. 固定维护地址
4. 固定密码
5. Server 版本
6. HTTP 默认端口 `48888`
7. 支持 `--ip` 与 `--port` 启动参数
8. 支持 `--password` 启动参数，默认密码为 `Dt123$`

建议示例：

```bash
./networktool-server --ip 169.254.100.2 --port 48888 --password 'Dt123$'
```

### 5.2 `logger`

提供统一日志入口。

最低要求：

1. 信息日志
2. 错误日志
3. 敏感头过滤

### 5.3 `deviceinfo`

负责提供：

1. 主机名
2. OS 版本
3. 设备 ID
4. 运行时长

### 5.4 `network/interfaces`

这是第一阶段最关键模块之一。

最低要求：

1. 枚举物理有线接口
2. 过滤虚拟接口
3. 返回接口名、MAC、链路状态、IPv4
4. 判断当前管理接口
5. 判断建议目标接口
6. 在维护地址不存在时，为管理接口执行运行时注入

### 5.5 `auth`

最低要求：

1. 校验 `X-Admin-Password`
2. 返回统一失败结果

### 5.6 `httpserver`

最低要求：

1. 路由注册
2. 统一 JSON 输出
3. 接入 `auth`

### 5.7 `discovery`

最低要求：

1. 启动 UDP 监听
2. 收包后读取 `deviceinfo`
3. 收包后读取管理地址
4. 返回发现响应

## 6. 第一阶段建议数据结构

### 6.1 ServerConfig

建议字段：

```go
type ServerConfig struct {
    HttpPort          int
    UdpPort           int
    MaintenanceIP     string
    MaintenanceCIDR   string
    AdminPassword     string
    Version           string
}
```

### 6.2 DeviceInfo

建议字段：

```go
type DeviceInfo struct {
    DeviceID      string
    Hostname      string
    OSVersion     string
    ServerVersion  string
    UptimeSeconds int64
}
```

### 6.3 NetworkInterface

建议字段：

```go
type NetworkInterface struct {
    Name                 string
    SystemName           string
    Role                 string
    LinkUp               bool
    IsManagement         bool
    IsSuggestedTarget    bool
    MAC                  string
    IPv4                 []IPv4Address
    Gateway              string
    DNS                  []string
}
```

### 6.4 IPv4Address

建议字段：

```go
type IPv4Address struct {
    Address string
    Prefix  int
    Source  string
}
```

### 6.5 InterfacesResponse

建议字段：

```go
type InterfacesResponse struct {
    ManagementInterface     string
    SuggestedTargetInterface string
    RequiresTargetSelection bool
    Interfaces              []NetworkInterface
}
```

## 7. 第一阶段建议目录落地

建议优先创建：

```text
server/
  cmd/
    networktool-server/
  internal/
    config/
    logger/
    auth/
    deviceinfo/
    discovery/
    httpserver/
    network/
      interfaces/
```

## 8. 第一阶段联调前置条件

在 Windows 客户端开始联调前，Server 至少应满足：

1. 能在 Ubuntu 24 上正常启动
2. 能监听 HTTP 端口
3. 能响应 UDP 发现
4. 能返回设备信息
5. 能返回真实接口列表
6. 能识别当前管理接口

## 9. 第一阶段验证顺序

建议按下面顺序验证：

1. 本机直接访问 `GET /api/health`
2. 本机直接访问 `GET /api/device/info`
3. 本机直接访问 `GET /api/network/interfaces`
4. Windows 端发送 UDP 发现
5. Windows 端通过密码访问上述 3 个接口

## 10. 第一阶段完成标准

满足以下条件即可认为第一阶段完成：

1. Windows 能发现设备
2. Windows 能通过固定密码连接设备
3. Windows 能看到设备信息
4. Windows 能看到真实接口列表
5. Windows 能自动识别当前管理接口
6. 当接口数为 2 时，Windows 能拿到建议目标接口

## 11. 第二阶段入口

第一阶段完成后，再进入第二阶段：

1. `GET /api/network/config`
2. `POST /api/network/validate`
3. `POST /api/network/apply`
4. `POST /api/network/rollback`
5. `GET /api/tasks/{task_id}`

也就是先把“只读链路”做稳，再开始改配置。