Merge pull request #60 from kc3hack/feature/issue-51-user-api

Issue #51 の実装と、レビュー対応を含む。

## 実装内容
- POST/GET/PUT/DELETE /users（CRUD）
- GET/PUT /users/{id}/profile（Upsert）
- GET /users/{id}/badges / skill-trees / quest-progress
- update_user_rank()（AI専用内部CRUD、HTTP非公開）
- ADR 010（rank管理）・ADR 011（エンドポイント設計）追加

## レビュー対応
- fix: PUT /users/{id} の ValueError を 400 に変換
- fix: update_user_rank() に rank 範囲（0–9）バリデーション追加
- fix: username 重複の事前チェック、null username の無視
- test: 異常系・バリデーション系テスト4件追加（計131 passed）
- docs: ADR 010/011 を実装と整合させる（rankフロー・user_id記述・IDORセキュリティ注記）

Closes #51

Author: Reeeid

.github/decisions/009-database-design-strategy.md

@@ -33,7 +33,7 @@ issue #31で6テーブル（Profile, OAuthAccount, Badge, Quest, QuestProgress,
 - **変更理由**:
   - **Langchain/フロントエンドとの統一的な操作**: JSONB型（バイナリ形式）で一貫した扱いが必要
   - **テスト環境の統一**: SQLite（BLOB型）/PostgreSQL（JSONB型）両対応
-  - **将来の拡張性**: JSON内部検索の可能性を考慮
+  - **スキルツリーのクリア状態更新・検索**: SkillTree.tree_data 内の各ノード（`completed` フラグ）をノード単位で更新・検索する予定があるため、JSONB の GIN インデックスによる JSON 内部検索（`@>`, `?` 演算子等）が必要になる（Issue #54 参照）
 - **実装方針**:
   - PostgreSQL: JSONB型として保存
   - SQLite: BLOB型として保存（JSONBのバイナリ表現）
@@ -152,8 +152,8 @@ issue #31で6テーブル（Profile, OAuthAccount, Badge, Quest, QuestProgress,
   - **対処法**: SQLAlchemy ORM の `relationship()` で簡潔に記述
 - **パフォーマンス**: 非正規化より若干遅い
   - **対処法**: ハッカソン規模（数百ユーザー）では影響なし、将来的にインデックス最適化
-- **JSONB型未使用**: PostgreSQL固有の高速検索機能を使えない
-  - **対処法**: MVP段階ではJSON内部検索が不要、必要になったら移行
+- **JSONB型採用による書き込みコスト**: JSON型より書き込み時のパース処理が若干重い
+  - **対処法**: ハッカソン規模では影響なし。スキルツリーはユーザー分析時のみ更新するため書き込み頻度が低い
 
 ### 実装ガイドライン
 

.github/decisions/010-user-api-rank-management.md

@@ -0,0 +1,128 @@
+# ADR 010: User API設計 - rankフィールドの管理方針
+
+## ステータス
+
+- [x] **決定**
+
+## コンテキスト (課題と背景)
+
+Issue #51 で `PUT /users/{user_id}` エンドポイントを実装する際、`rank` フィールドの扱いについて以下の問題が判明した。
+
+### 問題1: PUT /users/{id} に rank を公開するとユーザーが改ざん可能
+
+`PUT /users/{id}` に `rank` フィールドを含めた場合、任意のユーザーが `rank=9`（世界樹）を自由にセットできる。AI分析を経ずにランクを操作できることになり、ゲームバランスを破壊する。
+
+### 問題2: rankとexpの整合性バリデータとMVPフローの矛盾
+
+`app/schemas/user.py` の `User` レスポンススキーマに以下のバリデータが存在していた:
+
+```python
+@model_validator(mode="after")
+def validate_rank_consistency(self) -> "User":
+    expected_rank = calculate_rank(self.exp)
+    if self.rank != expected_rank:
+        raise ValueError(...)
+```
+
+product-spec のMVPフローでは、AIが `rank=4` と判定した状態で `exp=0` のままになるため、このバリデータは **500エラー** を引き起こす。
+
+product-spec 4.2:
+> **MVP段階**: 初回分析時のランク決定のみ実装。
+> **Future**: ポイント制や特定条件達成によるランクアップ機能。
+
+MVPではrankはAIが直接決定し、expの蓄積によるrankupはFutureスコープ。
+
+### rankとexpの関係
+
+`rank = calculate_rank(exp)` という関係性は定義されているが（`RANK_THRESHOLDS`）、それはFutureのexp蓄積ランクアップのための設計。MVPではrankはAI判定で決まり、expとの連動はない。
+
+また、rankが更新されるとスキルツリーの再生成フローが走る可能性もある（Issue #54）。このような複合的な処理はHTTPエンドポイントから直接操作できるべきではなく、サービス層・CRUD層で制御すべき。
+
+## 決定 (Decision)
+
+### 1. `PUT /users/{user_id}` から `rank` を除外
+
+```python
+class UserUpdate(BaseModel):
+    username: str | None = None
+    # rank / level / exp はサーバー側で管理するため含めない
+```
+
+### 2. AI専用のCRUD関数 `update_user_rank` を追加
+
+AI サービス（LangChain / rank_service.py）からのみ呼び出される内部関数として `app/crud/user.py` に実装。HTTPエンドポイントには公開しない。
+
+```python
+def update_user_rank(db: Session, user_id: int, rank: int) -> User | None:
+    """AI分析結果のランク保存専用。エンドポイントには公開しない。"""
+```
+
+### 3. `validate_rank_consistency` バリデータを削除
+
+MVPではrankとexpの連動はFutureスコープ。バリデータはFutureのランクアップ実装時に改めて検討する。
+
+### rankの更新フロー（MVP）
+
+```
+POST /analyze/rank (github_username, ...)
+  └─ analyze_user_rank() が LLM でpercentile・rank を判定して結果を返す
+  └─ フロントはレスポンス（rank, rank_name, reasoning）を表示するだけ
+
+PUT /users/{id} では rank は変更不可
+```
+
+> **Note**: 現在の `analyze_user_rank()`（`app/services/rank_service.py`）は `db` / `user_id` を受け取らず、LLM 判定結果を返すだけの純粋な分析ツールとして実装している。`update_user_rank(db, user_id, rank)` の呼び出しは AI サービス統合（Issue #54）のタイミングで追加する。
+
+### rankの更新フロー（Future: Issue #54 実装時）
+
+**設計原則**: rank の UPDATE はエンドポイントがサーバー内部で完結させる。フロントエンドは analyze 結果を受け取るだけでよく、別途 `PUT /users/{id}` で保存する必要はない。Issue #54 の `generate_skill_tree_ai(user_id, category, db)` が SkillTree テーブルを直接更新するパターンと同じ。
+
+```
+POST /analyze/rank (user_id, github_username, ...)
+  └─ analyze_user_rank(db, user_id, ...) を呼び出し
+  └─ LLM が percentile から rank 判定
+  └─ 内部で update_user_rank(db, user_id, rank) を呼び出して DB 保存
+  └─ フロントはレスポンスを表示するだけ（DB 保存はサーバー側で完結）
+
+PUT /users/{id} では rank は変更不可（変わらず）
+```
+
+## 代替案との比較 (Options)
+
+### 1. PUT /users/{id} に rank を含め、フロントが保存する
+
+- **Good**: シンプル、実装が容易
+- **Bad**: ユーザーが rank を自由に改ざん可能。MVP段階でOAuth認証が未実装のため、現時点で安全に実装できない
+- **却下理由**: セキュリティリスク
+
+### 2. POST /users/{id}/rank-init 専用エンドポイントを追加
+
+- **Good**: 意図が明確
+- **Bad**: エンドポイントが増えてAPIが複雑になる。AI内部でCRUD関数を呼べば同じことが実現できる
+- **却下理由**: 不要な複雑性の追加（YAGNI）
+
+## 結果 (Consequences)
+
+### Positive
+
+- **セキュリティ**: ユーザーによるrank改ざんが不可能
+- **MVP優先**: 技術負債を増やさず、動くものを優先して提供
+- **拡張性**: Future（ランクアップ・スキルツリー再生成連携）実装時は `update_user_rank` を拡張するだけでよい
+
+### Negative
+
+- **validate_rank_consistency の削除**: バリデータによる自動チェックがなくなる
+  - **対処法**: `update_user_rank` を内部専用CRUDに限定し、rank変更経路を制御する
+- **expとrankの非連動（MVP）**: expが増えてもrankは変わらない
+  - **対処法**: Future実装時（Issue #XX）に連動ロジックを追加する
+
+## 関連
+
+- Issue #51: User API エンドポイント実装
+- Issue #54: AI実装Phase 3 - スキルツリー生成（`update_user_rank` の利用元候補）
+- ADR 005: APEX Legendsスタイルランク分布（rankの意味・定義）
+- product-spec 4.2: ランクアップ方針（MVP vs Future）
+
+## 変更履歴
+
+- 2026-02-20: 決定（Issue #51 設計議論）

.github/decisions/011-user-api-endpoint-design.md

@@ -0,0 +1,165 @@
+# ADR 011: User API エンドポイント設計
+
+## ステータス
+
+- [x] **決定**
+
+## コンテキスト (課題と背景)
+
+Issue #51 で `/users` 配下の RESTful API を設計する際、以下の判断が必要になった。
+
+1. ネストされたリソース（Badge, SkillTree 等）のレスポンスに `user_id` を含めるか
+2. 各エンドポイントの Request / Response の確定
+
+## 決定 (Decision)
+
+### 1. ネストリソースの `user_id` を除去（コミット eaed96e）
+
+当初は既存スキーマを流用して `user_id` を含める方針だったが、
+その後のリファクタリング（eaed96e）でレスポンススキーマから冗長な `user_id` を除去した。
+
+除去した理由:
+- クライアントはパスから `user_id` を知っているため不要
+- RESTful 的に冗長情報を排除
+
+**Future**: API 公開・外部連携が必要になった段階で専用レスポンススキーマへ切り出しを検討。
+
+### 2. 確定エンドポイント仕様
+
+#### User
+
+| Method | Path | Status | 概要 |
+|---|---|---|---|
+| POST | `/users` | 201 | ユーザー登録（仮実装・username のみ） |
+| GET | `/users/{user_id}` | 200 | ユーザー情報取得 |
+| PUT | `/users/{user_id}` | 200 | username 更新のみ（ADR 010参照） |
+| DELETE | `/users/{user_id}` | 204 | ユーザー削除 |
+
+**POST /users**
+```
+Request:  { "username": "string" }
+Response: { id, username, level=1, exp=0, rank=0, created_at, updated_at }
+Error:    400 username重複
+Note:     SkillTree 6カテゴリが自動初期化される（CRUD層実装済み）
+```
+
+**GET /users/{user_id}**
+```
+Response: { id, username, level, exp, rank, created_at, updated_at }
+Error:    404
+```
+
+**PUT /users/{user_id}**
+```
+Request:  { "username"?: "string" }
+          ※ level / exp / rank はサーバー管理のため除外（ADR 010）
+Response: { id, username, level, exp, rank, created_at, updated_at }
+Error:    404
+```
+
+**DELETE /users/{user_id}**
+```
+Response: 204 No Content
+Error:    404
+```
+
+#### Profile
+
+| Method | Path | Status | 概要 |
+|---|---|---|---|
+| GET | `/users/{user_id}/profile` | 200 | プロフィール取得 |
+| PUT | `/users/{user_id}/profile` | 200 | プロフィール更新（Upsert） |
+
+**GET /users/{user_id}/profile**
+```
+Response: { id, user_id, github_username, qiita_id, connpass_id,
+            portfolio_url, portfolio_text, last_analyzed_at }
+Error:    404 (user not found / profile not found)
+```
+
+**PUT /users/{user_id}/profile**
+```
+Request:  { "github_username"?: str, "qiita_id"?: str, "connpass_id"?: str,
+            "portfolio_url"?: str, "portfolio_text"?: str }  ← 全て optional
+Response: { id, user_id, github_username, qiita_id, connpass_id,
+            portfolio_url, portfolio_text, last_analyzed_at }
+Error:    404 (user not found)
+Note:     profile が存在しない場合は作成（Upsert）
+```
+
+#### Badge
+
+| Method | Path | Status | 概要 |
+|---|---|---|---|
+| GET | `/users/{user_id}/badges` | 200 | バッジ一覧取得 |
+
+**GET /users/{user_id}/badges**
+```
+Response: [ { id, category, tier, earned_at } ]
+          ※ 空配列を返す（404にしない）
+Error:    404 (user not found)
+```
+
+#### SkillTree
+
+| Method | Path | Status | 概要 |
+|---|---|---|---|
+| GET | `/users/{user_id}/skill-trees` | 200 | スキルツリー一覧取得 |
+
+**GET /users/{user_id}/skill-trees**
+```
+Response: [ { id, category, tree_data, generated_at } ]
+          ※ ユーザー作成時に6カテゴリ自動初期化のため必ず6件
+Error:    404 (user not found)
+```
+
+#### QuestProgress
+
+| Method | Path | Status | 概要 |
+|---|---|---|---|
+| GET | `/users/{user_id}/quest-progress` | 200 | クエスト進捗一覧取得 |
+
+**GET /users/{user_id}/quest-progress**
+```
+Response: [ { id, quest_id, status, started_at, completed_at } ]
+          ※ 空配列を返す（404にしない）
+Error:    404 (user not found)
+```
+
+## 代替案との比較 (Options)
+
+### ネストリソースから user_id を除外する
+
+```python
+class BadgeResponse(BaseModel):
+    id: int
+    category: BadgeCategory
+    tier: int
+    earned_at: datetime
+    # user_id は除外
+```
+
+- **Good**: RESTful 的に冗長情報を排除、ペイロード削減
+- **Bad**: 既存 `Badge` スキーマと別に `BadgeResponse` を作る必要がある。全リソース分（Badge, SkillTree, QuestProgress）で作業が増える
+- **却下理由**: MVP のスピード感に合わない。フロントが無視すれば実害なし
+
+## 結果 (Consequences)
+
+### Positive
+
+- 既存スキーマをそのまま流用でき、実装が高速
+- エンドポイント仕様が ADR として記録され、チーム内で認識統一
+
+### Negative
+
+- **認証・認可未実装（MVP）**: `/users/{user_id}` は IDOR（Insecure Direct Object Reference）リスクあり
+  - **対処法**: OAuth 認証実装（Future）後にミドルウェアで認証・認可チェックを追加予定
+
+## 関連
+
+- Issue #51: User API エンドポイント実装
+- ADR 010: rankフィールドの管理方針（PUT /users/{id} の設計判断）
+
+## 変更履歴
+
+- 2026-02-20: 決定（Issue #51 設計議論）

backend/app/api/api.py

@@ -1,9 +1,10 @@
 """ルーター集約"""
 
 from fastapi import APIRouter
-from app.api.endpoints import analyze
+from app.api.endpoints import analyze, users
 
 
 api_router = APIRouter()
 
 api_router.include_router(analyze.router, prefix="/analyze", tags=["analyze"])
+api_router.include_router(users.router, prefix="/users", tags=["users"])