feat(ostool): migrate legacy board server_ip config to URL format

Author: ZCShou

README.en.md

@@ -317,7 +317,7 @@ Use the TUI editor to update it:
 ostool board config
 ```
 
-`server` should be a complete URL including `http://` or `https://`; the optional `port` overrides the URL port. For legacy LAN configurations, a bare IPv4 or IPv6 address is interpreted as `http://`; bare host names are not supported, and the removed `server_ip` field is not restored. Project-local `.board.toml` `server` / `port` fields still apply to `ostool board run`, with precedence lower than CLI flags and higher than the global config.
+`server` should be a complete URL including `http://` or `https://`; the optional `port` overrides the URL port. For legacy LAN configurations, a bare IPv4 or IPv6 address is interpreted as `http://`. The base release's persisted `server_ip` / `port` pair is also migrated to `server` / `port` when read; the next configuration save writes only the new format. Bare host names are not supported. Project-local `.board.toml` `server` / `port` fields still apply to `ostool board run`, with precedence lower than CLI flags and higher than the global config.
 
 ### Public board authentication
 

README.md

@@ -314,7 +314,7 @@ auth_mode = "disabled"
 ostool board config
 ```
 
-`server` 应使用包含 `http://` 或 `https://` 的完整 URL；可选的 `port` 会覆盖 URL 中的端口。为兼容旧的局域网配置，裸 IPv4 或 IPv6 地址会自动补为 `http://`；不支持无 scheme 的主机名，也不恢复已移除的 `server_ip` 字段。项目级 `.board.toml` 中的 `server` / `port` 仍可用于 `ostool board run`，其优先级低于命令行参数，高于全局配置。
+`server` 应使用包含 `http://` 或 `https://` 的完整 URL；可选的 `port` 会覆盖 URL 中的端口。为兼容旧的局域网配置，裸 IPv4 或 IPv6 地址会自动补为 `http://`。基线版本写出的 `server_ip` / `port` 也会在读取时迁移为 `server` / `port`，下一次保存配置时只写新格式；无 scheme 的主机名不支持。项目级 `.board.toml` 中的 `server` / `port` 仍可用于 `ostool board run`，其优先级低于命令行参数，高于全局配置。
 
 ### 公网开发板认证
 

docs/api.md

@@ -2,7 +2,7 @@
 
 本文根据当前 `ostool` 客户端实现整理认证网关和开发板服务的调用接口；不包含 `ostool-server` 管理后台的 `/api/v1/admin/...` 接口。
 
-服务地址来自全局或项目配置中的 `board.server`（完整 URL），可被命令行 `--server` 覆盖；可选的 `board.port` 或 `--port` 用于覆盖 URL 中的端口。为兼容旧的局域网配置，`board.server` 为裸 IPv4 或 IPv6 地址时客户端自动补为 `http://`；无 scheme 的主机名不支持，已移除的 `server_ip` 字段也不会恢复。认证网关和 board API 使用同一个 Base URL。
+服务地址来自全局或项目配置中的 `board.server`（完整 URL），可被命令行 `--server` 覆盖；可选的 `board.port` 或 `--port` 用于覆盖 URL 中的端口。为兼容旧的局域网配置，`board.server` 为裸 IPv4 或 IPv6 地址时客户端自动补为 `http://`。基线版本写出的 `board.server_ip` / `board.port` 也会在读取时迁移为 `board.server` / `board.port`，下一次保存配置时只写新格式；无 scheme 的主机名不支持。认证网关和 board API 使用同一个 Base URL。
 
 - `auth_mode = "required"` 时，`board.server` 必须使用 HTTPS，所有请求携带下文描述的 Bearer Token；
 - `auth_mode = "disabled"`（默认）时通常使用 HTTP，不会发送认证 Header，适合局域网直连 `ostool-server`。

ostool/src/board/global_config.rs

@@ -7,7 +7,7 @@ use std::{
 use anyhow::{Context, bail};
 use reqwest::Url;
 use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize, de::Error as _};
 
 // Keep the URL-based configuration aligned with ostool-server's established
 // default listen port so a newly generated config works without user edits.
@@ -90,8 +90,7 @@ pub struct BoardGlobalConfigFile {
     pub board: BoardGlobalConfig,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(deny_unknown_fields)]
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
 pub struct BoardGlobalConfig {
     /// Complete board service URL, including its scheme and optional base path.
     #[serde(default = "default_server")]
@@ -103,6 +102,53 @@ pub struct BoardGlobalConfig {
     pub auth_mode: AuthMode,
 }
 
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct BoardGlobalConfigInput {
+    #[serde(default)]
+    server: Option<String>,
+    // The base release persisted this field. It exists only in the input
+    // representation so upgraded installations can be read and rewritten in
+    // the URL-based format; new configuration is always serialized as `server`.
+    #[serde(default)]
+    server_ip: Option<String>,
+    #[serde(default)]
+    port: Option<u16>,
+    #[serde(default)]
+    auth_mode: AuthMode,
+}
+
+impl<'de> Deserialize<'de> for BoardGlobalConfig {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let input = BoardGlobalConfigInput::deserialize(deserializer)?;
+        let server = match (input.server, input.server_ip) {
+            (Some(server), None) => server,
+            (None, Some(server_ip)) => {
+                let server_ip = server_ip.trim();
+                match server_ip.parse::<IpAddr>() {
+                    Ok(IpAddr::V6(_)) => format!("http://[{server_ip}]"),
+                    Ok(IpAddr::V4(_)) | Err(_) => format!("http://{server_ip}"),
+                }
+            }
+            (None, None) => default_server(),
+            (Some(_), Some(_)) => {
+                return Err(D::Error::custom(
+                    "`board.server` and legacy `board.server_ip` cannot be used together",
+                ));
+            }
+        };
+
+        Ok(Self {
+            server,
+            port: input.port,
+            auth_mode: input.auth_mode,
+        })
+    }
+}
+
 impl Default for BoardGlobalConfig {
     fn default() -> Self {
         Self {
@@ -213,7 +259,7 @@ fn write_config_file(path: &Path, file: &BoardGlobalConfigFile) -> anyhow::Resul
 mod tests {
     use tempfile::tempdir;
 
-    use super::{AuthMode, BoardGlobalConfig, BoardGlobalConfigFile, LoadedBoardGlobalConfig};
+    use super::{AuthMode, BoardGlobalConfig, LoadedBoardGlobalConfig};
 
     #[test]
     fn load_or_create_creates_url_based_default_config_when_missing() {
@@ -327,15 +373,36 @@ mod tests {
     }
 
     #[test]
-    fn legacy_config_fields_are_rejected() {
-        let err = toml::from_str::<BoardGlobalConfigFile>(
+    fn load_migrates_base_server_ip_config_and_save_writes_url_format() {
+        let temp = tempdir().unwrap();
+        let path = temp.path().join(".ostool/config.toml");
+        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+        std::fs::write(
+            &path,
             r#"
                 [board]
-                server_ip = "10.0.0.2"
-                port = 9000
+                server_ip = "localhost"
+                port = 2999
             "#,
         )
-        .unwrap_err();
-        assert!(err.to_string().contains("server_ip"));
+        .unwrap();
+
+        let loaded = LoadedBoardGlobalConfig::load_or_create_at(&path).unwrap();
+        assert!(!loaded.created);
+        assert_eq!(loaded.board.server, "http://localhost");
+        assert_eq!(loaded.board.port, Some(2999));
+        assert_eq!(
+            loaded
+                .resolve_endpoint(None, None)
+                .unwrap()
+                .base_url
+                .as_str(),
+            "http://localhost:2999/"
+        );
+
+        loaded.save().unwrap();
+        let content = std::fs::read_to_string(path).unwrap();
+        assert!(content.contains("server = \"http://localhost\""));
+        assert!(!content.contains("server_ip"));
     }
 }