作成: 2026-05-11
最終更新: 2026-05-20
対象: まずは水稲関連機能を中心としつつ、将来的に他作目・関連作業にも展開可能な業務設計・データ設計・画面設計
位置づけ: 個別機能の詳細設計より上位にある共通方針
関連 Issue: akira/keinasystem#67
本システムでは、現場で起きた事実を最終的に追跡・説明できることを最優先にする。
特に水稲栽培では、苗不足、品種変更、ほ場変更、計画外実施、後日記録などが日常的に起こりうる。
そのため、計画や TODO を厳密な正本として扱うのではなく、生産履歴を成立させる実績データを中心に全体設計を行う。
この方針は、まず水稲の田植え実績や苗不足対応の見直しを起点に整理するが、
施肥、農薬散布、収穫など、他の作業記録機能にも同じ原則を適用できる前提で扱う。
最終的に必要なのは、品種 × ほ場 の単位で、
「何を」「いつ」「どこで」行ったかを追えることである。
- 正本は実績である
- 計画との差異があっても、実績として説明できればよい
- 画面、モデル、API は、生産履歴に必要な事実を落とさないことを優先する
計画は、現場作業を進めやすくするための事前仮説である。
実際の運用では、変更・無視・計画外実施が起こりうる。
- 計画は重要だが、真実そのものではない
- 実績は計画に従属しない
- 計画と違う実績が発生しても、異常系ではなく通常運用として扱う
- 計画変更は、実績入力のための文脈整理として扱う
計画の役割は「補助」であって「制御」ではない。
つまり、計画はユーザーの入力を速く・分かりやすくするための初期文脈として利用してよいが、
入力内容を縛る制約条件にしてはならない。
具体的には次の形で実装する。
- ユーザーは、計画起点でもリソース起点でも操作を開始してよい
- 計画を選んだ場合、その計画に対応するほ場・資材・数量などを初期表示やデフォルト値として利用してよい
- ただし、計画を選んだ後でも、ほ場・肥料・農薬などは通常操作で追加・変更・削除できるようにする
- 計画がない場合でも、同じ画面構造・同じ実績モデルで入力を完結できるようにする
- 将来計画機能が追加・拡張されても、実績入力の本質は変えず、初期表示や候補補助が増える形にとどめる
誤った実装パターン（避けること）：
- 「計画を選ばないと入力を開始できない」
→ 計画は入力開始の前提条件ではない
- 「計画由来の候補しか選べない」
→ 計画外のほ場・肥料・農薬も、通常操作で追加・選択できるべき
- 「計画と違う内容にしたい場合、特別な例外操作や別画面が必要になる」
→ 計画との差分修正は通常操作の範囲で扱えるべき
- 「計画が存在しないと入力できない」
→ 計画なし実績は通常運用として常に許容する
TODO は、何を次に行うべきかを示す導線である。
ただし、TODO の存在や完了は、実施事実そのものを意味しない。
- TODO は作業タイミングの指針である
- TODO 完了だけで実績完了と見なしてはいけない
- 実施した内容は必ず実績モデルへ記録する
- TODO は業務導線であり、業務記録の正本ではない
- 実績は「どういう経緯で入力したか」ではなく、「何が実施されたか」で表現する
- 記録者の都合による区分より、現場で起きた事実の差を優先する
- 同じ田植え実績なら、通常入力・緊急入力・後日入力でデータ構造を分けない
- 計画 FK は有用だが、実績成立の絶対条件ではない
- 計画外実施や未計画ほ場への実施も記録できるようにする
- 計画が存在しない場合でも、生産履歴に必要な品種・ほ場・実施日が残せる設計にする
購入苗かどうか のような単純フラグだけでは、生産履歴に必要な説明が不足する- 必要なのは、苗の調達元、自家育苗か外部調達か、分かる範囲の育苗履歴や使用資材情報である
- yes/no ではなく、追跡可能な単位で記録する
- 緊急対応、再配置、後日入力などの業務導線は存在してよい
- ただし、それらは実績の正本ではなく、入力補助・整理補助・判断補助である
- 専用フローの都合が、実績モデルの中心構造を支配してはいけない
- 役割は、今後の作業仮説を整理すること
- 中止、不要化、再計画、日程見直しなどを扱う
- 実績が計画と違っても受け止められる前提で設計する
- 役割は、現場で実際に行ったことを記録すること
- 入力起点が通常導線でも緊急導線でも、最終的には同じ実績として保存する
- 生産履歴に必要な項目を欠かさず記録できることを優先する
- 計画を初期文脈として利用してよい（計画起点での画面初期化・ほ場プリセットなど）。ただしその後の変更・追加・削除は通常操作で行えるようにする
- 計画値はデフォルト値として表示する（確定値ではない）。ユーザーが変更した場合は変更後の値が実績となる
- 参照値（計画由来）と入力値（ユーザー確定）は視覚的に区別する（例：参照値をグレーで表示し、入力欄に初期値としてセット）
- 一覧や1レコードのまとまりなど、ユーザーに見える単位は現場の言葉で説明できる意味を持たせる
- システム内部の都合（内部の計画解決、保存ロジック、関連の持ち方など）だけを理由に、ユーザー向けの行分割やまとまり分割をしてはいけない
- 役割は、次に何をすべきかを分かりやすくすること
- 実績入力への導線としては重要だが、実績の代替にはしない
- 完了状態だけで業務記録が成立したと誤解させない
- 実施日
- 対象ほ場
- 作物・品種
- 使用した苗や資材の由来
- 必要に応じて、計画との対応関係
- 入力経路の違いだけを表す分類
- 一時的な業務フローを前提にした中心モデル
- 生産履歴上の説明力が弱い単純フラグ
- TODO 完了を実績完了とみなす構造
- ユーザーから見て意味を説明できない実績の分割（内部実装都合だけで1件を複数件に見せること）
新しい画面、API、モデル、項目を追加する際は、少なくとも次を確認する。
- この情報は、生産履歴で後から説明が必要な事実か
- これは計画上の都合か、実績上の事実か
- TODO や業務導線の状態を、実績の代わりに保存しようとしていないか
- 計画が外れた場合でも、実施事実を無理なく記録できるか
- 品種 × ほ場単位で追跡したいとき、十分な情報が残るか
- 計画なしでも入力を開始できるか（計画選択が操作の前提条件になっていないか）
- 計画起点で始めてよいが、計画との差分を通常操作で修正できるか（例外操作や別画面が不要か）
- 計画由来の候補しか選べない状態になっていないか（計画外のほ場・肥料・農薬を通常操作で追加・選択できるか）
- ユーザーに見える1行・1件の単位は、現場の言葉で説明できるか（内部都合の分割を見せていないか）
改善案 配下の個別設計文書は、本ポリシーを前提に見直す- 水稲の田植え実績、苗不足対応、苗再配置、施肥連携などの設計判断は、本ポリシーを優先する
- 個別文書の記述と本ポリシーが衝突する場合は、個別文書側を見直す
この文書は、特定の一画面や一 issue のためのメモではなく、
今後の関連設計をぶらさないための共通基準として扱う。