コンテンツにスキップ

フィードバック記録

メソッド

RESTメソッドを採用しています。

HTTPメソッド

POST: 完了した wf2des 生成に対するデザイナーのフィードバックを記録する。

フィードバックは記録のみです。wf2des 行に feedbackStatus を刻印し、生成されたデザインがどのように受け入れられたか（利用前に手動で修正されたか、そのまま採用されたか）を利用者が確認できるようにします。SQSメッセージは送信されず、webhook も発火せず、後続の生成実行もトリガーされません。生成そのものは変更されません。

命名規則

一貫性と可読性を確保するため、リクエストとレスポンスのJSONノードにはcamelCaseを使用します。SQSペイロードのノードにはsnake_caseを使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダーに設定されます。

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

フィードバック記録

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/{wf2des_id}/feedback

パスパラメータ

Name Type Required Description
organization_id integer Required 組織ID
project_id integer Required プロジェクトID
wf2des_id string Required wf2des ID

リクエストボディ

リクエストボディはJSONです。

{
  "feedbackStatus": "0"
}

リクエストパラメータ

Name Type Required Description
feedbackStatus string (enum) Required 生成されたデザインがどのように受け入れられたか。"0" fixed（手動修正後に採用）／ "1" adopted（そのまま利用）。それ以外の値は400。

このエンドポイントが運ぶのはフラグのみです。フィードバックの詳細（{status, changed_nodes[], diff_url, at, by}）は、このエンドポイントが呼び出される前に、プラグインによって wf2des-api へ直接（POST /internal/wf2des/{wf2des_id}/feedback）書き込まれます — 詳細を先に・フラグを後に（detail first, flag last）。詳細がこのエンドポイントを通ることは決してありません（バックエンドのサービストークンはデータプレーンに対して read-only です）。処理フローを参照してください。

レスポンス

レスポンスはJSONです（HTTPステータス: 200 OK）。

{
  "wf2desId": "8f14e45f-ceea-467d-9a3e-1b2c3d4e5f60",
  "status": "1",
  "phase": null,
  "feedbackStatus": "0",
  "attempt": 1,
  "recordedAt": "2026-07-10T09:30:00Z"
}

レスポンスフィールド

Name Type Description
wf2desId string wf2des ID
status string (enum) 生成ステータス — フィードバックでは変更されません。フィードバックは完了した実行（"1"）に対してのみ記録されます。
phase string | null 生成フェーズ — 完了した実行では null（フィードバックはこれに触れません）。
feedbackStatus string (enum) 刻印された値 — "0" fixed ／ "1" adopted。
attempt integer 実行のフェンシングカウンタ（フィードバックでは変更されません）。
recordedAt string feedback_status が刻印されたときの ISO 8601 タイムスタンプ（updatedAt のミラー）。

ステータス / フェーズの enum（wf2des 行）:

  • status: "0" processing · "1" completed · "2" failed · "3" rejected · "4" cancelled
  • phase（status "0" 内、終了状態になると null）: "0" parse · "1" awaiting_confirm · "2" assemble
  • feedbackStatus: "0" fixed · "1" adopted

フィードバックは最終書き込みによる冪等（idempotent by last-write）です。フィードバックを再記録すると、以前の feedbackStatus が上書きされ（プラグインは同じ方法で wf2des-api を介して詳細を再書き込みします）、現在の値とともに 200 OK を返します。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）を使用して実行されます。

プロジェクトへの Write アクセス権を持つ認証済みセッションであれば、フィードバックを記録できます — 生成をトリガーしたセッションに限定されません。フィードバックの詳細は、このエンドポイントが行を刻印する前に、プラグインによって wf2des-api データプレーンを介して design_generation_result ドキュメントに書き込まれます。

例外処理

例外処理のステータスコードは以下の通りです。

Description Status Code Status Name
feedbackStatus の欠落または無効（不在、または "0" / "1" 以外） 400 Bad Request
認証情報の欠落 401 Unauthorized
権限不足 403 Forbidden
wf2des、プロジェクト、または組織が見つかりません 404 Not Found
内部サーバーエラー 500 Internal Server Error

フィードバックは完了した実行（status "1"）に対してのみ受け付けられます。完了していない行はフィードバックの観点では見つからないものとして扱われ、404 を返します — processing、failed、rejected、または cancelled の生成に対してフィードバックは意味を持ちません。

処理フロー

バックエンドが wf2des PostgreSQL 行を所有し、唯一の書き込み者です。フィードバックの記録は、バックエンド側で適用される単一のdetail-first-flag-lastシーケンスです — worker は PostgreSQL の認証情報を保持せず、一切関与しません。SQSメッセージは送信されず、webhook も発火せず、後続の実行もトリガーされません。エンドポイントは完了した行とその結果ドキュメントに注釈を付けるだけです。

  1. パスパラメータから組織ID、プロジェクトID、wf2des_id を抽出し、リクエストボディから feedbackStatus を抽出する。
  2. ユーザーがプロジェクトへの Write アクセス権を持つことを確認する。
  3. feedbackStatus（"0" fixed ／ "1" adopted）を検証し、不在または不明な値の場合は 400 を返す。
  4. wf2des 行をロードする。存在しない、ソフト削除されている、または organization_id / project_id がパスと一致しない場合は 404 を返す。
  5. 行が status "1" completed であることを確認する。それ以外の状態の場合は 404 を返す（フィードバックは完了した実行にのみ適用される）。
  6. Detail first（前提条件）。 フィードバックの詳細 — feedback ブロック（{status, changed_nodes[], diff_url, at, by}、artifact_urls.feedback_diff から参照）— は、この呼び出しの前にプラグインによって wf2des-api へ直接書き込み済みである。詳細をフラグより先に書くことで、フラグが立った行には常にフィードバック詳細が存在することが保証される。このエンドポイントは詳細を受け付けることも永続化することもない。
  7. Flag last。 1つの PostgreSQL トランザクションで wf2des 行に feedback_status を刻印する（updated_at / updated_by も刻印）。status、phase、attempt は変更されない。
  8. 刻印された feedbackStatus とともに行を返す。

再記録すると、以前の詳細ドキュメントが上書きされ、feedback_status が再刻印される（last-write-wins）。フィードバックは記録のみであるため、attempt に対する compare-and-set はありません — フラグは、完了した実行に対して記録された最新のフィードバックを単に反映するだけです。

詳細フローチャート

flowchart TD
    Start([POST /feedback]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Write Access?}
    HasAccess -->|No| Err403[403 Forbidden]
    HasAccess -->|Yes| Validate[Validate Body<br/>feedbackStatus '0' fixed / '1' adopted]

    Validate --> BodyValid{Valid?}
    BodyValid -->|No| Err400[400 Bad Request]
    BodyValid -->|Yes| LoadRow[Load wf2des Row<br/>WHERE id = :wf2des_id]

    LoadRow --> RowExists{Exists &<br/>org/project match?}
    RowExists -->|No| Err404[404 Not Found]
    RowExists -->|Yes| Completed{status '1'<br/>completed?}

    Completed -->|No| Err404
    Completed -->|Yes| DetailNote[Detail precondition<br/>the plugin has already written the<br/>feedback detail via wf2des-api]

    DetailNote --> FlagLast[Flag last<br/>stamp feedback_status in one PG txn<br/>status / phase / attempt untouched]

    FlagLast --> FlagResult{Success?}
    FlagResult -->|No| Err500[500 Internal Server Error]
    FlagResult -->|Yes| Success[200 OK<br/>row with feedbackStatus stamped]