docs(plans): 增加 K13 开发服务器地址实施计划

2026-10-17 22:49:58 +08:00
1 parent 1a5951ce98
commit 6405dff7c5
@@ -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 显示，不修改发布包的信息架构。