外部AI連携向けに提出物コメントAPIを整備する

[komagata]

機能の説明

外部AIエージェントが提出物にコメントできるように、提出物コメント用のAPIを整備する。

現状でも汎用コメントAPIで提出物へのコメント作成は可能。

• POST /api/comments?commentable_type=Product&commentable_id=:product_id
• パラメータ: comment[description]
• Bearer token が必要
• 作成・更新・削除には write scope が必要

ただし、外部AI連携の用途では以下の点が扱いづらい。

• 提出物専用のエンドポイントではなく、commentable_type=Product を指定する汎用APIになっている
• 外部クライアントが Rails 側のモデル名 Product を知っている必要がある
• API::CommentsController#create の成功レスポンスが JSON API として扱いやすい形ではなく、HTML partial を返す実装になっている
• 失敗時のエラー形式が外部クライアント向けに十分整理されていない

候補:

• POST /api/products/:product_id/comments のような提出物専用JSON APIを追加する
• 既存 POST /api/comments は維持しつつ、提出物IDで自然に扱えるAPIを追加する
• 成功時に作成されたコメント情報をJSONで返す

何故この機能が必要なのか

pjord/hermes agent が提出物レビューを行う場合、提出物本文を読んだうえでレビューコメントを投稿できる必要がある。

現状の汎用コメントAPIでも実現はできるが、外部クライアントに内部モデル名を要求し、成功レスポンスも機械処理に向いていないため、AI連携の基盤としては提出物専用APIまたはJSON応答の整備が必要。

受け入れ条件

• 外部クライアントが Bearer token で認証し、提出物IDと本文を指定してコメントを作成できる
• 成功時は作成されたコメントの id, description, commentable_type, commentable_id, user, created_at, updated_at などをJSONで返す
• 権限不足、存在しない提出物、本文未入力などの失敗時に、機械処理しやすいステータスコードとJSONエラーを返す
• integration test で提出物へのコメント作成、scope不足、validation error を確認する

関連コード

• config/routes/api.rb: resources :comments, only: %i(index create update destroy), resources :products, only: %i(index show)
• app/controllers/api/comments_controller.rb
• app/controllers/api/products_controller.rb
• app/models/comment.rb
• app/models/product.rb
• test/integration/api/comments_test.rb