docs(plans): 留痕 K68 编译期接口地址

2026-10-20 20:21:28 +08:00
1 parent fdc7314087
commit bce8d37d88
@@ -1,59 +1,65 @@
 # INBOX

-## [已处理] K67-A 删除无引用代码与无用资源
+## [已处理] K68-A 指定 API_BASE_URL 时跳过地址探测

-### 扫描结论
+### 背景

-按「文件是否被 import/part/export 引用」做了全量可达性分析（含 `test/`），以下是彻底无引用的文件。
+正式包通过 `--dart-define=API_BASE_URL=http://39.162.50.99:8081` 指定接口地址，
+但 `AppConfig.probeAndApplyBaseUrl()` 不支持构建期地址：它只按
+`127.0.0.1 → 192.168.31.187 → 公网` 探测，探测结果又会覆盖 `apiBaseUrl`。

-### 要删除的 Dart 文件（10 个）
+后果：正式包启动时仍会去探测局域网；若公网暂时不可达，会回落到开发机地址
+`192.168.31.187`，正式包里所有请求都指向错误服务器。

- `lib/core/widgets/library_drama_tile.dart`
- `lib/pages/auth/auth_binding.dart`
- `lib/pages/discover/category_dramas_page.dart`
- `lib/pages/discover/widgets/category_grid.dart`
- `lib/pages/discover/widgets/ranking_section.dart`
- `lib/pages/home/home_browse_view.dart`
- `lib/pages/home/home_browse_logic.dart`
- `lib/pages/home/widgets/home_browse_header.dart`
- `lib/pages/home/widgets/home_menu_sheet.dart`
- `lib/pages/mine/widgets/continue_watching_card.dart`
+### 目标

-说明：`auth_form_widgets.dart`、`auth_widgets.dart`、`player_view_actions.dart`、
-`home_feed_overlay_parts.dart`、`player_overlay_parts.dart` 是 `part` 文件，**不要删**。
+- `API_BASE_URL` 已指定时，**不再探测**，直接使用该地址。
+- 运行时地址（用户在 App 内手动改的服务器）仍保持最高优先级，不被构建期地址覆盖。
+- 未指定 `API_BASE_URL` 时，探测逻辑保持现状。

-### 要删除的安卓资源
+### 实现

- `android/app/src/main/res/drawable-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/splash_icon.png`
-  （K60 遗留，已无任何 xml 引用）
- `android/app/src/main/res/values/colors.xml` 里的
-  `<color name="ic_launcher_background">#FFF1E5</color>`（自适应图标已改用
-  `@mipmap/ic_launcher_background`，无引用）
+1. `lib/core/config/app_config.dart` 的 `probeAndApplyBaseUrl`：

-### 要删除的本机无用资源（未纳入 git）
+```dart
+static Future<void> probeAndApplyBaseUrl({
+  Future<bool> Function(String baseUrl)? probe,
+  String? fallbackBaseUrl,
+  String? compiledOverride, // 仅测试注入用
+}) async {
+  final compiled = compiledOverride ?? compiledBaseUrl;
+  if (compiled.isNotEmpty) {
+    // 构建期已指定接口地址：直接使用，避免正式包回落开发机地址
+    if (_runtimeBaseUrl.isEmpty) applyRuntimeBaseUrl(compiled);
+    return;
+  }
+  // …原有探测逻辑不变
+}
+```

- `assets/media/`（21 个 mp4，约 315MB）
- `assets/images/`（4 张旧海报，约 3.7MB）
+2. `lib/main.dart` 不改（已 `AppConfig.ready = AppConfig.probeAndApplyBaseUrl()`）。
+3. 测试 `test/config/` 补充：
+   - 传 `compiledOverride` 时：`probe` 回调一次都不会被调用，`AppConfig.apiBaseUrl` 等于该地址
+   - 已存在运行时地址且传 `compiledOverride` 时：运行时地址不被覆盖
+   - 不传 `compiledOverride`（默认空）时：探测逻辑与现有测试保持一致
+   - 测试结束复位运行时地址

-这两个目录已被 `.gitignore` 忽略、pubspec 也未声明，删除只清理本机磁盘，不产生提交内容。
+### 验收

-### 不要动
+- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。
+- 复核用正式包构建命令（Trae 负责重打，不需要 Codex 执行）：

- `assets/fonts/`（Outfit / PlusJakartaSans）：虽然当前 pubspec 未声明，
-  但代码里仍在用这两个 family，删除/启用另行决策，本批保持原样。
- `assets/icon/fruitshorts.png`：图标设计源图，保留。
- `android/app/src/main/res/drawable*/splash.png`、`background.png`、`android12splash.png`、
-  `ic_launcher_foreground.png`、`mipmap-*` 全部保留（仍被引用）。
+```
+flutter build apk --release --target-platform android-arm,android-arm64 \
+  --dart-define=API_BASE_URL=http://39.162.50.99:8081
+```

-### 任务
+### Git

-1. 删除上述文件与资源；删除后全局搜索确认无残留引用。
-2. 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。
-3. 从 `develop` 拉 `chore/cleanup-unused`，只提交 Dart 与安卓资源删除，**禁止 `git add -A`**。
-4. 提交：`chore(cleanup): 删除无引用代码与无用资源`，作者 `Zhou Weidong <502333560@qq.com>`。
-5. `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K67-A 留痕
-   （列出删除清单、释放体积、门禁输出）。
+- 从 `develop` 拉 `fix/lock-compiled-base-url`。
+- 提交：`fix(config): 指定 API_BASE_URL 时跳过地址探测`，作者 `Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K68-A 留痕。

 ### 约束

- 全程中文；不改任何业务行为；完成后停住等待验收。
+- 全程中文；禁止 `git add -A`；不改探测候选顺序与超时；完成后停住等待验收。
@@ -22422,3 +22422,33 @@ Running Gradle task 'assembleDebug'...
 ```

 解读：静态检查零告警，478 条测试全部通过，debug APK 构建成功。真机验收由用户执行。
+
+## 2026-10-20 ReelShort：K68-A 指定 API_BASE_URL 时跳过地址探测
+
+- 前置状态：K67-A 已完成并合并，develop 合并提交 `2c5ff35`。
+- 分支：`fix/lock-compiled-base-url`
+- 功能提交：`9ebb54e fix(config): 指定 API_BASE_URL 时跳过地址探测`
+- develop 合并提交：`51c3635 merge: 合并 K68-A 锁定编译期接口地址`，已推送。
+- `probeAndApplyBaseUrl()` 新增仅测试注入用的 `compiledOverride`；编译期地址非空时立即返回，不再发起任何候选探测。
+- 编译期地址仅在运行时地址为空时应用；用户运行时地址仍保持最高优先级，不会被 `API_BASE_URL` 覆盖。
+- 未指定编译期地址时，环回、开发机、公网的候选顺序、并行探测、超时与 fallback 行为均保持不变。
+
+测试：新增编译期地址零探测、运行时地址不被覆盖、空编译期地址继续原探测流程三条用例；测试结束复位运行时地址。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:51 +481: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+   8.4s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态检查零告警，481 条测试全部通过，debug APK 构建成功。正式包由 Trae 按任务书命令重打并验收。