akira/keinasystem

Fork 0

Files

akira c773c7d3b8 docs: add levee work master document

2026-04-04 11:13:11 +09:00

16 KiB

Raw Permalink Blame History

マスタードキュメント：畔塗作業機能

作成: 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イメージ

畔塗記録作成

[日付        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}`	水稲作付け圃場候補を返す

レスポンス例（候補圃場）

[
  {
    "field_id": 5,
    "field_name": "田中上",
    "field_area_tan": "1.2000",
    "group_name": "上エリア",
    "plan_id": 12,
    "crop_name": "水稲",
    "variety_name": "コシヒカリ",
    "selected": true
  }
]

リクエスト例（新規作成）

{
  "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 から補完を試みる

レスポンス例（詳細）

{
  "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. 新規作成

ユーザーが年度と日付を選ぶ
システムが当年の水稲作付け圃場を候補表示する
ユーザーが対象圃場を選択する
保存時に LeveeWorkSession を作成する
明細として LeveeWorkSessionItem を一括作成する
各明細の crop_name_snapshot / variety_name_snapshot をサーバー側で自動設定する
WorkRecord を自動生成または更新する

2. 編集

ユーザーが既存の畔塗記録を開く
日付・タイトル・備考・対象圃場を変更する
保存時に明細を再構成する
WorkRecord 側の作業日・タイトルも同期更新する
明細のスナップショットも保存時点情報で再構成する

3. 削除

ユーザーが畔塗記録を削除する
紐づく LeveeWorkSessionItem は CASCADE で削除される
紐づく 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 を推奨する

画面遷移案

作業記録一覧
  └─ 畔塗レコードの「開く」
       └─ 畔塗記録画面（該当セッションを編集状態で開く）

畔塗記録画面
  ├─ 新規作成
  ├─ 既存記録の編集
  └─ 保存後、作業記録一覧に反映

将来拡張

作業者名の保持
使用機械の記録
実施済み圃場を地図で確認
写真添付
代かき、耕起、播種など他作業への横展開
汎用作業日誌基盤への統合

実装タスク案

apps/levee_work アプリ新設
LeveeWorkSession / LeveeWorkSessionItem モデル追加
migration 作成
serializer / view / url 実装
候補圃場 API 実装
WorkRecord に畔塗種別と参照FK追加
sync_levee_work_record サービス実装
フロントエンド一覧・作成画面実装
作業記録一覧の遷移先対応
テスト追加

注意点と設計判断

なぜ「圃場ごと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

まとめ

畔塗作業機能は、「当年の水稲作付け圃場を候補として出し、日付単位で複数圃場をまとめて記録し、作業記録一覧へ自動反映する」というシンプルな構成を基本とする。

この構成により、既存の作付け計画・作業記録の設計を壊さずに、春作業の記録を自然に追加できる。

16 KiB Raw Permalink Blame History Unescape Escape

マスタードキュメント：畔塗作業機能

概要

機能スコープ（IN / OUT）

背景と目的

データモデル

LeveeWorkSession（畔塗記録本体）

LeveeWorkSessionItem（畔塗対象圃場明細）

WorkRecord（作業記録索引）

候補圃場抽出ルール

基本条件

補足

候補レスポンスで返したい情報

初期選択ルール

画面仕様

画面の位置づけ

主要画面

1. 畔塗記録一覧画面

2. 畔塗記録作成・編集画面

推奨UIイメージ

作業記録一覧への見え方

API エンドポイント

畔塗記録

候補圃場取得

レスポンス例（候補圃場）

リクエスト例（新規作成）

レスポンス例（詳細）

業務フロー

1. 新規作成

2. 編集

3. 削除

作業記録連携仕様

追加する種別

自動生成ルール

同期タイミング

バリデーションルール

必須

保存時チェック

業務上の許容

実装方針

バックエンド

フロントエンド

命名方針

画面遷移案

将来拡張

実装タスク案

注意点と設計判断

なぜ「圃場ごと1件」ではなく「日付ごと1件」か

なぜ作付け計画を参照するか

スナップショットを持つ理由

なぜ snapshot をクライアント入力にしないか

ソースファイル追加想定

バックエンド

フロントエンド

まとめ

16 KiB

Raw Permalink Blame History