math_cms/app/Services/ApiDocumentation.php

<?php

namespace App\Services;

/**
 * API 文档配置服务
 * 集中管理所有 API 的文档信息，包括参数说明、响应示例等
 */
class ApiDocumentation
{
    /**
     * 获取所有 API 文档
     */
    public static function all(): array
    {
        return [
            // ==================== 题库核心 API ====================
            'api/questions' => [
                'GET' => [
                    'summary' => '获取题目列表',
                    'description' => '分页获取题库中的题目，支持按知识点、难度等条件筛选',
                    'params' => [
                        'query' => [
                            ['name' => 'page', 'type' => 'integer', 'required' => false, 'default' => '1', 'description' => '页码'],
                            ['name' => 'per_page', 'type' => 'integer', 'required' => false, 'default' => '25', 'description' => '每页数量'],
                            ['name' => 'kp_code', 'type' => 'string', 'required' => false, 'description' => '知识点编码，用于筛选特定知识点的题目'],
                            ['name' => 'difficulty', 'type' => 'string', 'required' => false, 'description' => '难度等级：easy/medium/hard'],
                            ['name' => 'search', 'type' => 'string', 'required' => false, 'description' => '搜索关键词'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'data' => [
                                ['id' => 1, 'content' => '计算 2+3=?', 'answer' => '5', 'difficulty' => 'easy', 'kp_code' => 'MATH_ADD_001'],
                            ],
                            'meta' => [
                                'page' => 1,
                                'per_page' => 25,
                                'total' => 100,
                                'total_pages' => 4,
                            ],
                        ],
                        'error' => [
                            'error' => '错误信息',
                        ],
                    ],
                ],
            ],

            'api/questions/{id}' => [
                'GET' => [
                    'summary' => '获取单个题目详情',
                    'description' => '根据题目 ID 获取题目的完整信息',
                    'params' => [
                        'path' => [
                            ['name' => 'id', 'type' => 'integer', 'required' => true, 'description' => '题目 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'id' => 1,
                            'content' => '计算 2+3=?',
                            'answer' => '5',
                            'analysis' => '这是一道简单的加法题...',
                            'difficulty' => 'easy',
                            'kp_code' => 'MATH_ADD_001',
                            'kp_name' => '整数加法',
                            'created_at' => '2024-01-01T00:00:00Z',
                        ],
                        'error' => ['error' => 'Question not found'],
                    ],
                ],
                'DELETE' => [
                    'summary' => '删除题目',
                    'description' => '根据 ID 删除指定题目',
                    'params' => [
                        'path' => [
                            ['name' => 'id', 'type' => 'integer', 'required' => true, 'description' => '题目 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => ['success' => true, 'message' => 'Question deleted'],
                        'error' => ['success' => false, 'message' => 'Failed to delete'],
                    ],
                ],
            ],

            'api/questions/search' => [
                'GET' => [
                    'summary' => '搜索题目（简单）',
                    'description' => '通过关键词搜索题目',
                    'params' => [
                        'query' => [
                            ['name' => 'q', 'type' => 'string', 'required' => true, 'description' => '搜索关键词'],
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '20', 'description' => '返回数量限制'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'data' => [
                                ['id' => 1, 'content' => '...', 'score' => 0.95],
                            ],
                            'total' => 10,
                        ],
                    ],
                ],
                'POST' => [
                    'summary' => '语义搜索题目',
                    'description' => '使用 AI 语义搜索匹配题目',
                    'params' => [
                        'body' => [
                            ['name' => 'query', 'type' => 'string', 'required' => true, 'description' => '搜索查询文本'],
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '20', 'description' => '返回数量限制'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'data' => [
                                ['id' => 1, 'content' => '...', 'similarity' => 0.92],
                            ],
                        ],
                    ],
                ],
            ],

            'api/questions/random' => [
                'GET' => [
                    'summary' => '随机获取题目',
                    'description' => '随机获取指定数量的题目，可按条件筛选',
                    'params' => [
                        'query' => [
                            ['name' => 'count', 'type' => 'integer', 'required' => false, 'default' => '10', 'description' => '获取数量'],
                            ['name' => 'kp_code', 'type' => 'string', 'required' => false, 'description' => '知识点编码'],
                            ['name' => 'difficulty', 'type' => 'string', 'required' => false, 'description' => '难度等级'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'data' => [
                                ['id' => 5, 'content' => '...'],
                            ],
                            'count' => 10,
                        ],
                    ],
                ],
            ],

            'api/questions/statistics' => [
                'GET' => [
                    'summary' => '获取题目统计信息',
                    'description' => '获取题库的统计数据，包括总数、各难度分布等',
                    'params' => [],
                    'response' => [
                        'success' => [
                            'total' => 1000,
                            'by_difficulty' => [
                                'easy' => 300,
                                'medium' => 500,
                                'hard' => 200,
                            ],
                            'by_knowledge_point' => [
                                'MATH_ADD' => 150,
                                'MATH_SUB' => 120,
                            ],
                        ],
                    ],
                ],
            ],

            'api/questions/generate' => [
                'POST' => [
                    'summary' => 'AI 生成题目',
                    'description' => '使用 AI 根据知识点和关键词生成新题目（异步任务）',
                    'params' => [
                        'body' => [
                            ['name' => 'kp_code', 'type' => 'string', 'required' => true, 'description' => '知识点编码'],
                            ['name' => 'keyword', 'type' => 'string', 'required' => false, 'description' => '生成关键词/提示'],
                            ['name' => 'count', 'type' => 'integer', 'required' => false, 'default' => '5', 'description' => '生成数量'],
                            ['name' => 'strategy', 'type' => 'string', 'required' => false, 'description' => '生成策略'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'task_id' => 'task_abc123',
                            'message' => 'Generation task started',
                        ],
                        'error' => [
                            'success' => false,
                            'message' => '生成失败原因',
                        ],
                    ],
                ],
            ],

            'api/questions/{id}/solution' => [
                'GET' => [
                    'summary' => '获取题目解析',
                    'description' => '获取指定题目的详细解析和解题步骤',
                    'params' => [
                        'path' => [
                            ['name' => 'id', 'type' => 'integer', 'required' => true, 'description' => '题目 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'id' => 1,
                            'solution' => '解题步骤...',
                            'key_points' => ['加法运算', '进位'],
                        ],
                    ],
                ],
            ],

            // ==================== 试卷 API ====================
            'api/papers/assemble' => [
                'POST' => [
                    'summary' => '组装试卷',
                    'description' => '根据题目 ID 列表组装生成试卷',
                    'params' => [
                        'body' => [
                            ['name' => 'question_ids', 'type' => 'array', 'required' => true, 'description' => '题目 ID 数组'],
                            ['name' => 'title', 'type' => 'string', 'required' => false, 'description' => '试卷标题'],
                            ['name' => 'description', 'type' => 'string', 'required' => false, 'description' => '试卷描述'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'paper_id' => 'paper_abc123',
                            'title' => '期中测试卷',
                            'question_count' => 20,
                            'created_at' => '2024-01-01T00:00:00Z',
                        ],
                    ],
                ],
            ],

            'api/papers/{paperId}/json' => [
                'GET' => [
                    'summary' => '获取试卷 JSON',
                    'description' => '返回与智能出卷返回值中 exam_content 完全一致的试卷 JSON，可预览或下载',
                    'params' => [
                        'path' => [
                            ['name' => 'paperId', 'type' => 'string', 'required' => true, 'description' => '试卷 ID'],
                        ],
                        'query' => [
                            ['name' => 'download', 'type' => 'integer', 'required' => false, 'description' => '设为 1 时下载 JSON 文件'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'paper_id' => 'paper_abc123',
                            'title' => '期中测试卷',
                            'questions' => [
                                ['id' => 1, 'content' => '...', 'answer' => '...'],
                            ],
                        ],
                    ],
                    'examples' => [
                        'GET /api/papers/paper_1765788931_ce02f6a3/json',
                        'GET /api/papers/paper_1765788931_ce02f6a3/json?download=1',
                    ],
                ],
            ],

            // ==================== 智能出卷与学情报告 ====================
            'api/intelligent-exams' => [
                'POST' => [
                    'summary' => '智能出卷',
                    'description' => '根据学生情况智能生成个性化试卷，返回 PDF 和判卷地址',
                    'params' => [
                        'body' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'knowledge_points', 'type' => 'array', 'required' => false, 'description' => '指定知识点列表'],
                            ['name' => 'difficulty', 'type' => 'string', 'required' => false, 'description' => '难度偏好：easy/medium/hard/adaptive'],
                            ['name' => 'question_count', 'type' => 'integer', 'required' => false, 'default' => '20', 'description' => '题目数量'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'task_id' => 'exam_task_abc123',
                            'status' => 'processing',
                            'message' => '试卷生成任务已提交',
                        ],
                    ],
                ],
            ],

            'api/intelligent-exams/status/{taskId}' => [
                'GET' => [
                    'summary' => '查询出卷任务状态',
                    'description' => '查询智能出卷任务的处理状态',
                    'params' => [
                        'path' => [
                            ['name' => 'taskId', 'type' => 'string', 'required' => true, 'description' => '任务 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'task_id' => 'exam_task_abc123',
                            'status' => 'completed',
                            'pdf_url' => '/storage/exams/exam_abc123.pdf',
                            'exam_content' => ['...'],
                        ],
                        'pending' => [
                            'task_id' => 'exam_task_abc123',
                            'status' => 'processing',
                            'progress' => 60,
                        ],
                    ],
                ],
            ],

            'api/exam-analysis/report' => [
                'POST' => [
                    'summary' => '生成学情报告',
                    'description' => '根据学生答题数据生成学情分析报告 PDF',
                    'params' => [
                        'body' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'exam_id', 'type' => 'string', 'required' => false, 'description' => '指定考试 ID'],
                            ['name' => 'date_range', 'type' => 'object', 'required' => false, 'description' => '日期范围 {start, end}'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'task_id' => 'report_task_abc123',
                            'status' => 'processing',
                        ],
                    ],
                ],
            ],

            'api/exam-analysis/status/{taskId}' => [
                'GET' => [
                    'summary' => '查询学情报告任务状态',
                    'description' => '查询学情报告生成任务的处理状态',
                    'params' => [
                        'path' => [
                            ['name' => 'taskId', 'type' => 'string', 'required' => true, 'description' => '任务 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'task_id' => 'report_task_abc123',
                            'status' => 'completed',
                            'pdf_url' => '/storage/reports/report_abc123.pdf',
                        ],
                    ],
                ],
            ],

            // ==================== 错题本 API ====================
            'api/mistake-book' => [
                'GET' => [
                    'summary' => '获取错题列表',
                    'description' => '获取学生的错题记录列表，支持分页和筛选',
                    'params' => [
                        'query' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'page', 'type' => 'integer', 'required' => false, 'default' => '1', 'description' => '页码'],
                            ['name' => 'per_page', 'type' => 'integer', 'required' => false, 'default' => '20', 'description' => '每页数量'],
                            ['name' => 'kp_code', 'type' => 'string', 'required' => false, 'description' => '按知识点筛选'],
                            ['name' => 'error_type', 'type' => 'string', 'required' => false, 'description' => '错误类型筛选'],
                            ['name' => 'is_favorite', 'type' => 'boolean', 'required' => false, 'description' => '只看收藏'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'data' => [
                                [
                                    'id' => 1,
                                    'question_id' => 100,
                                    'question_content' => '...',
                                    'student_answer' => '...',
                                    'correct_answer' => '...',
                                    'error_type' => 'calculation',
                                    'is_favorite' => false,
                                    'review_count' => 2,
                                    'created_at' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'meta' => ['page' => 1, 'total' => 50],
                        ],
                    ],
                ],
                'POST' => [
                    'summary' => '新增错题',
                    'description' => '添加新的错题记录',
                    'params' => [
                        'body' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'question_id', 'type' => 'integer', 'required' => true, 'description' => '题目 ID'],
                            ['name' => 'student_answer', 'type' => 'string', 'required' => true, 'description' => '学生答案'],
                            ['name' => 'error_type', 'type' => 'string', 'required' => false, 'description' => '错误类型'],
                            ['name' => 'notes', 'type' => 'string', 'required' => false, 'description' => '备注'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'id' => 1,
                            'message' => '错题已添加',
                        ],
                    ],
                ],
            ],

            'api/mistake-book/{mistakeId}' => [
                'GET' => [
                    'summary' => '获取错题详情',
                    'description' => '获取单条错题的详细信息',
                    'params' => [
                        'path' => [
                            ['name' => 'mistakeId', 'type' => 'integer', 'required' => true, 'description' => '错题记录 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'id' => 1,
                            'question' => ['id' => 100, 'content' => '...', 'answer' => '...'],
                            'student_answer' => '...',
                            'error_analysis' => '...',
                            'review_history' => [],
                        ],
                    ],
                ],
            ],

            'api/mistake-book/{mistakeId}/favorite' => [
                'POST' => [
                    'summary' => '收藏/取消收藏错题',
                    'description' => '切换错题的收藏状态',
                    'params' => [
                        'path' => [
                            ['name' => 'mistakeId', 'type' => 'integer', 'required' => true, 'description' => '错题记录 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'is_favorite' => true,
                        ],
                    ],
                ],
            ],

            'api/mistake-book/{mistakeId}/review' => [
                'POST' => [
                    'summary' => '标记错题已复习',
                    'description' => '将错题标记为已复习状态',
                    'params' => [
                        'path' => [
                            ['name' => 'mistakeId', 'type' => 'integer', 'required' => true, 'description' => '错题记录 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'review_count' => 3,
                            'last_review_at' => '2024-01-01T00:00:00Z',
                        ],
                    ],
                ],
            ],

            'api/mistake-book/snapshot' => [
                'GET' => [
                    'summary' => '获取错题本快照',
                    'description' => '获取错题本的统计快照数据，用于仪表板展示',
                    'params' => [
                        'query' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'total_mistakes' => 50,
                            'reviewed_count' => 30,
                            'favorite_count' => 10,
                            'by_knowledge_point' => [
                                ['kp_code' => 'MATH_ADD', 'count' => 15],
                            ],
                            'recent_mistakes' => [],
                        ],
                    ],
                ],
            ],

            'api/mistake-book/batch-operation' => [
                'POST' => [
                    'summary' => '错题批量操作',
                    'description' => '对多条错题进行批量操作',
                    'params' => [
                        'body' => [
                            ['name' => 'mistake_ids', 'type' => 'array', 'required' => true, 'description' => '错题 ID 数组'],
                            ['name' => 'operation', 'type' => 'string', 'required' => true, 'description' => '操作类型：mark_reviewed/mark_mastered/favorite/unfavorite'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'affected_count' => 5,
                        ],
                    ],
                ],
            ],

            // ==================== 知识点掌握 API ====================
            'api/knowledge-mastery/stats/{studentId}' => [
                'GET' => [
                    'summary' => '获取知识点掌握统计',
                    'description' => '获取学生各知识点的掌握情况统计数据',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'student_id' => '1764913638',
                            'total_knowledge_points' => 50,
                            'average_mastery' => 0.75,
                            'mastered_count' => 25,
                            'good_count' => 15,
                            'weak_count' => 10,
                            'details' => [
                                ['kp_code' => 'MATH_ADD', 'kp_name' => '加法运算', 'mastery_level' => 0.85, 'mastery_change' => 0.05],
                            ],
                        ],
                    ],
                ],
            ],

            'api/knowledge-mastery/summary/{studentId}' => [
                'GET' => [
                    'summary' => '获取知识点掌握摘要',
                    'description' => '获取学生知识点掌握情况的简化摘要信息',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'student_id' => '1764913638',
                            'total' => 50,
                            'mastered' => 25,
                            'unmastered' => 25,
                            'mastery_rate' => 0.5,
                            'mastery_percentage' => '50%',
                        ],
                    ],
                ],
            ],

            'api/knowledge-mastery/graph/{studentId}' => [
                'GET' => [
                    'summary' => '获取知识点图谱数据',
                    'description' => '获取学生的知识点掌握图谱可视化数据',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'query' => [
                            ['name' => 'exam_id', 'type' => 'string', 'required' => false, 'description' => '考试 ID（可选）'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'nodes' => [
                                ['id' => 'MATH_ADD', 'name' => '加法运算', 'mastery' => 0.85, 'category' => '计算'],
                            ],
                            'edges' => [
                                ['source' => 'MATH_ADD', 'target' => 'MATH_SUB'],
                            ],
                            'statistics' => [
                                'total_nodes' => 50,
                                'total_edges' => 45,
                                'average_mastery' => 0.75,
                            ],
                        ],
                    ],
                ],
            ],

            'api/knowledge-mastery/graph/snapshots/{studentId}' => [
                'GET' => [
                    'summary' => '获取知识点图谱快照列表',
                    'description' => '获取学生知识点图谱的历史快照列表',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'query' => [
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '10', 'description' => '返回数量限制'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'snapshots' => [
                                [
                                    'snapshot_id' => 'snap_001',
                                    'overall_mastery' => 0.75,
                                    'weak_count' => 10,
                                    'strong_count' => 25,
                                    'created_at' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'total' => 5,
                        ],
                    ],
                ],
            ],

            'api/knowledge-mastery/snapshots/{studentId}' => [
                'GET' => [
                    'summary' => '获取知识点快照列表（简化路径）',
                    'description' => '获取学生知识点掌握情况的历史快照列表（简化路径）',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'query' => [
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '10', 'description' => '返回数量限制'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'snapshots' => [
                                [
                                    'snapshot_id' => 'snap_001',
                                    'overall_mastery' => 0.75,
                                    'weak_count' => 10,
                                    'strong_count' => 25,
                                    'created_at' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'total' => 5,
                        ],
                    ],
                ],
            ],

            'api/knowledge-mastery/snapshot/{studentId}' => [
                'POST' => [
                    'summary' => '创建知识点掌握度快照',
                    'description' => '为学生当前知识点掌握情况创建快照记录',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'body' => [
                            ['name' => 'snapshot_type', 'type' => 'string', 'required' => false, 'default' => 'report', 'description' => '快照类型'],
                            ['name' => 'source_id', 'type' => 'string', 'required' => false, 'description' => '来源 ID'],
                            ['name' => 'source_name', 'type' => 'string', 'required' => false, 'description' => '来源名称'],
                            ['name' => 'notes', 'type' => 'string', 'required' => false, 'description' => '备注信息'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'message' => '快照创建成功',
                            'data' => [
                                'snapshot_id' => 'snap_new_001',
                                'student_id' => '1764913638',
                                'created_at' => '2024-01-01T00:00:00Z',
                            ],
                        ],
                    ],
                ],
            ],

            // ==================== 教材 API ====================
            'api/textbooks' => [
                'GET' => [
                    'summary' => '获取教材列表',
                    'description' => '获取所有教材列表，按年级排序',
                    'params' => [],
                    'response' => [
                        'success' => [
                            'data' => [
                                ['id' => 1, 'name' => '七年级上册', 'grade' => 7, 'semester' => 1],
                            ],
                        ],
                    ],
                ],
            ],

            'api/textbooks/{id}' => [
                'GET' => [
                    'summary' => '获取教材详情',
                    'description' => '获取单个教材的详细信息',
                    'params' => [
                        'path' => [
                            ['name' => 'id', 'type' => 'integer', 'required' => true, 'description' => '教材 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'id' => 1,
                            'name' => '七年级上册',
                            'grade' => 7,
                            'chapters' => [],
                        ],
                    ],
                ],
            ],

            'api/textbooks/{id}/catalog' => [
                'GET' => [
                    'summary' => '获取教材目录',
                    'description' => '获取教材的章节目录结构',
                    'params' => [
                        'path' => [
                            ['name' => 'id', 'type' => 'integer', 'required' => true, 'description' => '教材 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'chapters' => [
                                [
                                    'id' => 1,
                                    'title' => '第一章 有理数',
                                    'sections' => [
                                        ['id' => 11, 'title' => '1.1 正数和负数'],
                                    ],
                                ],
                            ],
                        ],
                    ],
                ],
            ],

            // ==================== 知识点与能力 API ====================
            'api/knowledge-points' => [
                'GET' => [
                    'summary' => '获取知识点列表',
                    'description' => '获取所有知识点选项，用于下拉选择',
                    'params' => [],
                    'response' => [
                        'success' => [
                            ['code' => 'MATH_ADD', 'name' => '加法运算'],
                            ['code' => 'MATH_SUB', 'name' => '减法运算'],
                        ],
                    ],
                ],
            ],

            'api/knowledge/recommend' => [
                'GET' => [
                    'summary' => '知识点推荐',
                    'description' => '根据学生情况推荐需要加强的知识点',
                    'params' => [
                        'query' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '5', 'description' => '推荐数量'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'recommendations' => [
                                ['kp_code' => 'MATH_FRAC', 'kp_name' => '分数运算', 'reason' => '错题率较高', 'priority' => 1],
                            ],
                        ],
                    ],
                ],
            ],

            'api/abilities/evaluate' => [
                'POST' => [
                    'summary' => '能力评估',
                    'description' => '评估学生的数学能力水平',
                    'params' => [
                        'body' => [
                            ['name' => 'student_id', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'answers', 'type' => 'array', 'required' => true, 'description' => '答题记录数组'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'student_id' => 1,
                            'abilities' => [
                                ['name' => '计算能力', 'score' => 85],
                                ['name' => '逻辑推理', 'score' => 78],
                            ],
                            'overall_score' => 80,
                        ],
                    ],
                ],
            ],

            // ==================== MathRecSys 集成 API ====================
            'api/mathrecsys/health' => [
                'GET' => [
                    'summary' => 'MathRecSys 健康检查',
                    'description' => '检查 MathRecSys 服务的健康状态',
                    'params' => [],
                    'response' => [
                        'success' => [
                            'status' => 'healthy',
                            'service' => 'MathRecSys',
                            'timestamp' => '2024-01-01T00:00:00Z',
                        ],
                    ],
                ],
            ],

            'api/mathrecsys/students/{studentId}' => [
                'GET' => [
                    'summary' => '获取学生完整信息',
                    'description' => '从 MathRecSys 获取学生的完整学习信息',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'id' => 1,
                            'name' => '张三',
                            'grade' => 7,
                            'learning_profile' => [],
                        ],
                    ],
                ],
            ],

            'api/mathrecsys/students/{studentId}/recommendations' => [
                'GET' => [
                    'summary' => '获取个性化推荐',
                    'description' => '获取基于学生学习情况的个性化题目推荐',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'query' => [
                            ['name' => 'count', 'type' => 'integer', 'required' => false, 'default' => '10', 'description' => '推荐数量'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'recommendations' => [
                                ['question_id' => 100, 'reason' => '加强分数运算', 'priority' => 1],
                            ],
                        ],
                    ],
                ],
            ],

            'api/mathrecsys/students/{studentId}/trajectory' => [
                'GET' => [
                    'summary' => '获取学习轨迹',
                    'description' => '获取学生的学习轨迹数据',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'integer', 'required' => true, 'description' => '学生 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'trajectory' => [
                                ['date' => '2024-01-01', 'activity' => 'practice', 'duration' => 30],
                            ],
                        ],
                    ],
                ],
            ],

            'api/mathrecsys/classes/{classId}/analysis' => [
                'GET' => [
                    'summary' => '班级分析',
                    'description' => '获取班级整体学习分析数据',
                    'params' => [
                        'path' => [
                            ['name' => 'classId', 'type' => 'integer', 'required' => true, 'description' => '班级 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'class_id' => 1,
                            'student_count' => 40,
                            'average_mastery' => 0.75,
                            'weak_points' => [],
                        ],
                    ],
                ],
            ],

            // ==================== 学生作答分析 API ====================
            'api/student-answers/analyze' => [
                'POST' => [
                    'summary' => '提交学生作答结果',
                    'description' => '接收外部系统发送的学生作答结果，进行AI分析并更新掌握度',
                    'params' => [
                        'body' => [
                            ['name' => 'paper_id', 'type' => 'string', 'required' => true, 'description' => '试卷 ID'],
                            ['name' => 'student_id', 'type' => 'string', 'required' => true, 'description' => '学生 ID'],
                            ['name' => 'answers', 'type' => 'array', 'required' => true, 'description' => '作答结果数组'],
                            ['name' => 'answers.*.question_id', 'type' => 'string', 'required' => true, 'description' => '题目 ID'],
                            ['name' => 'answers.*.is_correct', 'type' => 'boolean', 'required' => true, 'description' => '是否正确'],
                            ['name' => 'answers.*.student_answer', 'type' => 'string', 'required' => false, 'description' => '学生答案'],
                            ['name' => 'answers.*.correct_answer', 'type' => 'string', 'required' => false, 'description' => '正确答案'],
                            ['name' => 'answers.*.score', 'type' => 'number', 'required' => false, 'description' => '得分'],
                            ['name' => 'answers.*.max_score', 'type' => 'number', 'required' => false, 'description' => '满分'],
                            ['name' => 'answers.*.step_scores', 'type' => 'array', 'required' => false, 'description' => '简答题步骤得分'],
                            ['name' => 'answers.*.knowledge_point', 'type' => 'string', 'required' => false, 'description' => '知识点编码'],
                            ['name' => 'answer_time', 'type' => 'timestamp', 'required' => false, 'description' => '答题时间'],
                            ['name' => 'submit_time', 'type' => 'timestamp', 'required' => false, 'description' => '提交时间'],
                            ['name' => 'source_system', 'type' => 'string', 'required' => false, 'description' => '来源系统'],
                            ['name' => 'callback_url', 'type' => 'url', 'required' => false, 'description' => '回调通知 URL'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'success' => true,
                            'message' => '作答结果已提交，正在分析中...',
                            'data' => [
                                'task_id' => 'analysis_task_xxx',
                                'paper_id' => 'paper_xxx',
                                'student_id' => 'student_xxx',
                                'status' => 'processing',
                                'created_at' => '2024-01-01T00:00:00Z',
                            ],
                        ],
                    ],
                ],
            ],

            'api/student-answers/analysis/status/{taskId}' => [
                'GET' => [
                    'summary' => '查询分析任务状态',
                    'description' => '查询作答分析任务的处理状态',
                    'params' => [
                        'path' => [
                            ['name' => 'taskId', 'type' => 'string', 'required' => true, 'description' => '任务 ID'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'task_id' => 'analysis_task_xxx',
                            'type' => 'analysis',
                            'status' => 'completed',
                            'progress' => 100,
                            'message' => '分析完成',
                            'answer_record_id' => 'ans_xxx',
                            'analysis_id' => 'analysis_xxx',
                            'mastery_snapshot_id' => 'snap_xxx',
                            'correct_count' => 15,
                            'wrong_count' => 5,
                            'overall_mastery' => 0.75,
                            'completed_at' => '2024-01-01T00:05:00Z',
                        ],
                        'pending' => [
                            'task_id' => 'analysis_task_xxx',
                            'status' => 'processing',
                            'progress' => 60,
                            'message' => '正在更新掌握度...',
                        ],
                    ],
                ],
            ],

            'api/student-answers/history/{studentId}' => [
                'GET' => [
                    'summary' => '获取学生学习历史',
                    'description' => '获取学生的练习记录、错题记录和掌握度快照历史',
                    'params' => [
                        'path' => [
                            ['name' => 'studentId', 'type' => 'string', 'required' => true, 'description' => '学生 ID'],
                        ],
                        'query' => [
                            ['name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => '10', 'description' => '返回记录数量限制'],
                        ],
                    ],
                    'response' => [
                        'success' => [
                            'exercises' => [
                                [
                                    'student_id' => 'student_xxx',
                                    'question_id' => 'q_xxx',
                                    'is_correct' => true,
                                    'kp_code' => 'MATH_ADD',
                                    'created_at' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'mistakes' => [
                                [
                                    'student_id' => 'student_xxx',
                                    'question_id' => 'q_xxx',
                                    'error_type' => 'calculation',
                                    'review_status' => 'pending',
                                    'created_at' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'mastery_snapshots' => [
                                [
                                    'snapshot_id' => 'snap_xxx',
                                    'overall_mastery' => 0.75,
                                    'weak_knowledge_points_count' => 3,
                                    'strong_knowledge_points_count' => 7,
                                    'snapshot_time' => '2024-01-01T00:00:00Z',
                                ],
                            ],
                            'summary' => [
                                'total_exercises' => 100,
                                'total_mistakes' => 25,
                                'mastery_snapshots_count' => 10,
                            ],
                        ],
                    ],
                ],
            ],
        ];
    }

    /**
     * 获取指定 API 的文档
     */
    public static function get(string $uri, ?string $method = null): ?array
    {
        $docs = self::all();

        if (!isset($docs[$uri])) {
            return null;
        }

        if ($method) {
            return $docs[$uri][$method] ?? null;
        }

        return $docs[$uri];
    }

    /**
     * 获取 HTTP 方法的颜色样式
     */
    public static function getMethodColor(string $method): string
    {
        return match (strtoupper($method)) {
            'GET' => 'bg-green-100 text-green-700 border-green-200',
            'POST' => 'bg-blue-100 text-blue-700 border-blue-200',
            'PUT' => 'bg-amber-100 text-amber-700 border-amber-200',
            'PATCH' => 'bg-purple-100 text-purple-700 border-purple-200',
            'DELETE' => 'bg-red-100 text-red-700 border-red-200',
            default => 'bg-gray-100 text-gray-700 border-gray-200',
        };
    }
}