docs(plans): 记录 K13 开发服务器地址回执
This commit is contained in:
Zhou Weidong committed
1 parent
6405dff7c5
commit
70b9823d5b
2 files changed
+182
-1
No files matched your search
+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