jrshikoku/docs/refactor-audit/10-refactor-roadmap.md

Refactor Roadmap

全面書き換えではなく、配信互換性・品質ゲート・データ境界を先に作り、機能を止めずに段階移行する。再検証で直近EAS Build成功を確認したため、CNG全面再構築ではなく、runtimeVersionとactive channelの安全化をPhase 0へ引き上げた。

Phase 0 — 安全網

内容

• Sentry auth tokenのrevoke/rotate、Maps key制限、Push Token/URL/log/Clipboard redaction。
• 現行build/profile/channel/runtime matrixを保存し、Native変更時のruntime更新条件とOTA rollbackを決定。
• typecheck script、lint/test runnerの最小導入方針、PR gate。
• npx expo-doctor / expo install --check結果をCI artifact化。現在のpatch mismatchはbaselineとして許容し、依存整合PR後にblocking化。
• Web export、patch-package、clean installの確認。
• 主要な既存挙動（深夜時刻、tab切替、現在位置）の手動smoke checklist。
• README/AGENTS提案を現行構成に同期。

完了条件

• secret incidentが閉じられ、再出力防止が確認できる。
• PRでtsc・Web exportと、段階導入したlint/unit/doctor/install-checkが実行される。既知のDoctor失敗は理由付きbaselineで、新規悪化を検出する。
• 既存コードの機能変更なしで基準値が記録される。

効果: 大 / コスト: 小〜中 / 破壊リスク: 小 / 将来価値: 大

Phase 1 — API / Error / State境界

内容

• raw fetch inventoryを完成させ、共通clientの適用対象を決める。
• status/timeout/Abort/parse/schema/source/fetchedAt/error taxonomyを統一。
• useCurrentTrainの二重初期fetch、in-flight dedupe、request sequence、stale response防止。
• useTrainDelayData effect依存バグの修正をfixtureと一緒に行う。
• Unyohub/Elesite/Bus/Widget/Nativeのcache TTLとownerを定義。
• ErrorBoundaryとuser-safe error state。

完了条件

• 主要endpointが「どこから」「いつ」「何件」「なぜ失敗」をSentryで追える。
• 同時pollingが一つになるか、例外に理由がある。
• HTTP/timeout/abort/schema errorをテストで区別できる。

効果: 非常に大 / コスト: 中 / 破壊リスク: 中 / 将来価値: 大

Phase 2 — Router / Screenの契約化

内容

• DeepLinkIntent parser、ready queue、cancel、priorityを一箇所へ寄せる。
• global navigation ref/350ms timeoutのstate machineを文書化し、aa6e51c、e5c90f6、cffbeca、cb6930aをprotected behaviorとしてtransition testを追加。
• tab、back、gesture、modal、rotation、WebView保持を固定する。
• 変更頻度の高い列車詳細・駅時刻表からcontainer/hook/pure viewを分離。
• ndViewは行数でなくdata adapter、timer scheduler、DOM patch、view wrapperのseamで分割。

完了条件

• deep link cold/warm、notification競合、Android backが自動/手動matrixで確認できる。
• 1画面の通信・domain変換・表示を別々にテストできる。

効果: 大 / コスト: 中〜大 / 破壊リスク: 大 / 将来価値: 大

Phase 3 — Domain Model統合

内容

• physical station / station stop / line namespaceを導入。
• M12、同名駅、枝番、FeliCa numeric IDを別namespaceでfixture化。
• TrainIdentity(serviceDate, trainNumber, variant)を導入。
• serviceDate（JST、04:00境界）、serviceMinute、臨時運転日、運休/遅延をtyped model化。
• TS/JSON/mock/WebView/APIをcanonical adapterへ接続し、元データとsource metadataを保持。

完了条件

• 駅/列車/時間のdomain testsがあり、既存画面の結果がfixtureで比較できる。
• API/駅DB統合時にlegacy keyからcanonical keyへ変換できる。

効果: 非常に大 / コスト: 大 / 破壊リスク: 大 / 将来価値: 非常に大

Phase 4 — Native整理

内容

• FeliCa TS/iOS/Android capability/error/lifecycle契約を一致させる。
• App Group、FeliCa entitlement、Widget target version、permissionを実機検証。
• Live ActivityとAndroid Foreground Serviceの違いをAPIに表現し、start/update/end結果を返す。
• RN repositoryとNative/Widgetのpolling重複を縮小。
• dangerous config pluginにmarker/生成後assert/fixtureを追加。

完了条件

• iOS/Android Development Build smokeが再現可能。
• clean prebuild相当でNative設定が生成され、root generated treeへの手編集に依存しない。

効果: 大 / コスト: 大 / 破壊リスク: 大 / 将来価値: 大

Phase 5 — CI/CD・Release自動化

内容

• activeなbeta7.1/gmarket、production7.1/geekbuying等とinstalled binaryの対応を確認してから、EAS profileをdevelopment/preview/productionへ意味ベースで整理。
• 旧channelを即rename/deleteせず、凍結/移行/rollback手順を作る。
• build number / version / runtime / update channelのcheck。
• EAS WorkflowsまたはGitHub ActionsでPR gate、internal build、submitの責務を分ける。
• Sentry release/source map、EAS build/update IDを連携。

完了条件

• 新規開発者がDevelopment Build→Preview→Productionを再現できる。
• Native変更だけが高コストbuildを要求し、JS変更は安全なOTA基準で判定できる。

効果: 大 / コスト: 中 / 破壊リスク: 中〜大 / 将来価値: 大

Phase 6 — 最適化

内容

• 実測に基づくList virtualization、rerender削減、WebView script負荷削減。
• Context value memoizationとglobal providerの遅延mount。
• image/cache/memory/animationの調整。
• 未使用dependency、legacy storage、icon/sheet重複を一件ずつ整理。
• Expo Router / TanStack Query / Zod等は、Phase 1〜3の境界ができた後に限定採用を再判断。

効果: 中 / コスト: 中〜大 / 破壊リスク: 中 / 将来価値: 中

30分〜半日でできるQuick Wins（今回は未実装）

• READMEのSDK 52→55、npm run webの誤記、Node/Dev Build手順を修正。
• 現行build/profile/channel/runtime matrixをread-only EAS CLI出力から作り、Native変更/OTA可否のchecklistを置く。
• typecheck scriptを追加し、CI候補のコマンドを固定。
• UpdateAsyncはExpo既定checkとの重複を決定してから、promiseをawait/returnする小修正と回帰確認。
• useTrainDelayDataのeffect依存を修正する前にfixtureを作り、修正PRを小さくする。
• Push tokenをlogger、URL query、Clipboard説明から外す方針を決め、redaction testを追加。
• NotificationSettingsでresponse.ok/errorを扱う設計メモとtestを作る。
• checkDiagramがtracked fileを書き換えることをREADME/CIから明示し、temp出力へ移す別PRを作る。
• staleなeject script、index.js/index.ts、direct-use未確認package/import、backup fileを削除せずinventoryへ登録。
• endpoint/polling matrixを更新し、各timerのowner・停止条件を1表にする。
• 既存のstation/time/position境界テスト用の入力fixtureだけを追加する。

やらない方がよいリファクタ

• Expo Routerへの全面移行: 現在のReact Navigationはtab保持、WebView、lifecycle workaroundと結合している。route宣言を変えてもデータ・timer問題は解決しない。
• screens/freeze/detach/350ms/Android tab patchの個別削除: Git履歴でクラッシュ・WebView/tab安定化の意図を確認した。4 commitのprotected behaviorをmatrixで置換できるまで触らない。
• Contextの一括削除/TanStack Queryへの一括移行: server stateの契約が未整理で、cache・notification・WebView・Nativeを別問題のまま移し替えるだけになる。
• ndView.tsx/webViewInjectjavascript.tsのformat-only分割: 公式サイトDOMとの互換、1秒timer、MutationObserver、過去クラッシュ対策を失いやすい。seamとfixtureを先に作る。
• 駅番号の一括置換・再命名: M12、同名駅、運行情報・位置APIのlegacy contractを壊す。canonical IDを併設して段階移行する。
• ios//android/の直接修正: Git管理外の生成物なのでprebuildで消える。修正はconfig/plugin/module/targetへ移す。
• 全依存の最新版化: Doctor/install-check mismatchは解消候補だが、Navigation patch、Native module、Reanimated、Widgetの互換検証なしに更新しない。
• active channelの命名整理を先に行うこと: gmarket等へ既存7.2 binaryが接続している。audienceとrollbackを確認する前のrename/deleteは避ける。
• runtimeVersionだけを即変更すること: 方針変更は既存binaryへのUpdate到達性を変える。検証Buildと互換matrixを先に作る。
• 巨大ファイルを行数だけで分割: felicaStationMapや静的trainListはデータ資産であり、分割しても保守性は自動的に上がらない。
• UIデザインの一括変更: 今回の目的は構造監査であり、表示仕様を同時に変えると不具合の原因が追えない。

推奨する変更PRの粒度

1 PR = 1境界 + 1検証セット

例:
  time parser + service-day fixtures + unit tests
  current-position repository + dedupe tests
  FeliCa JS contract + iOS/Android capability smoke
  EAS profile docs + dry-run/check script

各PRは、変更対象、保持する既存挙動、実行した検証、未検証の実機条件、rollback方法を記録する。