From 6405dff7c5c5dd733998cb3063ef6d62338feba7 Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Sat, 17 Oct 2026 22:49:58 +0800
Subject: [PATCH 1/2] =?UTF-8?q?docs(plans):=20=E5=A2=9E=E5=8A=A0=20K13=20?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=9C=8D=E5=8A=A1=E5=99=A8=E5=9C=B0=E5=9D=80?=
 =?UTF-8?q?=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/2026-10-17-K13.md | 121 +++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 docs/plans/2026-10-17-K13.md

diff --git a/docs/plans/2026-10-17-K13.md b/docs/plans/2026-10-17-K13.md
new file mode 100644
index 0000000..177c750
--- /dev/null
+++ b/docs/plans/2026-10-17-K13.md
@@ -0,0 +1,121 @@
+# 2026-10-17 K13 运行时服务器地址设置（仅 debug）
+
+## 一、目标与边界
+
+解决 debug APK 不带 `--dart-define` 时固定回退到
+`http://jiangdeMacBook-Air.local:8081` 的问题。增加仅 debug 可用的运行时地址
+覆盖，保存后下次启动生效。
+
+优先级：
+
+```text
+SharedPreferencesAsync dev.api_base_url
+  > --dart-define(API_BASE_URL)
+  > AppConfig 现有默认地址
+```
+
+- 客户端分支：`feature/flutter-k13-dev-server-setting`，基线 `b762289`。
+- 文档分支：`docs/k13-dev-server-setting`，FruitServer 基线 `1a5951c`。
+- release 不读取 SharedPreferences 覆盖，也不显示设置入口。
+- 不做环境列表、远程配置、接口或后端改动。
+- 不跑真机。当前有真机 `flutter run` 时，构建使用隔离副本，不终止用户会话。
+
+## 二、运行时解析
+
+新增 `lib/core/config/server_endpoint.dart`：
+
+1. 常量 key：`dev.api_base_url`。
+2. `normalize`：
+   - `trim()`；
+   - 只接受 `http://` 或 `https://`；
+   - `Uri.host` 必须非空；
+   - 去掉末尾所有 `/`。
+3. `resolve`：
+   - 本地值有效时使用本地值；
+   - 否则使用有效 dart-define；
+   - 否则使用现有默认值。
+4. `load({debug, preferences})`：
+   - debug=false 时立即返回，不创建/读取 SharedPreferences；
+   - debug=true 时读取并规范化，合法值写入 `AppConfig` 的运行时覆盖。
+5. `save` 与 `clear`：
+   - save 前规范化，非法值返回 false 且不写；
+   - clear 删除 key。
+
+`AppConfig` 增加运行时覆盖读写入口和编译期/默认地址 getter；`apiBaseUrl` 优先
+返回已加载的运行时值。`main()` 在 `runApp` 前
+`await ServerEndpoint.load(debug: kDebugMode)`，确保 `LumaDramaApp` 创建
+`ApiClient` 前已加载完成。
+
+## 三、Debug 设置入口
+
+`MineLogic.showLanguage` 增加 `showServerSetting` 参数。我的页设置弹窗中在语言
+列表下方增加「服务器地址」行：
+
+- 仅 `MyPage.debugShowSetting == true` 时显示，默认值 `kDebugMode`，测试可注入；
+- 副标题显示当前 `AppConfig.apiBaseUrl`；
+- 点击打开编辑弹窗，预填当前地址；
+- 保存合法地址后关闭编辑弹窗并提示“重启 App 生效”；
+- 非法地址在输入框显示校验错误，不保存；
+- 提供「恢复默认」，清除本地 key，并提示重启生效；
+- release 默认不显示，也不触发本地读取。
+
+新增三语文案：
+
+- `serverAddress`
+- `serverAddressHint`
+- `saveAddress`
+- `restartToApply`
+- `restoreDefault`
+- `invalidServerAddress`
+
+## 四、测试
+
+新增 `test/config/server_endpoint_test.dart`：
+
+- 本地覆盖 > dart-define > 默认；
+- 非法本地值忽略并回落；
+- trim、末尾斜杠、http/https；
+- `ftp://`、无 scheme、空 host 被拒绝；
+- debug=false 不读取覆盖；
+- save/clear 对 SharedPreferencesAsync 的行为。
+
+新增/扩展设置弹窗测试：
+
+- debug 注入 true：显示服务器地址行，可打开编辑弹窗；
+- 注入 false：不显示入口；
+- 非法地址显示错误且不写入。
+
+既有测试只更新必要锚点/新增断言，不删除用例。
+
+## 五、影响文件
+
+- `ReelShort/lib/core/config/server_endpoint.dart`（新增）
+- `ReelShort/lib/core/config/app_config.dart`
+- `ReelShort/lib/main.dart`
+- `ReelShort/lib/pages/mine/mine_view.dart`
+- `ReelShort/lib/pages/mine/mine_logic.dart`
+- `ReelShort/lib/l10n/app_en.arb`、`app_zh.arb`、`app_id.arb` 与生成文件
+- `ReelShort/test/config/server_endpoint_test.dart`（新增）
+- 我的设置弹窗测试
+- `FruitServer/docs/plans/2026-10-17-K13.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 六、门禁与 Git
+
+1. 先写运行时解析与入口可见性测试，确认红灯。
+2. 实现后跑定向测试。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 当前真机 run 会话不终止；构建在独立副本中进行，原 `build/` 不受影响。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 七、风险与待确认
+
+- `AppConfig.apiBaseUrl` 当前是纯 getter；增加运行时静态状态后，测试必须显式
+  清理，避免用例间污染。
+- release 的“完全不读取”由 `ServerEndpoint.load(debug: kDebugMode)` 和主入口
+  的 debug 参数共同保证；测试使用可注入 debug 参数验证。
+- 保存和恢复默认都只在下次启动生效，当前 ApiClient 不在运行中重建。
+- 设置入口只在 debug 显示，不修改发布包的信息架构。

From 70b9823d5bb89a809dd0d57f0a89656a7af5912f Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Sat, 17 Oct 2026 22:55:10 +0800
Subject: [PATCH 2/2] =?UTF-8?q?docs(plans):=20=E8=AE=B0=E5=BD=95=20K13=20?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=9C=8D=E5=8A=A1=E5=99=A8=E5=9C=B0=E5=9D=80?=
 =?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/INBOX.md    |  25 ++++++-
 docs/plans/PROGRESS.md | 158 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 182 insertions(+), 1 deletion(-)

diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md
index faf22c1..1de0960 100644
--- a/docs/plans/INBOX.md
+++ b/docs/plans/INBOX.md
@@ -20,7 +20,7 @@
 
 ---
 
-## [待处理] 2026-10-17 | K13 运行时服务器地址设置（仅 debug）
+## [已处理·待用户验收] 2026-10-17 | K13 运行时服务器地址设置（仅 debug）
 
 **用户反馈（2026-10-17，已重复 3 次）**：每次 Codex 门禁构建出的 APK 不带 `--dart-define`，App 就回退到 `http://jiangdeMacBook-Air.local:8081`，真机不可用。
 
@@ -63,6 +63,29 @@
 - 先写 `FruitServer/docs/plans/2026-10-17-K13.md`；每步「叙述 + 命令 + 原始输出 + 解读」追加到 `PROGRESS.md`；完成后停住写回执。
 - 提交作者与提交者统一 `Zhou Weidong <502333560@qq.com>`。
 
+### 五、K13 完成回执（2026-10-17）
+
+**结论**：新增 debug-only 运行时服务器地址覆盖。启动优先级为本地设置 >
+`--dart-define(API_BASE_URL)` > 现有默认；release 不读取本地覆盖且不显示入口。
+未改接口、后端或其他页面业务逻辑；未跑真机。
+
+- 客户端分支 `feature/flutter-k13-dev-server-setting` 从 `b762289` 完成并
+  `--no-ff` 合并；功能提交 `907562a`，合并提交 `f95325d`，已推送
+  `b762289..f95325d develop`。
+- 新增 `ServerEndpoint`，使用 `SharedPreferencesAsync` key
+  `dev.api_base_url`；URL 会 trim、校验 http(s) 和 host，并去掉末尾 `/`。
+- `main()` 在 `runApp` 前 debug 加载覆盖；ApiClient 创建时读取已解析地址。
+- 我的页设置弹窗新增服务器地址行、编辑/保存、非法值提示、重启生效提示和
+  恢复默认；入口可通过 `debugShowSetting` 注入，默认 `kDebugMode`。
+- 新增三语文案；既有语言设置流程保留。
+- `dart analyze lib test` 零告警；`flutter test` 为
+  `00:19 +309 ~1: All tests passed!`；不带 `dart-define` 的 Android debug
+  APK 在隔离副本中构建成功。
+
+用户真机验证步骤与逐步预期、原始输出见
+`docs/plans/PROGRESS.md`「29. K13 运行时服务器地址设置」。
+设备侧修改地址、重启和网络连通性验收由用户执行。
+
 ---
 
 ## [待处理] 2026-10-17 | K12 首页去标题 + 空态视觉重做
diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md
index 74c1b92..579faca 100644
--- a/docs/plans/PROGRESS.md
+++ b/docs/plans/PROGRESS.md
@@ -2635,6 +2635,164 @@ b5a8656..b762289  develop -> develop
 
 ---
 
+## 2026-10-17 K13 运行时服务器地址设置
+
+### 29.1 范围、分支与计划
+
+叙述：解决 debug APK 不带 `--dart-define` 时固定回退到 `.local` 的问题。
+新增 debug-only 运行时地址，优先级为本地设置 > dart-define > 现有默认。
+
+- 客户端分支：`feature/flutter-k13-dev-server-setting`，基线 `b762289`。
+- 文档分支：`docs/k13-dev-server-setting`，基线任务书 `1a5951c`。
+
+开工前先写并提交计划：
+
+```text
+6405dff docs(plans): 增加 K13 开发服务器地址实施计划
+```
+
+当前有真机 `flutter run` 会话，未主动终止；构建在独立副本中完成。
+
+### 29.2 先红：运行时配置与入口缺失
+
+```text
+$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart
+Error when reading 'lib/core/config/server_endpoint.dart': No such file or directory
+Member not found: 'AppConfig.clearRuntimeBaseUrl'
+No named parameter with the name 'showServerSetting'
+Some tests failed.
+```
+
+解读：运行时解析器、AppConfig 覆盖入口和 debug 设置参数均不存在，红灯符合 K13
+范围。
+
+### 29.3 运行时解析与启动顺序
+
+新增：
+
+```text
+86 lib/core/config/server_endpoint.dart
+```
+
+关键规则：
+
+```text
+preference key: dev.api_base_url
+runtime > dart-define(API_BASE_URL) > default
+normalize: trim, http(s), non-empty host, trailing slash removed
+release: ServerEndpoint.load(debug: false) returns before preferences are read
+```
+
+`main()` 在 `runApp` 前执行：
+
+```dart
+await ServerEndpoint.load();
+runApp(const LumaDramaApp());
+```
+
+因此 `LumaDramaApp` 创建共用 ApiClient 前，运行时地址已经加载完成。
+
+### 29.4 Debug 设置入口
+
+我的页设置弹窗增加服务器地址行：
+
+- 显示当前 `AppConfig.apiBaseUrl`；
+- 编辑弹窗预填当前地址；
+- 保存合法值后提示重启生效；
+- 非法值显示三语错误且不写 SharedPreferences；
+- 恢复默认清除 `dev.api_base_url`；
+- 设置面板改为 85% 屏高内可滚动，避免小屏溢出。
+
+可见性通过 `MyPage.debugShowSetting` 注入，默认 `kDebugMode`。release
+编译时默认 false，不显示该行，也不读取本地覆盖。
+
+新增三语 key：
+
+```text
+serverAddress
+serverAddressHint
+saveAddress
+restartToApply
+restoreDefault
+invalidServerAddress
+```
+
+### 29.5 定向与全量绿灯
+
+```text
+$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart
+00:00 +7: All tests passed!
+```
+
+覆盖：
+
+- 本地设置 > dart-define > 默认；
+- trim、末尾斜杠、http/https；
+- `ftp://`、缺 scheme、空 host 拒绝；
+- debug=false 不应用本地覆盖；
+- save/clear SharedPreferences；
+- debug 入口可见、注入 false 不可见；
+- 非法地址不保存并显示错误。
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+```text
+$ flutter test
+00:19 +309 ~1: All tests passed!
+```
+
+解读：309 项通过，1 项联调测试因客户端接口服务未启动按设计跳过。
+
+### 29.6 无 dart-define 的 Debug APK
+
+用户真机 run 未终止。将当前工作区同步到独立临时副本，并明确不带构建参数：
+
+```text
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                             23.4s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：即使 APK 没有 `--dart-define`，安装后也可在 debug 设置中保存真实服务器
+地址，重启后覆盖现有 `.local` 默认值。
+
+### 29.7 Git
+
+```text
+907562a feat(flutter): 增加 debug 运行时服务器地址设置
+f95325d merge: 合并 K13 开发服务器地址设置
+b762289..f95325d  develop -> develop
+```
+
+功能提交与合并提交 author/committer 均为
+`Zhou Weidong <502333560@qq.com>`。
+
+### 29.8 用户真机验证步骤与预期
+
+以下设备侧取证由用户执行，Codex 未跑真机。
+
+1. 安装本次不带 `--dart-define` 构建的 debug APK。
+   预期：App 可以启动，进入「我的 → 设置」能看到「服务器地址」。
+2. 点击「服务器地址」。
+   预期：编辑框预填当前地址，并显示「重启 App 生效」。
+3. 输入真实局域网地址，例如 `http://192.168.31.187:8081`，保存。
+   预期：返回设置页并提示重启；输入框不会保留非法格式。
+4. 完全结束 App 后重新打开，确认首页/发现请求成功，并在后端日志看到来自手机
+   的 `/app/home/feed` 等请求。
+   预期：请求使用新地址，不再访问 `.local` 默认地址。
+5. 再次进入设置，点击「恢复默认」并重启。
+   预期：本地覆盖被清除，回到编译配置地址。
+6. 用 release 构建检查。
+   预期：设置中完全没有服务器地址入口，且即使本地存有 key 也不会读取。
+
+设备侧日志、截图与最终连通性结论由用户执行。
+
+---
+
 ## 2026-10-17 iOS 构建阻塞：固定 shared_preferences_foundation 2.5.6
 
 ### 25.1 现象与根因