調整依頼実行画面 調整依頼内容の文章化(condition_text)利用方法
調整依頼実行画面(依頼側)で、ユーザーが画面上で入力した調整条件を、送信前の確認用に文章化して表示するためのAPI利用方法(手順)を示す。
issue #74(調整条件の説明文字列組み立てAPI追加、本来の用途である依頼実行側での利用)を参照。
調整依頼回答画面(受信側)での同APIの流用については Coordination_ResponseScreen_ConditionText.md(issue #92)を参照。
1.1. 画面表示条件
Section titled “1.1. 画面表示条件”調整依頼実行画面は、以下のいずれかの条件で表示可能(docs/coordination/CoordinationStatus_MappingTable_forDisplay.md 参照)。
| 参照元API | 参照フィールド | 状態対応表No | context_idの状態 |
|---|---|---|---|
GET /api/v1/coordination/conflictions | coordination_request_possible_flag = true | 1-A | 未発行(context_idフィールドが未設定) |
GET /api/v1/coordination/coordinations | request_possible_flag = true | 2-A / 9-A | 発行済み(context_idが設定済み) |
Sprint2の実装範囲はシングルターン(protocol_type = SINGLE_TURN)のみのため、対応表上の他のフラグtrueパターン(5-C/6-D、マルチターン専用)は本Sprintでは対象外。
TODO(#333)
重複情報一覧からの新規調整依頼(No.1-A)や、否認・期限切れ後の再調整依頼(No.9-A。合意に至るまで否認→再調整を繰り返すパターンとして実運用・デモの両方で発生する想定)は実運用で発生する。一方、No.2-Aは以下のとおり実運用ではほぼ発生しない想定の状態である。
- No.2-A: 調整依頼の開始API(
coordinate-initiations)実行後、調整依頼の実行API(coordinate-requests)が何らかの理由(通信エラー等)で未完了のまま画面を離脱・再表示した場合にのみ発生し得る。
1.2. coordinate-initiations と coordinate-requests の実行タイミングについて
Section titled “1.2. coordinate-initiations と coordinate-requests の実行タイミングについて”coordinate-initiations(調整依頼の開始)とcoordinate-requests(調整依頼の実行)は、以下の設計意図によりAPIを分割している。
- 調整依頼は否認→再調整を繰り返すケースがあるため、1回のみ送信すればよい情報(
protocol_type・session_interval)を再調整のたびに毎回送りたくない。そのため、1回のみ送ればよい情報はcoordinate-initiationsで、依頼のたびに送る情報(condition等)はcoordinate-requestsで送信する形にAPIを分割している。 - 重複相手とお互いが同時に調整依頼する可能性を考慮すると、どちらが調整依頼側(コンテキストオーナー)の立場になるかを確定するタイミングが必要になる。調整条件の検討には時間がかかることを踏まえると、この確定は
coordinate-requests(調整依頼の実行)のタイミングで行うのが望ましい(お互いが同時実行するケースでなければ、先に調整依頼を送った側が調整依頼側の立場で確定する)。 - Sprint2(10月デモ向け実装)では、お互いが同時に調整依頼を実行した場合のコンテキストオーナー変更のロジックは実装対象外であり、運用上同時実行が起きないよう回避する想定(重複相手側のNTT-DATA様とも合意済み)。
TODO(#335)
上記のとおり、コンテキストオーナーの確定はcoordinate-requests実行のタイミングで行われる設計のため、ユーザーが画面上で調整条件の入力・確認(プレビュー表示)まで完了させたうえで、「調整依頼実行」ボタン押下時に coordinate-initiations(context_id未発行の場合のみ)→ coordinate-requests を連続実行する。
なお、condition-texts(プレビュー用API)はcontext_idを必要としないため、context_id発行前でも条件入力と並行して自由に呼び出せる。
2.1. 画面上で調整条件(condition)を入力する
Section titled “2.1. 画面上で調整条件(condition)を入力する”ユーザーが画面上で調整条件を入力し、coordination_condition スキーマ(docs/openapi/openapi_coordination_backend.yaml)に沿った condition オブジェクトを組み立てる(この組み立て自体はフロントエンド側の実装範囲)。
Sprint2で文章化APIが対応しているのは type = move_from_here のみ。入力例:
{ "type": "move_from_here", "$and": [ { "conditions": [ { "start_time": { "value": "2027-05-12T11:30:00Z", "format": "RFC3339" }, "end_time": { "value": "2027-05-12T12:30:00Z", "format": "RFC3339" } }, { "min_flight_altitude": { "value": 100, "reference": "W84", "units": "M" }, "max_flight_altitude": { "value": 120, "reference": "W84", "units": "M" } }, { "outline_circle": { "center": { "lat": 35.681236, "lng": 139.767125 }, "radius": { "value": 500, "units": "M" } } } ] } ]}2.2. 入力した condition を condition-texts API へ渡し、プレビュー表示する
Section titled “2.2. 入力した condition を condition-texts API へ渡し、プレビュー表示する”2.1 で組み立てた condition を、そのまま POST /api/v1/coordination/condition-texts の condition に指定して呼び出す。context_idは不要なため、この時点でcontext_idが未発行(No.1-A)でも呼び出し可能。ユーザーが条件入力を変更するたびに、何度呼び出してもよい(副作用のない参照系API)。
POST /api/v1/coordination/condition-texts{ "condition": { /* 2.1 と同一のオブジェクト */ }}レスポンス例:
{ "condition_text": "Please move the flight plan so that it avoids the following range:\nTime: May 12, 2027, 11:30 UTC to May 12, 2027, 12:30 UTC AND Altitude: 100 to 120 M AND Area: within 500 M of (35.681236, 139.767125)"}condition_text を、調整依頼の送信確認画面(ユーザーが送信前に内容を確認するダイアログ等)に表示する。
2.3. ユーザーが「調整依頼実行」ボタンを押下したら、(A)(B)を連続実行する
Section titled “2.3. ユーザーが「調整依頼実行」ボタンを押下したら、(A)(B)を連続実行する”ユーザーが内容を確認し送信を確定した時点で初めて、以下を連続して実行する。
(A) (context_id が未発行の場合のみ) 調整依頼を開始する
Section titled “(A) (context_id が未発行の場合のみ) 調整依頼を開始する”直前に取得した confliction_record の context_id が未設定(No.1-A)の場合のみ実行する。既に発行済み(No.2-A/9-A)の場合はこのステップをスキップする。
POST /api/v1/coordination/coordinate-initiations{ "self_flight_plan_id": "AAAAAAAAAAAAAAAAAAA.FP20221125042709013.001", "opponent_flight_plan_id": "BBBBBBBBBBBBBBBBBBB.FP20221125042709013.001", "protocol_type": "SINGLE_TURN", "session_interval": 10}レスポンス例:
{ "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "context_id": "03e5572a-f733-49af-bc14-8a18bd53ee39"}protocol_type は一度設定すると変更不可のため、Sprint2の画面では SINGLE_TURN 固定で送信する想定(UI上でユーザーに選択させない)。
session_interval(否認後、再調整依頼が可能になるまでの待機時間)は、実運用では、状況が変わっていないのに間を置かず連続で調整依頼を送られると相手側の迷惑になるため、数日程度の間隔を想定している。一方、10月デモでは限られた時間内で状態が変化していく様子を見せる必要があるため、数十秒程度の値を設定する想定。Sprint2時点では暫定値(上記例では10秒)であり、デモ内容に合わせて今後調整予定。
(B) 続けて、調整依頼を実行する
Section titled “(B) 続けて、調整依頼を実行する”(A) で採番した context_id(またはNo.2-A/9-Aの場合は既存の context_id)を使用し、間を置かず実行する。
POST /api/v1/coordination/coordinate-requests{ "self_flight_plan_id": "AAAAAAAAAAAAAAAAAAA.FP20221125042709013.001", "opponent_flight_plan_id": "BBBBBBBBBBBBBBBBBBB.FP20221125042709013.001", "context_id": "03e5572a-f733-49af-bc14-8a18bd53ee39", "condition": { /* 2.1・2.2 と同一のオブジェクト */ }}レスポンス例:
{ "session_id": 1747044000000, "turn_id": 1747045800000}重要: condition-texts(2.2)と coordinate-requests((B))には、必ず同一の condition オブジェクトを渡すこと。内容が食い違うと、画面に表示した確認文言と、実際に相手へ送信される調整条件が一致しなくなる。
2.4. (参考) 実行後の画面遷移
Section titled “2.4. (参考) 実行後の画面遷移”送信成功後は、display_status が「調整回答待ち(Waiting for coordination response、No.5-A)」の状態になる。画面は運航調整情報一覧・詳細画面等へ遷移し、以降は GET /api/v1/coordination/coordinations の再取得により状態を反映する。
3. シーケンス図
Section titled “3. シーケンス図”sequenceDiagram
participant UI as 調整依頼実行画面(Frontend)
participant BE as UTM Backend
UI->>BE: GET /api/v1/coordination/conflictions (または /coordinations)
BE-->>UI: 200 OK (request_possible_flag系=true)
UI->>UI: ユーザーが調整条件(condition)を入力
UI->>BE: POST /api/v1/coordination/condition-texts (condition)
BE-->>UI: 200 OK (condition_text)
UI->>UI: condition_text を確認画面に表示(入力変更のたびに再実行可)
Note over UI: ユーザーが「調整依頼実行」ボタンを押下
alt context_id 未発行 (No.1-A)
UI->>BE: POST /api/v1/coordination/coordinate-initiations
BE-->>UI: 201 Created (context_id)
else context_id 発行済み (No.2-A/9-A)
Note over UI: 既存のcontext_idをそのまま使用
end
UI->>BE: POST /api/v1/coordination/coordinate-requests (context_id, condition)
BE-->>UI: 201 Created (session_id, turn_id)
4. 注意事項
Section titled “4. 注意事項”coordinate-initiationsとcoordinate-requestsは、ユーザーの「調整依頼実行」ボタン押下時に連続実行し、間に他の処理(画面遷移・追加の入力待ち等)を挟まないこと。理由は1.2節を参照(コンテキストオーナーの確定がcoordinate-requests実行のタイミングで行われる設計のため)。- Sprint2(10月デモ向け実装)では、お互いが同時に調整依頼を実行した場合のコンテキストオーナー変更を解決するロジックは実装対象外。運用上、重複相手側と調整依頼が同時実行にならないよう回避する想定(NTT-DATA様と合意済み)のため、画面側でも同時実行を誘発する操作(同一重複に対する複数タブでの並行操作等)は避けることが望ましい。
condition-textsAPI は現状condition.type = move_from_hereのみ文字列組み立てロジックを実装している。それ以外のtype(avoid_overlap等)を画面上で選択可能にする場合、そのtypeをcondition-textsに指定すると400が返るため、プレビュー表示は提供できない(今後のスプリントで対応予定。それまでは当該type選択時はプレビューをスキップする等の画面側の考慮が必要)。condition-textsAPI は副作用を持たない参照系API(DB更新・対向UTMへの通知は行わない)。coordinate-initiations/coordinate-requestsは、重複が既に解消済み・調整期限切れ等の理由で406(CoordinationStartNotAcceptable/CoordinationRequestNotAcceptable)を返すことがある。画面側では406受信時、reasonフィールドの内容をユーザーに提示した上で、重複情報・運航調整情報を再取得し最新状態の画面へ遷移する想定。protocol_typeは運航調整情報の作成時(coordinate-initiations)に一度設定すると変更不可。Sprint2ではSINGLE_TURN固定で送信する。
TODO(#335)