JoyDive

已知問題 & v1.1 規劃

最後更新請見 git log -- docs/KNOWN_ISSUES.md(不手動維護日期戳,理由見 V1_2_BACKLOG.md「使用方式」)


✅ 已解決(原「待決策事項」,2026-07-25 解決)

項目 說明 解決方式
macOS/iOS LSApplicationCategoryType 誤觸發遊戲模式 Info.plist 原設為 public.app-category.sports-games(Apple 分類體系裡「運動類電玩遊戲」子分類,非「運動」本身),會讓 iOS 18+/macOS 系統把 App 誤判為遊戲,觸發 Game Mode/Game Center 相關行為(iOS 端曾出現「遊戲模式:已開啟」橫幅)。已改為 public.app-category.healthcare-fitness;App Store Connect 的 Category 欄位同步改為 Health & Fitness。iOS + macOS 皆已用真機/直接雙擊安裝版驗證修復生效(不需要等這次送審核准)。詳見 V1_2_BACKLOG.md #1b 2026-10-10 後續:v1.3 依 PM 裁示改為 public.app-category.sports(運動,非 sports-games),對齊其他潛水日誌 App;ASC 主類別同步改 Sports。  
Trimix 潛水 Edit 後 Save 會靜默把氣體資料降級成 Air(資料損毀) DiveLogEditSheet 的 Gas picker 不支援編輯 trimix,但 save() 原本無條件用 picker 顯示值覆寫 dive.gasMixJSON。已修:記住原始 JSON,trimix 潛水 save() 時維持不動;picker 對 trimix 加 .disabled()。詳見 V1_2_BACKLOG.md #18  
配重/氣瓶壓力英制單位未換算 + 剖面圖多語系版面截斷 DiveLogEditSheet/DiveLogDetailView/DiveLogListView 三處各自獨立寫死 kg/bar/m;DiveAnalysisView 剖面圖互動列的 Ceiling/No Deco/Temp 標籤在德/法/泰/越/克羅埃西亞等語言下過長被截斷。已修復單位換算與版面保底(.minimumScaleFactor),部分翻譯內容縮短。詳見 V1_2_BACKLOG.md #18/#20/#22/#23  
ImportWizardView 進度/結果畫面完全未走在地化 "File X of Y"/匯入結果訊息原本是純字串插值,不管 App 語言設定永遠顯示英文;旁邊早有 18 語言翻譯的 key 閒置沒被呼叫。已重新接回既有 key。詳見 V1_2_BACKLOG.md #21  
3 處統計卡片在 Dynamic Type AX5 極限字級下視覺重疊 DiveLogListView/DiveLogDetailView/DiveSiteSheetView 的「圖示+數值+單位+標籤」3 欄橫排卡片,共用元件 DiveKitUI.DiveStatCell 內建的 minimumScaleFactor 只保護單一欄位不溢出,擋不住 3 欄硬擠一列的整體重疊;純程式碼審查沒抓到,模擬器實測(xcrun simctl ui content_size accessibility-extra-extra-extra-large)才發現。DiveStatCell 是 DiveKit 共用元件不在本 App 改,改為 App 層 3 處呼叫端各自判斷 dynamicTypeSize.isAccessibilitySize 切換直式排列。詳見 WCAG_2.1_AA_AUDIT_CHECKLIST.md 附錄 2  
真機 VoiceOver 走查抓到 4 個問題(2026-07-27) ①DiveLogDetailView.DetailRow 的 .accessibilityLabel("\(label): \(value)") 直接內插未本地化的英文 key(畫面顯示正確中文,VoiceOver 卻唸英文,日文版同樣受影響),改用 languageManager.localized(label);②DiveLogEditSheet 的 Entry Time DatePicker VoiceOver 朗讀值不吃 \.environment(\.locale)(Apple 元件內部行為,畫面顯示正確),改用 .accessibilityValue() 蓋掉系統算出來的朗讀值;③「新增潛水」Save 鈕在 maxDepth == 0 時靜默停用、無任何視覺/VoiceOver 提示,回報成「無法儲存」,已加可見 footer 提示+對應 accessibilityLabel/Hint;④「潛水剖面圖」被 2026-07-26 一次翻譯縮短 commit 誤改成語意不同的「潛水曲線」,已改回。詳見 WCAG_2.1_AA_AUDIT_CHECKLIST.md 附錄 3  

✅ v1.3 已解決(2026-10-17 整理;逐項證據見 docs/V1_3_WORK_PLAN.md §七~§九,對照表見 V1_2_BACKLOG.md 文末)

項目 說明 解決方式/現況驗證
v1.2→v1.3 升級是否丟資料;開資料庫失敗即 fatalError(升級失敗者每次開 App 閃退) v1.2 之後模型改兩處(waterTemperature 改選填、新增 diveMode),從未實測升級;失敗時直接 fatalError P0-1 模擬器實測:真 v1.2(3) 建 105 筆→覆蓋安裝 v1.3(4),資料指紋逐欄相同、無閃退。D2(6eb6552):失敗改顯示錯誤頁+記憶體後備容器,不刪、不重建、不覆寫資料檔;現在 DiveLogDatabase.swift 的 fatalError 只剩「記憶體後備容器也建不起來」一處
匯入精靈關閉時閃退(SIGABRT,181e441) 關閉匯入精靈後崩潰 P0-3:2026-10-10 模擬器以「檔案」App 選檔匯入多次、關閉精靈不閃退(模擬器實測,本次整理未重跑)
定位權限說明只有英文(稽核 R-06) NSLocationWhenInUseUsageDescription 18 種語言都顯示英文 P1-1 新增 JD2-Logbook/InfoPlist.xcstrings(09ac3f5),10/06 翻譯補齊 15 語
NSAllowsArbitraryLoads 全面放行 ATS(稽核 R-01) 當初為 AdMob 真機廣告加入 D7:改 AdMob 官方寫法,移除全面放行、補 NSAllowsArbitraryLoadsInWebContent,ForMedia 保留。Info.plist 現只剩這兩鍵;測試廣告照常顯示
不穩定的匯入效能測試 ImportCoordinatorTests SuuntoJSON 單次解析門檻 100 ms 貼著常態上緣(58–100 ms),全套並行偶發失敗 P1-3:門檻改 500 ms(常態約 5 倍,抓回歸用),註明「本專案決定」,見 ImportCoordinatorTests.swift:474;門檻 100 ms 本來就沒有出處
死碼 getStatistics()(稽核 R-04,平均深度算法錯誤) 無呼叫端 P1-2 移除;全專案 *.swift 搜尋 0 筆
Garmin FIT 氣體全變 air 讀錯訊息號 DiveImportKit v0.7.2(269→259);舊版匯入的 Garmin 紀錄標為氣體不可信(jd2GarminGasVerified),含 v1.2 資料與備份還原
剖面讀數 5 個 label 在 Xcode 27 建置下被縮到 65% .minimumScaleFactor(0.65) 放得下也縮小 改 ViewThatFits:先原字級,放不下才可縮小(DiveAnalysisView.swift)。另 4 處同型問題尚未改,見下方「v1.3 後仍開放」
Swift 6 隔離警告、Catalog 孤兒鍵 App 層警告 3 個;未使用鍵 P1-4(a560f1f)警告 3→0;P1-5(fd9b1cf)移除 50 個未使用鍵、補 Developer Tools

⏳ v1.3 後仍開放(2026-10-17 整理)

項目 說明 影響 排定版本
GDPR/UMP 廣告同意流程未做 GoogleUserMessagingPlatform 被解析為相依套件,但程式碼 UMP 呼叫 0 筆;非個人化廣告仍需同意(docs/V1_3_D6_D7_RESEARCH.md)。另:程式送出的廣告請求未設定非個人化(AdBannerView.swift:37 Request()),「App 只走非個人化廣告」無程式依據;隱私政策 11/07 已刪此說法(PM 裁示) 歐洲區廣告合規 下一版(PM 10/05 裁示)
另 4 處 .minimumScaleFactor 在 Xcode 27 建置下放得下也縮小 DiveLogListView.swift:307,313(統計列)、DiveRowView.swift:114(日期區塊)、ImportWizardView.swift:694(副檔名);改法同剖面讀數的 ViewThatFits,改完與 v1.2 截圖對照 版面外觀 ✅ v1.4 C 已改(View.shrinkOnlyIfNeeded);⚠️ 未驗證效果:11/04 Xcode 27.2/iOS 26.2 建置改前改後逐像素相同、原症狀未重現、縮小路徑(放不下時)未實測
SwiftData 無 SchemaMigrationPlan(稽核 R-07) 目前單一版本 Schema;v1.3 實測 lightweight migration 105 筆正常,但 breaking schema 變更沒有遷移路徑 日後改資料模型 下次改資料模型時一起做
最大字級(XXXL)+窄機時剖面讀數數值被「…」截斷 v1.2 起即有 極端字級 PM 10/05:不處理(系統字級放到最大,各 App 皆如此)
上升速率警示功能關閉中 showWarningEvents=false(DiveAnalysisView.swift:31),使用者看不到;重開前須改家族色 功能未啟用 未排程(8/13 PM:呈現方式未定)
匯入不辨識潛水模式(自潛/浮潛皆當水肺) DiveImportKit 尚無欄位;PM 10/04 裁示等 App-u 日誌格式定案 匯入資料的潛水類型 待 App-u
Localizable.xcstrings 的 %lld%% 被 Xcode 標 extractionState: stale 編輯頁改用 percentText 後無人引用;Xcode 每次 build/Archive 也會自動重排整份 xcstrings(2026-10-10 還原過一次),提交前先 git diff --stat,需要時 git checkout -- 還原 無功能影響 ✅ v1.4 C 已刪除(11/04)
UDDF 以 <link ref> 引用的潛伴未匯入、搜不到(稽核 F16,2026-10-27) DiveImportKit UDDFParser.swift:483-489 只讀直寫的 firstname;測試 DiveSearchTests.testUDDFLinkedBuddyIsNotImportedYet 鎖現況 標準寫法 UDDF 的潛伴不可搜尋 DiveImportKit(已回報總指揮,未排程)
手動新增的潛水沒有潛伴/標籤欄位(稽核 F11/D-B,2026-10-27) 潛伴/標籤只存在匯入紀錄的 importExtrasJSON;編輯頁無對應欄位,不動 schema 手動紀錄的潛伴/標籤無法填寫、搜尋擴充只對匯入紀錄有效 ✅ PM 11/04 裁示 D-B ①:不加欄位、不動 schema,列為已知限制(docs/decisions/D-2026-11-04-DB-DE已知限制與F-09複數形實驗.md)
iOS 26 搜尋作用中時無法改篩選(2026-11-04) 搜尋列作用中,系統把導覽列右上的篩選與+藏起來;按取消會清掉搜尋字。使用者要先篩選再搜尋(兩者 AND 照常) 搜尋中想改篩選要先取消搜尋 ✅ PM 11/04 裁示①:接受現況,記為已知行為(docs/decisions/D-2026-11-04-搜尋收合成按鈕.md)
v5 App Icon 外觀(v1.4 C,2026-11-04) 四張圖與 ICON_v5 cmp 相同、編譯產物含 dark/tinted、macOS AppIcon.icns 為 v5;iOS 一般/深色/著色 PM 11/04 iPhone 實機截圖確認;Mac Dock PM 11/04 Mac 實機截圖,經總指揮轉述 — ✅ 已驗
iOS 詳細頁「原始匯入資料」展開(v1.4 C,2026-11-04) 模擬器點兩次未展開(詳細頁回彈);PM 11/04 iPhone 實機截圖,經總指揮轉述:三筆皆正常展開、6 個新標籤與值正確 ⇒ 模擬器操作問題,非程式問題(DisclosureGroup 為 v1.1 f326c90 起的標準寫法,本次只改內容) — ✅ 結案
覆蓋安裝後第一次啟動畫面卡住 10–20 秒(PM 11/04 iPhone 16 實機,Xcode 安裝,71 筆) 重開不再卡;模擬器全新安裝與 105 筆皆未重現。候選:Xcode 偵錯器首次附掛、Debug 建置未最佳化、v1.4 首次遷移(lightweight,可能性較低)——皆未量測 若是遷移,使用者首次啟動會以為當機 ✅ 結案(PM 2026-11-07):同機 App Store v1.3+既有資料 → TestFlight 1.4(5)升級,首次啟動無延遲(docs/SUBMISSION_CHECK_NEXT.md)
v1.3 以前從 Diving Log 匯入的備註可能帶 RTF 殘留(字型名稱如「Microsoft Sans Serif;」等)(2026-11-04) DiveImportKit v0.8.2 以前的 RTF 轉純文字不跳過字型表等目的地群組;v0.8.3 已修(RTFPlainText,總指揮 91b960f)。已匯入的紀錄不自動清理(PM 11/04) 舊備註開頭或整段是字型名稱 使用者可自行編輯備註;重新匯入會被去重略過(ImportCoordinator.swift:116),要先刪除該筆再匯入
搜尋 2,000 筆時每鍵 30–38 ms(稽核 T26/D-E,2026-10-27) 每次按鍵對每筆解碼 importExtrasJSON;A2 前 12 ms。門檻 16 ms 為本專案決定;Debug、模擬器量測 大量資料打字略頓 ✅ PM 11/04 裁示 D-E ①:接受,列為已知限制(一般使用者紀錄數遠少於 2,000);有使用者回報再做解碼快取(docs/decisions/D-2026-11-04-DB-DE已知限制與F-09複數形實驗.md)
最大字級(AX5)版面:列表統計列占約六成、潛水列截斷;剖面圖時間刻度重疊;德文編輯頁標題截斷(稽核 F17) 既有版面,git diff ae3a629..HEAD 佐證非 v1.4 引入 無障礙大字級可讀性 待 PM 排程
MockDataSeeder 類別隨 Release 出貨(稽核 F18) MockDataSeeder.swift:10 未包 #if DEBUG;入口在 #if DEBUG 內,Release 無呼叫點 死碼,無功能影響 ✅ v1.4 修正(2026-11-05):整檔包 #if DEBUG,Release 產物不再含此類別
Localizable.xcstrings.backup 被打包進 App(稽核 F19) 400 KB 舊翻譯檔,2026-05-29 起在版控,fileSystemSynchronizedGroups 帶進 bundle;推定 v1.0–v1.3 已出貨 App 多 400 KB,無機敏資料 ✅ v1.4 修正(2026-11-05):檔案自 repo 移除,Release 產物 0 個 .backup
地圖同座標 2 筆以上聚合後無法點開看 log(PM 2026-10-26) 讀碼推斷:DiveMapRepresentable.swift:54-56 點聚合只 showAnnotations,成員座標相同時縮放無法拆開。未實機重現;App-u 同寫法(總指揮 10/26 讀碼,未重現) 同座標多筆紀錄看不到 v1.4(V1_4_WORK_PLAN.md B2;修完回報總指揮評估 App-u)
iPhone SE 寬度下標題被截斷(2026-11-05 模擬器,SE 3) 列表大標題「Dive Logbook」希臘文「Ημερολόγιο καταδύ…」、義文「Logbook / Diario di i…」;詳細頁標題「Dive Details」希臘/義/法/西文被右側刪除+編輯按鈕擠成「…」(截圖 docs/screenshots/v1.4-L10N-layout/04、05、10、12)。仍未處理:編輯/新增潛水 sheet 標題被「取消」「儲存」文字按鈕擠成「…」(希臘文模擬器「Επεξερ…」17;PM 11/05 iPhone 實機「Νέα κ…」) 小螢幕+長語言的標題不完整 ✅ 列表標題:PM 11/05「只改放不下的」⇒ it/el 改短;最終 PM 11/05「採納」:18 語(含英文)一律改用分頁「Logbook」譯文,捲動後小標題 17pt 實量最寬 el 94 pt < 145 pt(18、19、25;捲動後小標題 PM 11/05 iPhone 實機確認希臘文、德文完整(模擬器 iOS 26.5 捲動後不顯示小標題,無法代驗);與 App-u 譯法不同,送審後統一)。✅ 詳細頁:iOS 刪除+編輯收進「…」選單(DiveLogDetailView.swift,PM 11/05 指示;15、16;刪除路徑 PM 11/05 iPhone 實機確認正常)。✅ sheet 標題:PM 11/05 同意 iOS「取消」「儲存」改 ✕/✓ 圖示(✓ 為 iOS 26 .confirm 強調樣式,HIG〈Toolbars〉);希臘文「Νέα κατάδυση」「Επεξεργασία κατάδυσης」完整(20、23)
介面用色不符家族強調色原則(2026-11-05) 資料數值與圖示用了強調色或寫死色:列表深度數字與左側分隔線(DiveRowView.swift:56 等)、詳細頁統計格深度 .accentColor/時間 .orange/水溫 .cyan(DiveLogDetailView.swift)、地圖潛點卡片同三色(DiveSiteSheetView.swift)、氣體標籤淡藍底;地圖未選中圖釘與選中同為 systemBlue(DiveSiteAnnotation.swift)。剖面圖藍色維持(PM 刻意例外) 顏色意義不一致(HIG〈Color〉「Avoid using the same color to mean different things」) ⏸ v1.4 送審後改(PM 11/05 定稿:家族 decisions/2026-11-05_App介面強調色使用原則.md,ccea63d,§四待改清單);強調色維持系統藍(品牌薄荷綠白底 2.05:1,PM 11/05 不採用)
macOS 日誌分頁工具列位置亂跳(PM 2026-11-15 Mac 實機,深色,v1.4) 列表模式有選取潛水時,列表工具列(搜尋、篩選、日曆+新增)在左欄標題「Logbook」右側,詳細欄另有刪除、Edit(截圖 01、04);沒選取時,同一組按鈕跑到視窗最右上角(詳細欄右端,03);切到日曆模式,列表+新增也在視窗最右上角(02)。截圖:docs/screenshots/2026-11-15_macOS-toolbar-jump/。相關宣告(僅定位,原因未查):LogbookContainerView.swift:34-53(.automatic/.primaryAction)、DiveLogListView.swift:359-360(macOS .primaryAction)、DiveLogDetailView.swift:274-306 按鈕位置隨選取狀態改變,使用者找不到 下一版修正(PM 11/15:記下來,下次更新 What’s New 寫「修正」);開工時依開工三欄④先寫問題陳述與三個假設,不盲改
環境欄位無「未記錄」:解析器皆不填 environmentType,每筆預設 seawater DiveLog.swift:108;舊資料無法分辨預設值與真實選擇 淡水/高海拔紀錄顯示為海水 ✅ v1.4 A1 已實作(未發布;2026-10-26,docs/decisions/D-2026-10-26-環境欄位未記錄.md);舊資料不回溯

v1.0 已知限制

項目 說明 影響 排定版本
廣告在 macOS 無法顯示 GoogleMobileAds SDK 不支援 macOS 可接受,設計選擇 不排入
macOS 無 Premium/IAP 購買選項 2026-07-14 移除:macOS 本來就無廣告可移除,且未確認 iOS/macOS 是否為 Universal Purchase(同一 App Store Connect app 記錄),保留購買選項對 macOS-only 用戶形同賣一個沒有效果的商品。SettingsView.swift 的 Premium Section、PremiumUpgradeSheet 呼叫、restorePurchases() 均已 #if os(iOS) 包住,macOS 直接當免費版上架 已修復,macOS 現在是純免費版 已解決
ATMOS UDDF 假預設氣瓶資料 ATMOS 匯出 UDDF 時,若無實際記錄,仍填入預設值(200/50 bar、110L)。JD2 只負責單位換算,值的正確性由使用者自行確認,匯入後可手動清除。 低,使用者知情即可 不排入(資料來源問題)
地圖在 VoiceOver 下無法縮放/平移/展開聚合/選其他 pin 2026-07-27 真機 VoiceOver 完整走查發現(WCAG_2.1_AA_AUDIT_CHECKLIST.md 附錄 4/5)。查過 DiveMapRepresentable.swift/DiveSiteAnnotation.swift 沒有設定錯誤或手勢衝突,判斷為 MapKit 在 VoiceOver 下的固有限制(雙指縮放手勢被 VoiceOver 自己接管)。需要獨立的縮放按鈕+逐一切換 pin 機制才能解,範圍明確但工程量中等,非小修。 中,視障使用者無法用地圖瀏覽潛點,但日誌列表可完全 VoiceOver 操作作為替代路徑 排入下一版 backlog(地圖無障礙改造)
DiveRowView.dateBlock 月/年標籤 Dark Mode 對比不足(已修) 2026-07-27 用模擬器截圖+Python/PIL 實測 WCAG 對比公式(非目測)掃過 Dark Mode 主要畫面,抓到日誌列表卡片的「7月/2026」用系統 .secondary 只有 3.91:1(低於 4.5:1 門檻),是 2026-06-01 稽核修 DetailRow/StatsHeader 等處時漏掉的同款元件。已改用 Color.accessibleSecondary,複測 9.25:1 通過。同一行的「26°C」水溫標籤有一併複查,實測 5.20:1 本來就過,沒有動。 已解決 已解決
DiveReplayEngine.replay() 整趟潛水只吃單一 GasMix,不支援依時間切換氣體 家族總指揮 2026-08-16 查證回報:技術潛水常見操作(底部背氣、上升到減壓停留切換高氧氣體如 EAN50)會讓重放引擎在換氣後繼續用底氣組成計算——Interactive Tissue Loading/Ceiling/NDL 在換氣後那段顯示的數字是用錯誤氣體算出來的,不是精細度不足,是答案錯誤。DiveImportKit v0.4.2 新增的 gasSwitches(換氣序列,存在 importExtras)目前沒有消費端讀取,正是因為這個限制。docs/APPSTORE_COPY.md 第25/34/138/147行宣稱支援「advanced technical diving」與 Trimix,未註明此限制,對技術潛水使用者(多氣體換氣是常態操作)現況宣稱不夠準確。 高(顯示錯誤的減壓分析數字,非邊緣案例),但屬既有架構限制非本輪改動引入 待 PM 排優先序:(a) 若要修,需 Logbook 自行讀取 gasSwitches 並讓分析路徑依時間軸切換氣體(新功能,工程量不小);(b) 若暫不修,行銷文案應加註但書或調整措辭範圍;(c) 短期可比照舊 trimix 免責聲明模式,偵測到 gasSwitches 非空時顯示提示

技術雷區(維護時注意)

SwiftData Schema 變更

git 操作

xcstrings 空 key

語言切換不生效(String(localized:) vs languageManager.localized(_:))— 反覆發生,寫新 View 時注意

AdMob SDK v11 API 改名

xcodebuild test / TEST_HOST(2026-07-17 修復)

Supabase 專案(非本專案技術棧,勿誤認為有整合)


v1.1 功能規劃

⚠️ 本節僅列清單,完整設計說明與最新決策一律以 V1_1_BACKLOG.md 為準(此檔案曾在 2026-06-07~07-14 間漏未同步 3 項技術債,避免重蹈覆轍,此後不在兩處維護同一份細節)。

狀態(2026-07-17):13/14 項完工,僅 #9/#10 因 PM 確認不需要而終止規劃。

技術債(V1_1_BACKLOG.md #1–3):

功能擴充(V1_1_BACKLOG.md #4–14):


v1.0 修復的舊問題(供參考)

問題 修復 commit
macOS DiveLogEditSheet O₂ 重複顯示 56dc1a3
navigationTitle(“”) 產生空字串 key 49abcc9
部署目標不統一(17.6 / 26.5 混雜) deda6ca
AdMob SDK v11 API 不相容 656a246
PremiumAwareAdBanner 壓縮上方內容 656a246