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

summary 脱敏 + 截断（Phase 8D-polish 增强）。 <p>规则（按顺序依次替换，保留 key 名与分隔符，掩盖敏感值）： <ol> <li>{@code Authorization: Bearer xxx} / {@code Authorization=xxx} → {@

汇总最近 N 天的 AI usage 统计。 <p>权限：{@link AdminPermission#ADMIN_AI_USAGE_VIEW}</p> @param days 统计天数，默认 7，范围 {@code [1, 90]}，越界自动 clamp

User → AdminUserDto 映射。<b>不包含 password 字段</b>。

构造某用户的权限视图 DTO（包含 userId / username / role / explicitMode / permissions）。

统计当前启用的 ADMIN 用户数量（deleted = 0），用于"不能禁用/降级最后一个管理员"保护。

检查 username 或 email 是否已被占用（含已禁用用户），用于启动时管理员初始化的冲突检测， 避免插入时撞 users.username / users.email 的 UNIQUE 约束。

Try to skip intro/preamble pages and start from actual exam content. Looks for common IELTS test-content markers; returns the original text if none fo

按任务类型筛选 preset。 <p>规则：taskType 为 null 的自定义模板（OPENAI_COMPATIBLE）不会被返回， 因为它的任务类型由用户配置时决定，不属于某一固定任务类型的预设。</p>

分页查询用户当前周期 quota 列表。无 quota 行的用户返回虚拟默认视图，不创建行。

构造 guard 并注入可选的 Redis limiter mock；传 null 模拟 Redis 未启用

Upload PDF bytes to LlamaParse, poll for completion, return markdown text. Blocks in the calling thread (call from @Async context only).

注册一个 preset。本阶段主要为内置 preset 服务；后续阶段可由用户自定义 Provider 注入。

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

去除首尾空白，空白字符串返回 null。

修改用户角色。 <p>保护：不能降级自己、不能降级最后一个 ADMIN、role 必须是 USER / ADMIN。 @param currentAdminId 当前操作的管理员 ID（从 AuthUser 取） @param targetUserId 目标用户 ID @param role

禁用用户（deleted = 1）。 <p>保护：不能禁用自己、不能禁用最后一个 ADMIN。 @param currentAdminId 当前操作的管理员 ID @param targetUserId 目标用户 ID @return 更新后的用户 DTO @throws RuntimeEx

Phase 5C-3：写作要点生成迁移到新 Provider 架构。 <p>流程：{@code AiSettingsService.resolve(userId, TEXT)} → {@code AiUsageGuard.checkBeforeCall(userId, WRITING_GUIDAN

Get heading descriptions: try regex extraction first, fall back to AI extraction. <p>Phase 5C-3：{@code userId == null} 时跳过 AI fallback（旧 {@code postP

获取当前用户 AI 设置；无记录时创建默认 BUILTIN 设置并返回。

查询某用户的有效权限集合。 <p>规则： <ul> <li>USER → 永远返回空集合。</li> <li>ADMIN + 兼容模式 → 返回全部权限枚举。</li> <li>ADMIN + 显式模式 → 返回表中的权限。</li> </ul> @param userId 用户 I

查询单个用户当前周期 quota。无 quota 行时返回虚拟默认视图，不创建行。

Handle the structured JSON returned by QwenAiParseService. The result may contain {"sections":[...]} or flat {"passages":[...],"questions":[...]}.

是否处于显式权限模式：表非空时为 true。

生成 masked key，供前端展示 / 日志记录。 <p>委托 {@link AiLogSanitizer#maskApiKey(String)}，行为示例：{@code sk-abcdef123456 → sk-abc 3456}。</p> @param plainApiKey 明文

读取请求体并返回字符串。

防御性校验：Controller 正常会传 {@code authUser.getId()}， 但 Service 层自己也应拒绝 null userId，避免后续查询/写入出现 NPE 或脏数据。

插入 quota 行，处理 (user_id, period_start) 唯一约束并发冲突： 插入失败时重新查询已存在的行返回。

通用脱敏：移除 Authorization 头、屏蔽疑似 key 片段、截断过长内容。 <p>适用于把任意输入（请求头、字符串、异常 message）写入日志前的处理。</p> @param input 原始输入 @return 脱敏后的字符串；null 返回空串

分页查询审计日志，按 created_at DESC 排序。 <p>所有筛选参数均可为 null（表示不过滤）。使用 {@code <script>} 动态 SQL 保持项目现有 Mapper 风格。</p> @param offset 偏移量（page pageSize） @par

发送 JSON 响应。

启动绑定 127.0.0.1 + 随机端口的 fake provider，返回 baseUrl。

构造纯文本消息

截断到 maxLen 字符，避免 DB 列长度溢出

统一基础参数校验，三个入口方法共用

Three-step workflow parse using DeepSeek (each step has a focused prompt): Step 1A: Extract passages only (focused on article text extraction) Ste