docs: add levee work master document

document/15_マスタードキュメント_畔塗作業編.md

@@ -0,0 +1,557 @@
+# マスタードキュメント：畔塗作業機能
+
+> **作成**: 2026-04-04
+> **最終更新**: 2026-04-04
+> **対象機能**: 畔塗作業記録（日付単位の圃場選択・作業記録索引連携）
+> **実装状況**: 実装予定（仕様策定版）
+
+---
+
+## 概要
+
+農業生産者が、水稲作付け圃場に対して実施した「畔塗」作業を日付単位で記録する機能。
+対象圃場をまとめて選択し、保存時に作業記録一覧へ自動反映する。
+
+本機能は、施肥計画の散布実績と同様に
+「作業本体を専用テーブルで持ち、作業記録一覧には索引を自動生成する」
+という設計方針を採用する。
+
+### 機能スコープ（IN / OUT）
+
+| IN（本機能で扱う） | OUT（本機能では扱わない） |
+|---|---|
+| 畔塗日単位の記録作成 | 畔塗作業の工程管理 |
+| 水稲作付け圃場の候補抽出 | 作業者別の工数集計 |
+| 複数圃場の一括選択・保存 | 機械・資材の在庫管理 |
+| 作業記録一覧（WorkRecord）への自動反映 | 写真添付 |
+| 畔塗記録の編集・削除 | GPS軌跡連携 |
+| 対象圃場一覧の参照画面 | 汎用作業日誌への完全統合 |
+
+---
+
+## 背景と目的
+
+現状システムには、運搬や肥料散布のような作業実績を日付順に参照する仕組みがあるが、
+春作業の一つである畔塗については記録先が存在しない。
+
+畔塗は次の特徴を持つ。
+
+- 1日で複数圃場をまとめて実施することが多い
+- 対象圃場は当年の作付け計画と密接に関係する
+- 後から「いつ、どの圃場を畔塗したか」を一覧で見返したい
+
+そのため、圃場ごとに単発レコードを大量に作るのではなく、
+`1日 = 1件の畔塗記録` とし、対象圃場を明細としてぶら下げる構成とする。
+
+---
+
+## データモデル
+
+### LeveeWorkSession（畔塗記録本体）
+
+日付単位の畔塗作業記録。
+
+| フィールド | 型 | 制約 | 説明 |
+|---|---|---|---|
+| id | int | PK | |
+| year | int | required | 年度フィルタ用。既存機能に合わせて暦年を保持し、原則 `date.year` と一致させる |
+| date | DateField | required | 畔塗日 |
+| title | varchar(100) | required, default=`水稲畔塗` | 一覧表示タイトル。未指定時はサーバー側で `水稲畔塗` を補完する |
+| notes | text | blank | 備考 |
+| created_at | datetime | auto | |
+| updated_at | datetime | auto | |
+
+- `year + date` の一意制約は付けない
+- 同日に午前・午後や地区別で複数記録を持てるようにする
+
+### LeveeWorkSessionItem（畔塗対象圃場明細）
+
+畔塗記録に紐づく対象圃場一覧。
+
+| フィールド | 型 | 制約 | 説明 |
+|---|---|---|---|
+| id | int | PK | |
+| session | FK(LeveeWorkSession) | CASCADE | 親の畔塗記録 |
+| field | FK(fields.Field) | PROTECT | 対象圃場 |
+| plan | FK(plans.Plan) | SET_NULL, nullable | 保存時点の作付け計画参照 |
+| crop_name_snapshot | varchar(100) | required | 保存時点の作物名 |
+| variety_name_snapshot | varchar(100) | blank | 保存時点の品種名 |
+| created_at | datetime | auto | |
+| updated_at | datetime | auto | |
+
+- `unique_together = ['session', 'field']`
+- 圃場名そのものは `Field` を参照して表示する
+- 作物・品種は履歴保全のためスナップショット保持を推奨する
+
+### WorkRecord（作業記録索引）
+
+既存 `apps/workrecords` の `WorkRecord` に畔塗種別を追加して連携する。
+
+追加内容:
+
+- `work_type` に `levee_work` を追加
+- `levee_work_session` への `OneToOne FK('levee_work.LeveeWorkSession')` を追加
+
+想定制約:
+
+- `on_delete=models.CASCADE`
+- `null=True`
+- `blank=True`
+- `related_name='work_record'`
+
+削除方針:
+
+- 親である `LeveeWorkSession` 削除時に、関連する `WorkRecord` は DB 制約の `CASCADE` で自動削除する
+- アプリケーション側での「紐づく WorkRecord を削除する」は、この DB 制約により満たされるものとして扱う
+
+一覧表示時の想定値:
+
+| 項目 | 値 |
+|---|---|
+| 作業日 | 畔塗記録の日付 |
+| 種別 | 畔塗 |
+| タイトル | 水稲畔塗 |
+| 参照先 | 畔塗した圃場一覧画面 |
+
+---
+
+## 候補圃場抽出ルール
+
+畔塗対象候補は、作付け計画 `Plan` から抽出する。
+
+### 基本条件
+
+- 指定年度の `Plan` であること
+- `crop.name = "水稲"` の圃場であること
+- 圃場が存在すること
+
+### 補足
+
+- 判定条件は「品種が水稲」ではなく、原則として「作物が水稲」とする
+- `variety` は任意項目のため、品種未設定でも `crop=水稲` なら候補に含める
+- 並び順は `field.display_order`, `field.id`
+
+### 候補レスポンスで返したい情報
+
+| 項目 | 説明 |
+|---|---|
+| field_id | 圃場ID |
+| field_name | 圃場名 |
+| field_area_tan | 面積（反） |
+| group_name | グループ名 |
+| plan_id | 対応する作付け計画ID |
+| crop_name | 作物名 |
+| variety_name | 品種名 |
+| selected | 初期選択状態。候補圃場は原則 `true` を返し、全選択をデフォルトとする |
+
+### 初期選択ルール
+
+- 候補として返す水稲圃場は、原則すべて `selected=true` とする
+- 品種未設定の水稲圃場も `selected=true` とする
+- UI 上のチェック解除は、ユーザーが今回畔塗しない圃場を明示的に外すための操作と位置づける
+- 先行イメージ図にあった `☐ 山の前` は例示上の表現であり、初期ルールそのものではない
+
+---
+
+## 画面仕様
+
+### 画面の位置づけ
+
+畔塗機能は、日付を先に決めて対象圃場を選ぶ「日報型UI」とする。
+圃場ごとの個別登録画面ではなく、1回の保存で複数圃場をまとめて記録する。
+
+### 主要画面
+
+#### 1. 畔塗記録一覧画面
+
+目的:
+
+- 年度内の畔塗記録を一覧する
+- 新規作成画面へ遷移する
+- 既存記録の編集・削除を行う
+
+表示項目:
+
+- 畔塗日
+- タイトル
+- 対象圃場数
+- 対象圃場名の要約
+- 備考
+
+#### 2. 畔塗記録作成・編集画面
+
+入力項目:
+
+- 日付
+- タイトル
+- 備考
+- 対象圃場一覧
+
+対象圃場一覧の表示項目:
+
+- 選択チェック
+- 圃場名
+- 面積
+- グループ
+- 作物
+- 品種
+
+操作:
+
+- 全選択
+- 全解除
+- 個別選択
+- 保存
+
+初期表示ルール:
+
+- 初回表示時は候補圃場を全選択状態で表示する
+- 編集時は保存済み明細に含まれる圃場を選択状態で復元する
+
+### 推奨UIイメージ
+
+```text
+畔塗記録作成
+
+[日付        2026-04-20]
+[タイトル    水稲畔塗]
+[備考        __________________ ]
+
+対象圃場一覧
+[全選択] [全解除]
+
+☑ 田中上     1.2反  上エリア  水稲  コシヒカリ
+☑ 田中下     0.8反  上エリア  水稲  あきたこまち
+☐ 山の前     1.5反  南エリア  水稲  （未設定）
+
+[保存]
+```
+
+### 作業記録一覧への見え方
+
+既存の作業記録一覧には次の形式で表示する。
+
+| 列 | 表示内容 |
+|---|---|
+| 作業日 | 指定した日付 |
+| 種別 | 畔塗 |
+| タイトル | 水稲畔塗 |
+| 参照先 | 畔塗記録 #ID または対象圃場要約 |
+| 開く | 畔塗記録詳細画面へ遷移 |
+
+---
+
+## API エンドポイント
+
+すべて JWT 認証必須。
+
+### 畔塗記録
+
+| メソッド | URL | 説明 |
+|---|---|---|
+| GET | `/api/levee-work/sessions/?year={year}` | 年度別一覧 |
+| POST | `/api/levee-work/sessions/` | 新規作成 |
+| GET | `/api/levee-work/sessions/{id}/` | 詳細取得 |
+| PUT/PATCH | `/api/levee-work/sessions/{id}/` | 更新 |
+| DELETE | `/api/levee-work/sessions/{id}/` | 削除 |
+
+### 候補圃場取得
+
+| メソッド | URL | 説明 |
+|---|---|---|
+| GET | `/api/levee-work/candidates/?year={year}` | 水稲作付け圃場候補を返す |
+
+### レスポンス例（候補圃場）
+
+```json
+[
+  {
+    "field_id": 5,
+    "field_name": "田中上",
+    "field_area_tan": "1.2000",
+    "group_name": "上エリア",
+    "plan_id": 12,
+    "crop_name": "水稲",
+    "variety_name": "コシヒカリ",
+    "selected": true
+  }
+]
+```
+
+### リクエスト例（新規作成）
+
+```json
+{
+  "year": 2026,
+  "date": "2026-04-20",
+  "title": "水稲畔塗",
+  "notes": "",
+  "items": [
+    {
+      "field": 5,
+      "plan": 12
+    },
+    {
+      "field": 6,
+      "plan": 13
+    }
+  ]
+}
+```
+
+備考:
+
+- `crop_name_snapshot` / `variety_name_snapshot` はクライアント送信項目ではない
+- サーバーが `plan` と `field` の整合を検証したうえで、保存時に `Plan` から自動設定する
+- `plan` が `null` の場合は、保存時点で参照できる `field` に対応する当年 `Plan` から補完を試みる
+
+### レスポンス例（詳細）
+
+```json
+{
+  "id": 3,
+  "year": 2026,
+  "date": "2026-04-20",
+  "title": "水稲畔塗",
+  "notes": "",
+  "work_record_id": 15,
+  "item_count": 2,
+  "items": [
+    {
+      "id": 11,
+      "field": 5,
+      "field_name": "田中上",
+      "plan": 12,
+      "crop_name_snapshot": "水稲",
+      "variety_name_snapshot": "コシヒカリ"
+    },
+    {
+      "id": 12,
+      "field": 6,
+      "field_name": "田中下",
+      "plan": 13,
+      "crop_name_snapshot": "水稲",
+      "variety_name_snapshot": "あきたこまち"
+    }
+  ],
+  "created_at": "2026-04-20T08:00:00Z",
+  "updated_at": "2026-04-20T08:00:00Z"
+}
+```
+
+---
+
+## 業務フロー
+
+### 1. 新規作成
+
+1. ユーザーが年度と日付を選ぶ
+2. システムが当年の水稲作付け圃場を候補表示する
+3. ユーザーが対象圃場を選択する
+4. 保存時に `LeveeWorkSession` を作成する
+5. 明細として `LeveeWorkSessionItem` を一括作成する
+6. 各明細の `crop_name_snapshot` / `variety_name_snapshot` をサーバー側で自動設定する
+7. `WorkRecord` を自動生成または更新する
+
+### 2. 編集
+
+1. ユーザーが既存の畔塗記録を開く
+2. 日付・タイトル・備考・対象圃場を変更する
+3. 保存時に明細を再構成する
+4. `WorkRecord` 側の作業日・タイトルも同期更新する
+5. 明細のスナップショットも保存時点情報で再構成する
+
+### 3. 削除
+
+1. ユーザーが畔塗記録を削除する
+2. 紐づく `LeveeWorkSessionItem` は `CASCADE` で削除される
+3. 紐づく `WorkRecord` は `levee_work_session` の `on_delete=CASCADE` により削除される
+
+---
+
+## 作業記録連携仕様
+
+畔塗記録保存時に `apps/workrecords` 側へ自動反映する。
+
+### 追加する種別
+
+| enum値 | 表示名 |
+|---|---|
+| `levee_work` | 畔塗 |
+
+### 自動生成ルール
+
+- `work_date` = `session.date`
+- `work_type` = `levee_work`
+- `title` = `session.title`
+- `year` = `session.year`
+- `auto_created` = `True`
+- `levee_work_session` = 対応する畔塗記録
+- `delivery_trip` = `None`
+- `spreading_session` = `None`
+
+実装メモ:
+
+- 既存の `sync_spreading_work_record()` と同様に、`update_or_create()` の `defaults` 内で他系統 FK を明示的に `None` へそろえる
+- `title` の未入力は `LeveeWorkSession` 保存時にサーバー側で `水稲畔塗` を補完するため、同期処理では補完済みの `session.title` をそのまま使う
+
+### 同期タイミング
+
+- 畔塗記録作成時: `update_or_create`
+- 畔塗記録更新時: `update_or_create`
+- 畔塗記録削除時: `levee_work_session` の `on_delete=CASCADE` により `WorkRecord` も自動削除される
+
+---
+
+## バリデーションルール
+
+### 必須
+
+- `year`
+- `date`
+- `items`（1件以上）
+
+### 保存時チェック
+
+- 選択圃場が0件の保存を禁止する
+- 同一セッション内で同じ圃場を重複登録しない
+- 候補外圃場の保存を原則禁止する
+- `year` は原則 `date.year` と一致しなければならない
+- `plan` が指定されている場合、その `plan.field` と `field` は一致しなければならない
+- `plan` が指定されている場合、その `plan.year` は `session.year` と一致しなければならない
+
+### 業務上の許容
+
+- 品種未設定の水稲圃場は保存可
+- 同日に別記録を複数作ることは可
+- 一度畔塗した圃場を別日に再度記録することは可
+
+---
+
+## 実装方針
+
+### バックエンド
+
+- 新規アプリ `apps/levee_work` を追加する案を第一候補とする
+- `Session` / `SessionItem` 構成でモデル化する
+- Serializer は `read` と `write` を分離する
+- 候補取得 API は `Plan` を起点に組み立てる
+- `sync_levee_work_record(session)` を作成して `WorkRecord` と同期する
+- `WorkRecord` から `LeveeWorkSession` への参照は、アプリ間循環参照を避けるため文字列参照 `OneToOneField('levee_work.LeveeWorkSession', ...)` を使う
+
+### フロントエンド
+
+- 画面候補: `frontend/src/app/levee-work/page.tsx`
+- 1画面完結の一覧 + 作成/編集パネル、または一覧画面 + 詳細画面のどちらでも可
+- 既存の `fertilizer/spreading` の「一覧 + 編集」導線を参考にする
+- `workrecords/page.tsx` に遷移先判定を追加する
+
+### 命名方針
+
+- ユーザー向け表示は「畔塗」で統一
+- コード上の英語名は `levee_work` または `levee_coating` が候補
+- 既存の `WorkRecord.WorkType` に追加する値は、短く意味がぶれない `levee_work` を推奨する
+
+---
+
+## 画面遷移案
+
+```text
+作業記録一覧
+  └─ 畔塗レコードの「開く」
+       └─ 畔塗記録画面（該当セッションを編集状態で開く）
+
+畔塗記録画面
+  ├─ 新規作成
+  ├─ 既存記録の編集
+  └─ 保存後、作業記録一覧に反映
+```
+
+---
+
+## 将来拡張
+
+- 作業者名の保持
+- 使用機械の記録
+- 実施済み圃場を地図で確認
+- 写真添付
+- 代かき、耕起、播種など他作業への横展開
+- 汎用作業日誌基盤への統合
+
+---
+
+## 実装タスク案
+
+1. `apps/levee_work` アプリ新設
+2. `LeveeWorkSession` / `LeveeWorkSessionItem` モデル追加
+3. migration 作成
+4. serializer / view / url 実装
+5. 候補圃場 API 実装
+6. `WorkRecord` に畔塗種別と参照FK追加
+7. `sync_levee_work_record` サービス実装
+8. フロントエンド一覧・作成画面実装
+9. 作業記録一覧の遷移先対応
+10. テスト追加
+
+---
+
+## 注意点と設計判断
+
+### なぜ「圃場ごと1件」ではなく「日付ごと1件」か
+
+- 実際の作業単位が日付ベースである
+- 一覧が見やすい
+- 既存の散布実績機能と整合する
+- 作業記録索引との親和性が高い
+
+### なぜ作付け計画を参照するか
+
+- 水稲圃場だけを自然に抽出できる
+- 年度との整合が取りやすい
+- 将来「未畔塗候補」や「前年比較」に発展させやすい
+
+### スナップショットを持つ理由
+
+- 後から作付け計画が変更されても、記録時点の情報を追える
+- 作業記録としての監査性を保ちやすい
+
+### なぜ snapshot をクライアント入力にしないか
+
+- `plan` と `field` からサーバーが一意に導出できる情報だから
+- クライアント送信にすると改ざんや不整合の余地が増えるから
+- API 入力を最小限に保った方が UI 実装が単純になるから
+
+---
+
+## ソースファイル追加想定
+
+### バックエンド
+
+- `backend/apps/levee_work/models.py`
+- `backend/apps/levee_work/serializers.py`
+- `backend/apps/levee_work/views.py`
+- `backend/apps/levee_work/urls.py`
+- `backend/apps/levee_work/admin.py`
+- `backend/apps/levee_work/migrations/0001_initial.py`
+- `backend/apps/workrecords/models.py`
+- `backend/apps/workrecords/services.py`
+- `backend/apps/workrecords/serializers.py`
+- `backend/apps/workrecords/views.py`
+- `backend/keinasystem/urls.py`
+
+### フロントエンド
+
+- `frontend/src/app/levee-work/page.tsx`
+- `frontend/src/types/index.ts`
+- `frontend/src/app/workrecords/page.tsx`
+
+---
+
+## まとめ
+
+畔塗作業機能は、
+「当年の水稲作付け圃場を候補として出し、日付単位で複数圃場をまとめて記録し、作業記録一覧へ自動反映する」
+というシンプルな構成を基本とする。
+
+この構成により、既存の作付け計画・作業記録の設計を壊さずに、
+春作業の記録を自然に追加できる。