返回带数据的成功响应（200）

解析某用户在某任务类型下的凭据。 @param userId 登录用户 ID（为 null 时回退 BUILTIN） @param taskType 任务类型 @return 凭据快照（apiKey 仅存在于后端内存）

脱敏 toString：只输出 key 是否已配置，不输出 key 本身。 避免被无意中打印到日志或异常栈。

AI 调用前守卫（旧签名，provider=null）。 <p>保留兼容；新调用点应使用 {@link #checkBeforeCall(Long, AiFeature, AiKeyMode, String)}。</p>

发送一次 chat completions 请求。 @param request 统一请求（含凭据、消息、参数） @return 统一响应（content / provider / model / statusCode） @throws Exception 网络 / 超时 / provider 错

AI 调用成功后回调（旧签名，provider=null）。 <p>保留兼容；新调用点应使用 {@link #markSuccess(Long, AiFeature, AiKeyMode, String)}。</p>

返回指定状态码的错误响应

AI 调用失败后回调（旧签名，provider=null）。 <p>保留兼容；新调用点应使用 {@link #markFailure(Long, AiFeature, AiKeyMode, String, Exception)}。</p>

按主键查询用户（包含已逻辑删除的用户），用于管理端查看禁用用户详情。

从 Token 中提取角色

从 Token 中提取用户 ID

构造 user 文本消息

返回 404 资源不存在响应

PUT /exam-collections/{id} — 更新试卷集

加密明文 API Key。 @param plainApiKey 明文 Key @return {@code Base64(IV||密文+tag)}；null / 空白输入返回 null

从 Token 中提取用户名

构造 system 文本消息

根据 Provider 类型查找 preset。 @return preset；不存在时返回 {@link Optional#empty()}

Phase 5C-3：所有 AI 调用已接入新 Provider 架构，统一走 {@link AiSettingsService#resolve}，本方法始终返回 true， 避免在 USER 模式下因站点内置 DeepSeek key 为空而被误判为“AI not configured”。

构造一个已存在的默认 BUILTIN 实体（避免触发 insert）

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

更新当前用户 AI 设置，返回更新后的脱敏设置。 <p>本阶段允许在 USER 模式下保存不完整配置（如先填 provider/baseUrl/model 暂不填 key）； 真正解析 credentials 时（{@code AiSettingsService.resolve}）才校验 key

把 provider 调用相关异常脱敏后转为业务异常， 避免把原始 response body / API Key 透传给前端。

批改完形填空。 @param userId 当前登录用户 ID @param passage 短文全文（最长 6000 字符） @param blanks 题目列表（含 number, answer, options, correctOption），最多 20 题 @p

解密 API Key 密文。 @param encryptedApiKey {@code Base64(IV||密文+tag)} 密文 @return 明文 Key；null / 空白输入返回 null @throws IllegalStateException 解密失败（异常信息不含密文 / 明

记录一条成功写操作审计日志。 <p>调用方应在主业务成功返回后调用本方法。{@code request} 用于读取 IP / User-Agent； 可为 null（例如异步场景），此时 IP / UA 字段为 null。</p> <p>写入失败不会抛异常（仅 warn log），避免影响主业务

检查指定用户在指定 feature 上的当前分钟窗口是否允许调用。 @param userId 用户 ID @param feature AI 功能 @param limitPerMinute 每分钟允许调用次数上限 @return {@code true} 允

查询某用户被分配的全部权限。 @param userId 用户 ID @return 权限记录列表（按 id 升序）

管理端统计用户总数（包含已逻辑删除的用户），过滤条件与 {@link #selectAdminUsers} 一致。

DELETE /exam-collections/{id} — 删除试卷集（不删除内部试卷）

查询用户当前周期 quota 行，无则返回 null（不创建）

是否已配置 API Key（非 null 且非空白）

幂等初始化管理员账号。 <p>包级可见以方便单元测试（不强制）。</p>

统计表中权限记录总数，用于判断是否进入显式权限模式。 @return 表中权限记录总数；0 表示仍处于兼容模式（所有 ADMIN 拥有全部权限）

新增用户。 <p>权限：{@link AdminPermission#ADMIN_USERS_MANAGE}</p> <p>规则：role 白名单（USER/ADMIN）、username/email 唯一性、密码 BCrypt 加密、不返回 password。 userId / role 一律

调用 AI 生成完形填空。 @param userId 当前登录用户 ID（由 Controller 从 AuthUser 注入，禁止前端传入） @param words 用户选择的单词列表（1-10 个） @param meanings 对应的中文释义列表（可为空或长度不足

加载用户（包含已禁用），不存在则抛业务异常。

Apply all post-processing fixes to a parsed result: - Enrich letter-only MCQ options with full descriptions - Enrich roman-numeral-only heading option

管理端分页查询用户（包含已逻辑删除的用户）。 <p>使用原生 SQL 而非 wrapper，避免 MyBatis-Plus {@code @TableLogic} 自动追加 {@code deleted = 0} 导致无法查到已禁用用户。</p> @param offset 偏移量（{@cod

校验某 Provider 是否支持给定任务类型。 <p>规则：</p> <ul> <li>自定义模板（OPENAI_COMPATIBLE）默认支持 TEXT 与 VISION（具体能力由用户配置的模型决定）。</li> <li>其它 Provider：当 preset.taskType =

更新用户启用/禁用状态（直接操作 deleted 字段，绕过 @TableLogic 的逻辑删除语义）。 @param id 用户 ID @param deleted 0=启用，1=禁用

更新用户角色。

删除某用户的全部权限记录（用于更新权限时的先删后插策略）。 @param userId 用户 ID @return 被删除的记录数

分页查询用户列表（包含已禁用用户）。 @param page 页码，最小 1（小于 1 自动 clamp 到 1） @param pageSize 每页条数，范围 1~100（越界自动 clamp） @param keyword 关键字（匹配 username / email），可为 n

查询当前用户的 AI 用量视图。 @param userId 当前登录用户 ID（来自 AuthUser） @return 只读用量 DTO（含默认视图，永不返回 null）

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

按 username 或 email 查询用户（含已禁用 deleted=1），用于启动时管理员初始化的"升级现有账号"分支： 若目标用户名/邮箱已存在且为 USER，则升级为 ADMIN 并重置密码。

AI chat: answer user's question based on exam context. Returns plain text answer (not JSON).

Backward-compatible overload without rawText.

统计所有 ADMIN 用户数量（包含已禁用 deleted=1），用于启动时管理员初始化的幂等判断： 只要库中曾存在过 ADMIN（即使被禁用），就不再用环境变量凭据自动创建新的管理员， 避免初始密码被重新激活。

统计拥有指定权限的用户数量，用于"不能移除最后一个权限管理员"保护。 @param permission 权限名（{@link com.ieltsstudio.entity.AdminPermission} 枚举名） @return 拥有该权限的用户数量

判断某用户是否拥有指定权限。 <p>规则： <ul> <li>USER → 永远 false。</li> <li>ADMIN + 兼容模式 → 永远 true。</li> <li>ADMIN + 显式模式 → 表中包含该权限时 true。</li> </ul> <p>注意：role

要求当前用户拥有指定权限，否则抛 {@link org.springframework.security.access.AccessDeniedException}。 <p>Controller 内调用 {@code requirePermission(authUser.getId(), Admi

设置当前周期 creditsTotal。 <ul> <li>无 quota 行：创建当前周期 quota 行（creditsTotal=request, creditsUsed=0）。</li> <li>已存在：更新 creditsTotal，不修改 creditsUsed。</li>

摘要 provider 错误响应体：屏蔽疑似 key / Bearer 片段，并截断到 300 字符。 <p>用于把 provider 原始错误写入日志前的脱敏处理， <b>不得</b>把脱敏后的结果直接返回给前端（前端只看通用提示）。</p> @param body provider 返回的原

更新用户密码哈希（已通过 {@code PasswordEncoder.encode(...)} 加密）。

更新某 ADMIN 用户的权限集合（先删后插）。 <p>执行 5 条安全规则（见类注释），任一不满足时抛 {@link RuntimeException}。</p> <p><b>事务：</b>加 {@link Transactional} 防止"删除成功但插入失败"导致目标 ADMIN 权限被部

管理员新增用户。 <p>规则： <ul> <li>role 必须是 USER / ADMIN（白名单校验，不信任前端）。</li> <li>username / email 必须未被占用（含已禁用用户，避免唯一约束冲突）。</li> <li>密码使用 {@link PasswordEn

当前自然周：周一 00:00:00 到下周一 00:00:00（与 AiUsageGuard 一致）

Ensure the user has a default 生词本; create one if absent.

获取或创建用户设置实体。无记录时插入一条默认 BUILTIN 记录（不含任何 API Key）。

脱敏 API Key，保留首部前缀与尾部 4 位，中间用 {@code } 替代。 <p>示例：</p> <ul> <li>{@code maskApiKey("sk-abcdef123456")} → {@code sk- 3456}</li> <li>{@code mask

解析 Token，返回 Claims（Payload） @throws JwtException Token 无效或已过期时抛出