外部AI連携向けに日報コメントAPIを整備する

[komagata]

機能の説明

外部のAIエージェントから日報にコメントできるように、日報コメント用のAPIを整備する。

現状でも汎用コメントAPIで日報へのコメント作成は可能。

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

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

• 日報専用のエンドポイントではなく、commentable_type=Report を指定する汎用APIになっている
• API::CommentsController#create の成功レスポンスが JSON API として扱いやすい形ではなく、HTML partial を返す実装になっている
• 外部クライアント向けに、リクエスト・レスポンス形式やエラー形式が明確に定義されていない

候補:

• POST /api/reports/:report_id/comments のような日報専用JSON APIを追加する
• もしくは既存 POST /api/comments の JSON レスポンスを外部クライアント向けに整える

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

外部AIが日報を読んでフィードバックや質問を投稿する用途では、APIから安定してコメントを作成できる必要がある。

現状の汎用コメント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)
• app/controllers/api/comments_controller.rb: create
• test/integration/api/comments_test.rb: can create comment with read, write scope