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

POST /words/books/default/quick-add — 快速批量添加单词到默认词书（异步） <p>请求体：{@code { "words": ["apple", "banana", ...] }} <p>后台自动查询释义并保存，接口立即返回处理数量。

记录一条失败写操作审计日志。 <p>调用方应在 catch 块中调用本方法。{@code summary} 可包含异常类名 / 简短消息， 但禁止包含密码/key/token/provider body。</p> <p>写入失败不会抛异常（仅 warn log），避免影响主业务的异常传播。</p

回滚预扣的 credits：GREATEST 防止越界减为负数

用户注册 <p>注册成功后自动创建默认词书，并直接返回登录态（免去二次登录）。 @param req 注册请求（用户名 + 邮箱 + 密码） @return 包含 token 和 user 信息的 Map @throws RuntimeException 用户名或邮箱已被占用时抛出

* Render a single PDF page to an HTMLCanvasElement.

Re-number heading matching questions to be sequential.

防御性 ADMIN 校验 + 精细权限校验（Phase 8C）。 <p>Spring Security 已在路由层做 {@code hasRole("ADMIN")} 拦截， 此处做二次校验防止配置遗漏，并要求精细权限以兼容模式/显式模式规则判断。</p>

重置用户密码。 <p>安全：使用 {@link PasswordEncoder#encode(CharSequence)} 存储 BCrypt 哈希， 不记录明文密码日志，不返回 password。 @param targetUserId 目标用户 ID @param newPassword

解析用户当前 keyMode；无设置或为空视为 BUILTIN（与扣费路径回退逻辑一致）

解析 USER 模式凭据。任何字段缺失 / 解密失败抛 {@link IllegalStateException}， 异常信息<b>不</b>包含 key 或密文。

根据 provider 决定 vision 任务的 maxTokens。 USER 模式下自定义 provider（OPENAI_COMPATIBLE）默认使用 {@link #aiMaxTokens}。

计算剩余额度，下限 0，兼容 null 字段

脱敏：去除 API Key / Authorization / Bearer，并截断到 500 字符 （与 {@code ai_usage_records.error_message} 的 VARCHAR(500) 对齐）。

Split raw text into sections by common IELTS markers. Each returned chunk contains one passage + its questions.

Kick off async word processing — returns immediately with status "processing".

Remove visual/table blocks and inline chart/table lines from question text to keep prompt clean.

异常摘要：类名 + 简短 message，后续由 {@link #sanitize} 脱敏

更新试卷信息

校验 Token 是否有效（签名正确且未过期） @return true 表示 Token 可用

Workflow Step 1 (legacy combined): Extract passages and question group skeleton (no answers).

Workflow Step 1A: Extract passages only (focused, short prompt).

Spring 构造注入：从 {@code app.ai.key-encryption-secret} 读取密钥， 缺失时回退到 {@link #FALLBACK_DEV_SECRET}。 @param secret 配置中的加密密钥（可为空）

构造函数注入 {@link ObjectProvider}，使 {@link AiRedisRateLimiter} 成为可选依赖。 <p>当 {@code app.redis.enabled=false} 时 {@link AiRedisRateLimiter} bean 不存在， {@code

POST /exam-collections/{id}/exams — 添加试卷到试卷集

POST /words/books/default/entries — 添加单词到默认词书 <p>请求体：{@code { "word": "单词", "meaning": "释义", "example": "例句（可选）" }}

POST /exams/ai-chat — AI assistant chat based on exam context body: { "examContext": "...", "question": "..." }

PUT /users/me/password — 修改密码 <p>请求体：{@code { "oldPassword": "旧密码", "newPassword": "新密码（至少8位）" }} <p>需要先验证旧密码正确后，才允许设置新密码。

POST /words/cloze/check — AI 批改完形填空 <p>请求体：{@code { "passage": "...", "blanks": [...], "userAnswers": {"1":"A","2":"C"} }}