Keina System - Claude 向けガイド

プロジェクト概要

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

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

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

絶対に守るべき制約

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

コーディング規約

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/          # パスワード変更

よくある作業パターン

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

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

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

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

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

# 本番デプロイ（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`

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

開始時

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

終了時（または作業の区切りで必ず実行）

HANDOVER.md を定型フォーマットで更新する
重要な設計判断があれば CLAUDE.md と該当マスタードキュメントを更新
実装状況に変化があれば TASK_CONTEXT.md を更新

5.7 KiB Raw Blame History Unescape Escape