2026-10-17 K13 运行时服务器地址设置（仅 debug）

一、目标与边界

解决 debug APK 不带 --dart-define 时固定回退到 http://jiangdeMacBook-Air.local:8081 的问题。增加仅 debug 可用的运行时地址覆盖，保存后下次启动生效。

优先级：

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：

常量 key：dev.api_base_url。
normalize：
- trim()；
- 只接受 http:// 或 https://；
- Uri.host 必须非空；
- 去掉末尾所有 /。
resolve：
- 本地值有效时使用本地值；
- 否则使用有效 dart-define；
- 否则使用现有默认值。
load({debug, preferences})：
- debug=false 时立即返回，不创建/读取 SharedPreferences；
- debug=true 时读取并规范化，合法值写入 AppConfig 的运行时覆盖。
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

先写运行时解析与入口可见性测试，确认红灯。
实现后跑定向测试。
运行 dart analyze lib test、flutter test、flutter build apk --debug。
当前真机 run 会话不终止；构建在独立副本中进行，原 build/ 不受影响。
完成后 merge --no-ff 回客户端 develop 并 push；FruitServer 文档同样合并推送。作者与提交者统一为 Zhou Weidong <502333560@qq.com>。

七、风险与待确认

AppConfig.apiBaseUrl 当前是纯 getter；增加运行时静态状态后，测试必须显式清理，避免用例间污染。
release 的“完全不读取”由 ServerEndpoint.load(debug: kDebugMode) 和主入口的 debug 参数共同保证；测试使用可注入 debug 参数验证。
保存和恢复默认都只在下次启动生效，当前 ApiClient 不在运行中重建。
设置入口只在 debug 显示，不修改发布包的信息架构。

4.6 KiB Raw Permalink Blame History Unescape Escape