From 8926f9b5f3784755318f3e7915f893155858277a Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Sat, 17 Oct 2026 23:13:46 +0800
Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E8=AE=B0=E5=BD=95=20K15=20?=
 =?UTF-8?q?=E9=A6=96=E9=A1=B5=E6=9C=8D=E5=8A=A1=E5=99=A8=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E5=9B=9E=E6=89=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/PROGRESS.md | 95 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md
index fb11755..b831de3 100644
--- a/docs/plans/PROGRESS.md
+++ b/docs/plans/PROGRESS.md
@@ -2891,6 +2891,101 @@ f95325d..9fe62d1  develop -> develop
 
 ---
 
+## 2026-10-17 K15 首页服务器设置与真机默认地址
+
+### 31.1 最终范围
+
+用户最终确认手机与 Mac 在同一网络，不使用 USB 转发。修复范围确定为：
+
+1. 真机默认地址改为 `http://10.157.242.1:8081`，只替换
+   `devHostBaseUrl`；
+2. 平台默认选择与优先级保持不变：运行时设置 > dart-define > 平台默认；
+3. 首页加载失败页 debug 下增加「服务器设置」，复用 K13 地址弹窗；
+4. release 不显示入口。
+
+客户端修复分支：`fix/home-server-default`，基线 `9fe62d1`。
+
+### 31.2 地址与失败页实现
+
+`AppConfig`：
+
+```text
+devHostBaseUrl = "http://10.157.242.1:8081"
+```
+
+注释已说明该 IP 跟随开发机网络变化，换网络时只改这一行。模拟器、桌面端和
+iOS 模拟器仍使用 `127.0.0.1`；iOS/Android 真机使用该局域网地址。
+
+K13 的服务器地址弹窗抽到：
+
+```text
+lib/core/widgets/server_endpoint_dialog.dart
+```
+
+我的页和首页错误页共用同一弹窗。首页错误页新增
+`home-server-settings` 按钮，仅调试工具开启时显示；可编辑、保存、恢复默认，
+保存后提示重启生效。
+
+### 31.3 测试与门禁
+
+新增/更新测试：
+
+- `AppConfig.devHostBaseUrl` 为最终局域网地址；
+- 原有运行时 > dart-define > 默认优先级继续通过；
+- 首页错误页 debug 下显示按钮并可打开 `server-endpoint-input`；
+- 注入 release 条件时按钮不显示；
+- 我的页设置入口与非法地址拒绝继续通过。
+
+```text
+$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart test/home/home_server_setting_test.dart
+00:02 +10: All tests passed!
+```
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+```text
+$ flutter test
+00:21 +312 ~1: All tests passed!
+```
+
+```text
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                             13.2s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：312 项通过，1 项联调测试因服务未启动跳过；debug APK 构建成功。
+
+### 31.4 Git
+
+```text
+c4694c6 fix(flutter): 增加首页服务器设置并更新真机默认地址
+4778ce2 merge: 合并 K15 首页服务器设置修复
+9fe62d1..4778ce2  develop -> develop
+```
+
+功能提交与合并提交 author/committer 均为
+`Zhou Weidong <502333560@qq.com>`。
+
+### 31.5 用户真机验证步骤
+
+1. Android Studio 直接 Run，不额外传 `--dart-define`。
+   预期：默认请求 `http://10.157.242.1:8081`。
+2. 若首页仍加载失败，在错误页查看 debug 地址和「服务器设置」按钮。
+   预期：点击后打开与「我的 → 设置」相同的地址弹窗。
+3. 修改地址并保存，完全结束 App 后重开。
+   预期：使用新地址请求，后端日志出现手机侧请求。
+4. release 构建中检查首页错误页。
+   预期：不显示服务器设置入口。
+
+设备侧日志、截图和最终网络连通性结论由用户执行。
+
+---
+
 ## 2026-10-17 iOS 构建阻塞：固定 shared_preferences_foundation 2.5.6
 
 ### 25.1 现象与根因