docs(plans): 合并 K13 开发服务器地址回执
This commit is contained in:
Zhou Weidong committed
commit
8b4e0ff5ca
3 files changed
+303
-1
No files matched your search
@@ -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 显示，不修改发布包的信息架构。
|
||||
+24
-1
@@ -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 首页去标题 + 空态视觉重做
|
||||
|
||||
@@ -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 现象与根因
|
||||
|
||||
Reference in new issue
Block a user