From d214a9791c87744fe8722c70a7a911db82928200 Mon Sep 17 00:00:00 2001 From: Zhou Weidong <502333560@qq.com> Date: Tue, 20 Oct 2026 18:18:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E7=95=99=E7=97=95=20K55=20?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=8A=A0=E8=BD=BD=E8=AF=8A=E6=96=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/INBOX.md | 34 ++++++++++++++++------------------ docs/plans/PROGRESS.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index 2d8c178..7274350 100644 --- a/docs/plans/INBOX.md +++ b/docs/plans/INBOX.md @@ -1,25 +1,23 @@ -## [已处理] 2026-10-20 | K54-A 修复 iOS 启动「剧目列表加载失败」（ATS + 探测顺序）（仅 App 端） +## [已处理] 2026-10-20 | K55-A iOS 加载失败定位：错误详情可见 + 重试前重新探测地址（仅 App 端） **用户指令（2026-10-20，原文）**： -> 「我现在启动iOS 显示剧目列表加载失败」 +> 「现在iOS 启动还是剧目列表加载失败」 -**根因（已定位）** -1. `ios/Runner/Info.plist` 只配置了 `NSAllowsLocalNetworking`，它只放行 `.local` 与无点主机名，**不放行** `http://127.0.0.1`、`http://192.168.x.x`、`http://39.162.50.99` 这类明文本 IP 请求 → iOS 上所有接口被 ATS 拦截，首页/剧场报「剧目列表加载失败」。 -2. `AppConfig.probeAndApplyBaseUrl()` 只探测 `127.0.0.1:8081`，失败后直接回落到公网 `39.162.50.99:8081`；iOS 真机既没有 adb reverse（127 不可达），公网也可能不可达，于是必然失败。 +**现状** +- Mac 侧后端 `127.0.0.1:8081` 与 `39.162.50.99:8081` 均返回 200；Mac 局域网 IP 仍为 `192.168.31.187`； +- iOS 侧 `Info.plist` 已放开 ATS，`AppConfig` 探测顺序已改为 127 → 192.168.31.187 → 公网； +- 失败页现在只显示通用文案「剧目列表加载失败」，看不到实际请求地址与异常，无法继续定位。 -**口径（只改 Flutter / iOS 配置，不动后端、不改接口）** -1. `Info.plist`：`NSAppTransportSecurity` 中： - - 增加 `NSAllowsArbitraryLoads = true`（开发阶段放开明文）； - - 同时保留 `NSAllowsLocalNetworking = true`； - - 增加 `NSExceptionDomains`：`127.0.0.1`、`localhost`、`192.168.31.187`、`39.162.50.99`，均 `NSExceptionAllowsInsecureHTTPLoads = true`、`NSIncludesSubdomains = true`。 -2. `AppConfig.probeAndApplyBaseUrl()` 改为按顺序探测并选第一个 200： - `127.0.0.1:8081` → `devHostBaseUrl`（192.168.31.187）→ `publicBaseUrl`； - 全部失败时使用平台默认（模拟器/桌面 = 127.0.0.1；真机 = devHostBaseUrl），**不再无条件回落公网**。 -3. 探测超时保持 2s/个，不阻塞首帧（首页已有 loading 占位）。 -4. Android 行为不回退：有 `adb reverse` 时仍优先 127.0.0.1，无 reverse 时会尝试开发机局域网地址，最后公网。 +**口径（只改 Flutter，不动后端、不改接口）** +1. 诊断信息可见（仅 `kDebugMode`）： + - 首页/剧场失败页追加两行小字：「服务地址：{AppConfig.apiBaseUrl}」「错误：{error 原文}」（Key `catalog-debug-endpoint` / `catalog-debug-error`），12 号 `AppColors.subtle`，最多 2 行省略； + - `CatalogController.load/refresh` 失败时 `debugPrint('[catalog] base=... error=...')`；`AppConfig` 探测每个候选地址打印 `[probe] -> ok/fail()`。 +2. 重试逻辑增强：首页与剧场错误态的「重试」按钮先 `await AppConfig.probeAndApplyBaseUrl()`，再 `catalog.load()`（Key 不变）；避免首次启动网络未就绪/权限弹窗期间探测失败后一直用错地址。 +3. App 回到前台（`AppLifecycleState.resumed`）时，若上次目录请求失败，自动重新探测并重载一次（不弹提示）。 +4. 不改 release 行为（debug 信息仅在 kDebugMode 显示与打印）。 **测试/门禁** -- 单元测试：探测候选顺序与「全部失败时使用平台默认」； -- `dart analyze lib test` 零告警 + `flutter test` 全过 + `flutter build apk --debug`（iOS 构建由用户在 Xcode 执行）。 +- 单测：失败态 debug 行显示当前地址与错误；重试会先调用探测再 load； +- `dart analyze lib test` 零告警 + `flutter test` 全过 + `flutter build apk --debug`。 -**流程**：从 `develop` 拉 `fix/ios-k54-network`；作者 `Zhou Weidong <502333560@qq.com>`；`--no-ff` 合回 develop 并 push；PROGRESS 留痕；真机验收由用户执行（iOS 模拟器/真机冷启动能正常加载首页）。 +**流程**：从 `develop` 拉 `fix/ios-k55-diagnostics`；作者 `Zhou Weidong <502333560@qq.com>`；`--no-ff` 合回 develop 并 push；PROGRESS 留痕；iOS 复现由用户执行（重建后把失败页上的「服务地址 / 错误」两行发回来即可精确定位）。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index 2d1707b..2ae4d12 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -21918,6 +21918,36 @@ Running Gradle task 'assembleDebug'... 解读：静态检查零告警，463 条测试全部通过，Android debug APK 构建成功。iOS 未执行真机构建，由用户在 Xcode 重新 Pod install 后验收 Swift 编译。 +## 2026-10-20 ReelShort：K55-A 目录加载诊断与前台重试 + +- 前置状态：`shared_preferences_foundation 2.5.6` 已完成并合并，develop 合并提交 `d68734c`。 +- 分支：`fix/ios-k55-diagnostics` +- 功能提交：`730a965 feat(flutter): 增加目录加载诊断与前台重试` +- develop 合并提交：`eab5d3e merge: 合并 K55 目录加载诊断`，已推送。 +- 首页与剧场错误态在 debug 下增加 `catalog-debug-endpoint`、`catalog-debug-error` 两行诊断，展示当前 `AppConfig.apiBaseUrl` 与原始错误，12 号 subtle、最多 2 行省略；release 不展示。 +- `CatalogController.load/refresh` 失败输出 `[catalog] base=... error=...`；`CategoryController` 同样输出目录诊断；地址探测逐项输出 `[probe] url -> ok/fail(reason)`，全部仅 debug。 +- 首页和剧场重试统一使用 `retryCatalogLoad`，先重新探测服务地址再加载数据；App 从后台回到 `resumed` 且目录仍失败时，自动重新探测并只重载失败的数据源一次，不弹提示。 + +测试：新增首页失败态地址/原始错误和 12 号 subtle 样式断言，以及“探测先于 load”顺序测试；剧场错误态增加两个诊断 Key 和原始异常文本断言。 + +门禁原始输出： + +```text +$ dart analyze lib test +Analyzing lib, test... +No issues found! + +$ flutter test +00:51 +465: All tests passed! + +$ flutter build apk --debug +Running Gradle task 'assembleDebug'... + 9.0s +✓ Built build/app/outputs/flutter-apk/app-debug.apk +``` + +解读：静态检查零告警，465 条测试全部通过，debug APK 构建成功。本机 Flutter 自动改写的 `pubspec.lock` 已恢复，未纳入提交。iOS 复现时可直接查看失败页服务地址与错误，或从 Xcode 日志筛选 `[probe]`、`[catalog]`。 + ## 2026-10-20 ReelShort：K53-A 详情页首帧直出 - 前置状态：K52-A 已完成并合并，develop 合并提交 `a11ba50`。