Skip to content

docs: ワイヤーフレームを作成し、ドキュメント群を整理する #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hduehgw0 merged 15 commits into from
Jul 30, 2026
Merged

docs: ワイヤーフレームを作成し、ドキュメント群を整理する #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ffd6683
docs: MVP のワイヤーフレームを追加する
hduehgw0 Jul 30, 2026
46eeac4
docs: 要件概要に用語定義・前提と制約・完了基準を持たせる
hduehgw0 Jul 30, 2026
65652bc
docs: データモデルの正本を schema.prisma の /// に寄せる
hduehgw0 Jul 30, 2026
299f6ea
docs: ロードマップのフェーズ 3 を依存関係の順に並べ替える
hduehgw0 Jul 30, 2026
aa91bf9
docs: ADR-0004 を「正規化を先取りしない」に改める
hduehgw0 Jul 30, 2026
7647d55
docs: 用語を「国」から「産地」に統一する
hduehgw0 Jul 30, 2026
01047a5
docs: 開発ガイドを現状のコマンド・CI・フェーズ表記に合わせる
hduehgw0 Jul 30, 2026
bc920b0
docs: README を現状の機能と用語に合わせる
hduehgw0 Jul 30, 2026
35b9ff5
docs: ユーザーストーリーを廃止し、機能軸のスコープ定義に統合する
hduehgw0 Jul 30, 2026
d41281c
docs: ADR に簡潔さの規約を追記し、既存 ADR を整理する
hduehgw0 Jul 30, 2026
9a44aad
docs: 開発ガイドから重複と密結合な記述を落とす
hduehgw0 Jul 30, 2026
c894dc8
docs: 重複判定の一意制約をユーザー単位にし、区切り文字を明示する
hduehgw0 Jul 30, 2026
5a2eff0
docs: ロードマップの期間を当初計画と実績に分ける
hduehgw0 Jul 30, 2026
0dcfe2d
docs: 産地リストのコメントを実体に合わせる
hduehgw0 Jul 30, 2026
7c8a98f
docs: 要件概要の冒頭に 1 章と 7 章の役割を示す
hduehgw0 Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@
## 動作確認

- [ ] `pnpm lint` が通る
- [ ] `pnpm format:check` が通る
- [ ] `pnpm typecheck` が通る
- [ ] `pnpm test` が通る
- [ ] `pnpm build` が通る
- [ ] モバイル幅で表示が崩れない

<!-- 必要ならスクリーンショット / GIF を貼る。
Expand Down
41 changes: 24 additions & 17 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,27 @@

## Tech Stack

- Next.js（App Router）/ TypeScript
- Prisma + PostgreSQL（Neon）
- Better Auth（Google OAuth）
- Tailwind CSS + shadcn/ui
- react-hook-form + zod / Recharts
- Deploy: Vercel ／ Package manager: pnpm（Node 22）
- **Next.js 16**（App Router・Turbopack 既定）/ **React 19** / TypeScript 5
- **Prisma 7** + PostgreSQL（Neon）
- Better Auth 1.6（Google OAuth）
- **Tailwind CSS v4**
- shadcn/ui
- react-hook-form + **zod 4**
- テスト：**Vitest 4**
- Deploy: Vercel ／ Package manager: pnpm（Node 22.12+）

## Commands

- `pnpm install` – 依存関係のインストール
- `pnpm dev` – 開発サーバ
- `pnpm build` – 本番ビルド（型チェック含む）
- `pnpm lint` – ESLint
- `pnpm test` – Vitest（単体・結合）
- `pnpm prisma migrate dev` – DB マイグレーション
- `pnpm format` – Prettier で整形（差分確認は `pnpm format:check`）
- `pnpm typecheck` – 型チェック（`tsc --noEmit`）
- `pnpm test` – Vitest（単体・結合）※ `test:watch` は終了しないので使わない
- `pnpm build` – 本番ビルド（`prisma generate` 込み）。CI では実行せず Vercel が担う
- `pnpm shadcn add <name>` – UI 部品を `src/components/ui/` に追加
- `pnpm prisma migrate dev` – DB マイグレーション（クライアント再生成も走る）
- `pnpm prisma studio` – DB の中身を GUI で確認

## Project Structure

Expand All @@ -29,15 +35,16 @@
## Principles

- **YAGNI**：着手中の Issue 要件だけを完全に満たす。Issue に明記されない範囲外（未指示のUI・過剰なバリデーション・将来機能）は実装しない。
- **スキーマは前提ではなく判断**：`schema.prisma` の現在の構造は、その時点の要件に対する判断にすぎない。実装前・実装中に要件と構造が噛み合わないと感じたら、構造に合わせて要件を削らず、**構造の側を疑って開発者に提示する**（自分の判断で変更はしない）。→ `docs/data-model.md`
- **アーキの鉄則**：読み取り（一覧・詳細）＝ Server Component が Prisma を直接呼ぶ／書き込み＝ Route Handler で明示実装（**zod による再検証＋認可（自分の `userId` のみ）**。クライアント側バリデーションは信用しない）／zod スキーマはフォームと Route Handler で**共有**する（`src/lib/schemas` 等。二重定義しない）／**Server Actions は使わない**。→ 理由は `docs/adr.md`

## References

| ファイル | 内容 |
| ---------------------- | -------------------------------- |
| `docs/requirements.md` | 要件概要（目的・スコープ・方針） |
| `docs/user-stories.md` | ユーザーストーリー＋受け入れ条件 |
| `docs/data-model.md` | データモデル（ER・スキーマ下地） |
| `docs/adr.md` | 意思決定記録（なぜその選択か） |
| `docs/roadmap.md` | ロードマップ＋マイルストーン |
| `CONTRIBUTING.md` | 開発フロー・コードスタイル・PR |
| ファイル | 内容 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs/requirements.md` | 要件概要（目的・スコープ・方針） |
| `docs/data-model.md` | データモデルに関するコンテクスト(メタデータ) |
| `docs/adr.md` | 意思決定記録（なぜその選択か） |
| `docs/roadmap.md` | ロードマップ＋マイルストーン |
| `docs/ui-mockups/` | MVP の UI モック 9 枚（＝「UI をモックに合わせる」の完了条件）。`assets/` はモックが使う SVG で**設計資料**（ここから import しない。実装時に `src/` へ移す） |
| `CONTRIBUTING.md` | 開発フロー・コードスタイル・PR |
45 changes: 13 additions & 32 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@

- **シンプルで意味論的な HTML**：過剰な `div` ラッパーのネストを避け、可能な限りシンプルで無駄のない構造にする。
- **最低限のスタイリング**：shadcn/ui と HTML 要素のデフォルトスタイルを最大限に活かす。マジックナンバーを避け、手動の独自 Tailwind クラスは必要最低限に抑え、保守性を優先する。
- **モバイルファースト**で組む。

## テスト方針

Expand All @@ -40,14 +39,12 @@
- **Testing Trophy** を採用（静的 → 単体 → 結合 → E2E）。各層の比重はコスト対効果とプロジェクトの状況で調整する（本プロジェクトは結合を厚く、E2E は主要導線のみ）。
- カバレッジの数値目標は追わない（数合わせのテストは書かない）。

| レベル | 対象 | ツール | 時期 |
| -------------- | ------------------------------------------------------- | ---------- | ---------- |
| 静的 | ESLint / Prettier / TS strict（上記「コードスタイル」） | — | 常時 |
| 単体 | zod スキーマ、集計・判定などの純ロジック | Vitest | 実装と併走 |
| 結合（最重要） | Route Handler：検証 → 認可（自分の `userId` のみ）→ DB | Vitest | 実装と併走 |
| E2E | ログイン→登録→一覧→編集→削除→グラフ の主要導線 1 本 | Playwright | 第 4 週 |

> E2E ランナー（Playwright）の導入は別 Issue（第 4 週）。
| レベル | 対象 | ツール | 時期 |
| -------------- | -------------------------------------------------------------------------------------------------- | ---------- | ---------- |
| 静的 | ESLint / Prettier / TS strict（上記「コードスタイル」） | — | 常時 |
| 単体 | zod スキーマ、集計・判定などの純ロジック | Vitest | 実装と併走 |
| 結合（最重要） | Route Handler：検証 → 認可（自分の `userId` のみ）→ DB（これは一例であり要するに最重要箇所が対象） | Vitest | 実装と併走 |
| E2E | ログインから主要な操作を通す導線 1 本 | Playwright | フェーズ 4 |

## Issue 起票

Expand All @@ -73,33 +70,17 @@
- 例：`feat: ボトル登録フォームを追加`
- 関連 Issue は本文か末尾で参照する（例：`Closes #12`）。

## セットアップ

```bash
# 1. 依存をインストール
pnpm install

# 2. 環境変数（DB）：Vercel の Neon 統合から取得
pnpm dlx vercel link # 初回のみ：Vercel プロジェクトに紐付け
pnpm dlx vercel env pull .env # DATABASE_URL などを .env に書き出す

# 3. 環境変数（認証）：AUTH_ 系を .env に手動で追記（項目は .env.example 参照）

# 4. DB マイグレーション
pnpm prisma migrate dev

# 5. 開発サーバ起動
pnpm dev
```

## プルリクエスト

- PR 前に必ず通す：
- PR 前に必ず通す（**CI が実行するものと同じ 4 つ**）：

```bash
pnpm lint # ESLint
pnpm test # Vitest（単体・結合）
pnpm build # 型エラー含めビルドが通るか
pnpm lint # ESLint
pnpm format:check # Prettier の差分（落ちたら pnpm format で直す）
pnpm typecheck # tsc --noEmit
pnpm test # Vitest（単体・結合）
```

> `pnpm build` は CI では実行しない（ビルドは Vercel 側で走る）。

- PR は `gh pr create` で作成する。本文テンプレート（`.github/pull_request_template.md`）が自動適用されるので、Issue の受け入れ条件をコピーしてセルフチェックする。
63 changes: 28 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MyCellar 🥃

> 父のウイスキーコレクションを管理する、自分専用の在庫・カタログ Web アプリ。
> 自分専用のウイスキー在庫を管理・コレクションするためのアプリケーション。
> 産地・年数・樽・限定版まで含めて所有ボトルを記録し、コレクションの全体像や傾向を眺めて楽しめる。

<!-- TODO（実装後）: デモURL / スクリーンショット / デモGIF を貼る -->
Expand All @@ -19,10 +19,8 @@

- Google ログイン（ユーザーごとにデータを分離）
- ボトルの登録・一覧・詳細・編集・削除（必須は銘柄名のみ、他は任意）
- 国・地域 / 年数（NAS 可）/ 樽 / 限定版 / 本数 / メモ の記録
- コレクションの傾向を簡単なグラフで可視化（国別の本数 など）

> 次点：写真アップロード・テイスティング記録・AI「今夜の1杯」提案（詳細は `docs/roadmap.md`）
- 産地・地域 / 年数（NAS 可）/ 樽 / 限定版 / 本数 / メモ の記録
- コレクションの傾向を簡単なグラフで可視化（産地別の本数 など）

## アーキテクチャ

Expand All @@ -44,37 +42,36 @@ flowchart LR

> 「重い分岐があった決定」は ADR（`docs/adr.md`）に記録。下表は各スタックの一言理由。

| 技術 | 役割 | 選んだ理由（一言） |
| ---------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| Next.js（App Router） | フロント＋API | フロントと API を 1 つに閉じられる主スタック。現行標準（→ ADR-0002 / ADR-0008） |
| TypeScript | 言語 | 型安全で、フォーム〜API〜DB を一貫した型で繋ぐ |
| Route Handlers | バックエンド | 書き込みAPIを自分で実装。読みは Server Component 直読み（→ ADR-0002） |
| Prisma | ORM | スキーマ駆動で型安全・マイグレーションが一貫（→ ADR-0007） |
| PostgreSQL（Neon） | DB | 定番のリレーショナル DB。サーバーレスで無料枠あり |
| Better Auth（Google） | 認証 | パスワードを保持せず安全。父も使える。auth.js のメンテナンスモード化を受け再選定（→ ADR-0010） |
| Tailwind CSS | スタイル | モバイルファーストを高速に書ける |
| shadcn/ui | UI 部品 | アクセシブルな部品を「自分のコード」として持てる |
| react-hook-form ＋ zod | フォーム/検証 | フォーム管理と型安全なバリデーション |
| Recharts | 可視化 | React と相性が良く、傾向グラフを手早く |
| Vercel | デプロイ | Next.js に最適。push で前後まとめてデプロイ |
| ESLint ＋ Prettier | 規約 | コーディング規約をツールで強制（文書化しない） |
| Playwright ＋ GitHub Actions | テスト/CI | 主要フローの E2E と継続的インテグレーション |
| UploadThing / Vercel Blob | 画像（次点） | 写真保存をマネージドで軽く（→ ADR-0005） |
| 技術 | 役割 | 選んだ理由(選んだ理由が弱い)（一言） |
| ----------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Next.js（App Router） | フロント＋API | 現状、フロントエンド領域で最も使用されているフレームワーク。フロントとAPIを1つに閉じられるのも魅力。現行標準（→ ADR-0002 / ADR-0008） |
| TypeScript | 言語 | 型安全で、フォーム〜API〜DB を一貫した型で繋ぐ |
| Route Handlers | バックエンド | 書き込みAPIを自分で理解して実装できる点が魅力。読みは Server Component 直読み（→ ADR-0002） |
| Prisma | ORM | スキーマ駆動で型安全・マイグレーションが一貫しており、`schema.prisma`がそのまま正本となり宣言的なのもいい（→ ADR-0007） |
| PostgreSQL（Neon） | DB | 定番のリレーショナル DB。サーバーレスで無料枠あり |
| Better Auth 　　　　　　　　 | 認証 | auth.jsの非推奨化やメンテナンスモード化を受け再選定（→ ADR-0010） |
| Google OAuth | 認証 | パスワードを保持せず安全！父でもGoogleアカウントを持っており、めんどくさがりな父が登録を一瞬で行える。（→ ADR-0010） |
| Tailwind CSS | スタイル | モバイルファーストを高速に書ける |
| shadcn/ui | UI 部品 | アクセシブルな部品を「自分のコード」として持てる |
| react-hook-form ＋ zod | フォーム/検証 | フォーム管理と型安全なバリデーション |
| Vercel | デプロイ | 小規模なプロダクトに最適。手軽にデプロイでき、各PR毎に確認ができるpreview環境や環境毎に分けられるDBが魅力 |
| ESLint ＋ Prettier | 規約 | コーディング規約をツールで強制 |
| Playwright/Vitest ＋ GitHub Actions | テスト/CI | ? |
| UploadThing / Vercel Blob | 画像 | 写真保存をマネージドで軽く（→ ADR-0005） |
Comment thread
coderabbitai[bot] marked this conversation as resolved.

## ドキュメント

| ファイル | 内容 |
| ---------------------- | --------------------------------------- |
| `docs/requirements.md` | 要件概要（目的・スコープ・方針） |
| `docs/user-stories.md` | ユーザーストーリー＋受け入れ条件 |
| `docs/data-model.md` | データモデル（ER・Prisma スキーマ下地） |
| `docs/roadmap.md` | ロードマップ＋マイルストーン |
| `docs/adr.md` | 意思決定記録（なぜその選択をしたか） |
| `CONTRIBUTING.md` | 開発フロー・コードスタイル・PR |
| ファイル | 内容 |
| ---------------------- | -------------------------------------------- |
| `docs/requirements.md` | 要件概要（目的・スコープ・方針） |
| `docs/data-model.md` | データモデルに関するコンテクスト(メタデータ) |
| `docs/roadmap.md` | ロードマップ＋マイルストーン |
| `docs/adr.md` | 意思決定記録（なぜその選択をしたか） |
| `CONTRIBUTING.md` | 開発フロー・コードスタイル・PR |

## セットアップ
<!-- (ここはまだ雑い！) -->

<!-- TODO（#2 実装後）: Prisma 導入後に `pnpm prisma migrate dev` の検証結果を反映する -->
## セットアップ

```bash
# 1. 依存をインストール
Expand All @@ -100,8 +97,4 @@ pnpm dev
> - ローカル：`http://localhost:3000/api/auth/callback/google`
> - 本番：`{BETTER_AUTH_URL}/api/auth/callback/google`（例：`https://<本番ドメイン>/api/auth/callback/google`）

## ステータス

開発中（MVP）。進捗は GitHub Issues / Projects を参照。

<!-- TODO（実装後）: ライセンス / 作者リンク など -->
Loading
Loading