自動修正(issue #112) API利用方法
重複情報一覧・調整依頼回答画面まわりで、自動修正機能(issue #100・issue #112)に関連する新規APIをフロントエンドから利用する方法(手順)を示す。
issue #112(運航調整機能 自動修正(AI提案)機能のコンポーネント間フロー整理)を参照。
- 自動提案API(AIによる自動生成)は10月デモでは実装しない。修正後の飛行計画情報は実行者が事前に用意し、AWS上のデモ用クライアント環境(
demo-001-coordination-client)からCurlで手動登録する。 - 下記2APIは10月デモでは画面を持たず、Curlによる手動実行のみを想定する(フロントエンド側の実装対象外)。
PATCH /api/v1/coordination/conflictions/auto-coordination-setting(自動調整設定の切り替え。自動修正フラグauto_correction_flagを含む)POST /api/v1/coordination/auto-correction-proposals(飛行計画自動修正案の登録)
- 上記の登録APIは、Outlookカレンダーの変更を契機に自動修正案を自動生成するLambdaからも同じ形で呼び出される想定(issue #149、認識合わせ中)。フロントエンド側の呼び出し方には影響しないが、この場合は登録時に変更案生成理由(
generation_reason)が指定されうる(2.3節参照)。 - フロントエンドが呼び出すのは、下記2APIのみ。
GET /api/v1/coordination/auto-correction-proposals/{id}(飛行計画自動修正案の取得)PATCH /api/v1/coordination/auto-correction-proposals/{id}(飛行計画自動修正案への回答)
- 画面表示条件:
GET /api/v1/coordination/conflictionsのレスポンスのauto_correction_proposal_exists_flagがtrueの行にのみ、「AIからの提案を確認」ボタンを表示する。 - 提案確認画面の操作は「採用」(英語表記:
Accept)「修正して採用」(Edit & Accept)「却下」(Reject)の3つを画面上に用意するが、10月デモで実際に動作するのは「採用」のみ。「修正して採用」「却下」はボタンを表示するが、押下しても本ドキュメントのAPIは呼ばれない(issue #112コメント参照。将来対応の積み残し事項)。
TODO(#338)
2.1. 重複情報一覧を取得し、ボタンの表示可否を判定する
Section titled “2.1. 重複情報一覧を取得し、ボタンの表示可否を判定する”GET /api/v1/coordination/conflictions を実行する(通常の重複情報一覧表示と同じタイミング)。
GET /api/v1/coordination/conflictions?self_flight_plan_id=AAAAAAAAAAAAAAAAAAA.FP20221125042709013.001レスポンス例(該当項目抜粋):
{ "auto_correction_flag": true, "auto_correction_proposal_exists_flag": true, "auto_correction_proposal_id": "9f1c2b3a-4d5e-4f6a-8b7c-1a2b3c4d5e6f"}auto_correction_proposal_exists_flag が true の行にのみ「AIからの提案を確認」ボタンを表示する。
2.2. 飛行計画自動修正案を取得する
Section titled “2.2. 飛行計画自動修正案を取得する”ユーザーが「AIからの提案を確認」ボタンを押下したら、2.1で取得した auto_correction_proposal_id を指定して取得する。
GET /api/v1/coordination/auto-correction-proposals/9f1c2b3a-4d5e-4f6a-8b7c-1a2b3c4d5e6fレスポンス例:
{ "id": "9f1c2b3a-4d5e-4f6a-8b7c-1a2b3c4d5e6f", "confliction_id": "6f2c9a1e-4b7a-4e3f-9c2a-1a2b3c4d5e6f", "flight_plan": { "flightPlanId": "550e8400-e29b-41d4-a716-446655440000", "status": "ACCEPTED", "reportRequired": true, "reportStatus": "UNREPORTED", "dipsFlightPlanId": "O40SIFXUOCCAAXXTJXNZ.FP20250221050353423.001", "conflict": null, "flightPlan": { "name": "サンプル飛行計画", "flyRoute": { "type": "circle", "geometry": { "type": "Point", "coordinates": [141.3548784, 43.0604674] }, "radiusM": 50 } }, "createdAt": "2027-05-12T11:00:00.000Z", "updatedAt": "2027-05-12T11:30:00.000Z" }, "generation_reason": "Outlookカレンダーの予定変更(開始時刻 10:00→11:00)を検知し、相手の要求時間帯との重複が解消されるため生成", "adoption_status": "Undecided", "execution_status": "NotStarted", "created_at": { "value": "2027-05-12T11:30:00Z", "format": "RFC3339" }, "updated_at": { "value": "2027-05-12T11:30:00Z", "format": "RFC3339" }}flight_plan は、UTM Backendsの飛行計画詳細取得API(GET /api/v1/fp/flight-plans/{flightPlanId})のレスポンス(FlightPlanDetailResponse)と同形式。既存の飛行計画詳細画面のパース実装をそのまま流用できる(issue #112での合意事項)。
2.3. 修正案を画面表示する
Section titled “2.3. 修正案を画面表示する”専用の読み取り専用画面で、現在の飛行計画(flight_planの元になった飛行計画)との新旧比較・地図表示を行う。
修正案を生成した理由の自然文は、generation_reason(変更案生成理由、issue #149)として返る場合がある。登録側の任意項目のため、Curlによる手動登録では通常指定されず、その場合はレスポンスにgeneration_reasonキー自体が含まれない。したがって画面側は、
- キーが存在する場合のみ理由を表示する(表示位置・体裁はフロントエンド側の判断でよい)
- キーが存在しない場合は、従来どおり項目の新旧比較のみを表示する
の2通りに対応する必要がある(値はバックエンドで解釈しない自然文であり、決まった書式は持たない)。
2.4. 「採用」ボタン押下時、回答APIを呼ぶ
Section titled “2.4. 「採用」ボタン押下時、回答APIを呼ぶ”PATCH /api/v1/coordination/auto-correction-proposals/9f1c2b3a-4d5e-4f6a-8b7c-1a2b3c4d5e6f{ "result": "Adopt"}成功時、更新後の飛行計画自動修正案レコード(adoption_status = Adopted)が200で返る。この1回の呼び出しで、調整相手への合意回答・UTM側の飛行計画更新・DIPS通報までが(バックエンド側の処理として)完了する想定(execution_statusの遷移はバックエンド内部の進行管理のためのものであり、フロントエンド側で個別に判定する必要はない。最終的に200が返ってくれば完了とみなしてよい)。
承認後は調整依頼回答画面の遷移元(飛行計画編集画面)へ戻る想定(issue #112合意事項)。
3. シーケンス図
Section titled “3. シーケンス図”sequenceDiagram
participant UI as 調整依頼回答画面(Frontend)
participant BE as UTM Backend
participant Opp as 調整相手(UTM)
UI->>BE: GET /api/v1/coordination/conflictions
BE-->>UI: 200 OK (auto_correction_proposal_exists_flag=true)
Note over UI: 「AIからの提案を確認」ボタンを表示
UI->>BE: GET /api/v1/coordination/auto-correction-proposals/{id}
BE-->>UI: 200 OK (flight_plan, adoption_status=Undecided,<br/>generation_reason=登録時に指定があった場合のみ)
UI->>UI: 現在の飛行計画との新旧比較・地図表示
Note over UI: ユーザーが「採用」を選択
UI->>BE: PATCH /api/v1/coordination/auto-correction-proposals/{id} (result=Adopt)
BE->>Opp: 合意回答 (PATCH coordinate-responses と同様の動作)
BE->>BE: UTM側飛行計画更新・DIPS通報(10月デモではダミー実装)
BE-->>UI: 200 OK (adoption_status=Adopted)
Note over UI: 遷移元(飛行計画編集画面)へ戻る
4. 注意事項
Section titled “4. 注意事項”PATCH /api/v1/coordination/conflictions/auto-coordination-settingとPOST /api/v1/coordination/auto-correction-proposalsは、フロントエンド側で呼び出す必要はない(Curlによる手動実行のみ)。PATCH /api/v1/coordination/auto-correction-proposals/{id}のresultは10月デモではAdopt固定。他の値は現状APIとして定義していない。- 406エラー(
reason=ALREADY_DECIDED)は、対象の飛行計画自動修正案が既に採用/不採用が決定済みの場合に返る(二重送信等)。受信した場合は、重複情報・飛行計画自動修正案を再取得し、最新状態に応じた画面へ遷移する想定。 execution_statusの中間状態(NotStarted/AgreementDone/UtmUpdateDone)は、自動修正案回答APIが再実行された際にバックエンド側で完了済み処理をスキップするための内部状態であり、フロントエンド側で個別に出し分ける必要はない。- 「修正して採用」「却下」ボタンの実際の動作(対応するAPI呼び出し)は、10月デモでは未定義。将来対応の積み残し事項。
TODO(#338)