Backend: AI実装Phase 2 - モックAPIエンドポイント

## 目的
AI基盤（Issue #32）と全テーブルCRUD（Issue #31, PR #42マージ済み）の上に、フロントエンド開発と並行作業可能なモックAPIエンドポイントを実装。
固定レスポンスを返すことで、APIインターフェースの確定とフロントエンド統合準備を完了させる。

## 背景
- Issue #32でLangChain基盤は完成
- Issue #31（PR #42）で全6テーブル（Profile, OAuthAccount, Badge, Quest, QuestProgress, SkillTree）実装完了
- しかし本格的なAI実装（Phase 3）にはGitHub API統合やプロンプト調整が必要
- フロントエンド開発者が待機状態にならないよう、先にAPIインターフェースを確定

## 実装エンドポイント（全3つ）

### 1. POST /api/v1/analyze/rank - ランク判定（モック）

**Request Body**:
```json
{
  "user_id": 1
}
```

**Response（固定）**:
```json
{
  "rank": 4,
  "rank_name": "母樹",
  "percentile": 65.0,
  "reasoning": "GitHubリポジトリ3件、複数言語使用、継続的コミット実績を評価。中級エンジニアレベルと判定。"
}
```

**注**: 実際にはProfileテーブルから`github_username`, `qiita_id`, `connpass_id`, `portfolio_text`を取得して分析（Phase 3で実装）

### 2. POST /api/v1/analyze/skill-tree - スキルツリー生成（モック）

**Request Body**:
```json
{
  "user_id": 1,
  "category": "web"
}
```

**Response（固定 - SkillTreeテーブルのtree_data JSON構造）**:
```json
{
  "category": "web",
  "tree_data": {
    "nodes": [
      {
        "id": "html-css",
        "name": "HTML/CSS基礎",
        "completed": true,
        "description": "基本的なマークアップとスタイリング",
        "prerequisites": [],
        "estimated_hours": 20
      },
      {
        "id": "js-basics",
        "name": "JavaScript基礎",
        "completed": true,
        "description": "変数、関数、DOM操作の基礎",
        "prerequisites": ["html-css"],
        "estimated_hours": 30
      },
      {
        "id": "react",
        "name": "React/Next.js",
        "completed": false,
        "description": "モダンフロントエンドフレームワーク",
        "prerequisites": ["js-basics"],
        "estimated_hours": 50
      },
      {
        "id": "typescript",
        "name": "TypeScript",
        "completed": false,
        "description": "型安全なJavaScript開発",
        "prerequisites": ["js-basics"],
        "estimated_hours": 40
      },
      {
        "id": "api-design",
        "name": "REST API設計",
        "completed": false,
        "description": "API設計とOpenAPI仕様",
        "prerequisites": ["js-basics"],
        "estimated_hours": 30
      }
    ],
    "edges": [
      {"from": "html-css", "to": "js-basics"},
      {"from": "js-basics", "to": "react"},
      {"from": "js-basics", "to": "typescript"},
      {"from": "js-basics", "to": "api-design"}
    ],
    "metadata": {
      "total_nodes": 5,
      "completed_nodes": 2,
      "progress_percentage": 40.0,
      "next_recommended": ["react", "typescript"]
    }
  },
  "generated_at": "2026-02-20T12:00:00+09:00"
}
```

**カテゴリ6種類（SkillCategory enum準拠）**:
- `web` - Web開発
- `ai` - AI/機械学習
- `security` - セキュリティ
- `infrastructure` - インフラ/DevOps
- `design` - UI/UX設計
- `game` - ゲーム開発

**注**: 各カテゴリごとに異なる固定tree_dataを用意（計6パターン）

### 3. POST /api/v1/analyze/quest - 演習生成（モック）

**Request Body**:
```json
{
  "user_id": 1,
  "category": "web",
  "difficulty": 4,
  "document_text": "FastAPIのドキュメント..."
}
```

**Response（固定 - Questテーブル構造準拠）**:
```json
{
  "id": 101,
  "title": "FastAPIで認証付きTodo API構築",
  "description": "JWT認証を実装したCRUD APIを作成し、OpenAPI仕様書を自動生成する演習。\n\n**学習目標**:\n- FastAPIの基本構造理解\n- JWT認証の実装\n- SQLAlchemyでのDB操作\n- pytest によるテスト作成\n\n**提出物**:\n- GitHubリポジトリURL\n- Swagger UI スクリーンショット\n- テスト実行結果",
  "difficulty": 4,
  "category": "web",
  "is_generated": true,
  "steps": [
    "1. FastAPIプロジェクト初期化（poetry/pip）",
    "2. SQLAlchemyでTodoモデル定義（id, title, completed, user_id）",
    "3. JWT認証ミドルウェア実装（python-jose）",
    "4. CRUD エンドポイント実装（GET /todos, POST /todos, PUT /todos/{id}, DELETE /todos/{id}）",
    "5. pytest でテスト作成（カバレッジ80%以上）",
    "6. Swagger UIで動作確認"
  ],
  "estimated_time_minutes": 120,
  "resources": [
    {"title": "FastAPI公式ドキュメント", "url": "https://fastapi.tiangolo.com/ja/"},
    {"title": "SQLAlchemy公式ドキュメント", "url": "https://docs.sqlalchemy.org/"},
    {"title": "JWT認証実装ガイド", "url": "https://fastapi.tiangolo.com/tutorial/security/"}
  ],
  "created_at": "2026-02-20T12:00:00+09:00"
}
```

**注**: `document_text`はPhase 3でRAG（Retrieval-Augmented Generation）に使用予定

## アーキテクチャ

### ディレクトリ構造
```
backend/app/
├── api/
│   └── endpoints/
│       └── analyze.py  # 新規作成（3エンドポイント）
├── services/
│   └── mock_ai_service.py  # 新規作成（固定データ返却）
└── schemas/
    └── analyze.py  # 新規作成（Request/Response定義）
```

### レイヤー分離（architecture/SKILL.md準拠）
- **Presentation Layer** (`api/endpoints/analyze.py`): ルーティング、バリデーションのみ
- **Business Logic Layer** (`services/mock_ai_service.py`): モックデータ生成ロジック
- **将来の移行**: Phase 3で`services/mock_ai_service.py`を`services/ai_service.py`（Real LLM）に置き換え

### データ構造の整合性（DB設計準拠）

モック実装でも、DB設計（Issue #31）との整合性を保つ:

1. **Profileテーブル連携**:
   - `github_username`, `qiita_id`, `connpass_id`, `portfolio_text`, `portfolio_url`
   - `last_analyzed_at`（分析実行時刻）

2. **SkillTreeテーブルtree_data JSON**:
   - `nodes[]`: スキルノード配列
   - `edges[]`: 前提条件の関係
   - `metadata`: 進捗情報

3. **Questテーブル**:
   - `difficulty` (0-9): ランクと対応
   - `category`: SkillCategory enumと同じ6種類
   - `is_generated`: AI生成フラグ（モックはtrue）

4. **User.rank, User.exp**:
   - ランク判定結果はUser.rankに反映（Phase 3で実装）

## 実装タスク
- [ ] `backend/app/schemas/analyze.py`: Pydantic Request/Responseスキーマ定義
  - RankAnalysisRequest, RankAnalysisResponse
  - SkillTreeRequest, SkillTreeResponse（tree_data構造含む）
  - QuestGenerationRequest, QuestGenerationResponse
- [ ] `backend/app/services/mock_ai_service.py`: 固定データ返却関数（3つ）
  - `analyze_rank_mock(user_id: int) -> RankAnalysisResponse`
  - `generate_skill_tree_mock(user_id: int, category: str) -> SkillTreeResponse`
  - `generate_quest_mock(user_id: int, category: str, difficulty: int, document_text: str) -> QuestGenerationResponse`
- [ ] `backend/app/api/endpoints/analyze.py`: FastAPIエンドポイント（3つ）
  - POST /api/v1/analyze/rank
  - POST /api/v1/analyze/skill-tree
  - POST /api/v1/analyze/quest
- [ ] `backend/app/api/api.py`: ルーター登録
- [ ] テスト: `tests/test_api/test_analyze_mock.py`（各エンドポイントの動作確認）
  - 各エンドポイントが正しいスキーマでレスポンスを返すこと
  - バリデーションエラーが適切に処理されること
  - 全カテゴリ（6種類）のスキルツリーデータが存在すること
- [ ] Swagger UI動作確認（スクリーンショット撮影）

## セキュリティ考慮
- [ ] user_id検証（存在チェックは将来実装、今は省略可）
- [ ] Request Bodyサイズ制限（document_text: 最大100KB）
- [ ] Rate Limiting（将来実装、今はコメントで方針記載）
- [ ] カテゴリEnum検証（SkillCategory, QuestCategoryに準拠）

## テスト要件
- 各エンドポイントが正しいスキーマでレスポンスを返すこと
- バリデーションエラーが適切に処理されること（無効なcategory等）
- 全カテゴリ（6種類）のスキルツリーデータが存在すること
- tree_data JSONの構造が正しいこと（nodes, edges, metadata）
- Questのdifficulty範囲（0-9）が正しいこと

## 完了条件（DoD）
- [ ] 3エンドポイント実装完了
- [ ] Swagger UIで全エンドポイント動作確認可能
- [ ] テスト3件以上、全パス
- [ ] PR説明にSwagger UIスクリーンショット添付（Evidence of Functionality）
- [ ] フロントエンド開発者が統合テスト開始可能
- [ ] DB設計（Issue #31）との整合性確認完了

## 依存
- ✅ Issue #32（AI基盤セットアップ）マージ済み
- ✅ Issue #31（全6テーブルCRUD実装）マージ済み（PR #42）

## 次のステップ（Phase 3）
- Issue #34: GitHub API統合
- Issue #36: AI実装Phase 3 - ランク判定AI（モック→Real LLM）
- Issue #37: AI実装Phase 3 - スキルツリー生成AI
- Issue #38: AI実装Phase 3 - 演習生成AI

## 参考
- [Issue #31](https://github.com/kc3hack/2026_team29/issues/31): DB設計とモデル実装
- [PR #42](https://github.com/kc3hack/2026_team29/pull/42): 全6テーブルCRUD実装
- [backend/app/models/](https://github.com/kc3hack/2026_team29/tree/main/backend/app/models): 最新モデル定義
- [backend/app/models/enums.py](https://github.com/kc3hack/2026_team29/blob/main/backend/app/models/enums.py): カテゴリEnum定義


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Backend: AI実装Phase 2 - モックAPIエンドポイント #35

目的

背景

実装エンドポイント（全3つ）

1. POST /api/v1/analyze/rank - ランク判定（モック）

2. POST /api/v1/analyze/skill-tree - スキルツリー生成（モック）

3. POST /api/v1/analyze/quest - 演習生成（モック）

アーキテクチャ

ディレクトリ構造

レイヤー分離（architecture/SKILL.md準拠）

データ構造の整合性（DB設計準拠）

実装タスク

セキュリティ考慮

テスト要件

完了条件（DoD）

依存

次のステップ（Phase 3）

参考

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Backend: AI実装Phase 2 - モックAPIエンドポイント #35

Description

目的

背景

実装エンドポイント（全3つ）

1. POST /api/v1/analyze/rank - ランク判定（モック）

2. POST /api/v1/analyze/skill-tree - スキルツリー生成（モック）

3. POST /api/v1/analyze/quest - 演習生成（モック）

アーキテクチャ

ディレクトリ構造

レイヤー分離（architecture/SKILL.md準拠）

データ構造の整合性（DB設計準拠）

実装タスク

セキュリティ考慮

テスト要件

完了条件（DoD）

依存

次のステップ（Phase 3）

参考

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions