要件定義

1. プロジェクト概要

1.1 目的

ハンドドリップ (Pour over) の抽出を記録し、「この豆に一番合う抽出はどれか」を振り返るための個人ツール。

1.2 ゴール

• 自分が毎日のコーヒー抽出記録に使う実用ツール
• Modern Web 開発（Next.js App Router / RSC / Server Actions / TypeScript）の学習機会
• 将来的に他人にも開放可能なアーキテクチャで設計

1.3 対象ユーザー

• Phase 1: 開発者本人のみ（実質ベータ運用）
• Phase 2 以降: 他のコーヒー愛好家にも開放する可能性あり（Open registration 想定）

1.4 スコープ外

• エスプレッソ、フレンチプレス等、Pour over 以外の抽出方式
• Bluetooth スケール連携
• ソーシャル機能（豆推薦、フォロー等）

2. 機能要件

2.1 Phase 1 (MVP)

2.2 抽出記録のコアフロー

1. 豆を選ぶ → 同じ豆で最新の Brew があれば、パラメータと pour 計画を pre-fill
2. パラメータ入力（dose, water, water_temp, grind, dripper）
3. pour 計画を事前入力（投数 + 各投の water_g）
4. 「抽出開始」ボタン → タイマー開始
5. 経過時間表示。各注ぎに対し「+ pour」ボタンは計画配列のカーソルを次へ進めるだけ。water_g には計画値が自動セットされ、後で編集可
6. 「抽出終了」ボタン → 抽出時間記録
7. ★1-5 評価と flavor notes、メモを入力
8. 「保存」（Server Action）→ クライアント側で Brew 詳細または Bean 詳細へ遷移

2.2.1 状態管理 / UX 規約

• タイマー稼働中〜保存前の状態は client React state のみで保持する（localStorage / DB への永続化はしない）
• 抽出開始から保存までの間だけ beforeunload リスナを登録し、誤ってリロード / タブ閉じが発生したらブラウザ標準ダイアログで警告
• 単一画面（/brews/new）で全工程を完結。順序強制: 前のステップが完了するまで次のセクションは disabled
• pour 計画は事前に入力する。投数追加 / 途中スキップは保存前のテーブル UI で編集可
• 「計画」と「実績」は同一フィールド（pour.water_g 1 本）として扱う。計画値は入力時のデフォルト、保存前に書き換えればそれが事実
• pre-fill のソースは 同じ Bean で brewed_at DESC LIMIT 1 の Brew（recipe エンティティは作らない）

2.3 Phase 2 へ送る機能

• 豆ごとの統計（★平均、抽出回数、最高評価の抽出をトップ表示）
• 写真添付（豆袋・抽出後）
• データエクスポート（CSV / JSON）
• マスタデータ化（origin / roast_level / variety / process）→ 詳細は architecture.md §5
• Email verification と Password reset（Resend を導入）
• Playwright E2E の CI 統合（Phase 1 は手動）
• 豆名のテキスト検索（Phase 1 は絞り込みのみ。規模次第で ILIKE → pg_trgm GIN index に拡張）

3. 非機能要件（UX / 運用面）

3.1 認証

• better-auth + Email/Password
• sign-up: 開放（Open registration）
• Email verification / Password reset: Phase 2
• レート制限を sign-in / sign-up に必須（ブルートフォース対策）

3.2 削除

• 全テーブル Soft delete
• 物理削除は管理者の手動オペレーション想定（運用ツール未実装）

3.3 タイムゾーン

• DB は UTC で保持、表示時に Asia/Tokyo 変換