-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 我们非常欢迎您为本项目做出贡献！无论是报告错误、提出改进建议，还是直接贡献代码，您的参与都对项目至关重要。
-git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY_NAME.gitgit checkout -b feature/your-feature-name 或 bugfix/issue-number。请为您的分支选择一个描述性的名称。git commit -m "feat: 添加了 XXX 功能" 或 fix: 修复了 YYY 问题 (#issue_number)。请遵循 Conventional Commits 规范编写提交信息。git push origin feature/your-feature-namemain 或 develop)。Closes #issue_number。请参考项目主 README.md 中的“快速开始”部分，使用 install.sh 脚本来设置您的本地开发环境。
本项目使用 MkDocs 和 Material for MkDocs 主题来生成文档网站。
-安装依赖:
- 确保您已安装项目依赖，特别是 mkdocs 和 mkdocs-material。可以运行 pip install -r requirements.txt 来安装或更新。
本地预览文档:
- 在项目根目录下运行以下命令，可以在本地启动一个实时预览服务器，通常访问 http://127.0.0.1:8000 即可查看：
-
docs/ 目录下的 Markdown 文件或 mkdocs.yml 配置文件时，网页会自动刷新。
-构建静态文档: - 要生成静态的 HTML 文档网站（通常用于部署），请在项目根目录下运行： -
- 构建后的文件将默认输出到项目根目录下的site/ 文件夹中。--clean 参数表示在构建前清除旧的构建文件。
-我们期望所有贡献者都能遵守友好和互相尊重的社区行为准则。
-感谢您的贡献！
- - - - - - - - - - - - - -本文档描述了仅供管理员使用的API端点。所有这些端点都需要有效的管理员Token进行认证（通过请求参数 ?token={ADMIN_ACCESS_TOKEN} 传递），并且通常以 /admin 作为路径前缀。
基础路径: /admin/settings
这些端点允许管理员查看和修改应用的核心配置。
-GET /settings)¶settings.json 文件的内容，可能不完全包含通过环境变量最终生效的配置值。敏感信息（如数据库密码）不会在此接口返回。200 OK: 成功获取配置信息。返回 SettingsResponseModel。
- 401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员或无权访问。500 Internal Server Error: 服务器内部错误导致无法获取配置。POST /settings)¶settings.json 文件并尝试动态重新加载配置到应用内存。注意：通过环境变量设置的配置项具有最高优先级，其在内存中的值不会被此API调用修改，但 settings.json 文件中的对应值会被更新。application/json): SettingsUpdatePayload 模型
- 200 OK: 配置成功更新并已重新加载。返回更新后的 SettingsResponseModel。400 Bad Request: 提供的配置数据无效或不符合约束。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。422 Unprocessable Entity: 请求体验证失败。500 Internal Server Error: 配置文件写入失败或更新时发生未知服务器错误。基础路径: /admin/users
这些端点允许管理员管理用户账户。
-GET /users)¶skip (integer, 可选, 默认: 0): 跳过的记录数，用于分页 (最小值为0)。limit (integer, 可选, 默认: 100): 返回的最大记录数 (最小值为1，最大值为200)。200 OK: 成功获取用户列表。返回 List[UserPublicProfile]。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。500 Internal Server Error: 获取用户列表时发生服务器内部错误。GET /users/{user_uid})¶user_uid (string, 必需): 要获取详情的用户的UID。200 OK: 成功获取用户信息。返回 UserPublicProfile 模型。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定UID的用户未找到。PUT /users/{user_uid})¶user_uid (string, 必需): 要更新信息的用户的UID。application/json): AdminUserUpdate 模型200 OK: 用户信息成功更新。返回更新后的 UserPublicProfile 模型。400 Bad Request: 提供的更新数据无效（例如，无效的标签值）。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定UID的用户未找到。422 Unprocessable Entity: 请求体验证失败。基础路径: /admin/papers
这些端点允许管理员管理用户生成的试卷。
-GET /papers)¶skip (integer, 可选, 默认: 0): 跳过的记录数。limit (integer, 可选, 默认: 100): 返回的最大记录数。200 OK: 成功获取试卷摘要列表。返回 List[PaperAdminView]。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。500 Internal Server Error: 获取试卷列表时发生服务器内部错误。GET /papers/{paper_id})paper_id (string, 必需, UUID格式): 要获取详情的试卷ID。200 OK: 成功获取试卷详细信息。返回 PaperFullDetailModel。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定ID的试卷未找到。500 Internal Server Error: 获取试卷详情时发生服务器内部错误。DELETE /papers/{paper_id})paper_id (string, 必需, UUID格式): 要删除的试卷ID。204 No Content: 试卷成功删除。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定ID的试卷未找到。500 Internal Server Error: 删除试卷时发生服务器内部错误。基础路径: /admin/question-banks
这些端点允许管理员管理题库的元数据和题目内容。
-GET /question-banks)200 OK: 成功获取题库元数据列表。返回 List[LibraryIndexItem]。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。500 Internal Server Error: 获取题库元数据时发生服务器内部错误。GET /question-banks/{difficulty_id}/content)difficulty_id (string, 必需): 要获取内容的题库难度ID (例如: "easy", "hybrid")。200 OK: 成功获取题库内容。返回 QuestionBank 模型。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定难度的题库未找到。500 Internal Server Error: 获取题库内容时发生服务器内部错误。POST /question-banks/{difficulty_id}/questions)difficulty_id (string, 必需): 要添加题目的题库难度ID。application/json): QuestionModel 模型201 Created: 题目成功添加到题库。返回已添加的 QuestionModel。400 Bad Request: 提供的题目数据无效。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定难度的题库未找到。422 Unprocessable Entity: 请求体验证失败。500 Internal Server Error: 添加题目到题库时发生服务器内部错误。DELETE /question-banks/{difficulty_id}/questions)difficulty_id (string, 必需): 要删除题目的题库难度ID。index (integer, 必需, ge=0): 要删除的题目在列表中的索引 (从0开始)。204 No Content: 题目成功删除。400 Bad Request: 提供的索引无效。401 Unauthorized: Token缺失或无效。403 Forbidden: 当前用户非管理员。404 Not Found: 指定难度的题库或指定索引的题目未找到。500 Internal Server Error: 删除题目时发生服务器内部错误。版本: 3.0.0
-本文档详细描述了在线考试系统的 API 接口。系统功能包括用户认证、试卷获取、答题、进度保存、历史记录查看以及管理员后台管理等。
-本 API 文档分为以下几个主要部分：
-大部分核心 API 端点需要通过 Token 进行认证。Token 在用户登录或注册成功后返回。
-token={USER_ACCESS_TOKEN} 来传递。token 进行认证，并且服务器端会校验该 Token 对应的用户是否拥有 admin 标签。当前系统使用的是自定义的简单Token机制，并非基于JWT。
-为方便理解，以下列出一些关键的 Pydantic 模型（详细字段请参考各 API 说明）：
-UserCreationPayload: 用户注册请求体。UserCredentials: 用户登录请求体 (FastAPI的OAuth2PasswordRequestForm通常在后台使用，但概念上用户提供用户名密码)。TokenResponse: 认证成功后的 Token 响应。UserPublicProfile: 用户公开信息响应。UserProfileUpdatePayload: 用户更新个人资料请求。UserPasswordUpdatePayload: 用户更新密码请求。PaperDetailModel: （通常作为获取新试卷或历史试卷详情的）试卷详情响应。PaperSubmissionPayload: 提交/更新试卷答案的请求。ProgressUpdateResponse: 更新试卷进度的响应。GradingResultResponse: 试卷批改结果的响应。UserPaperHistoryItem: 用户历史记录条目。LibraryIndexItem: 题库元数据。QuestionModel: 题库题目模型。SettingsResponseModel: 管理员获取配置响应。SettingsUpdatePayload: 管理员更新配置请求。PaperAdminView: 管理员查看试卷摘要。PaperFullDetailAdminView: 管理员查看试卷完整详情。MessageResponse: 通用的消息响应体 (例如，操作成功但无特定数据返回)。ErrorResponse: 通用的错误响应体 (通常由 HTTPException 自动处理)。QuestionTypeEnum, PaperPassStatusEnum, AuthStatusCodeEnum: 常用枚举类型，定义在 app/models/enums.py。本API力求遵循标准的HTTP状态码来指示请求的结果。
-200 OK: 请求成功执行，响应体中通常包含所请求的数据。201 Created: 资源成功创建（例如，用户注册成功后），响应体中可能包含新创建的资源或相关信息（如Token）。204 No Content: 请求成功执行，但响应体中无内容返回（例如，用户成功修改密码后，或部分删除操作成功后）。400 Bad Request: 客户端请求无效。这可能因为参数错误、业务逻辑不满足（如请求的题目数量不足以出题）、或提交的数据格式不正确但不符合特定验证错误类型。响应体的 detail 字段通常包含具体的错误描述。401 Unauthorized: 未认证或认证失败。通常由于Token无效、过期、缺失，或凭证不正确。响应头可能包含 WWW-Authenticate。403 Forbidden: 用户已认证，但无权访问所请求的资源。例如，用户账户被封禁，或普通用户尝试访问管理员专属接口。404 Not Found: 请求的资源不存在。例如，查询一个不存在的试卷ID或用户UID。409 Conflict: 请求与服务器当前状态冲突，无法完成。例如，尝试创建已存在的用户 (UID冲突)。422 Unprocessable Entity: 请求体数据虽然格式正确（例如是合法的JSON），但无法通过Pydantic模型的验证规则（如类型错误、必填字段缺失、值不符合约束等）。响应体通常包含详细的字段级验证错误信息。429 Too Many Requests: 客户端在给定时间内发送的请求过多，已超出速率限制。500 Internal Server Error: 服务器内部发生未预期的错误，导致无法完成请求。关于响应体中的业务状态字段：
-在部分成功响应（如 200 OK）的场景下，响应体内的特定字段（例如 GradingResultResponse 中的 status_code 字段，其值为 PaperPassStatusEnum 枚举的成员如 "PASSED" 或 "FAILED"）会提供更细致的业务处理结果。这些字段用于区分业务逻辑上的不同成功状态，而非HTTP层面的错误。对于API错误，应优先参考HTTP状态码和 HTTPException 返回的 detail 信息。
系统通过读取 data/library/index.json 文件动态生成此枚举。通常可能包含：
easyhybridhardindex.json 中定义的 id)定义在 app/models/user_models.py 中的 UserTag 枚举，主要包括：
admin: 管理员user: 普通用户banned: 禁用用户limited: 受限用户grader: 批阅者 (规划中)examiner: 出题者/题库管理员 (规划中)manager: 运营管理员 (规划中)定义在 app/models/enums.py，目前主要使用：
-- single_choice: 单选题
定义在 app/models/enums.py，例如：
-- PASSED: 已通过
-- FAILED: 未通过
-- PENDING: 待处理/待批改
[end of docs/api/index.md]
- - - - - - - - - - - - - -本文档详细描述了与普通用户操作相关的API端点，包括用户认证、个人资料管理、核心的考试答题流程以及一些公开查询的接口。所有路径相对于应用根路径。
-基础路径: /auth
POST /signin)¶application/json): UserCreationPayload 模型
- 201 Created: 注册成功。返回 TokenResponse 模型。
- 409 Conflict: 用户名已存在。响应体: {"detail": "用户名 'yonghu001' 已被注册。"}422 Unprocessable Entity: 请求数据验证失败 (例如，uid 或 password 不符合要求)。429 Too Many Requests: 请求过于频繁。响应体: {"detail": "注册请求过于频繁，请稍后再试。"}POST /login)¶application/x-www-form-urlencoded 表单数据（由FastAPI的 OAuth2PasswordRequestForm 处理），而非JSON。成功后返回访问令牌。application/x-www-form-urlencoded):username: (string, 必需) 用户名 (对应 uid)password: (string, 必需) 密码200 OK: 登录成功。返回 TokenResponse 模型。401 Unauthorized: 用户名或密码错误。响应体: {"detail": "用户名或密码不正确。"}422 Unprocessable Entity: 请求数据验证失败 (例如，表单字段缺失)。429 Too Many Requests: 请求过于频繁。响应体: {"detail": "登录请求过于频繁，请稍后再试。"}GET /login)¶token 提供）获取一个新的访问令牌。成功后，旧令牌将失效。token (string, 必需): 待刷新的有效旧访问令牌。200 OK: 令牌刷新成功。返回 TokenResponse 模型。401 Unauthorized: 提供的旧令牌无效或已过期。响应体: {"detail": "提供的令牌无效或已过期，无法刷新。"}基础路径: /users/me
-认证: 所有此部分接口都需要用户Token认证 (?token={USER_ACCESS_TOKEN} 作为查询参数)
GET /)¶200 OK: 成功获取用户信息。返回 UserPublicProfile 模型。401 Unauthorized: 令牌无效或已过期。403 Forbidden: 用户账户已被封禁。404 Not Found: 用户未找到（理论上在Token有效时此错误不应发生）。PUT /)¶application/json): UserProfileUpdatePayload 模型 (所有字段可选)200 OK: 更新成功。返回更新后的 UserPublicProfile 模型。401 Unauthorized: 令牌无效或已过期。403 Forbidden: 用户账户已被封禁。404 Not Found: 用户未找到。422 Unprocessable Entity: 请求体验证失败。PUT /password)application/json): UserPasswordUpdatePayload 模型204 No Content: 密码修改成功。无响应体。400 Bad Request: 当前密码不正确。响应体: {"detail": "当前密码不正确。"}401 Unauthorized: 令牌无效或已过期。403 Forbidden: 用户账户已被封禁。404 Not Found: 用户未找到。422 Unprocessable Entity: 新密码不符合要求。500 Internal Server Error: 更新密码时发生未知错误。认证: 所有此部分接口都需要用户Token认证 (?token={USER_ACCESS_TOKEN} 作为查询参数)
GET /get_exam)¶token (string, 必需): 用户访问令牌。difficulty (string, 可选, 默认: "hybrid"): 新试卷的难度级别 (来自 DifficultyLevel 枚举)。num_questions (integer, 可选, 1-200): 请求的题目数量。200 OK: 成功获取新试卷。返回 PaperDetailModel 模型，其中 questions 列表中的题目为 ExamQuestionClientView 类型。
- // PaperDetailModel (部分) 结合 ExamQuestionClientView 示例
-{
- "paper_id": "uuid-string-paper-id",
- "user_uid": "yonghu001",
- "difficulty": "hybrid",
- "num_questions": 2, // 实际生成的题目数
- "questions": [
- {
- "question_id": "uuid-string-q1", // 题目在试卷中的唯一ID
- "body": "题目1的题干内容...",
- "choices": [ // 所有选项合并打乱后呈现给用户
- "选项A文本",
- "选项B文本",
- "选项C文本",
- "选项D文本"
- ],
- "question_type": "single_choice" // 题目类型
- },
- {
- "question_id": "uuid-string-q2",
- "body": "题目2的题干内容...",
- "choices": [
- "选项X文本",
- "选项Y文本",
- "选项Z文本"
- ],
- "question_type": "single_choice"
- }
- ],
- "created_at": "2024-01-01T10:00:00Z",
- "pass_status": "PENDING" // 初始为待处理
- // ... 其他试卷元数据
-}
-400 Bad Request: 请求参数无效或业务逻辑错误（如题库题目不足）。401 Unauthorized: 令牌无效或已过期。403 Forbidden: 用户账户已被封禁。429 Too Many Requests: 获取新试卷请求过于频繁。500 Internal Server Error: 创建新试卷时发生意外服务器错误。POST /update)¶token (string, 必需): 用户访问令牌。application/json): PaperSubmissionPayload 模型200 OK: 进度已成功保存。返回 ProgressUpdateResponse 模型。
- 400 Bad Request: 请求数据无效（如答案数量错误）。401 Unauthorized: 令牌无效或已过期。403 Forbidden: 试卷已完成，无法更新进度。404 Not Found: 试卷未找到或用户无权访问。500 Internal Server Error: 更新进度时发生意外服务器错误。POST /finish)¶token (string, 必需): 用户访问令牌。application/json): PaperSubmissionPayload 模型200 OK: 试卷已成功接收并完成批改。返回 GradingResultResponse 模型。
- 400 Bad Request: 无效的提交数据（例如，提交的答案数量与试卷题目总数不匹配）。401 Unauthorized: 用户未认证（Token无效或缺失）。403 Forbidden: 用户无权进行此操作（非预期，但为完备性保留）。404 Not Found: 要提交的试卷ID不存在，或不属于当前用户。409 Conflict: 操作冲突（例如，该试卷已被最终批改且系统配置为不允许重复提交）。422 Unprocessable Entity: 请求体数据校验失败。500 Internal Server Error: 服务器内部错误（例如，因试卷数据结构问题导致无法批改，或在批改过程中发生其他意外）。GET /history)¶token (string, 必需): 用户访问令牌。200 OK: 成功获取答题历史。返回 List[UserPaperHistoryItem]。401 Unauthorized: 令牌无效或已过期。GET /history_paper)token (string, 必需): 用户访问令牌。paper_id (string, 必需, UUID格式): 要获取详情的历史试卷ID。200 OK: 成功获取历史试卷详情。返回 PaperDetailModel (或类似的包含完整题目、用户答案和正确答案的详细模型)。401 Unauthorized: 令牌无效或已过期。404 Not Found: 指定的历史试卷未找到或用户无权查看。响应体: {"detail": "指定的历史试卷未找到或您无权查看。"}此部分包含所有公开访问的API端点，无需用户认证。
-GET /difficulties)¶200 OK: 成功获取题库难度列表。返回 List[LibraryIndexItem]。500 Internal Server Error: 获取题库元数据时发生服务器内部错误。GET /users/directory)200 OK: 成功获取用户目录列表。返回 List[UserDirectoryEntry]。500 Internal Server Error: 获取用户目录时发生服务器内部错误。[end of docs/api/user_exam.md]
- - - - - - - - - - - - - - - - -