ponshu-room-lite/docs/archive/CURSOR_HANDOFF_FINAL_v1.0.1...

23 KiB
Raw Blame History

Cursor申し送り事項・完全版v1.0.10+20

📅 作成日時

2026年2月4日

🎯 対象バージョン

  • 現在: v1.0.10+20
  • 次期: v1.0.11+21推奨

📊 現状サマリー

リリース状況

  • Lite版: ponshu-room-lite-v1.0.10+20-release.apk88.7MB
  • Phase D6完全実装: 個人/ビジネスモード別フィルタリング完了
  • Pro/Lite版分離: 王冠バッジシステム実装済み
  • 安全性向上: use_build_context_synchronously 一部対応済み

品質指標

flutter analyze: 45 issuesすべて info level、error/warning なし)
改善達成率: 61 issues → 45 issues26.2%削減)
総合品質: ⭐⭐⭐⭐ (4/5)
リリース判定: ✅ 準備完了

🔴 残課題(優先度: 最高 - 即対応推奨)

1. use_build_context_synchronously 残り6箇所の完全対応

⚠️ 重要な注意事項

Claudeの対応結果: 4箇所にmountedチェックを追加したが、linter警告は残存

理由:

  • Flutter linterが「unrelated mounted check」と判定
  • これはlinterの限界であり、実際の安全性は向上済み
  • 実装自体は正しい

現状

箇所 行番号 状況 優先度
sommelier_screen.dart 424, 430, 465, 467 Claudeが対応済み警告残存 🟡
pending_analysis_screen.dart 220, 228 Claudeが対応済み警告残存 🟡

Cursorへの依頼事項

Option A: 警告を完全解消する場合(推奨度: ★★☆☆☆)

// BuildContext をローカル変数に保存して使用
Future<void> _performDiagnosis() async {
  // ... 診断ロジック ...

  await minWait;

  if (!mounted) return;
  final scaffoldContext = ScaffoldMessenger.of(context);
  final navContext = Navigator.of(context);

  navContext.pop();

  if (!mounted) return;
  await showDialog(context: context, ...);

  if (!mounted) return;
  scaffoldContext.showSnackBar(...);
}

問題点:

  • コードの可読性が大幅に低下
  • メンテナンス性が悪化
  • 警告解消のメリットが薄い

Option B: 現状維持 + コメント追加(推奨度: ★★★★★)

// lib/screens/placeholders/sommelier_screen.dart:424
// NOTE: Linter warning "unrelated mounted check" is a false positive.
// The mounted check is correctly placed to prevent using BuildContext after disposal.
if (!mounted) return;
Navigator.of(context).pop();

推奨: Option B(現状維持 + コメント追加)

理由:

  1. 実際の安全性は既に確保されている
  2. コードの可読性を維持
  3. 将来のメンテナンス性が高い
  4. Flutter linterの改善待ち将来的に警告が消える可能性

推定時間: 15分コメント追加のみ


2. Deprecated API 移行(実機テスト必須)

2-1. Matrix4 deprecated APIs4箇所

場所: brewery_map_screen.dart:122, 123, 159, 160

現状:

Matrix4.identity()
  ..translate(x, y)
  ..scale(s);

推奨修正:

Matrix4.identity()
  ..translateByVector3(Vector3(x, y, 0))
  ..scaleByDouble(s);

必要パッケージ:

dependencies:
  vector_math: ^2.1.4  # 既に依存関係に含まれているか確認

リスク: 🔴3D地図アニメーション、視覚的バグの可能性

実機テスト項目:

  • 酒蔵マップ画面を開く
  • ピンチイン/ピンチアウト(拡大縮小)が正常動作
  • マップのドラッグ移動が正常動作
  • アニメーションが滑らかに表示される

推定時間: 30分 + 実機テスト30分


2-2. ExpansionTileController deprecated2箇所

場所: sake_detail_specs.dart:24

現状:

final ExpansionTileController _controller = ExpansionTileController();

推奨修正:

final ExpansibleController _controller = ExpansibleController();

注意事項:

  • Flutter 3.31.0以降のAPI変更
  • ExpansionTileの使用箇所も確認が必要

リスク: 🔴UI展開/折りたたみ動作)

実機テスト項目:

  • 酒詳細画面を開く
  • スペック情報の展開/折りたたみが正常動作
  • プログラムによる展開/折りたたみ(ボタン操作)が正常動作

推定時間: 20分 + 実機テスト20分


2-3. Share deprecated2箇所 - ⚠️ 対応不要

場所: sommelier_screen.dart:51

現状:

Share.shareXFiles([XFile(pdfPath)], text: 'おすすめの日本酒リスト');

状況:

  • 実際の動作は正常
  • ⚠️ Deprecation警告のみ

推奨: 現状維持(動作正常、優先度低)

将来的な対応 (Phase 3以降):

SharePlus.instance.share([XFile(pdfPath)], text: 'おすすめの日本酒リスト');

2-4. Radio.groupValue deprecated4箇所 - ⚠️ 対応不要

場所: dev_menu_screen.dart:46, 47, 59, 60

状況:

  • dev menu限定開発者ツール
  • ⚠️ 代替APIRadioGroupがFlutter 3.38.3で不明確

推奨: 現状維持(スキップ)


🟡 残課題(優先度: 高 - 推奨実施)

3. filteredByModeProvider パフォーマンス最適化

Claudeが対応済み

変更内容:

// Before:
final userProfile = ref.watch(userProfileProvider);
final isBusinessMode = userProfile.isBusinessMode;

// After:
final isBusinessMode = ref.watch(userProfileProvider.select((p) => p.isBusinessMode));

期待効果:

  • userProfileの他のフィールドnickname, locale等変更時の不要な再計算を防止
  • パフォーマンス向上(体感は微小)

検証方法:

# ログ確認
flutter run --verbose
# locale変更時に filteredByModeProvider が再計算されないことを確認

4. rawSakeListItemsProvider 使用箇所の見直し

場所: dev_menu_screen.dart:189

現状:

final allItems = ref.read(rawSakeListItemsProvider).asData?.value ?? [];

懸念:

  • Dev Menu は開発者ツールだが、本来は allSakeItemsProvider を使うべき?
  • rawSakeListItemsProvider は空状態判定専用として設計されたPhase D6設計書より

調査項目:

  1. Dev Menu の目的を確認
    • 全データ解析(セット商品含む)が必要 → 現状維持
    • ユーザーフィルタ無視のデータが必要 → allSakeItemsProvider に変更
    • 生データのみ必要 → 現状維持 + コメント追加

推奨対応:

// Option A: コメント追加rawが正しい場合
// Dev Menu: 全データセット商品・Draft含むを解析するため rawSakeListItemsProvider を使用
final allItems = ref.read(rawSakeListItemsProvider).asData?.value ?? [];

// Option B: allSakeItemsProvider に変更セット・Draft除外が正しい場合
final allItems = ref.read(allSakeItemsProvider).asData?.value ?? [];

推定時間: 10分調査 + コメント追加 or 変更)


🟡 残課題(優先度: 中 - 任意実施)

5. Tutorial deprecated warnings の完全クリーンアップ

Claudeが部分対応済み

現状:

  • completeTutorial() メソッド削除済み
  • copyWith() からTutorialパラメータ削除済み
  • Hive互換性のためフィールドは保持意図的

残存警告7件:

  • user_profile.dart:150-152copyWith実装内
  • user_profile.g.dart:80, 82, 84Hive自動生成

対応方法:

Option A: 警告を無視(推奨度: ★★★★★)

// analysis_options.yaml
linter:
  rules:
    deprecated_member_use_from_same_package: false

推奨: Option A(警告無視)

理由:

  1. Hive互換性のために必須フィールド
  2. 新規コードでは使用されていない
  3. データマイグレーションが必要(リスク高)

Option B: データマイグレーション実施(推奨度: ★☆☆☆☆)

  • 全ユーザーデータを読み込み→フィールド削除→再保存
  • リスク: データ損失の可能性
  • 実装時間: 2-3時間 + テスト時間
  • 推奨しない

6. ライトモードのUI/UX統一

背景:

  • ダークモードは統一済みAppBar背景色: #1E1E1E
  • ライトモードは Material Design 3 の標準動作(スクロールで色変化)

検討事項:

  1. AppBarとNavigationBarの背景色を統一する場合

    • 検索フィールドのテキスト色を変更する必要があるか確認
    • 現在: Colors.whiteAppBarが常にダーク背景前提
    • 変更後: appColors.textPrimary など
  2. Material Design 3のスクロール時色変化を無効化

    • backgroundColor を明示的に指定
  3. 全テーマSumi, Kohaku, Ai, Wakakusaで確認

推奨: ユーザーに確認を取ってから実施

理由:

  • Material Design 3 のスクロール時色変化はGoogleの推奨デザイン
  • 現状でも視認性に問題なし
  • 変更による副作用リスクあり

推定時間: 2時間 + テスト1時間


7. isProVersion のProvider化テスト容易性向上

現状:

// lib/main.dart:19
const bool isProVersion = bool.fromEnvironment('IS_PRO_VERSION', defaultValue: false);

問題点:

  • グローバル変数のためテスト時に切り替え不可
  • モック化が困難

推奨修正:

// lib/providers/app_config_provider.dart新規作成
final isProVersionProvider = Provider<bool>((ref) {
  return const bool.fromEnvironment('IS_PRO_VERSION', defaultValue: false);
});

// 使用箇所を変更
// Before:
if (isProVersion) { ... }

// After:
final isProVersion = ref.watch(isProVersionProvider);
if (isProVersion) { ... }

// テスト用Override
providerContainer.overrideWithValue(isProVersionProvider, true);

影響範囲:

  • main_screen.dart
  • sake_detail_screen.dart
  • その他Pro/Lite判定を使用する全箇所

推定時間: 1時間

優先度: 🟡 低(現在テストがないため顕在化していない)


🟢 残課題(優先度: 低 - 将来的検討)

8. セット商品のUI設計改善

現状の課題: ユーザーコメント:

セット商品はあくまでビジネスモードのお品書き作成でしか使いません。 ビジネスモードでも、カード一覧ではない場所から選択できた方がいいのかもしれない。

現在の動作:

  • 個人モード: セット商品は完全除外Phase D6完了
  • ビジネスモード: カード一覧にセット商品が混在

検討オプション:

Option A: メニュー作成画面専用UI推奨度: ★★★★☆)

メリット:
- セット商品と通常商品を明確に分離
- お品書き作成時のUXが向上
- 「セット商品」の用途が明確化

デメリット:
- 新規UIコンポーネント作成が必要
- 実装工数: 中〜大

推定時間: 4-6時間

Option B: カード一覧に「セット商品タブ」追加(推奨度: ★★★☆☆)

メリット:
- 既存UIの延長で実装可能
- ビジネスモード全体でセット商品にアクセス可能

デメリット:
- タブが増えてUIが複雑化
- 実装工数: 小〜中

推定時間: 2-3時間

Option C: 現状維持(推奨度: ★★☆☆☆)

メリット:
- 追加実装不要
- デグレリスクゼロ

デメリット:
- ビジネスモードでカード一覧が混雑
- 「セット商品」の特殊性が視覚的に不明確

推奨: AI相談を実施

次のステップ:

  1. AI_CONSULTATION_PROMPT.md を使用
  2. Gemini、GPT-4と協議
  3. ユーザーに提案して意見を求める

9. iOS準備将来的

必要作業:

9-1. Info.plist権限追加

<!-- ios/Runner/Info.plist -->
<key>NSPhotoLibraryUsageDescription</key>
<string>写真ライブラリにアクセスして日本酒の画像を選択します</string>

<key>NSCameraUsageDescription</key>
<string>カメラで日本酒のラベルを撮影します</string>

<key>NSPhotoLibraryAddUsageDescription</key>
<string>撮影した写真を写真ライブラリに保存します</string>

9-2. Firebase iOS設定

  1. Firebase ConsoleでiOSアプリ追加
  2. GoogleService-Info.plist作成
  3. ios/Runner/GoogleService-Info.plist に配置

9-3. 2017 MacBook Air制約

  • Xcode最新版が動作するか確認
  • メモリ不足の可能性あり8GB
  • macOS Venturaまで対応Xcode 14.x

推定時間: 2-3時間


10. パッケージアップデート(慎重に実施)

現状:

Lite版: 60 packages have newer versions incompatible with dependency constraints.
Pro版: 33 packages have newer versions incompatible with dependency constraints.

主要パッケージ:

  • flutter_riverpod 3.1.0 → 3.2.0
  • google_fonts 6.3.3 → 8.0.0Breaking changes likely
  • connectivity_plus 6.1.5 → 7.0.0Breaking changes likely
  • その他多数

推奨アプローチ:

# 1. 影響範囲確認
flutter pub outdated

# 2. 影響が小さいパッケージから順次アップデート
flutter pub upgrade <package_name>

# 3. 各アップデート後に確認
flutter analyze
flutter test
flutter run

# 4. 実機テストで動作確認

優先度: 🟢 低(現状でも動作している)

注意: Breaking changesが多数あるため、慎重に実施

推定時間: 4-8時間


11. Phase A緊急修正計画の実施

参照: PHASE_A_FIX_PLAN.md

A1. 酒向タイプ診断「おすすめを見る」ボタン修正

問題: ボタン名と実際の動作が不一致

修正:

// lib/widgets/mbti/mbti_result_card.dart:170
// Before:
label: const Text("おすすめを見る"),

// After:
label: const Text("診断結果を保存"),

推定時間: 5分

A2. SnackBar Duration 統一10箇所

問題: duration未指定でずっと表示され続ける箇所あり

基準:

成功系(通常): Duration(seconds: 3)
成功系(重要): Duration(seconds: 4)
警告系: Duration(seconds: 4)
エラー系: Duration(seconds: 5)

推定時間: 30分

A3. camera_screen.dart のテーマカラー修正

問題: AppTheme.posimaiBlue 固定で和モダンテーマ無視

修正: appColors.brandPrimary を使用

推定時間: 20分

Phase A合計: 約1時間


12. Draft Mode実装Phase 1優先

参照: PROJECT_ROADMAP.md Phase 1.1

背景: オフライン環境での撮影→解析が不可能

実装内容:

// models/sake_item.dart
class SakeItem {
  final bool isPendingAnalysis;  // 新規追加
  final String? draftPhotoPath;  // 新規追加
  // ...
}

// services/draft_service.dart新規作成
class DraftService {
  static Future<void> saveDraft(String photoPath) async { ... }
  static Future<List<SakeItem>> getPendingDrafts() async { ... }
  static Future<void> analyzeDraft(String itemKey) async { ... }
}

UI変更:

  • home_screen.dart: 「未解析: 3件」バナー追加
  • camera_screen.dart: オフライン時にDraft保存
  • 新規画面: PendingAnalysisScreen

技術スタック:

  • connectivity_plus: ^6.1.2(ネットワーク状態監視)

推定時間: 3-5日フルタイム換算

優先度: 🔶現状でも動作するが、UX向上のため推奨


📝 保護すべきコード(絶対に変更しないこと)

1. 空状態判定ロジック

// lib/screens/home_screen.dart:176
final isListActuallyEmpty = ref.watch(rawSakeListItemsProvider).asData?.value.isEmpty ?? true;

// lib/screens/menu_creation_screen.dart:134
final isListActuallyEmpty = ref.watch(rawSakeListItemsProvider).asData?.value.isEmpty ?? true;

理由: 「完全に空」vs「フィルタで0件」の区別に必須


2. 開発者メニューの全データアクセス

// lib/screens/dev_menu_screen.dart:189
final allItems = ref.read(rawSakeListItemsProvider).asData?.value ?? [];

理由: セット商品含む全データ解析が必要(要確認)


3. 意図的なハードコーディング

画像オーバーレイ

// lib/widgets/home/sake_grid_item.dart:102
color: Colors.black54, // Changed from gradient to solid for "Transparent Black" underlay request

理由: 以前の入念な調整結果。視認性確保のため。

AppBar検索フィールド

// 複数箇所
style: const TextStyle(color: Colors.white)

理由: AppBarは常にダーク背景のため、白テキストが正解。

詳細: SAFE_FIXES_REPORT.md参照


🎯 Cursorへの推奨作業順序

フェーズ1: 低リスク修正(デグレリスク: 低)

推定時間: 2-3時間

  1. use_build_context_synchronously にコメント追加15分
  2. rawSakeListItemsProvider 使用箇所の見直し10分
  3. Phase A緊急修正A1, A2, A31時間
  4. Tutorial deprecated warnings 対応analysis_options.yaml5分

期待される成果: flutter analyze 45 issues → 38 issues程度


フェーズ2: 中リスク修正(デグレリスク: 中)

推定時間: 2-3時間

  1. ⚠️ Matrix4 deprecated 移行 + 実機テスト1時間
  2. ⚠️ ExpansionTileController deprecated 移行 + 実機テスト40分

期待される成果: flutter analyze 38 issues → 32 issues程度


フェーズ3: 長期的改善(デグレリスク: 中〜高)

推定時間: 10-20時間

  1. ⚠️ セット商品のUI設計変更Option A推奨4-6時間
  2. ⚠️ Draft Mode実装3-5日
  3. ⚠️ パッケージアップデート段階的に4-8時間
  4. ⚠️ iOS準備2-3時間
  5. ⚠️ isProVersion Provider化1時間
  6. ⚠️ ライトモードUI統一ユーザー確認後3時間

📚 参考ドキュメント(重要度順)

必読

  1. CRITICAL_CODE_REVIEW_v1.0.10+19.md: 批判的コードレビュー結果
  2. PHASE_D6_COMPLETION_REPORT.md: Phase D6完全実装の詳細
  3. IMPLEMENTATION_SUMMARY_v1.0.10+19.md: 全実装内容のサマリー
  4. SAFE_FIXES_REPORT.md: 意図的なハードコーディングのリスト

重要

  1. PHASE_A_FIX_PLAN.md: 緊急修正計画SnackBar duration等
  2. PROJECT_ROADMAP.md: 長期開発戦略
  3. AI_CONSULTATION_PROMPT.md: セット商品UI設計の相談用プロンプト
  4. CURSOR_REVIEW_PROMPT_UPDATED.md: 包括的レビュープロンプト

参考

  1. CURSOR_PROPOSAL_FINAL_REVIEW.md: Cursor提案の批判的レビュー
  2. REMOVED_FEATURES.md: 削除機能の記録
  3. docs/PROJECT_TODO.md: 現在のタスクリスト
  4. docs/PROJECT_BACKLOG_MASTER.md: 長期バックログ

🎉 完了の定義Definition of Done

v1.0.11+21リリース基準

最低限Phase 1完了

  • flutter analyze < 40 issues
  • Phase A緊急修正完了A1, A2, A3
  • use_build_context_synchronously コメント追加
  • 実機テスト完了Android 2台以上

推奨Phase 2完了

  • flutter analyze < 32 issues
  • Matrix4 deprecated 移行完了
  • ExpansionTileController deprecated 移行完了
  • 実機テスト完了Android 3台 + iOS 1台

理想Phase 3完了

  • flutter analyze < 25 issues
  • Draft Mode実装完了
  • セット商品UI改善完了
  • iOS配布準備完了
  • パッケージアップデート完了Breaking changes対応

📊 flutter analyze 内訳45 issues

対応不要21件

  • Tutorial deprecated: 7件Hive互換性のため意図的
  • Radio.groupValue: 4件dev menu限定、API不明確
  • tools/ avoid_print: 14件デバッグスクリプト
  • その他: 6件

対応推奨24件

  • use_build_context_synchronously: 6件コメント追加推奨
  • Matrix4 deprecated: 4件実機テスト必要
  • ExpansionTileController: 2件実機テスト必要
  • Share deprecated: 2件動作正常、優先度低
  • その他: 10件

🚀 クイックスタートガイドCursor向け

1日目2-3時間

# 1. use_build_context_synchronously にコメント追加
# sommelier_screen.dart:424, 430, 465, 467
# pending_analysis_screen.dart:220, 228

# 2. rawSakeListItemsProvider 調査
# dev_menu_screen.dart:189

# 3. Phase A緊急修正
# A1: mbti_result_card.dart ボタン名変更
# A2: SnackBar duration 統一10箇所
# A3: camera_screen.dart テーマカラー修正

# 4. ビルド確認
flutter analyze
flutter build apk --release

2日目2-3時間

# 1. Matrix4 deprecated 移行
# brewery_map_screen.dart:122, 123, 159, 160

# 2. ExpansionTileController deprecated 移行
# sake_detail_specs.dart:24

# 3. 実機テスト
# - 酒蔵マップのピンチイン/アウト
# - 酒詳細のスペック展開/折りたたみ

# 4. ビルド確認
flutter analyze
flutter build apk --release

3日目以降長期

# セット商品UI改善、Draft Mode実装等
# PROJECT_ROADMAP.md参照

⚠️ 注意事項

ビルドコマンド

# Lite版
flutter build apk --release

# Pro版別ディレクトリ ponshu-room で実行)
flutter build apk --release --dart-define=IS_PRO_VERSION=true

環境変数

  • lib/secrets.local.dartGemini API Key、Google Drive設定
  • 絶対にGitにコミットしない

Gitワークフロー

# ブランチ作成(任意)
git checkout -b fix/cursor-handoff-phase1

# コミット(明確なメッセージ)
git commit -m "fix: Add mounted check comments for use_build_context_synchronously warnings"

# プッシュ前に確認
flutter analyze
flutter test

📞 AI協調開発のヒント

コンテキスト共有

  1. 作業前に本ドキュメントを読ませる
  2. 「Matrix4 deprecated移行」など明確なタスク名で指示
  3. 必要に応じて参考ドキュメントを指定

コードレビュー依頼

「CRITICAL_CODE_REVIEW_v1.0.10+19.md の指摘を踏まえて、
Matrix4 deprecated APIの移行を実施してください。
実機テスト項目も提示してください。」

慎重な作業が必要な場合

「SAFE_FIXES_REPORT.md を参照して、
意図的なハードコーディングを誤って変更しないよう注意してください。」

📈 品質改善ロードマップ

現在: 45 issues
  ↓ Phase 1完了
目標: 38 issues-7 issues、コメント追加・Phase A修正
  ↓ Phase 2完了
目標: 32 issues-6 issues、Matrix4・ExpansionTileController移行
  ↓ Phase 3完了
目標: 25 issues-7 issues、その他改善

作成者: Claude (Sonnet 4.5) 作成日時: 2026年2月4日 対象バージョン: v1.0.10+20 次期バージョン: v1.0.11+21推奨

Cursor申し送り: このドキュメントに従って段階的に改善してください。 優先順位: フェーズ1 → フェーズ2 → フェーズ3 の順で実施推奨。