# 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 显示，不修改发布包的信息架构。