コンテンツにスキップ
utm-backend Docs

データモデル設計ドキュメントの規約

docs/data-model/配下の設計ドキュメントに共通する図の記法・命名規約・記述の正典を定める。 個別ドメインの設計判断とその理由は各ドキュメントの「設計方針」に置く。

適用範囲: docs/data-model/ 配下のドキュメントに限定する。他ドメインのデータモデルには適用しない （データモデルの規約はバックエンド全体に関わるため、共通ルールとするには他チームとの合意が必要である。 まず本範囲で運用して有効性を確認する）。整合性検査（scripts/check-datamodel.mjs）と pre-commit の 対象も同じディレクトリで、宣言と実装を一致させている。

現在このディレクトリには本規約を含めて6ファイルがあり、図の記法と命名規約の対象となるのは次の4ドキュメント（飛行計画・Asset・空域制限・テレメトリの各ドメインが対象）である。

設計ドキュメント横断のフォローアップ台帳は未決事項を集約する台帳でER図を持たないため、 図の記法・命名規約は適用されない（下記「記述の追随」は適用される）。

GeoSpatialのAPI設計ドキュメント（docs/geospatial/design/geospatial-api-design.md）はデータモデル 文書ではないため対象外である。ただし同ドキュメントは本ディレクトリのデータモデルを参照するため、 参照する記述については下記「図を単一の正とする」に従う。

[!NOTE] 本来の置き場所について: データモデルの規約は、上位の概念モデルを持つ utm-design-docs に置くのが筋である。 ただし規約の内容がまだ固まっていないため、まず本リポジトリの上記のドキュメントで運用し、 有効性を確認してから utm-design-docs への移設を提案する。

図の記法

Section titled “図の記法”

ER図はmermaidのerDiagramで記述する。

表記意味
赤枠・赤字のテーブル概念モデル（data-model.md）に対して本設計で追加したテーブル
枠のみでカラムがないテーブル他の図、または他ドメインで定義しているテーブル。リレーションを示すために名前だけを配置している

追加を示すのはテーブル単位のみとし、既存テーブルへのカラム追加は色では表現しない。 枠のみで参照しているテーブルも、追加テーブルであれば同じく赤で示す。

カラムのマーカー

Section titled “カラムのマーカー”
マーカー意味
PK主キー
FK外部キー
UK単独カラムのUNIQUE制約
PK,FK親の主キーをそのまま主キーとして持つ（1:1・クラステーブル継承・サテライト）
FK,UK外部キーかつ単独UNIQUE。親に対して最大1件であることを表す

カーディナリティ

Section titled “カーディナリティ”

図で使う記法は次の7種である。原則として左を親、右を子として読む。ただし他ドメインのテーブルと外部キーによらず値で対応づける関連は親子関係を表さない（多対多の}o--o{と、DIPS_FLIGHT_PLAN |o--o{ COORDINATION_CONFLICTIONのように基数を保ったまま値で対応づけるもの）。この場合はどちらが親かではなく、関係のラベルが対応づけの根拠（対応に使う値）を示す。

記法意味
||--o{1対0以上
||--|{1対1以上（子が最低1件必須）
||--o|1対0または1
||--||1対1（双方必須）
|o--o{0または1対0以上
|o--o|0または1対0または1
}o--o{多対多。本設計では外部キーによらず値で対応づける他ドメインとの関連（DIPS_REPORTと運航調整ドメインのCOORDINATION_CONFLICTION）にのみ使う

図を単一の正とする

Section titled “図を単一の正とする”

同じ結論がmermaid図・カラム補足・設計方針・命名規約表・フィールド対応表に分散して書かれており、 片側だけ直す追随漏れが起きやすい。これを避けるため、カーディナリティと格納形式は図を単一の正とする。 本文の記述が図と食い違う場合は図を正として読み、本文側を図に合わせて直す。

ここでいう格納形式はDBカラムの型とカーディナリティを指す。フィールド対応表のAPI型（OASが正）とDIPS型（DIPS仕様が正）は対象外である。桁数・値域は flight-plan-field-mapping.mdの「DIPS側の入力チェックとAPI制約の対応」を 単一の正とする。NULL可否・CHECK制約・索引は図に表現できないため、いずれもカラム補足を正とする。

PostGISのgeometry型のサブタイプも図の対象外とし、カラム補足を正とする。 mermaidの型欄に geometry(MultiPolygon, 4326)のような表記は書けず、図では一律geometryにしかならないためである。 サブタイプの絞り込み（Polygon／MultiPolygon／絞らないGeometry）はDDLに直接影響するため、 geometry系のカラムはカラム補足に必ずPostGIS型を書く。 カラム補足側の補完はPR #133で実施しており、 本PRの系譜には入らない（#133 の base は main）。本PR時点ではflight-plan-er.mdの operational_intent_geometryとDIPS_FLIGHT_PLAN.plan_geometryにPostGIS型の記載がなく、 #133 のマージで解消する。

「桁数・値域は同節を単一の正とする」の範囲は、DIPS通報の対象項目に限る。次の3つは例外である。

  • flight-plan-er.mdの「入力制限の是正」の一覧は、是正計画として当面残置する（PR #139が同節への参照へ置き換えており、#133のマージで解消する）
  • 設計ドキュメント横断のフォローアップ台帳は値を持たない。出典不一致の両方の値は由来のドキュメント側に置く
  • DIPS通報の対象外の項目（空域制限IDなど）は同節が扱わないため、記述した箇所を正とする
  • 設計方針の節で制約値を根拠として使う場合（例: バッファ適用後の点数が上限に収まるかの計算）は実値を書いてよい。ただし同節へのアンカー付きリンクを添え、値が同節由来であることを示す

同一のテーブル間に複数の関係がある場合は、関係のラベルで区別する。たとえば FLIGHT_PLANとFLIGHT_PLAN_REVISIONの間には「リビジョン履歴」（||--o{）と「current_revision」 （||--o|）の2本があり、後者は外部キーが親側（FLIGHT_PLAN.current_revision_id）にある。 どちらの関係を指しているかはラベルで判断する。

ただし一意制約には但し書きが必要である。mermaidのUKマーカーは単一カラムにしか付けられないため、 次の2つは図に表現できず、カラム補足を正とする。

  • 複合UNIQUE … (flight_plan_revision_id, pilot_id, aircraft_id)など
  • 部分UNIQUE … ASSET_RELATIONのcurrent_status='LINKED'を条件としたものなど

単独UNIQUEは図にUK（外部キーを兼ねる場合はFK,UK）としてマークする。したがって 「図にUKがない」ことは「一意制約がない」ことを意味しない。複合・部分UNIQUEの有無は必ずカラム補足で確認する。

命名規約

Section titled “命名規約”

テーブル名・カラム名の付け方を以下に統一する。既存の逸脱には理由を添える。

種別規約例
N:M中間テーブル<親>_<関連>_ASSIGNMENTFLIGHT_PLAN_PILOT_ASSIGNMENT
親と1:1または1:0..1のサテライト<親>_<種別>_ATTRSASSET_UAS_ATTRS（1:0..1）・FLIGHT_PLAN_DIPS_ATTRS（1:1）
イベント<リソース>_EVENTASSET_EVENT・PILOT_EVENT
イベントの実行者actor_user_idFLIGHT_PLAN_STATE_EVENT.actor_user_id
リソースの操作者<動作>_bycreated_by・changed_by・registered_by
dips_ 接頭辞テーブル名でDIPS固有と分かる場合は付けない。DIPSが発番するIDのみ例外的に付けるdips_receipt_no（付ける）／report_required（付けない）

既存の逸脱は次の4つで、いずれも改名しない。

  • FLIGHT_PLAN_DIPS_NEARBY_LINK … N:M中間だが_LINK。「収集結果と自組織計画の対応づけ」という性質が _ASSIGNMENT（割り当て）より_LINK（紐付け）に近いため。
  • DIPS_UAS_LINK … 1:0..1サテライトだが_LINK。概念モデル由来の既存名で、改名すると上位ドキュメントとの 追跡性が切れるため。
  • FLIGHT_PLAN_STATE_EVENT … <リソース>_EVENTの形から外れSTATEが挟まる。飛行計画のイベントには内容 リビジョン（FLIGHT_PLAN_REVISION）もあり、状態遷移に限ることを名前で示す必要があるため。
  • FLIGHT_PLAN_AREA_CIRCLE／_ROUTE … クラステーブル継承だが_ATTRSを付けない。area_typeの値がそのまま 接尾辞になっており、_ATTRSを足しても情報が増えないため。

記述の追随

Section titled “記述の追随”

加筆・変更時に追随漏れを起こさないための手順は、Claude Code 向けのルール .claude/rules/design-docs.md に定める（リポジトリ内のパス。ドキュメントサイトには掲載しない）。