GeoSpatialService 業務ロジック仕様

1. 目的

本ドキュメントは、GeoSpatial機能の業務ロジック仕様を定義する。

10月デモ向けに制限した機能については「forDemo」を記載する。

OASの設計判断の根拠（データモデルとのマッピング、旧USS GeoServer APIのCQLフィルタとの対応）は geospatial-api-design.mdにあり、本ドキュメントは処理フローを定義する。 API契約のSource of Truthはdocs/openapi/frontend/geospatial.yamlである。

2. 機能概要

GeoSpatial機能は、地図上への重畳表示に必要な地理情報（飛行計画領域・空域制限・飛行軌跡・現在位置）を GeoJSON（application/geo+json）で提供する機能である。

提供APIはfrontend/geospatial.yaml・frontend/geospatial-sse.yamlが定義しており、現時点で処理フロー（5章）を記載しているのは次のAPIである（2.2参照）。

自組織の飛行計画領域検索
- POST /api/v1/geo/flight-plan-area/search
近傍の他Operatorの飛行計画領域検索
- POST /api/v1/geo/flight-plan-area/others/search
空域制限検索（制限分類ごとにエンドポイントが分かれるが、検索条件・応答スキーマは共通）
- POST /api/v1/geo/airspace-restriction/{airport|red-zone|yellow-zone|ordinance|manned-airport|emergency|other1|other2}/search

2.1. ユースケースとの対応

上流のユースケース定義はutm-design-docs/docs/usecase/flight-plan/flight-plan-usecase.mdにある。 1つのAPIが複数のユースケースから呼ばれるため、処理フロー（5章）はユースケース単位ではなくAPI単位に構成する（ユースケース単位にすると同じ処理フローを複数箇所へ書くことになり、追随漏れの原因になる）。

API	呼び出し元のユースケース
自組織の飛行計画領域検索	UC-PLAN-06「付近の空域の状況を確認する」手順5（飛行計画の重畳表示のうち「自分のもの」）、UC-PLAN-01「飛行計画を作成する」・UC-PLAN-03「飛行計画を確認・更新する」（編集中の自計画の重畳表示）
他Operatorの飛行計画領域検索	UC-PLAN-01-9「他の飛行計画を確認する」、UC-PLAN-06 手順5（同「他社のもの」）
空域制限検索	UC-PLAN-01-7「飛行禁止エリアを確認する」（飛行計画の作成・更新中の重畳表示）、UC-PLAN-06 手順6（飛行禁止エリアの重畳表示）

UC-PLAN-06の補足「飛行計画の表示は、自分のもの、他社のものをON/OFFできる」がエンドポイントを自組織向け・他Operator向けに分割している根拠であり、同「飛行計画の表示は、指定した時刻丁度だけでなく、前後のものも含む」がcurrentTimeFrom/currentTimeTo（区間の重なり判定）を設けている根拠である。

2.2. 本ドキュメントの記載範囲

本ドキュメントはGeoSpatial機能全体の業務仕様であり、APIを実装した順に5章へ節を追加する（ドメインごとに1ファイルとし、API単位・ユースケース単位のファイル分割はしない）。 2章に挙げたAPIのほか、次のAPIは未実装のため5章に節を持たない。

空域制限（DID）のPMTilesアーカイブ取得
飛行軌跡取得
現在位置一覧検索
現在位置のリアルタイム購読（SSE）

3. 用語定義

飛行計画機能と共通の用語（UTM・DIPS・飛行計画・Operator等）は飛行計画の業務ロジック仕様3章を参照する。本ドキュメント固有の用語のみを次に示す（全体はgeospatial-api-design.md4章）。

用語	意味
bbox	検索範囲を表すバウンディングボックス（`minLon,minLat,maxLon,maxLat`、WGS84）。
FeatureCollection / Feature	GeoJSON（RFC 7946）に準拠した地物集合／地物の表現。
自組織 / 他Operator	自組織＝自組織のOperatorがUTMに登録した飛行計画。他Operator＝DIPSへ通報された自組織以外の飛行計画（他社UTM管理下のものと、自社UTM内の他組織のものの両方を含む。5.2の1-1参照）。
dataType	同一の飛行計画に対して返却する複数のFeatureが、元の形状（`FLIGHT_PLAN`）・バッファ適用後の形状（`OPERATIONAL_INTENT`）・上面下面の3D形状（`TOP_BOTTOM_3D`）のどれを表すかの区分。
altitudeReference	Featureの`geometry`のZ値（高度）が準拠する高度基準（`AGL`＝対地高度／`WGS84`＝WGS84楕円体高）。
制限分類	空域制限の種別。ソースを横断して正規化した軸で、検索エンドポイントの切り分けキーになる（OASの`AirspaceRestrictionType`。飛行計画ドメインと共有する）。
天面 / 床面	3D形状の上面（ceiling）と下面（floor）。飛行計画領域は`dataType=TOP_BOTTOM_3D`のFeatureで両方を返し（`coordinates[0]`が上面、`coordinates[1]`が下面）、空域制限は天面のみを返す。
currentTime	「指定時刻時点で有効な」計画を取得するための検索条件。
currentTimeFrom / currentTimeTo	「指定期間内のいずれかの時点で有効な」計画を取得するための検索条件（区間の重なり判定）。`currentTime`とは併用しない。

4. forDemo制約事項

4.1. 認証未導入に伴う自組織の判定

forDemoでは認証（auth-service連携）を導入せず、Row Level Security（RLS）も入れていないため、「自組織」はアプリ側の固定値（NoAuthActor.ORGANIZATION_ID）で判定する（AuthenticationSpecification_Flightplanning_forDemo.md2節、docs/implementation-guide.md 「RLS / マルチテナント対応（拡張ポイント）」）。

geospatial-api-design.md6.1は、旧USSのis_managedフラグを新APIではRLSによる透過的なフィルタで置き換えると記述しているが、RLSが入るまでは検索条件として明示的に絞り込む。認証連携の実装後にRLSへ寄せる。

4.2. ページング・ソート機能の非対応

ページング・ソートは提供しない。limitによる件数上限と、上限で切り詰めたことを示す totalCount/truncatedのみを提供する（5.1の1-3）。返却順は規定しない。

4.3. 未通報の自組織計画は`dipsFlightPlanId`で検索できない

dipsFlightPlanIdはDIPSへの通報後にDIPS側で払い出される識別子であり、reportRequired=trueかつ reportStatus=REPORTEDの計画のみが値を持つ。未通報の計画は本条件では検索できない。

4.4. 収集未実装に伴う空域制限データの直接投入

forDemoではDIPSからの空域制限の収集（UC-USP-03）を実装しない。アプリケーションが AIRSPACE_RESTRICTIONの行を作る経路がないため、データはDBへ直接投入して用意する（docs/data-model/airspace-er.mdの「スコープ」）。次の制約が生じる。

statusをDISAPPEAREDへ遷移させる主体がいないため、実データはACTIVEに限られる。 status=DISAPPEAREDを指定した検索は常に0件になる（5.3の1-2-2）
取得日時（鮮度）は提供しない。UC-PLAN-01-7は種別ごとに情報の鮮度を表示する補足を持つが、同補足は10月デモ実装対象外（飛行禁止エリアを収集せず取得日時が存在しないため）であり、 OASにも対応するプロパティがない
手動登録（sourceKind=MANUAL）の行は取得元の識別子を持たないため、externalIdが未設定になる

5. ユースケース毎の処理フロー

5.1. 自組織の飛行計画領域検索（POST /api/v1/geo/flight-plan-area/search）

自組織の飛行計画領域検索

1-1. 検索条件
- 以下の内容をAND条件で絞り込んだ飛行計画を対象とする。
  - 自組織のOperatorが登録した飛行計画であること（forDemoでは固定値で判定。4.1参照）
  - bboxが指定された場合、飛行領域FLIGHT_PLAN_AREA.plan_geometryが指定範囲と重なること（未指定の場合は条件なし）
  - currentTimeが指定された場合、planned_start_at <= currentTime AND planned_end_at >= currentTimeであること
  - currentTimeFrom/currentTimeToが指定された場合、planned_start_at <= currentTimeTo AND planned_end_at >= currentTimeFromであること
  - statusが指定された場合、FLIGHT_PLAN.statusが指定値のいずれかであること（未指定の場合は条件なし）
  - flightPlanIdが指定された場合、FLIGHT_PLAN.idが一致すること
  - dipsFlightPlanIdが指定された場合、当該飛行計画のDIPS_REPORT.dips_receipt_noが一致すること（同一計画の通報履歴が複数行あってもdips_receipt_noは不変で同一値になる。db/schema/flight_planning.sqlの列コメント「計画内では不変で再通報でも同一値のため、単独UNIQUE制約は置かない」）
- 1-1-1. 空間条件の判定対象
  - bboxとの重なりはFLIGHT_PLAN_AREA.plan_geometryで判定する。geometryはarea_type=CIRCLEのとき中心点のPointであり、「円の一部はbboxに重なるが中心は範囲外」の計画を取りこぼすためである（db/schema/flight_planning.sqlのidx_flight_plan_area_plan_geometryのコメント）。
- 1-1-2. 検索条件の必須要件
  - bbox・flightPlanId・dipsFlightPlanIdのうち少なくとも1つの指定を必須とする。すべて省略した組織内全件検索は許可しない。
- 1-1-3. DRAFTを指定した場合は常に0件になる
  - 一時保存中の飛行計画は飛行領域を正規化して保持せず（内容はFLIGHT_PLAN_DRAFT.draft_fieldsの jsonbにまとまっている）、検索対象となるFLIGHT_PLAN_AREAの行が存在しないためである。エラーとはしない。
  - DRAFT以外の値はいずれもFLIGHT_PLAN.statusに格納されうる。OASのFlightPlanStatusと flight_planning.flight_plan_status_typeはともに5値（DRAFT/ACCEPTED/ACTIVATED/ CANCELLED/ENDED）で一致しており、値域の差による該当0件は生じない。

1-2. 返却するFeatureへの展開

該当した飛行計画1件を、dataTypeとaltitudeReferenceの組み合わせごとに1件のFeatureへ展開する。 areaType=ROUTEは6件（dataType3種 × altitudeReference2種）、POLYGON/CIRCLEは4件（OPERATIONAL_INTENTが存在しないため2種 × 2種）となる。

1-2-1. dataTypeと元の列の対応

`dataType`	`altitudeReference=AGL`の元の列	`altitudeReference=WGS84`の元の列	返却条件
`FLIGHT_PLAN`	`plan_geometry`	`plan_geometry_wgs84`	常に返却する
`OPERATIONAL_INTENT`	`operational_intent_geometry`	`operational_intent_geometry_wgs84`	`area_type=ROUTE`の場合のみ（他は列がNULL）
`TOP_BOTTOM_3D`	`top_bottom_3d_geometry`	`top_bottom_3d_geometry_wgs84`	常に返却する

1-2-2. WGS84基準の形状の前提
- *_wgs84列は登録・収集の時点で充填済みであることを前提とする。本APIは応答のたびに標高（DEM）・ジオイド高を参照せず、実体化列をそのまま返す。充填処理は本APIの責務ではない（docs/data-model/followups.mdの「WGS84基準の形状（*_geometry_wgs84列）へ換算値を充填する処理」の行）。
1-2-3. Featureのプロパティ
- パラメータとデータベースカラムの項目単位の対応関係は geospatial-api-design.md5.1のマッピング表を参照。
- reportExemptionReason（通報義務なしの根拠）はreportRequired=falseの場合のみ返す。 FLIGHT_PLAN_DIPS_ATTRSは両列を縛るCHECK制約を持たず、通報要否がfalse→trueへ変わった計画に古い根拠が残りうるため、OASの契約に合わせて応答側で落とす。
- 空白のみの根拠は未設定として返す。同じくCHECK制約がなく保存されうるが、根拠として情報を持たないためである。1件の不整合で該当した他の計画まで返せなくなることを避ける。

1-3. 件数の上限と切り詰めの通知
- limit（既定1000・最大10000）は飛行計画の件数を数える。1件が複数のFeatureへ展開されるため、 features配列の要素数はlimitを上回りうる。
- totalCountにはlimit適用前の該当件数を、truncatedにはtotalCountがlimitを超えたかどうかを設定する。
1-4. エラーケースに合わせてステータスコードを返却する。
- 400: リクエストボディのパース失敗（不正なJSON・型不一致など）
- 401: 未認証（forDemoでは認証を導入しないため発生しない。4.1参照）
- 422: bboxが上限（幅50km・高さ50km・面積2500km²のいずれか）を超える、bboxの要素数が4でない、 currentTimeとcurrentTimeFrom/currentTimeToの同時指定、currentTimeFrom/currentTimeToの片方のみの指定、limitが1〜10000の範囲外、bbox・flightPlanId・dipsFlightPlanIdのすべてが未指定

5.2. 他Operatorの飛行計画領域検索（POST /api/v1/geo/flight-plan-area/others/search）

1. 他Operatorの飛行計画領域検索
- 1-1. 取得対象
  - DIPSから収集した飛行計画（DIPS_FLIGHT_PLAN）のみを対象とする。自社UTM内の他組織の飛行計画も、 DIPSへ通報されたものはDIPS収集経路で本テーブルに格納されるため、取得元は本テーブル1つに閉じる。 DIPSへ通報されていない他組織の飛行計画は対象外である。
  - 自組織がDIPSへ通報した飛行計画もDIPSからの収集結果に含まれうるため、 DIPS_FLIGHT_PLAN.dips_flight_plan_idが自組織のDIPS_REPORT.dips_receipt_noのいずれかと一致する行は結果から除外する（自組織の計画が「他Operator」として二重に表示されることを防ぐ）。
- 1-2. 検索条件
  - 5.1の1-1と同じ条件をAND結合で適用する。ただし次の差異がある。
    - statusによる絞り込みは行わない。DIPSの飛行計画参照APIは運航状態を返さず、UTM側で状態を保持していないためである。指定されても無視し、エラーとはしない。
    - flightPlanIdはDIPS_FLIGHT_PLAN.id（UTMが発行し、再収集のUPSERTでも同一値を保つID）と対応する。
    - dipsFlightPlanIdはDIPS_FLIGHT_PLAN.dips_flight_plan_idと対応する。5.1の1-1と異なり DIPS_REPORTを経由しない。
    - bboxとの重なりはDIPS_FLIGHT_PLAN.plan_geometryで判定する（理由は5.1の1-1-1と同じ）。
  - 検索条件の必須要件は5.1の1-1-2と同じ。
- 1-3. 返却するFeatureへの展開
  - 展開規則は5.1の1-2と同じだが、DIPS_FLIGHT_PLANはarea_typeがCIRCLE/POLYGONの2値で（flight_planning.dips_flight_plan_area_type）、operational_intent_geometryに相当する列を持たないため、dataType=OPERATIONAL_INTENTのFeatureは返却しない。1計画あたり常に4件となる。
  - 公開するプロパティはOtherFlightPlanAreaPropertiesに限る。createdBy・uasId等の内部IDと、通報情報（reportRequired/reportStatus/reportExemptionReason）は含まない。
  - statusは設定しない（1-2参照）。
- 1-4. 件数の上限と切り詰めの通知
  - 5.1の1-3と同じ。
- 1-5. エラーケースに合わせてステータスコードを返却する。
  - 5.1の1-4と同じ。

5.3. 空域制限検索（POST /api/v1/geo/airspace-restriction/{category}/search）

空域制限検索

1-1. 対象エンドポイントと制限分類

制限分類（AirspaceRestrictionType）ごとに独立したエンドポイントを持つ。検索条件・応答スキーマは全分類で共通で、categoryはリクエストボディに含まない（エンドポイント自体が分類を表す）。分類ごとに分ける根拠はgeospatial-api-design.md6.3節にある。

`category`	エンドポイント
`AIRPORT_VICINITY`	`POST /api/v1/geo/airspace-restriction/airport/search`
`SMALL_UAV_PROHIBITION_RED_ZONE`	`POST /api/v1/geo/airspace-restriction/red-zone/search`
`SMALL_UAV_PROHIBITION_YELLOW_ZONE`	`POST /api/v1/geo/airspace-restriction/yellow-zone/search`
`ORDINANCE_DESIGNATED_AREA`	`POST /api/v1/geo/airspace-restriction/ordinance/search`
`MANNED_AIRCRAFT_TAKEOFF_LANDING_AREA`	`POST /api/v1/geo/airspace-restriction/manned-airport/search`
`EMERGENCY_OPERATIONS_AIRSPACE`	`POST /api/v1/geo/airspace-restriction/emergency/search`
`OTHER_1`	`POST /api/v1/geo/airspace-restriction/other1/search`
`OTHER_2`	`POST /api/v1/geo/airspace-restriction/other2/search`

1-1-1. 人口集中地区は検索エンドポイントを持たない
- AirspaceRestrictionTypeは9値だが、DENSELY_INHABITED_DISTRICT（人口集中地区）は静的PMTiles アーカイブで配信するため検索の対象外である。AIRSPACE_RESTRICTIONに行も持たず、 db/schema/airspace_restriction.sqlのck_airspace_restriction_no_didが登録自体を禁じている（docs/data-model/airspace-er.mdの決定事項D2）。

1-2. 検索条件
- 以下の内容をAND条件で絞り込んだ空域制限を対象とする。
  - AIRSPACE_RESTRICTION.categoryがエンドポイントに対応する値であること
  - 形状AIRSPACE_RESTRICTION.geometryがbboxの範囲と重なること
  - AIRSPACE_RESTRICTION.statusがstatusと一致すること（未指定の場合はACTIVE。1-2-2参照）
  - validAtが指定された場合、valid_from <= validAt AND valid_to >= validAtであること
  - validFrom/validToが指定された場合、valid_from <= validTo AND valid_to >= validFromであること
- 1-2-1. bboxは必須である
  - 飛行計画領域検索（5.1の1-1-2）がbbox・flightPlanId・dipsFlightPlanIdのいずれか1つ以上を必須としているのに対し、本APIはbboxを単独で必須とする。ID指定で1件を引く検索経路を持たず、用途が地図の表示範囲の重畳表示に限られるためである（UC-PLAN-01-7の補足「飛行禁止エリアの情報は、画面の表示の範囲をフィルターする」）。
- 1-2-2. statusの既定値はACTIVEである
  - 未指定は「絞り込みなし」ではない。 省略時はACTIVEのみを対象とする（OASのdefault）。地図表示では現存する制限のみを見るのが通常であるためで、status未指定を「全件」と解釈する 5.1の1-1のstatusとは扱いが異なる。取得元から消失した制限を見るにはDISAPPEAREDを明示指定する。
  - forDemoではDISAPPEAREDの行は現れない（4.4参照）。
- 1-2-3. 空間条件の判定対象
  - bboxとの重なりは接尾辞のないAIRSPACE_RESTRICTION.geometryで判定する。GiSTインデックス（idx_airspace_restriction_geometry）が張られているのも本列である。geometry_wgs84は応答の組み立て専用で、検索条件には用いない。

1-3. 返却するFeatureへの展開

該当した空域制限1件を、altitudeReferenceごとに1件のFeatureへ展開する。飛行計画領域のようなdataTypeによる分岐は持たない。

1-3-1. altitudeReferenceと元の列の対応

`altitudeReference`	天面の元の列	天面を持たない場合の代替
`AGL`	`top_bottom_3d_geometry`の上面リング（`coordinates[0]`）	`geometry`
`WGS84`	`top_bottom_3d_geometry_wgs84`の上面リング（`coordinates[0]`）	`geometry_wgs84`

1-3-2. 応答のaltitudeReferenceは返却した形状の列で決まる
- AIRSPACE_RESTRICTION.altitude_referenceは接尾辞のない列のZ値が準拠する基準を示すもので、現時点では常にAGLである（同列のコメント。飛行計画のFLIGHT_PLAN_AREA.altitude_referenceと同じ扱い）。応答のFeatureを作り分けるフラグではなく、値をそのまま写してはならない。
- _wgs84列の基準は列名で自明なため、同列の対象外である。
1-3-3. 返却するのは天面のみである
- geometryは3D表示補助として天面（ceiling）を表し、水平方向は元の形状のまま返す。床面（floor）は返却せず、クライアント側で地表面に沿わせて表示する。
- geometryType=CIRCLEもPolygon近似で返す。元の中心・半径はcircleCenterLng/circleCenterLat/ circleRadiusMが保持する。
1-3-4. 2件を返すのが前提である
- _wgs84列は接尾辞のない列に対応して設定される列であり、1件の空域制限は2件のFeatureへ展開されるのが前提である。クライアントも両基準が返ることを前提に表示を切り替える。
- _wgs84列の充填は取得処理側の責務であり、本APIは換算を行わない（airspace-er.mdの「WGS84基準の形状も実体化列で持つ」）。
1-3-5. 過渡期に_wgs84列がNULLの行はAGLのFeatureのみを返す
- DDLが_wgs84列をNULL可としているのは、収集を実装するまでの過渡的な措置である（db/schema/airspace_restriction.sqlの列コメント。ck_airspace_restriction_geometry_wgs84・ ck_airspace_restriction_top_bottom_3d_wgs84も型・SRID・次元のみを保証し、接尾辞のない列との対応は強制しない）。
- NULLの行に遭遇した場合はWGS84のFeatureを組み立てられないため、AGLのFeatureのみを返す。 1件の欠落で検索結果全体を落とさないためであり、通常の姿ではない。
- この「全体を落とさない」は_wgs84列がNULLの場合に限る。 形状そのものを解釈できない行（面を持たないジオメトリ、geometry_typeと実ジオメトリの不一致など）は行単位で読み出しに失敗し、検索全体が失敗する。取得元が与えるデータを表示するだけの立場では欠落した1行を落として続ける方が整合するため（周辺計画収集も同じ軸で1件の除外を選んでいる）、方針を揃えるかは followups.mdに種別実体未作成で登録した。
- また、1件で返った行が「高度を持たない行」（1-3-6）なのか「_wgs84列がNULLの行」（本項）なのかを、クライアントが応答から区別する手段はない。信号の追加はOASの変更を伴うため、同じ論点を持つ他Operator計画検索と一体で決める（同じく台帳へ登録した）。
- OASのAirspaceRestrictionFeatureも「1件または2件」とし、本節および1-3-6に揃えてある。
1-3-6. 高度を持たない行は1件のFeatureのみを返す
- 高度の概念がない分類（レッドゾーン・イエローゾーン等）と、取得元が高度を提供しない行は、 geometryが2次元でmin/maxAltitudeMAglも未設定になる。水平形状は基準によって変わらないため、 AGLとWGS84で内容が一致する。この場合は1件のFeatureのみを返し、altitudeReferenceは設定しない（OASのAirspaceRestrictionProperties.altitudeReferenceが「geometryがZ値を持たない場合（高度の概念がない種別、および取得元が高度を提供しない場合）は未設定。」と定める）。
- 同一内容のFeatureを2件返しても、クライアントが区別できず情報が増えないためである。
- 空域制限の高度は取得元が提供する値であり、「地表から150mAGLまで」のような固定値は持たない。高度を持たない行は例外ではなく正規のデータである（airspace-er.mdの決定事項D3）。
1-3-7. Featureのプロパティ
- パラメータとデータベースカラムの項目単位の対応関係は geospatial-api-design.md5.2のマッピング表を参照。
- externalIdは取得元の識別子を持つ行のみ返す。手動登録（sourceKind=MANUAL）の行は持たない。
- externalTypeIdに相当するプロパティは公開しない（airspace-er.mdの決定事項D6）。

1-4. 件数の上限と切り詰めの通知
- limit（既定1000・最大10000）は空域制限の件数を数える。1件が複数のFeatureへ展開されるため、 features配列の要素数はlimitを上回りうる。
- totalCountにはlimit適用前の該当件数を、truncatedにはtotalCountがlimitを超えたかどうかを設定する。
1-5. エラーケースに合わせてステータスコードを返却する。
- 400: リクエストボディのパース失敗（不正なJSON・型不一致など）
- 401: 未認証（forDemoでは認証を導入しないため発生しない。4.1参照）
- 422: bboxが上限（幅50km・高さ50km・面積2500km²のいずれか）を超える、bboxの要素数が4でない、 bboxが未指定、validAtとvalidFrom/validToの同時指定、validFrom/validToの片方のみの指定、 limitが1〜10000の範囲外