調整依頼回答画面 調整依頼内容の文章化(condition_text)利用方法
調整依頼回答画面(受信側)で、相手から受信した調整依頼内容を文章化して表示するためのAPI利用方法(手順)を示す。
issue #74(依頼実行側の調整条件の説明文字列組み立てAPI追加)・issue #92(本手順の対象、受信側での同APIの流用)を参照。
1. 前提: 画面表示条件
Section titled “1. 前提: 画面表示条件”調整依頼回答画面は、GET /api/v1/coordination/coordinations のレスポンスの response_possible_flag が true の場合のみ表示可能(docs/coordination/CoordinationStatus_MappingTable_forDisplay.md の No.5-E/6-A、display_status = Coordination response in progress)。
このタイミングでは、相手から受信した調整依頼のターン(turn_status = Proposed)が必ず存在し、body.condition も設定されている。
2.1. 運航調整情報を取得する
Section titled “2.1. 運航調整情報を取得する”GET /api/v1/coordination/coordinations を実行し、回答対象ターンの運航調整情報を取得する。パラメータは、重複一覧画面などから遷移する際に保持している self_flight_plan_id / opponent_flight_plan_id / context_id の組み合わせ(パターンA)、または context_id のみ(パターンB)のいずれかを使用する。
GET /api/v1/coordination/coordinations?context_id=03e5572a-f733-49af-bc14-8a18bd53ee39レスポンス例(配列の該当ターンの要素):
{ "id": "6f2c9a1e-4b7a-4e3f-9c2a-1a2b3c4d5e6f", "context_id": "03e5572a-f733-49af-bc14-8a18bd53ee39", "self_flight_plan_id": "AAAAAAAAAAAAAAAAAAA.FP20221125042709013.001", "opponent_flight_plan_id": "BBBBBBBBBBBBBBBBBBB.FP20221125042709013.001", "self_side": "RESPONDER", "display_status": "Coordination response in progress", "request_possible_flag": false, "response_possible_flag": true, "body": { "condition": { "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" } } } ] } ] } }}self_side(依頼者/調整対象者いずれの立場か)に関わらず、body.condition には同じ形式で調整条件が設定されている。
2.2. 取得した condition を condition-texts API へ渡す
Section titled “2.2. 取得した condition を condition-texts API へ渡す”2.1 で取得した body.condition を、そのまま POST /api/v1/coordination/condition-texts の condition に指定して呼び出す。
POST /api/v1/coordination/condition-texts{ "condition": { "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" } } } ] } ] }}レスポンス例:
{ "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)"}2.3. condition_text を画面に表示する
Section titled “2.3. condition_text を画面に表示する”2.2 のレスポンスの condition_text を、調整依頼回答画面に表示する(issue #74 で依頼実行側の確認画面に表示しているものと同じ文字列形式)。
2.4. 回答結果の送信(参考・本対応による変更なし)
Section titled “2.4. 回答結果の送信(参考・本対応による変更なし)”ユーザーが合意/否認を選択した後は、従来通り PATCH /api/v1/coordination/coordinate-responses を実行する。
3. シーケンス図
Section titled “3. シーケンス図”sequenceDiagram
participant UI as 調整依頼回答画面(Frontend)
participant BE as UTM Backend
UI->>BE: GET /api/v1/coordination/coordinations?context_id=...
BE-->>UI: 200 OK (body.condition を含む)
UI->>UI: レスポンスから body.condition を抽出
UI->>BE: POST /api/v1/coordination/condition-texts (condition)
BE-->>UI: 200 OK (condition_text)
UI->>UI: condition_text を画面表示
Note over UI: ユーザーが合意/否認を選択
UI->>BE: PATCH /api/v1/coordination/coordinate-responses (result)
BE-->>UI: 200 OK
4. 注意事項
Section titled “4. 注意事項”condition-textsAPI は現状condition.type = move_from_hereのみ文字列組み立てロジックを実装している。それ以外のtype(avoid_overlap等)を指定した場合は 400 が返る(今後のスプリントで対応予定)。condition-textsAPI はconditionが必須パラメータ。body.conditionが存在しないターン(合意/否認等)に対して呼び出すと 400 が返るが、前提の通りresponse_possible_flag = trueのタイミングでのみ本画面を表示する想定のため、通常このケースは発生しない。condition-textsAPI は副作用を持たない参照系API(DB更新・対向UTMへの通知は行わない)。同じconditionを指定すれば常に同じcondition_textが返る。