# Keina System - Claude 向けガイド

> **最終更新**: 2026-02-16
> **現在のフェーズ**: Phase 1 (MVP) - 基本機能実装完了、試験中

## 📌 このファイルの目的

このファイルは、Claude が新しいセッションを開始する際に最初に読むべきドキュメントです。
プロジェクト全体の構造、重要な設計判断、現在の状態を把握するための情報を集約しています。

## ⚠️ Claude への重要な指示

**このファイルは、セッションごとに必ず最初に読んでください。**

さらに、以下のルールを厳守してください：

### 📝 更新義務

**ドキュメントドリブンの徹底**
- ✅ 仕様に変更がある時は、まず関連するドキュメントから更新する事。

**機能追加・変更時は、必ずこのファイルを更新すること。**

- ✅ 新機能実装時 → 「実装状況」セクションを更新
- ✅ データモデル変更時 → 「データモデル概要」を更新
- ✅ 重要な設計判断時 → 「重要な制約・ルール」に追記
- ✅ 新作業パターン確立時 → 「よくある作業パターン」に追加
- ✅ 問題解決時 → 「トラブルシューティング」に追加
- ✅ 更新時は必ず「更新履歴」セクションに記録


**更新を忘れると、次のセッションで情報が失われます。これは最優先事項です。**

---

## 🎯 プロジェクト概要（30秒で理解）

**何を作っているか:**
農業生産者向けの作付け計画管理システム。圃場管理、作付け計画、申請書自動生成を行う。

**ユーザー:**
65歳の農家（元プログラマー）、シングルユーザー、39筆の圃場を管理

**技術スタック:**
- Backend: Django 5.2 + DRF + PostGIS
- Frontend: Next.js 14 (App Router) + TypeScript + Tailwind CSS
- Database: PostgreSQL 16 + PostGIS 3.4

**開発方針:**
シンプルさ最優先、段階的な機能追加、過度な複雑化を避ける

---

## 📂 プロジェクト構造

```
keinasystem_t02/
├── CLAUDE.md              # このファイル（Claude向けガイド）
├── document/              # 詳細設計書（人間向け）
│   ├── 00_Gemini向け統合指示書.md  # 全体像の詳細
│   ├── 01_プロダクトビジョン.md
│   ├── 02_ユーザーストーリー.md
│   ├── 03_データ仕様書.md
│   ├── 04_画面設計書.md
│   └── 05_実装優先順位.md
├── backend/
│   ├── keinasystem/        # Django設定
│   │   ├── settings.py     # 重要: CORS, JWT, DB設定
│   │   └── urls.py         # ルートURL設定
│   └── apps/
│       ├── fields/         # 圃場管理アプリ
│       │   ├── models.py   # Field, OfficialKyosaiField, OfficialChusankanField
│       │   ├── views.py    # インポート機能、CRUD API
│       │   └── urls.py
│       ├── plans/          # 作付け計画アプリ
│       │   ├── models.py   # Plan, Crop, Variety
│       │   └── views.py    # 作付け計画API、集計API
│       └── reports/        # 申請書生成アプリ
│           ├── views.py    # PDF生成API
│           └── templates/  # PDF用HTMLテンプレート
└── frontend/
    └── src/app/
        ├── allocation/     # 作付け計画編集画面（メイン）
        ├── fields/         # 圃場一覧・詳細
        ├── reports/        # 申請書ダウンロード
        └── import/         # データ取込画面
```

---

## 🗄️ データモデル概要

### コアエンティティ

```
Field (実圃場)
├── 39筆の実際の農地
├── area_tan (反), area_m2 (m2) の2つの面積フィールド
├── group_name, display_order (グループ分け・表示順)
└── ManyToMany関係
    ├── kyosai_fields (共済マスタ、M:N)
    └── chusankan_fields (中山間マスタ、M:N)

OfficialKyosaiField (共済マスタ)
└── 31区画（水稲共済細目書用）

OfficialChusankanField (中山間マスタ)
├── 71区画（中山間地域等直接支払交付金用）
└── 17フィールド: c_id, chusankan_flag, oaza, aza, chiban,
    branch_num, land_type, area, planting_area,
    original_crop, manager, owner, slope,
    base_amount, steep_slope_addition, smart_agri_addition,
    payment_amount

Plan (作付け計画)
├── field (FK to Field)
├── year (年度)
├── crop (FK to Crop)
├── variety (FK to Variety, nullable)
└── unique_together = ['field', 'year']

Crop (作物マスタ)
└── 米、トウモロコシ、エンドウ、野菜、その他

Variety (品種マスタ)
├── crop (FK to Crop)
├── name (品種名)
└── unique_together = ['crop', 'name']
```

### 重要な設計判断

1. **M:N関係に変更**: 当初はM:1だったが、実運用で「1つの実圃場が複数の申請区画に紐づく」ケースが判明し、ManyToManyに変更（マイグレーション0003で実施）

2. **面積単位の二重管理**:
   - DB内部は `area_m2` (整数) で保存
   - 表示用に `area_tan` (反, Decimal) も保持
   - 理由: 申請書ではm2、農家の感覚では反

3. **品種は全作物で統一**:
   - 「作付けしない」も「その他」作物の品種として扱う
   - UI操作を統一するため

4. **グループ機能**:
   - `group_name` (エリアや用途によるグループ分け)
   - `display_order` (リスト表示時の順序)
   - マイグレーション0004で追加

---

## 🔑 重要な制約・ルール

### 絶対に守るべきこと

1. **データの整合性**
   - 年度 + 圃場の組み合わせは1つの Plan のみ (`unique_together`)
   - 作物 + 品種名の組み合わせは一意 (`unique_together`)

2. **面積の扱い**
   - 表示: 反 (tan)
   - 計算・保存: m2
   - 変換: 1反 = 1000m2 (正確には991.736m2だが、実運用では1000で統一)

3. **M:N関係の重要性**
   - Field と OfficialKyosaiField は M:N
   - Field と OfficialChusankanField は M:N
   - 決して FK (1:N) に戻さない

4. **シンプルさ優先**
   - 過度な抽象化を避ける
   - 3回同じコードを書くまでは抽象化しない
   - ユーザーは1人、パフォーマンス最適化は後回し

### コーディング規約

- **Backend**: Django のベストプラクティスに従う
- **Frontend**: TypeScript strict mode、ESLint に従う
- **API**: REST原則、エンドポイントは複数形 (`/api/fields/`, `/api/plans/`)
- **命名**: 日本語のフィールドは `verbose_name` で対応

---

## 📍 現在の実装状況

### ✅ 実装済み（Phase 1 - MVP）

1. **認証**: JWT認証（アクセストークン24h、リフレッシュトークン7日）
2. **圃場管理**:
   - CRUD API (`/api/fields/`)
   - ODS/Excelインポート (`/api/fields/import/`)
   - グループ機能（マイグレーション0004）
3. **作付け計画**:
   - 年度別の作付け計画 CRUD (`/api/plans/?year=2025`)
   - 前年度コピー機能 (`/api/plans/copy_from_previous_year/`)
   - 一括更新 (`/api/plans/bulk_update/`)
   - 集計API (`/api/plans/summary/?year=2025`)
4. **申請書生成**:
   - 水稲共済細目書 PDF (`/api/reports/kyosai/?year=2025`)
   - 中山間交付金 PDF (`/api/reports/chusankan/?year=2025`)
5. **フロントエンド**:
   - 作付け計画編集画面（集計サイドバー付き）
   - 圃場一覧・詳細・新規作成
   - データ取込画面
   - 申請書ダウンロード画面

### 🚧 既知の課題・技術的負債

1. **認証周り**: ログアウト処理が未実装（トークン破棄のみ）
2. **エラーハンドリング**: フロントエンドでの統一的なエラー表示が未実装
3. **テスト**: 自動テストが未実装（Phase 2で追加予定）
4. **パフォーマンス**: N+1問題が一部存在（現状は問題ないが、データ増加時に対応必要）
5. **セキュリティ**: DEFAULT_PERMISSION_CLASSES が AllowAny → IsAuthenticated に変更必要
6. **settings.py**: LANGUAGE_CODE と TIME_ZONE が二重定義されている（前の定義を削除）
7. **PDF生成バグ**: reports/views.py で variety が null 時にクラッシュ（null チェック未実装）
8. **init_crops.py**: 不正データを含むため削除予定
9. **PDF帳票**: 現在のテンプレートは仕様と不一致（中国語混入、セクション形式、@page未設定）→ 再設計必要
10. **中山間モデル**: 現在6フィールド → 17フィールドに拡張必要（E-1c）

### 🔜 次の実装タスク（優先順）

1. **A-8**: 圃場詳細に共済/中山間情報表示（最優先）
2. **D-1〜D-4**: バグ修正（null crash, settings二重定義, AllowAny→IsAuthenticated, init_crops削除）
3. **E-1**: PDF帳票フォーマット再設計（中山間モデル拡張含む）
4. **A-3**: 前年度コピーボタン（Frontend）
5. **A-4**: 品種のインライン追加・削除
6. **A-5**: PDFプレビュー機能
7. **A-6**: エクスポート機能（サーバー移行時のデータ移動用）
8. **A-2**: チェックボックス・一括操作
9. **A-1**: ダッシュボード画面
10. **A-7**: 検索・フィルタ

詳細は `document/06_ドキュメントvs実装_差異レポート.md` を参照

### 📅 次のマイルストーン（Phase 2）

- 栽培履歴管理（播種日、農薬・肥料の散布記録）
- 作業予定のカレンダー表示
- モバイル対応の改善（スマホでの記録入力）

---

## 🛠️ よくある作業パターン

### 新しいモデルを追加する場合

1. `apps/<app_name>/models.py` にモデルクラスを追加
2. `python manage.py makemigrations`
3. `python manage.py migrate`
4. `apps/<app_name>/admin.py` に登録（管理画面で確認するため）
5. Serializer 作成 (`apps/<app_name>/serializers.py`)
6. ViewSet 作成 (`apps/<app_name>/views.py`)
7. URL登録 (`apps/<app_name>/urls.py`)

### 新しいAPI エンドポイントを追加する場合

1. `apps/<app_name>/views.py` にビューを追加
2. `apps/<app_name>/urls.py` にパスを追加
3. フロントエンドで型定義 (`frontend/src/lib/types.ts`)
4. API呼び出し関数作成 (`frontend/src/lib/api.ts` または直接fetch)

### 新しい画面を追加する場合

1. `frontend/src/app/<page_name>/page.tsx` を作成
2. 必要に応じてレイアウト調整 (`layout.tsx`)
3. API呼び出しは `useEffect` + `fetch` で実装
4. ローディング状態、エラー状態を適切に処理

---

## 🔍 トラブルシューティング

### マイグレーションエラー

```bash
# マイグレーションをリセット（開発環境のみ！）
docker-compose exec backend python manage.py migrate <app_name> zero
docker-compose exec backend python manage.py makemigrations
docker-compose exec backend python manage.py migrate
```

### CORS エラー

- `backend/keinasystem/settings.py` の `CORS_ALLOWED_ORIGINS` を確認
- 現在は `http://localhost:3000` と `http://127.0.0.1:3000` を許可

### JWT トークンエラー

- トークンの有効期限を確認（アクセストークン: 24時間）
- リフレッシュトークンを使って更新（エンドポイント: `/api/auth/jwt/refresh/`）

### PDF 生成エラー

- WeasyPrint のインストールを確認
- 日本語フォントの設定を確認（HTMLテンプレートのCSS）

---

## 📚 詳細情報へのリンク

- **プロジェクトの背景・目的**: `document/01_プロダクトビジョン.md`
- **機能要求・ユーザーストーリー**: `document/02_ユーザーストーリー.md`
- **データモデル詳細**: `document/03_データ仕様書.md`
- **画面設計**: `document/04_画面設計書.md`
- **実装手順**: `document/00_Gemini向け統合指示書.md`
- **差異レポート・タスク一覧**: `document/06_ドキュメントvs実装_差異レポート.md`

---

## 💡 新しいセッションでの推奨フロー

1. この `CLAUDE.md` を読む
2. 現在のタスクに関連する `document/` 内のファイルを確認
3. 該当するモデル・ビュー・コンポーネントのコードを読む
4. 実装・修正を行う
5. 重要な設計判断があれば、この `CLAUDE.md` を更新

---

## 📝 更新履歴

- 2026-02-17: ドキュメント一斉更新（差異レポートA〜E反映、CSV→PDF統一、M:N関係、中山間モデル17列化、インライン編集方式、Navbar追加、既知の課題・次タスク一覧追加）
- 2026-02-16: 初版作成（ハイブリッドアプローチの方針決定）