ponshu-room-lite/EMERGENCY_IMAGE_REPAIR.md

# 🚨 緊急: 画像パス修復ガイド

**発生日**: 2026-01-22  
**影響**: バックアップ復元後に写真が見れなくなる  
**ステータス**: ✅ 修復ツール作成完了

---

## 📊 現状

### 一括圧縮の結果
```
圧縮: 59枚
スキップ: 17枚
エラー: 20枚 ← 🚨 これが問題
削減: 35.2MB
```

### バックアップ復元の結果
```
復元前: 一部の写真が見れない
復元後: 見えない写真がさらに増えた ← 🚨 悪化
```

---

## 🔍 問題の原因

### 1. 画像パスの不整合

**バックアップの仕組み**:
```
1. バックアップ作成時:
   imagePaths: ["/data/user/0/.../app_flutter/UUID_A.jpg"]
   
2. バックアップ復元時:
   - 画像ファイル: UUID_B.jpg でコピー（新しいUUID）
   - Hive: 古いパス("/data/user/0/.../UUID_A.jpg")のまま復元
   
3. 結果:
   - Hive: UUID_A.jpg を参照
   - 実際のファイル: UUID_B.jpg が存在
   - 画像が見れない ❌
```

### 2. 一括圧縮の20エラー

**考えられる原因**:
- ファイルが既に存在しない（パス不整合）
- ファイルが破損している
- 権限エラー

---

## ✅ 修復手順（必須）

### ステップ1: 画像パス診断

**操作**:
1. ソウル画面 → 右上の歯車アイコン
2. 「🔬 開発者メニュー」
3. **「🔍 画像パス診断」** をタップ

**結果の見方**:
```
総アイテム数: 96
問題のあるアイテム: 30 ← この数が重要
欠損ファイル: 45
```

### ステップ2: 画像パス修復

**操作**:
1. 開発者メニュー
2. **「🔧 画像パス修復」** をタップ
3. 確認ダイアログで「修復する」

**処理内容**:
```
1. Hiveの imagePaths を取得
2. 存在しないパスを検出
3. ファイル名で実際のファイルを照合
4. パスを更新
```

**結果の見方**:
```
修復したアイテム: 25
修復したパス: 40

✅ 画像パスを更新しました
```

### ステップ3: 写真の表示確認

**操作**:
1. ホーム画面に戻る
2. カード一覧を確認
3. 各カードの詳細画面を確認

**期待結果**:
- 修復されたカードの写真が表示される
- 修復できなかったカードは引き続き表示されない

---

## 📋 修復できないケース

### ケース1: ファイル自体が存在しない

**症状**:
```
修復したアイテム: 0
⚠️ 修復が必要なパスはありませんでした
```
→ しかし、写真は見れない

**原因**:
- 画像ファイルが物理的に削除された
- バックアップに画像が含まれていなかった

**対応**:
- その日本酒を**再撮影**
- または、削除して再登録

### ケース2: ファイル名が一致しない

**症状**:
```
⚠️ No match for: OLD_UUID.jpg (日本酒名)
```

**原因**:
- バックアップのファイル名と実際のファイル名が異なる

**対応**:
- 孤立ファイル削除（後述）を実行して確認
- 該当する日本酒を再撮影

---

## 🗑️ 孤立ファイル削除

### 目的
Hiveに参照されていない画像ファイルを削除してストレージを解放

### 操作
1. 開発者メニュー
2. **「🗑️ 孤立ファイル削除」** をタップ
3. 診断結果を確認
4. 確認ダイアログで「削除」

### 診断結果の見方
```
孤立ファイル: 15個
サイズ: 145.3MB

⚠️ これらのファイルを削除します
```

### 注意事項
⚠️ **削除したファイルは復元できません**

---

## 📊 ストレージの最終確認

### 手順
1. Androidの設定 → アプリ → ポンシュルーム → ストレージ
2. ストレージ使用量を確認

### 期待値（57枚の場合）

| 項目 | 現在 | 期待値 |
|------|------|--------|
| **アプリデータ** | 409MB | **11-15MB** |
| **削減量** | - | **約394MB** |

---

## 🎯 完全修復の流れ

### 最適な順序

```
1. 🔍 画像パス診断
   ↓
2. 🔧 画像パス修復
   ↓
3. 📱 写真の表示確認
   ↓
4. 🗑️ 孤立ファイル削除（オプション）
   ↓
5. 📊 ストレージ確認
```

---

## ⚠️ よくある質問

### Q1: 修復後も写真が見れない

**A**: 以下を確認してください:
1. ファイル自体が存在するか？
   - 開発者メニュー → 画像パス診断
2. 孤立ファイルがあるか？
   - 開発者メニュー → 孤立ファイル削除
3. 該当する日本酒を再撮影

### Q2: 一括圧縮で20エラー

**A**: 画像パス修復後に再実行してください:
1. 画像パス修復を実行
2. 写真の表示確認
3. 開発者メニュー → 既存画像を一括圧縮（再実行）

### Q3: バックアップ復元で悪化した

**A**: 今回の修復ツールで対応可能です:
- バックアップ復元 → 画像パス不整合
- 画像パス修復 → パスを正しく更新

### Q4: どの写真が見れないかわからない

**A**: カード一覧画面で確認:
- 写真が表示されていないカード = 問題あり
- グレーの背景 or エラーアイコン = ファイル不在

---

## 🔧 技術的な詳細

### 修復ツールの実装

**ファイル**:
- `lib/services/image_path_repair_service.dart` - 修復ロジック
- `lib/screens/dev_menu_screen.dart` - UI

**主要メソッド**:
```dart
// 診断
Future<(int, int, int)> diagnose()
// → (総アイテム, 問題あり, 欠損ファイル)

// 修復
Future<(int, int)> repair()
// → (修復アイテム, 修復パス)

// 孤立ファイル検出
Future<(int, int)> findOrphanedFiles()
// → (孤立ファイル数, サイズ)

// 孤立ファイル削除
Future<(int, int)> cleanOrphanedFiles()
// → (削除数, サイズ)
```

### 修復ロジック

```dart
1. Hiveの全SakeItemを取得
2. 各アイテムの imagePaths をチェック
3. 存在しないパスを検出
4. ファイル名で照合:
   - バックアップ: /old/path/UUID_A.jpg
   - 実際: /new/path/UUID_A.jpg
   - マッチング: ファイル名（UUID_A.jpg）で照合
5. パスを更新してHiveに保存
```

---

## 📝 今後の対策

### 1. バックアップ復元の改善（将来対応）

**現在の問題**:
- 画像パスが絶対パスで保存される
- 復元時にパスが不整合

**改善案**:
- 相対パスで保存
- 復元時にパスを自動更新

### 2. 一括圧縮の改善

**現在の問題**:
- 20エラーが発生

**改善案**:
- エラー時の詳細ログ
- リトライ機能
- エラーファイルのリスト出力

### 3. 画像ファイル管理の改善

**現在の問題**:
- 孤立ファイルが発生しやすい

**改善案**:
- 削除時に自動クリーンアップ
- 定期的な整合性チェック

---

**作成日**: 2026-01-22  
**作成者**: Cursor AI  
**優先度**: 🔴 Critical  
**次のアクション**: 画像パス診断 → 修復 → 確認