# さけのわAPI連携ドキュメント

## 概要
Ponshu Room Liteはさけのわ（Sakenowa）APIを活用し、日本酒ランキング・ブランド情報・フレーバーチャートを取得しています。

---

## API エンドポイント

| エンドポイント | 説明 | 更新頻度 |
|:---------------|:-----|:---------|
| `/rankings` | TOP100ランキング | 毎日 |
| `/brands` | 銘柄マスタ（16,000件以上） | 週次 |
| `/flavor-charts` | 6軸フレーバーチャート | 週次 |

---

## データモデル

### SakenowaRanking
```dart
class SakenowaRanking {
  final int rank;       // 順位
  final String brandId; // 銘柄ID
}
```

### SakenowaBrand
```dart
class SakenowaBrand {
  final String id;    // 銘柄ID
  final String name;  // 銘柄名
}
```

### SakenowaFlavorChart
```dart
class SakenowaFlavorChart {
  final String brandId;
  final double f1;  // 華やか (0-1)
  final double f2;  // 芳醇
  final double f3;  // 重厚
  final double f4;  // 穏やか
  final double f5;  // 軽快
  final double f6;  // ドライ
}
```

---

## Riverpodプロバイダー

```dart
// lib/providers/sakenowa_providers.dart
final sakenowaRankingsProvider = FutureProvider<List<SakenowaRanking>>();
final sakenowaBrandsProvider = FutureProvider<List<SakenowaBrand>>();
final sakenowaFlavorChartsProvider = FutureProvider<List<SakenowaFlavorChart>>();
```

---

## 実装済み機能

### 1. ソムリエ画面
- **SakenowaNewRecommendationSection**: コサイン類似度で未飲銘柄を推薦
- **SakenowaRankingSection**: 3Dカルーセルでランキング表示、既飲ハイライト+MBTI相性

### 2. MBTI相性計算
```dart
// 6軸フレーバー → 5軸五味へのマッピング
f1(華やか) → aroma
f2(芳醇)+f4(穏やか) → sweetness
f3(重厚) → body
f5(軽快) → acidity
f6(ドライ) → bitterness
```

---

## 未実装/改善予定

| 項目 | 状態 |
|:-----|:-----|
| カード詳細画面でのさけのわ連携おすすめ | ❌ 未実装 |
| ランキングカードから詳細画面遷移 | ❌ 未実装 |
| オフラインキャッシュ | ✅ 実装済み |

---

## 帰属表示
データ提供: さけのわ (https://sakenowa.com)