From 94f9590128ec84e8f1ea7ce0050737536752ee47 Mon Sep 17 00:00:00 2001 From: awei Date: Tue, 28 Jul 2026 09:29:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(ios):=20IOS=5FPLAN=20=E5=8B=BE=E9=81=B8?= =?UTF-8?q?=E5=B0=8D=E9=BD=8A=E7=8F=BE=E6=B3=81=EF=BC=8B=E6=9B=B4=E6=AD=A3?= =?UTF-8?q?=E3=80=8CCI=20=E6=8E=A8=E4=B8=8D=E4=B8=8A=E5=8E=BB=E3=80=8D?= =?UTF-8?q?=E7=9A=84=E9=81=8E=E6=9C=9F=E6=95=98=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 盤點 A2/A5 前置條件時發現的洞:IOS_PLAN 的散文說階段 1–4、7 都完成, 但**勾選框仍是 [ ]/[~]**(階段 1 的 1-1/1-2/1-3/1-5、3-4、7-1)。 只讀清單的人會以為要重跑那些需要 sudo 的工具鏈步驟。 不照散文打勾,逐條重新取證: - xcode-select -p = /Applications/Xcode.app/...、xcodebuild = Xcode 26.6 (17F113) - xctrace list devices 有 iOS 26.5 runtime;flutter doctor → No issues found! - Info.plist 確認 UIBackgroundModes: location +兩則定位用途說明皆在 - **實跑 flutter build ios --no-codesign --flavor driver -t lib/main_driver.dart → ✓ Built Runner.app (20.6MB),Xcode build 116.8s**(先前只驗過 customer flavor) 更正 7-1:「已寫好但推不上去(token 缺 workflow scope)」是過期敘述—— CI 檔案早就在 main,最近一次完整執行 build-ios success(6 分鐘)。 同時記下它**不是 branch protection 的必要檢查**(PR #49 就是在它 pending 時合掉的)。 「0. 環境現況」表加註為動工前的歷史快照,避免被當成現況讀。 前置條件當日實查:google-services.json 不存在(A2 卡)、 devicectl list devices → No devices found(A5 階段 5 卡)。 Co-Authored-By: Claude Opus 5 --- docs/IOS_PLAN.md | 60 ++++++++++++++++++++++++++++++------------------ docs/TODO.md | 14 +++++++++-- 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/docs/IOS_PLAN.md b/docs/IOS_PLAN.md index 36a88a6..04c8cef 100644 --- a/docs/IOS_PLAN.md +++ b/docs/IOS_PLAN.md @@ -44,12 +44,24 @@ 回到 **No issues found**、`flutter test` 169 passed。CI 是乾淨 checkout 所以沒被影響, 但本機分析會被淹沒。 - ✅ **階段 7(收尾)也完成**:CI 加了 iOS job、README 補了 iOS 段、TODO 回填。 +- 🔁 **2026-07-28 重驗與勾選對齊**:先前階段 1 的四項(1-1/1-2/1-3/1-5)、3-4、7-1 + 的**勾選框與這段散文不一致**——散文說完成、勾選框仍是 `[ ]`/`[~]`, + 下一個 session 只讀清單會以為要重跑那些 sudo 步驟。已逐條重新取證後補勾: + `xcode-select -p`/`xcodebuild -version`(Xcode 26.6)/`xctrace list devices`(iOS 26.5 runtime)/ + `flutter doctor`(No issues found)/`Info.plist` 三個定位鍵; + **並實跑 `flutter build ios --no-codesign --flavor driver -t lib/main_driver.dart` + → `✓ Built build/ios/iphoneos/Runner.app (20.6MB)`(Xcode build 116.8s)** + ——先前只驗過 customer flavor 的 build,driver flavor 的不簽名 build 這次才真的跑過。 + 7-1「CI 推不上去」是過期敘述,已更正(見階段 7)。 - ➡️ **只剩階段 5(實機)與階段 6(推播,需付費帳號)**。 階段 5 需要使用者把 iPhone 接上電腦,並在 Xcode 幫 Runner target 選 Personal Team(簽名) +在手機上信任開發者憑證——這兩件事是 GUI 操作,Claude 代勞不了。 這階段最大的產出是 **A1「鎖屏長跑背景定位」的 iOS 實機驗收**,模擬器測不出來。 -## 0. 環境現況(2026-07-20 實測) +## 0. 環境現況(2026-07-20 實測 — **歷史快照**) + +> ⚠️ 這張表是**動工前**的狀態,四個 ❌ 都已在階段 1 清掉(2026-07-28 重驗仍成立)。 +> 保留它是為了重裝機器時知道要處理什麼,**不要當成現況讀**。 | 項目 | 實測結果 | 是否阻塞 | | --- | --- | --- | @@ -68,22 +80,24 @@ ## 階段 1 — 工具鏈打通(必須先做,會需要 sudo 密碼) -- [ ] **1-1 切換 developer directory** +- [x] **1-1 切換 developer directory** ✅ 2026-07-21(使用者執行,需 sudo) `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` - 驗收:`xcodebuild -version` 印出 `Xcode 26.x`。 -- [ ] **1-2 同意授權 + 安裝首次啟動元件** - `sudo xcodebuild -license accept` → `sudo xcodebuild -runFirstLaunch` - 驗收:兩個指令 exit 0。 -- [ ] **1-3 安裝 iOS 模擬器 runtime**(Xcode 26 預設不含) - `xcodebuild -downloadPlatform iOS` - 驗收:`xcrun simctl list devices available | grep iPhone` 有裝置。 + 驗收(2026-07-28 重驗):`xcode-select -p` = `/Applications/Xcode.app/Contents/Developer`、 + `xcodebuild -version` = **Xcode 26.6 (17F113)**。 +- [x] **1-2 同意授權 + 安裝首次啟動元件** ✅ 2026-07-21(使用者執行,需 sudo) + 驗收:`xcodebuild` 可正常執行(若授權未接受會在每次呼叫時擋下並要求同意); + 2026-07-28 的 `flutter build ios` 實跑全程無授權提示。 +- [x] **1-3 安裝 iOS 模擬器 runtime** ✅ 2026-07-21 + 驗收(2026-07-28 重驗):`xcrun xctrace list devices` 列出 **iOS 26.5** 的 + iPhone 17/17 Pro/iPad 等模擬器。 - [x] **1-4 安裝 CocoaPods** ✅ 2026-07-21 `brew install cocoapods`(避開系統 Ruby 2.6)。 驗收:`pod --version` → **1.17.0**,`which pod` → `/opt/homebrew/bin/pod`。 -- [ ] **1-5 `flutter doctor -v`** - 驗收:Xcode 與 CocoaPods 兩列都是 ✓,無 `!`。 +- [x] **1-5 `flutter doctor -v`** ✅ 2026-07-21 + 驗收(2026-07-28 重驗):`[✓] Xcode - develop for iOS and macOS (Xcode 26.6)`、 + **No issues found!**(Flutter 3.44.4 stable/macOS 26.5.2)。 -> ⚠️ 1-1 / 1-2 需要 sudo 密碼,Claude 無法代打。下次 session 開場請使用者自己跑這兩行,或允許互動輸入。 +> ⚠️ 1-1 / 1-2 需要 sudo 密碼,Claude 無法代打——**已由使用者執行完畢,這段留作重裝機器時的參考**。 --- @@ -131,7 +145,9 @@ - [x] **3-3 區網權限說明** ✅ 2026-07-21(plist 已加,驗收要等階段 5 真機) iOS 14+ 存取區網要 `NSLocalNetworkUsageDescription`,已寫入 Info.plist。 驗收:真機第一次連 `192.168.x.x:8080` 時出現權限詢問並可連線。 -- [ ] **3-4 背景定位 Info.plist 補齊** +- [x] **3-4 背景定位 Info.plist 補齊** ✅(階段 5 所需的部分已齊;`remote-notification` 留給階段 6) + 驗收(2026-07-28 實查 `ios/Runner/Info.plist`):`UIBackgroundModes` 含 `location`、 + `NSLocationWhenInUseUsageDescription` 與 `NSLocationAlwaysAndWhenInUseUsageDescription` 皆在。 現況已有 `UIBackgroundModes: location` + 兩則位置用途說明 ✅,階段 5 實機驗背景定位夠用。 `remote-notification` 留到階段 6(買付費帳號)再補——現在加了也沒有 APNs 可用。 程式面 [`driver_location_settings.dart`](../lib/core/location/driver_location_settings.dart) @@ -261,18 +277,18 @@ App 既有的 **WebSocket 派單路徑(`ride.assigned`)不依賴 APNs**, ## 階段 7 — 收尾 -- [~] **7-1 CI 加 iOS job** —— **已寫好但推不上去(2026-07-21)**: - `git push` 被 GitHub 擋下(`refusing to allow an OAuth App to create or update workflow - ... without workflow scope`),改動留在本機工作區未提交。 - 要納入請先 `gh auth refresh -h github.com -s workflow` 再提交,或把下面這段自己貼進檔案。 - 內容:`.github/workflows/flutter-ci.yml` 新增 - `build-ios`(`macos-latest`),跑 +- [x] **7-1 CI 加 iOS job** ✅ **已進 main 並實際在跑**(2026-07-28 查證) + `.github/workflows/flutter-ci.yml` 的 `build-ios`(`macos-latest`)跑 `flutter build ios --no-codesign --flavor customer -t lib/main_customer.dart`。 只跑一個 flavor 控 macOS runner 時間——兩個 flavor 共用同一個 Runner target, 會壞的東西(Podfile/xcconfig/Info.plist)一個就測得出來。 - **同一條指令已在本機跑過**:`✓ Built build/ios/iphoneos/Runner.app (20.4MB)`, - 且產物 Info.plist 是 `dev.linefleet.line_fleet_app.customer`/「乘客端」 - → 連 **Release-customer** configuration 都驗到了,不只 Debug。 + **驗收**:最近一次完整執行(run `30319680445`)`build-ios` **success,6 分鐘** + (01:14→01:20),同一 run 的 `analyze-and-test` 也 success。 + ⚠️ **2026-07-21 寫的「已寫好但推不上去(token 缺 `workflow` scope)」是過期敘述**, + 2026-07-28 更正:檔案早就在 main(`.github/workflows/flutter-ci.yml`), + 不需要再 `gh auth refresh`。 + **注意 `build-ios` 不是 branch protection 的必要檢查**——它 pending 時 PR 仍可合併 + (app PR #49 就是這樣合的)。要讓它擋門得去 repo Settings 設 required check。 - [x] **7-2 README 補 iOS 段** ✅ 2026-07-21:環境需求改寫(Xcode 26+模擬器 runtime+CocoaPods)、 新增「iOS」章節(兩個 flavor 指令、bundle id、顯示名機制、ATS、`--flavor` 配對 `-t` 的坑、 `GoogleService-Info.plist` 為何還沒導入)、以及 `API_BASE` 平台預設值對照表。 diff --git a/docs/TODO.md b/docs/TODO.md index 98585fe..20a53b1 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -60,8 +60,12 @@ 兩個 shared scheme,bundle id 對齊 Android(`dev.linefleet.line_fleet_app.driver`/`.customer`), 顯示名走 xcconfig 變數;模擬器主畫面「司機端」「乘客端」**兩個 icon 並存不互相覆蓋**。 **✅ 階段 7 收尾**:README 補 iOS 段與 `API_BASE` 平台預設對照表; - CI 的 `build-ios` job(macos-latest,customer flavor 不簽名 build)**已寫好但推不上去**—— - token 缺 `workflow` scope,改動留在本機工作區,需 `gh auth refresh -h github.com -s workflow`。 + CI 的 `build-ios` job(macos-latest,customer flavor 不簽名 build)**已在 main 並且真的在跑**—— + 2026-07-28 查證最近一次完整執行 `build-ios` **success(6 分鐘)**。 + 先前寫的「已寫好但推不上去(token 缺 `workflow` scope)」是**過期敘述,已更正**。 + ⚠️ 但它**不是 branch protection 的必要檢查**:pending 時 PR 照樣合得進去(PR #49 即如此)。 + **2026-07-28 補驗**:`flutter build ios --no-codesign --flavor driver -t lib/main_driver.dart` + 實跑過(`20.6MB`,Xcode build 116.8s)——先前只驗過 customer flavor 的不簽名 build。 **➡️ 只剩階段 5 實機部署**(需使用者接上 iPhone+Xcode 選 Personal Team+手機信任憑證, 產出是 A1「鎖屏長跑背景定位」的 iOS 實機驗收)**與階段 6 推播**(卡在付費 Apple 帳號)。 **實機已有、Apple 帳號為免費 Personal Team**:階段 1–5(含實機部署與 A1 背景定位實機驗收) @@ -587,6 +591,12 @@ ride_ratings 2、ride_messages 1、daily_driver_earnings 11、device_tokens 1。 > **條件**:等實際累積評分、營運說得出要對低分司機做什麼再開—— > 做在前面只會做出沒人用的流程。 > +> **2026-07-28 又補了一項(不在原清單上)**:`docs/IOS_PLAN.md` 的**勾選框與散文不一致**—— +> 階段 1 的四項、3-4、7-1 的散文說完成、勾選框卻仍是 `[ ]`/`[~]`。 +> 只讀清單的人會以為要重跑那些 sudo 步驟。已逐條重新取證後補勾(見 IOS_PLAN「執行進度」)。 +> **前置條件當日實查**:`android/app/google-services.json` **不存在**(A2 仍卡)、 +> `xcrun devicectl list devices` → **No devices found**(A5 階段 5 仍卡)。 +> > **🎯 下次開工第一件事**:**維護項已經清空了**(5、6 都完成,7 要等營運需求)。 > 第 1–4 項全部需要你提供外部資源或拍板,**沒有前置條件就不要硬找事做**—— > 開工前先確認:Firebase 專案(A2)/iPhone+Xcode Personal Team(A5 階段 5)/