把 provider 调用相关异常脱敏后转为业务异常， 避免把原始 response body / API Key 透传给前端。 不 log ex.getMessage()，因为里面可能含 provider body。

构建认证响应（Token + 用户信息） <p>登录和注册共用此方法，避免重复代码。

Build fallback questions from Step1 skeleton when Step2 fails for a group. These will have text but no answer/explanation (user can still see the ques

统一 Vision Provider 调用：{@link AiSettingsService} 已解析好 {@link AiCredentials}， 这里只负责 {@link AiUsageGuard} 用量守卫 + {@link OpenAiCompatibleClient} 发请求 + JSO

单机内存限流（Redis 降级路径）。 <p>返回 {@code true} 表示放行；{@code false} 表示触发限流。 不直接写流水、不抛异常，由 {@link #checkUserRateLimit} 统一处理。</p>

统计符合筛选条件的审计日志总数。 <p>筛选参数与 {@link #selectAdminOperationLogs} 一致。</p>

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

启用用户（deleted = 0）。不改变其 role。 @param currentAdminId 当前操作的管理员 ID（保留以保持签名一致，本方法不使用） @param targetUserId 目标用户 ID @return 更新后的用户 DTO @throws RuntimeExce

Ensure Task 1 passages contain a [Visual Data Summary] block. If missing, try to synthesize it from detected chartTitle/chartType lines and data point

Scan raw text for option list patterns like: A There is a complicated combination... B The rainforests are being destroyed... Returns a map of l

构造一个简单的精准解析返回（单 section、1 道 fill 题，避免触发 commitSection 内部 retry）。

Post-processing: detect inline string options like "A cost B falling C technology ..." and convert them into JSON objects.

Post-processing: detect questions with letter-only options (e.g. ["A","B","C",...]) and attempt to extract full option descriptions from the raw input

Validate each question's locatorText against passages + raw input text. If locatorText is not found verbatim, attempt fuzzy correction by searching fo

Detect heading matching questions (MCQ with "Paragraph X" text and roman numeral options) and auto-generate missing paragraph questions when the AI on

Detect MCQ questions whose options is a range string like "i-vii" or "A-F" and replace with properly extracted heading/option objects from raw text.

根据配置的密钥字符串构建 HMAC-SHA 签名密钥

给当前周期增加 creditsTotal。 <ul> <li>无 quota 行：创建（creditsTotal=100+credits, creditsUsed=0）。</li> <li>已存在：creditsTotal += credits，不修改 creditsUsed。</li> <

* 判断当前 Token 是否为本地 Mock Token * Mock Token 以 'mock_token_' 开头，仅用于无后端时的开发调试

分页查询审计日志。page / pageSize 自动 clamp（page≥1，pageSize∈[1,100]）。 <p>所有筛选参数可为 null（不过滤）。结果按 {@code created_at DESC, id DESC} 排序。</p>

列出按任务类型分组的 Provider 预设（含 OPENAI_COMPATIBLE 自定义模板）。 @return {@code {"text": [...], "vision": [...]}}

屏蔽字符串中疑似 API Key / Bearer token 的片段。 保留前 3 位 + {@code }，避免完整 token 进入日志。

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

* Parse options from a multi-line string format: "A: text\nB: text\n..." * or "A text\nB text\n..." (used when AI returns options as plain text).

读取旧 encrypted (encrypted=true) 或 masked (encrypted=false)

仅返回 provider 枚举名或 null，避免在 usage record 中暴露 baseUrl / model / API Key

查询最近 N 条 AI usage records，按 createdAt 倒序。 <p>权限：{@link AdminPermission#ADMIN_AI_USAGE_VIEW}</p> @param limit 返回数量，默认 50，范围 {@code [1, 100]}，越界自动 cla

防御性 ADMIN 校验 + 精细权限校验（Phase 8C）。

校验 API Key 已配置。异常消息<b>不</b>包含 key 本身或任何 key 片段。

重置当前周期 creditsUsed=0。 <ul> <li>无 quota 行：创建默认 quota 行（creditsTotal=100, creditsUsed=0）。</li> <li>已存在：creditsUsed=0。</li> </ul>

构造 user 多模态消息（content 为 List/Map 结构）

Workflow Step 1B: Identify question groups structure only (focused, short prompt).

Workflow Step 2: Given passage and one question group, generate answers and explanations.

Add a word by data (used for builtin/client-side words that have no DB entry).

Vision 调用失败时构造脱敏异常。不输出 ex.getMessage()（可能含 provider body）， 不返回原始 body / Key / Authorization 给调用方。

Assess exam difficulty on a 1-5 scale based on question types, count, and passage complexity. Returns a Chinese label: 入门(1), 简单(2), 中等(3), 较难(4), 困难(

构造 Redis key。 <p>Key 仅包含 userId / feature / epochMinute，禁止拼接 API Key、provider、 baseUrl、model、prompt 等任何敏感或可变信息。</p>

根据正确题数与总题数计算雅思 Band 分 <p>换算标准参考雅思官方评分表（阅读部分）： <pre> 正确率 ≥ 92.5% → Band 9.0 正确率 ≥ 87.5% → Band 8.5 ... 正确率 &lt; 32.5% → Band 4.0 </pre>

预扣 credits：原子更新，credits_total - credits_used >= cost 才成功

Copy a word entry from any book into the user's default 生词本.