KDOP仕様書のベースパス変更と認証方式の明記

[kigawa01]

概要

KDOP (Keruta Document Protocol) 仕様書のベースパスを /v1/ に変更し、Keycloak OIDC Access Token による認証を明記しました。

背景・目的

REST APIのベースパスを統一し、認証方式を明確にすることで、実装時の混乱を防ぎ、セキュリティを強化します。

変更内容

• ベースパスを /api/v1/documents から /v1/ に変更
• 認証方式を Keycloak OIDC Access Token と明記
• トークン検証方法を追加

確認方法

• 仕様書ファイル spec/document-protocol.md を確認
• エンドポイントが /v1/ から始まっていることを確認
• 認証セクションで Keycloak OIDC が記載されていることを確認

その他

なし

[kigawa01]

@claude review

[claude]

Claude finished @kigawa01's task in 1m 52s —— View job

---

レビュー完了

タスクリスト

• 変更ファイルの確認
• spec/document-protocol.md の詳細レビュー
• ワークフローファイルの変更確認
• レビューフィードバックの作成

---

📋 レビューサマリー

KDOP仕様書の作成お疲れ様です。全体的によく構造化された仕様書になっています。以下、改善提案と指摘事項をまとめます。

---

✅ 良い点

1. 明確な構造: REST API仕様として必要な要素（エンドポイント、認証、エラーハンドリング等）が網羅されている
2. 既存仕様との整合性: task-client-protocolと同様にKeycloak OIDC認証を採用し、システム全体で統一された認証方式を維持
3. 実用的な設計: ページネーション、キャッシュ、バージョン管理など実装に必要な機能が考慮されている

---

🔍 改善が必要な点

1. ベースパスの不整合 (重要度: 高)

場所: spec/document-protocol.md:29

すべてのKDOPエンドポイントは `/v1/` をベースパスとします。

問題点:

• PRの説明では「ベースパスを /api/v1/documents から /v1/ に変更」と記載されているが、仕様書内に旧パス /api/v1/documents への言及が残っていない
• /v1/ というベースパスは他のkerutaシステムのAPIとの整合性に課題がある可能性

推奨:

• kerutaシステム全体でのAPIパス規則を確認し、統一すべき
• 他のサービス（keruta-api）のエンドポイントが /api/v1/ を使用している場合、/v1/ だけでは不整合になる
• OpenAPI仕様（common/apiSpec/openapi.yaml）との整合性も確認が必要

2. 認証仕様の詳細不足 (重要度: 高)

場所: spec/document-protocol.md:129-131

現状:

- **Keycloak OIDC Access Token**: BearerトークンとしてAuthorizationヘッダーで送信
- **トークン検証**: Keycloakの公開鍵による署名検証
- **スコープ検証**: ドキュメント操作権限の確認

不足している情報:

1. 具体的なAuthorizationヘッダーの形式例（Authorization: Bearer <token>）
2. 必要なスコープの具体的な名前（例: document:read, document:write, document:delete）
3. Keycloakサーバーのエンドポイント情報（環境変数での指定方法など）
4. トークンの有効期限とリフレッシュ方法
5. 認証失敗時の具体的なレスポンス例

推奨:

### 認証と認可

#### Access Tokenの送信
すべてのAPIリクエストには、Keycloak OIDC Access Tokenを含める必要があります。

```http
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

必要なスコープ

操作	必要なスコープ
ドキュメント一覧取得・詳細取得	document:read
ドキュメント作成・更新	document:write
ドキュメント削除	document:delete

トークン検証

• Keycloakの公開鍵（JWKS）による署名検証
• トークンの有効期限確認
• 発行者（iss）クレームの検証
• オーディエンス（aud）クレームの検証

認証失敗時のレスポンス

{
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "認証に失敗しました",
    "details": {
      "reason": "token_expired"
    }
  },
  "timestamp": "2024-01-01T10:00:00Z"
}

#### 3. **リクエストボディの仕様が不明** (重要度: 高)
**場所**: `spec/document-protocol.md:33-41`

**問題点**:
- エンドポイント一覧にリクエストボディの形式が記載されていない
- POST/PUT操作で必要なフィールドが不明

**推奨**:
各エンドポイントについて、リクエスト/レスポンスの具体例を追加すべき

```markdown
#### ドキュメント作成 (POST /v1/documents)

**リクエストボディ例**:
```json
{
  "title": "ドキュメントタイトル",
  "content": "ドキュメント本文",
  "tags": ["tag1", "tag2"],
  "metadata": {
    "author": "user-id",
    "category": "technical"
  }
}

レスポンス例 (201 Created):

{
  "success": true,
  "data": {
    "id": "doc-123456",
    "title": "ドキュメントタイトル",
    "content": "ドキュメント本文",
    "tags": ["tag1", "tag2"],
    "version": 1,
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": "2024-01-01T10:00:00Z"
  },
  "timestamp": "2024-01-01T10:00:00Z",
  "version": "1.0"
}

#### 4. **バージョン管理の詳細不足** (重要度: 中)
**場所**: `spec/document-protocol.md:40-41, 86-87`

**問題点**:
- バージョン履歴のレスポンス形式が不明
- 楽観的ロックの実装方法（ETagの使用など）が明記されていない
- バージョン競合時の解決方法が具体的でない

**推奨**:
```markdown
#### バージョン管理

##### 楽観的ロック
ドキュメント更新時はETagを使用した楽観的ロックを実装：

1. GETリクエストでETagを取得
```http
GET /v1/documents/doc-123
Response:
ETag: "version-5"

2. PUTリクエスト時にIf-Matchヘッダーで指定

PUT /v1/documents/doc-123
If-Match: "version-5"

3. バージョン競合時は409 Conflictを返す

{
  "success": false,
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "ドキュメントが他のユーザーによって更新されています",
    "details": {
      "current_version": 6,
      "provided_version": 5
    }
  }
}

#### 5. **APIバージョンの矛盾** (重要度: 中)
**場所**: `spec/document-protocol.md:156-165`

**問題点**:
```markdown
### APIバージョン
- **v1**: 基本ドキュメント操作
- **v1.1**: バージョン管理機能
- **v1.2**: 高度な検索とフィルタリング

一方で、ベースパスは /v1/ のみで、v1.1やv1.2への対応が不明確

推奨:

• セマンティックバージョニングではなく、メジャーバージョンのみをURLに含める（/v1/, /v2/）
• マイナーバージョンはヘッダーまたは後方互換性を保って追加機能として扱う
• または、この「APIバージョン」セクション自体を削除し、将来の拡張として扱う

6. サンプルデータの日付が古い (重要度: 低)

場所: 複数箇所（spec/document-protocol.md:58, 71など）

問題点:

"timestamp": "2024-01-01T10:00:00Z"

現在は2025年のため、サンプルの日付が古い

推奨:

• 相対的な表現に変更（例: "timestamp": "2025-12-31T10:00:00Z" または <ISO 8601形式のタイムスタンプ>）

7. セキュリティ項目の追加検討 (重要度: 中)

場所: spec/document-protocol.md:121-138

追加を検討すべき項目:

• CORS設定: クロスオリジンリクエストの許可ポリシー
• Rate Limiting: APIレート制限の仕様（例: 1分間に100リクエストまで）
• 監査ログ: ドキュメント操作の監査ログ記録
• データ暗号化: 保存時のデータ暗号化（at rest）

8. ワークフローファイルの変更について

場所: .github/workflows/claude-code-review.yml:3

変更内容:

-on:
+#on:

この変更により、ワークフローが完全に無効化されていますが、意図的な変更でしょうか？PRの説明には記載がありません。

確認事項:

• この変更の意図を明確にすべき（コミットメッセージまたはPR説明に追記）
• 完全に無効化するのであれば、ファイル全体を削除する方が明確

---

🎯 その他の推奨事項

1. OpenAPI仕様の作成: この仕様書をもとに、OpenAPI 3.0形式の仕様ファイルを作成することを推奨（common/apiSpec/ディレクトリに配置）

2. 実装例の追加: keruta-adminやクライアントライブラリでの実装例を別ドキュメントとして追加すると有用

3. エラーハンドリングの拡充: 各エンドポイントで発生しうる具体的なエラーケースをマッピング

---

📝 まとめ

この仕様書は良い出発点ですが、実装時の混乱を防ぐために以下の対応を推奨します：

必須対応:

1. ベースパスの全体設計確認と統一（他サービスとの整合性）
2. 認証仕様の詳細化（スコープ、ヘッダー形式、エラーレスポンス）
3. リクエスト/レスポンスボディの具体例追加

推奨対応:
4. バージョン管理の詳細化（楽観的ロック、競合解決）
5. APIバージョニング戦略の明確化
6. セキュリティ項目の追加（CORS、Rate Limiting等）

---