# Keina System - Claude 向けガイド

## プロジェクト概要

農業生産者向けの作付け計画管理システム。圃場管理、作付け計画、申請書自動生成を行う。
ユーザーは65歳の農家（元プログラマー）、シングルユーザー、39筆の圃場を管理。

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

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

---

## 絶対に守るべき制約

1. **Field ↔ OfficialKyosaiField / OfficialChusankanField は M:N** — 決してFK (1:N) に戻さない
2. **年度+圃場の組み合わせは1つの Plan のみ** (`unique_together`)
3. **面積**: 表示=反(tan)、計算・保存=m2、変換: 1反=1000m2
4. **FertilizationEntry.fertilizer は PROTECT** — 使用中の肥料は削除不可
5. **3回同じコードを書くまでは抽象化しない**
6. **ドキュメントドリブン**: 仕様変更時はまず関連ドキュメントから更新する

## コーディング規約

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

---

## プロジェクト構造

```
keinasystem_t02/
├── CLAUDE.md              # このファイル
├── TASK_CONTEXT.md        # 実装状況・課題・次のマイルストーン
├── document/              # 設計書・マスタードキュメント
├── backend/
│   ├── keinasystem/       # Django設定 (settings.py, urls.py)
│   └── apps/
│       ├── fields/        # 圃場管理（Field, OfficialKyosaiField, OfficialChusankanField）
│       ├── plans/         # 作付け計画（Plan, Crop, Variety）
│       ├── weather/       # 気象データ（WeatherRecord）
│       ├── reports/       # 申請書PDF生成
│       ├── fertilizer/    # 施肥計画・散布実績・運搬計画
│       ├── workrecords/   # 作業記録索引
│       └── mail/          # メールフィルタリング（Windmill連携）
└── frontend/src/app/
    ├── allocation/        # 作付け計画編集（メイン画面）
    ├── fields/            # 圃場一覧・詳細
    ├── fertilizer/        # 施肥計画・散布実績
    ├── distribution/      # 運搬計画
    ├── weather/           # 気象データ
    ├── reports/           # 申請書DL
    ├── import/            # データ取込
    ├── mail/              # メール管理
    └── settings/          # パスワード変更
```

---

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

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

1. `apps/<app>/models.py` → 2. `makemigrations` → 3. `migrate` → 4. `admin.py` 登録
5. Serializer → 6. ViewSet → 7. URL登録

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

- API: `views.py` → `urls.py` → フロントの型定義 (`lib/types.ts`) → API呼び出し
- 画面: `frontend/src/app/<page>/page.tsx` → ローディング/エラー状態を処理

---

## デプロイ・トラブルシューティング

```bash
# 本番デプロイ（git pull → build → up -d を一括実行）
ssh keinafarm-claude 'sudo -u keinasystem bash /home/keinasystem/keinasystem_t02/deploy.sh'

# 本番ヘルスチェック（9項目、curlベース）
bash scripts/check_prod.sh claude keina1234

# 本番マイグレーション（バックエンド変更時のみ）
ssh keinafarm-claude 'cd /home/keinasystem/keinasystem_t02 && \
  sudo -u keinasystem docker compose build backend && \
  sudo -u keinasystem docker compose up -d && sleep 5 && \
  sudo -u keinasystem docker compose exec backend python manage.py migrate'
```

- **Docker Compose**: `docker-compose.yml`=本番、`docker-compose.develop.yml`=開発
- **CORS**: `settings.py` の `CORS_ALLOWED_ORIGINS`（localhost:3000 許可済み）
- **JWT**: アクセストークン24h、リフレッシュ: `/api/auth/jwt/refresh/`

---

## マスタードキュメント（機能別リファレンス）

特定機能の詳細を知りたい場合、**まずマスタードキュメントを参照**すること。
データモデル・API仕様・画面仕様がソースコード参照不要なレベルで記載されている。

| 機能 | ドキュメント |
|------|------------|
| 圃場管理 | `document/10_マスタードキュメント_圃場管理編.md` |
| メール通知 | `document/11_マスタードキュメント_メール通知関連編.md` |
| 気象データ | `document/12_マスタードキュメント_気象データ編.md` |
| 施肥計画 | `document/13_マスタードキュメント_施肥計画編.md` |
| 運搬計画 | `document/14_マスタードキュメント_分配計画編.md` |
| 田植え計画 | `document/16_マスタードキュメント_田植え計画編.md` |
| 農薬散布管理 | `document/18_マスタードキュメント_農薬散布管理編.md` |
| データモデル全体 | `document/03_データ仕様書.md` |

---

## セッション開始・終了フロー

### 開始時
1. この `CLAUDE.md` を読む
2. `HANDOVER.md` で前回の引き継ぎを確認する
3. `TASK_CONTEXT.md` で現在の状況を把握する
4. タスク対象の**マスタードキュメント**を読む

### 終了時（または作業の区切りで必ず実行）
1. `HANDOVER.md` を定型フォーマットで更新する
2. 重要な設計判断があれば `CLAUDE.md` と該当マスタードキュメントを更新
3. 実装状況に変化があれば `TASK_CONTEXT.md` を更新