CORS 跨域配置 <p>仅允许本地开发地址（localhost / 127.0.0.1 / IPv6 回环）。 <strong>生产环境部署时，请将此处替换为你的实际前端域名。</strong>

当前自然周：周一 00:00:00 到下周一 00:00:00（基于服务器默认时区）

由 secret 派生 AES-256 密钥（SHA-256 → 32 字节）。

Detect lettered paragraphs (A, B, C, ...) from passages and raw text.

禁用用户（deleted = 1）。 <p>权限：{@link AdminPermission#ADMIN_USERS_MANAGE}</p> <p>保护：不能禁用自己、不能禁用最后一个 ADMIN。</p>

提取客户端真实 IP。 <p>优先读 {@code X-Forwarded-For} 第一个 IP（反向代理场景）， 其次 {@code X-Real-IP}，最后 {@code request.getRemoteAddr()}。</p>

Extract heading list from raw text, e.g.: i Avoiding an overcrowded centre ii A successful exercise in people power Returns map like {"i": "A

Phase 5C-3：使用 AI 抽取 heading 列表的 fallback。 <p>流程：{@code AiSettingsService.resolve(userId, TEXT)} → {@code AiUsageGuard.checkBeforeCall(userId, HEADING

Extract the reading passage from raw text by stripping question sections. Looks for where questions start (e.g. "Questions 1-8", numbered items like "

Extract shared options from question explanations. AI often writes "Option E: 'Without rainforests...'" in the explanation.

从请求头 Authorization 中提取 Bearer Token @param request HTTP 请求 @return Token 字符串；若不存在或格式不符则返回 null

Filter out question-like content from passage text. This removes lines that look like questions to prevent mixing article and questions.

Find the substring in `text` that best matches `target` using word-overlap scoring. Returns the best matching window of similar word count, or null if

Generate tags based on exam type, title, and question content. Includes: type label, Academic/General, Task 1/Task 2, Cambridge source, etc.

生成 JWT Token @param userId 用户 ID @param username 用户名 @param role 用户角色 @return 签名后的 JWT 字符串

根据 ID 获取试卷详情

获取试卷下的所有题目

获取或创建当前周期的 quota 行。 <p>并发插入会因 unique key (user_id, period_start) 冲突，捕获后重新查询。</p>

获取当前用户个人信息 @param userId 用户 ID（从 JWT Token 解析） @return 用户信息 Map（不含密码）

获取单次考试记录详情（含 AI 写作反馈） @param recordId 记录 ID @param userId 当前用户 ID（用于鉴权，只能查自己的记录） @return 记录详情 Map；记录不存在或无权限时返回 null

查询单个用户详情（包含已禁用用户）。 @param id 用户 ID @return 用户 DTO（不包含 password） @throws RuntimeException 用户不存在时

获取用户未掌握的错题列表

分页获取试卷列表（支持按类型、关键词筛选）

获取用户所有的考试历史记录

判断 Token 是否已过期 @return true 表示已过期或解析失败

判断字符串是否为合法的 {@link AdminPermission} 枚举名。 @param value 待校验的字符串 @return true=合法权限值；false=非法或 null

列出所有合法权限枚举名（按 {@link AdminPermission#values()} 顺序）。

列出所有 preset（含自定义模板）。

查询最近 {@link #RECENT_RECORD_LIMIT} 条 usage records，按 createdAt 倒序

用户登录 <p>支持使用用户名或邮箱登录，密码使用 BCrypt 比对。 @param req 登录请求（用户名/邮箱 + 密码） @return 包含 token 和 user 信息的 Map @throws RuntimeException 用户不存在或密码错误时抛出

* Mock 登录：从 localStorage 的模拟用户列表中匹配账号密码

* Mock 注册：将新用户存入 localStorage 的模拟用户列表

* OCR all pages of a loaded pdf.js document using tesseract.js. * @param {PDFDocumentProxy} pdf * @param {function} onProgress optional callback(pa

构造 OpenAI-compatible 响应：{"choices":[{"message":{"content":"<content>"}}]}

构造 OpenAI-compatible 响应：{"choices":[{"message":{"content":"<content>"}}]}

Parse a multi-line string of options in "A: text\nB: text\n..." or "A text\nB text\n..." format into a map of letter -> description text.

将 status 参数映射为 deleted 字段值。 <ul> <li>null/空/ALL → null（不过滤）</li> <li>ACTIVE → 0</li> <li>DISABLED → 1</li> <li>其他 → 抛 IllegalArgumentExceptio