管理端 AI usage 分组统计 bucket（Phase 6B-2B）。 <p>用于 byStatus / byProvider / byFeature / byKeyMode / byTaskType / dailyTrend。 dailyTrend 时 name = yyyy-MM-dd。

管理端 AI usage 统计接口（Phase 6B-2B）。 <p>路径前缀：{@code /admin/ai-usage}（叠加 context-path {@code /api} 后为 {@code /api/admin/ai-usage}）。</p> <p><b>鉴权：</b>所有接口必

管理端 AI usage 最近记录 DTO（Phase 6B-2B）。 <p>用于管理端排查最近 AI 调用。errorMessage 已由 {@code AiUsageGuard} 脱敏。 不返回 API Key / encrypted key / masked key / baseUrl /

管理端 AI usage 统计服务（Phase 6B-2B）。 <p>只读服务：不 insert / update / delete 任何数据。 查询时间范围内全部 records 后在 Java 内 stream 聚合，避免写复杂 SQL。 本阶段面向管理端低频统计，{@code days} 最

{@link AdminAiUsageStatsService} 单元测试（Phase 6B-2B）。 <p>不连接真实数据库：{@link AiUsageRecordMapper} 用 Mockito mock。 验证只读统计聚合、参数 clamp、dailyTrend 补 0、null buc

管理端 AI usage 汇总统计响应 DTO（Phase 6B-2B）。 <p>聚合最近 N 天的 AI usage 数据，包含： <ul> <li>状态汇总：total / success / failed / rejected</li> <li>分组聚合：byStatus / byP

管理端操作审计日志查询接口（Phase 8D）。 <p>路径前缀：{@code /admin/audit-logs}（叠加 context-path {@code /api} 后为 {@code /api/admin/audit-logs}）。</p> <p><b>鉴权：</b>所有接口必须 A

管理端操作审计日志服务（Phase 8D）。 <p>职责： <ul> <li>写入审计日志（{@link #recordSuccess} / {@link #recordFailure}）。</li> <li>查询审计日志（{@link #listLogs}），支持 actor/targe

{@link AdminAuditLogService} 单元测试（Phase 8D）。 <p>不连接真实数据库：{@link AdminOperationLogMapper} 用 Mockito mock。 覆盖 summary 脱敏、FAILED 状态写入、summary 截断、分页 clam

管理员账号启动时自动初始化（Phase 8A 配套）。 <p>读取配置 {@code app.init-admin.username / email / password} （对应环境变量 {@code INIT_ADMIN_USERNAME / INIT_ADMIN_EMAIL / INIT_A

{@link AdminBootstrapConfig} 单元测试。 <p>覆盖启动时管理员初始化的关键分支：未配置跳过、已有 ADMIN 跳过、 升级现有 USER（含重置密码+启用）、创建新 ADMIN。</p>

管理端新增用户请求体（Phase 8A 补充）。 <p><b>安全：</b>{@code password} 通过 {@link ToString.Exclude} 排除， 避免日志意外打印明文密码。后端使用 {@code PasswordEncoder.encode(...)} 存储 BCryp

管理端给当前周期增加 {@code creditsTotal} 请求体（Phase 8B）。

管理端高风险写操作的 action 枚举（Phase 8D 审计日志）。 <p>本枚举仅覆盖管理端写操作；普通列表/详情查询不记录审计日志。 每个枚举值对应一类高风险 Admin 操作，写入 {@code admin_operation_logs.action} 字段。</p> <p><b>re

管理端操作审计日志实体，对应 {@code admin_operation_logs} 表（Phase 8D）。 <p>记录高风险 Admin 写操作的执行情况，便于后续追溯。</p> <p><b>安全：</b>{@link #summary} 字段必须经过脱敏处理，禁止包含 password

管理端操作审计日志响应 DTO（Phase 8D）。 <p><b>安全：</b>本 DTO 不包含 password / newPassword / apiKey / Authorization / Bearer / token / JWT / encrypted key / masked key

管理端操作审计日志 Mapper（Phase 8D）。 <p>对应 {@code admin_operation_logs} 表。除 {@link BaseMapper} 标准方法外， 提供 {@code selectAdminOperationLogs} / {@code countAdminO

管理端操作审计日志分页响应 DTO（Phase 8D）。 <p>与 {@link AdminUserPageDto} / {@link AdminQuotaPageDto} 保持一致的分页结构。</p>

管理端审计日志操作状态枚举（Phase 8D）。 <p>Phase 8D 至少记录成功写操作（{@link #SUCCESS}）。 失败审计（{@link #FAILED}）可先只记录已经捕获的业务异常场景； 如果接入成本太高，本阶段允许只记录成功写操作，但文档必须明确说明。</p>

Admin 后台细粒度权限枚举（Phase 8C）。 <p>本阶段保留 USER / ADMIN 两级基础角色不变，仅在 ADMIN 内部做权限细分。 普通用户永远没有后台权限。</p> <p><b>兼容模式：</b>当 {@code admin_user_permissions} 表为空时，

管理端 Admin 权限管理接口（Phase 8C）。 <p>路径前缀：{@code /admin/permissions}（叠加 context-path {@code /api} 后为 {@code /api/admin/permissions}）。</p> <p><b>鉴权：</b>所有接

Admin 权限视图 DTO（Phase 8C）。 <p>用于 {@code GET /admin/permissions/users/{userId}} 与 {@code GET /admin/permissions/me} 返回某个 ADMIN 的有效权限集合。</p> <p><b>安全：<

Admin 权限服务（Phase 8C）。 <p>负责权限枚举列出、用户权限查询、权限判断、权限更新与安全保护。 保留 USER / ADMIN 两级基础角色不变，仅在 ADMIN 内部做权限细分。</p> <h3>显式权限模式（explicit permission mode）</h3> <u

{@link AdminPermissionService} 单元测试（Phase 8C）。 <p>不连接真实数据库：{@link UserMapper} 与 {@link AdminUserPermissionMapper} 用 Mockito mock。 覆盖显式/兼容模式、USER 无权限、

管理端 AI 额度管理接口（Phase 8B）。 <p>路径前缀：{@code /admin/quotas}（叠加 context-path {@code /api} 后为 {@code /api/admin/quotas}）。</p> <p><b>鉴权：</b>所有接口必须 ADMIN 角色访

管理端用户当前周期 AI 额度视图（Phase 8B）。 <p><b>安全：</b>本 DTO 不包含 {@code password} / {@code apiKey} / {@code encryptedKey} / {@code maskedKey} / {@code baseUrl} /

管理端用户额度分页结果（Phase 8B）。

管理端 AI 额度管理服务（Phase 8B）。 <p>仅管理当前自然周期 quota 行： <ul> <li>读操作（list / get）在无 quota 行时返回虚拟默认视图（100/0/100），不创建行。</li> <li>写操作（setTotal / grant / reset

{@link AdminQuotaService} 单元测试（Phase 8B）。 <p>不连接真实数据库：{@link UserMapper} 与 {@link AiUsageQuotaMapper} 用 Mockito mock。 验证虚拟默认视图、quota 行创建/更新、setTotal/

管理端重置用户密码请求体（Phase 8A）。 <p><b>安全：</b>{@code newPassword} 通过 {@link ToString.Exclude} 排除， 避免日志意外打印明文密码。后端使用 {@code PasswordEncoder.encode(...)} 存储 BCr

管理端设置当前周期 {@code creditsTotal} 请求体（Phase 8B）。

更新某个 ADMIN 用户权限的请求体（Phase 8C）。 <p>对应 {@code PUT /admin/permissions/users/{userId}}。 后端会按 {@link com.ieltsstudio.entity.AdminPermission} 枚举白名单校验每个值， 并

管理端修改用户角色请求体（Phase 8A）。 <p>仅允许 {@code USER} / {@code ADMIN} 两个值，service 层会做白名单校验， 拒绝 {@code SUPER_ADMIN} 等非法角色。</p>

管理端用户管理接口（Phase 8A）。 <p>路径前缀：{@code /admin/users}（叠加 context-path {@code /api} 后为 {@code /api/admin/users}）。</p> <p><b>鉴权：</b>所有接口必须 ADMIN 角色访问。 <ul

管理端用户详情 DTO（Phase 8A）。 <p><b>安全：</b>本 DTO <b>不包含</b> {@code password} 字段，密码永远不会通过本类返回前端。 {@code deleted} 字段用于管理端展示用户启用/禁用状态（0=启用，1=禁用）。</p>

管理端用户分页 DTO（Phase 8A）。 <p>封装分页用户列表与分页元信息。{@code records} 中的每个 {@link AdminUserDto} 均不包含 password 字段。</p>

Admin 用户权限实体，对应 {@code admin_user_permissions} 表（Phase 8C）。 <p>记录某个 ADMIN 账号被分配的后台细粒度权限。{@link #permission} 字段存储 {@link AdminPermission} 枚举名。{@code (

Admin 用户权限 Mapper（Phase 8C）。 <p>对应 {@code admin_user_permissions} 表。除 {@link BaseMapper} 标准方法外， 提供 {@code selectByUserId} / {@code countAllPermission

管理端用户管理服务（Phase 8A）。 <p>职责：用户列表/搜索、用户详情、角色修改、禁用/启用、重置密码。 <p><b>安全规则：</b> <ul> <li>不能禁用自己</li> <li>不能降级自己</li> <li>不能禁用最后一个 ADMIN</li> <li>不能

{@link AdminUserService} 单元测试（Phase 8A）。 <p>不连接真实数据库：{@link UserMapper} 与 {@link PasswordEncoder} 用 Mockito mock。 验证分页 clamp、role/status 过滤、角色修改保护、禁用

用户自填 API Key 的加密 / 解密 / 脱敏工具。 <p>职责：</p> <ul> <li>{@link #encrypt(String)} —— 用 AES/GCM/NoPadding 加密明文 Key，输出 {@code Base64(IV||密文+tag)}。</li> <l

{@link AiApiKeyCrypto} 单元测试。 <p>不使用真实 API Key，统一使用测试字符串 {@code sk-test-secret-123456}。</p> <p>重点验证：</p> <ul> <li>加密后不等于明文，且密文不含明文片段。</li> <li>解密

OpenAI-compatible chat 消息。 <p>{@link #content} 类型说明：</p> <ul> <li>文本消息：{@code String}，对应 {@code "content": "..."}</li> <li>多模态消息：{@code List<Map<

{@link AiChatMessage} 单元测试。 <p>验证静态工厂方法生成的 role 正确，且多模态 content 不被错误转为字符串。</p>

统一 AI 调用请求。 <p>由业务层组装后交给 {@link com.ieltsstudio.ai.client.OpenAiCompatibleClient} 发送。</p>

统一 AI 调用响应。 <p>仅承载业务关心的字段（content / provider / model / statusCode）， provider 原始错误体由 {@link com.ieltsstudio.ai.client.OpenAiCompatibleClient} 脱敏后转为异常。

一次 AI 调用的凭据快照。 <p>由 {@link com.ieltsstudio.ai.service.AiSettingsService} 在运行时构造： BUILTIN 模式从站点配置注入；USER 模式从 {@code user_ai_settings} 解密后注入。</p> <p><

{@link AiCredentials} 单元测试。 <p>重点验证：</p> <ul> <li>{@code toString()} 不泄露真实 API Key。</li> <li>{@code hasApiKey()} 行为正确。</li> <li>空 / null key 不抛

AI 功能枚举，用于 {@link com.ieltsstudio.ai.service.AiUsageGuard} 的扣费 / 限流映射。 <p>每个功能绑定一个 {@link AiTaskType} 与内置模式下的扣费 cost， cost 取值与 {@code docs/security-a

{@link AiFeature} 单元测试。 <p>验证每个功能的 taskType 与 builtinCost 与 {@code docs/security-and-quota-plan.md} §2.2 一致。</p>

AI 调用 Key 模式枚举。 <ul> <li>{@link #BUILTIN} —— 使用站点内置 API Key，未来消耗站点 credits。</li> <li>{@link #USER} —— 使用用户自填 API Key，未来不消耗站点 credits，但仍限流。</li> <

AI 日志与错误脱敏工具。 <p>职责：</p> <ul> <li>{@link #maskApiKey(String)} —— 将 API Key 脱敏为 {@code sk- 3456} 形式，便于日志 / 前端展示 masked key。</li> <li>{@link #su

{@link AiLogSanitizer} 单元测试。 <p>重点验证：</p> <ul> <li>{@code maskApiKey} 保留前缀与尾部 4 位，中间脱敏。</li> <li>{@code sanitize} 移除 / 脱敏 Authorization 头与 Bearer

Phase 5C-1：{@link AiParseService} 普通文本试卷解析接入新 AI Provider 架构的单元测试。 <p>不真实访问 DeepSeek / Qwen / MiMO： {@link AiSettingsService} / {@link AiUsageGuard}

Phase 5C-3：Legacy AI 调用清理后的回归测试。 <p>覆盖：</p> <ol> <li>{@code generateWritingGuidance(userId, ...)} 走新 Provider 架构 + markSuccess</li> <li>{@code ge

Phase 5A-local-provider-test：{@link AiParseService} 通过真实 {@link OpenAiCompatibleClient} 调用本地 fake provider 的端到端式测试。 <p>使用真实 client + 真实 {@link Object

Phase 5A：文本类 AI 功能接入新 Provider 架构的单元测试。 <p>不真实访问 DeepSeek / Qwen / MiMO： {@link AiSettingsService} / {@link AiUsageGuard} / {@link OpenAiCompatibleCl

Phase 5B：{@link AiParseService#generateWordEntries(Long, String)} 接入新 AI Provider 架构的单元测试。 <p>不真实访问 DeepSeek / Qwen / MiMO： {@link AiSettingsService}

保存某一类 Provider（text / vision）配置的请求体。 <p>语义：</p> <ul> <li>{@code provider}：{@code DEEPSEEK} / {@code QWEN} / {@code MIMO} / {@code OPENAI_COMPATIBLE

单个 Provider 配置的脱敏响应。 <p><b>安全：</b>不返回明文 apiKey，也不返回 encryptedApiKey； 只返回 maskedApiKey（如 {@code sk- abcd}）与 {@code hasApiKey} 标记。</p>

预设 Provider 描述：内置 Provider 的默认 baseUrl / model / tokenField 等元数据。 <p>不含 API Key，Key 由 {@link com.ieltsstudio.ai.service.AiSettingsService} 在运行时注入。</p

Provider 预设描述，用于前端展示可选 Provider 列表。 <p>来自 {@link com.ieltsstudio.ai.model.AiProviderPreset}，不含任何 API Key。</p>

AI Provider 配置绑定，读取 {@code application-ai.yml} 中的现有站点配置。 <p>本阶段只读不写，且<b>不删除</b>任何现有配置项（旧 Service 仍在直接使用 {@code @Value}）。 该类仅为新的 AI 抽象层（{@link com.iel

Provider 预设注册表。 <p>职责：</p> <ul> <li>维护内置 Provider preset（DeepSeek / Qwen / MiMO / OPENAI_COMPATIBLE 模板）。</li> <li>按 {@link AiProviderType} 查找默认配置

{@link AiProviderRegistry} 单元测试。 <p>不依赖数据库 / Spring 容器，直接构造并触发 {@code @PostConstruct}。</p>

AI Provider 类型枚举。 <ul> <li>{@link #DEEPSEEK} —— DeepSeek，预设文本 Provider。</li> <li>{@link #QWEN} —— 通义千问 VL，预设视觉 Provider。</li> <li>{@link #MIMO}

AI USER 模式 Redis 分布式限流器（Phase 6B-2C）。 <p>固定窗口算法：每用户每 feature 每分钟一个 Redis key，{@code INCR} 计数， 首次写入设置 TTL（70 秒，略大于 60 秒窗口，确保过期清理）。 超过 {@code limitPerM

{@link AiRedisRateLimiter} 单元测试（Phase 6B-2C）。 <p>不连接真实 Redis：{@link StringRedisTemplate} / {@link ValueOperations} 用 Mockito mock。 验证固定窗口 INCR + TTL

AI 设置 DTO 安全性测试。 <p>目标：确认 {@link AiProviderConfigRequest} 与 {@link AiSettingsUpdateRequest} 的 {@code toString()} 不会输出明文 {@code apiKey}（包括嵌套 text / vi

当前用户 AI 设置的脱敏响应。 <p>包含 keyMode 与 text / vision 两组 Provider 配置（均脱敏）。</p>

AI 凭据解析服务。 <p>支持两种模式：</p> <ul> <li><b>BUILTIN</b>：从 {@code application-ai.yml} 读取站点内置配置，构造 {@link AiCredentials}。</li> <li><b>USER</b>：从 {@code u

{@link AiSettingsService} 单元测试（BUILTIN 模式）。 <p>不查数据库、不发真实网络请求。{@link UserAiSettingsMapper} 用 Mockito mock， 默认返回 null（无用户设置），使 resolve 回退到 BUILTIN，保持本

{@link AiSettingsService} USER 模式解析单元测试。 <p>不查真实数据库：{@link UserAiSettingsMapper} 用 Mockito mock； 用同一 {@link AiApiKeyCrypto} 实例加密测试 Key，确保 resolve 时能正

更新当前用户 AI 设置的请求体。 <p>语义：</p> <ul> <li>{@code keyMode}：{@code BUILTIN} / {@code USER}。</li> <li>{@code text} / {@code vision}：可为 {@code null}，为 nu

AI 任务类型枚举。 <ul> <li>{@link #TEXT} —— 文本任务：写作评分、AI Chat、翻译、普通解析、完形填空。</li> <li>{@link #VISION} —— 多模态任务：PDF / 图片精准解析、扫描版试卷、图表识别。</li> </ul>

AI 用量守卫：负责 credits 额度、流水记录与基础限流。 <p>Phase 6A 落地实现：</p> <ul> <li><b>BUILTIN 模式</b>：每用户每周 100 credits，采用「调用前预扣 + 失败回滚」模型， 保证高并发下不超卖。额度不足写 REJEC

{@link AiUsageGuard} 单元测试（Phase 6A + Phase 6B-2C）。 <p>不连接真实数据库：{@link AiUsageQuotaMapper} / {@link AiUsageRecordMapper} 用 Mockito mock。 不连接真实 Redis：{

AI 用量查询服务（只读）。 <p>用于用户中心展示当前周期 credits 与最近使用记录。</p> <p><b>只读语义：</b>查询不会创建 quota 行，也不会扣费。若当前周期 quota 不存在， 返回默认视图（creditsTotal=100, creditsUsed=0, cre

{@link AiUsageQueryService} 单元测试（Phase 6B-1）。 <p>不连接真实数据库：三个 Mapper 用 Mockito mock。 验证查询接口只读、不创建 quota、正确返回额度与最近记录。</p>

用户 AI 内置额度快照实体，对应 {@code ai_usage_quota} 表。 <p>记录每用户当前周期的 credits 发放与已用额度。本阶段仅建表与 Entity/Mapper， 扣费逻辑留待后续阶段（Phase 3B/3C）。</p> <p>无敏感字段，{@link #toStr

{@code ai_usage_quota} 表的 MyBatis-Plus Mapper。 <p>本阶段只提供 {@link BaseMapper} 通用能力，扣费 / 周期切换 SQL 留待后续阶段。</p>

{@link AiUsageQuota} 单元测试。 <p>轻量测试：字段可正常 set / get，{@code toString()} 安全（无敏感字段）。</p>

AI 调用流水实体，对应 {@code ai_usage_records} 表。 <p>用于审计、调试与统计：每次 AI 调用记录任务类型、功能、cost、Key 模式、Provider、状态等。</p> <p><b>安全注意：</b></p> <ul> <li>{@link #errorM

单条 AI 使用记录的脱敏视图。 <p>{@link #errorMessage} 已由 {@code AiUsageGuard} 在写入时脱敏， 查询接口不再加工；本 DTO 不包含任何 API Key / Authorization 字段。</p>

{@code ai_usage_records} 表的 MyBatis-Plus Mapper。 <p>本阶段只提供 {@link BaseMapper} 通用能力，统计 / 审计 SQL 留待后续阶段。</p>

{@link AiUsageRecord} 单元测试。 <p>轻量测试：字段可正常 set / get，{@code toString()} 安全。</p>

自定义异步线程池配置，替代默认 SimpleAsyncTaskExecutor。 核心线程 4（匹配 DeepSeek API 实际并行能力 3~4），最大线程 8，队列 20。 超出后使用 CallerRunsPolicy，由调用线程同步执行，起到天然限流作用。

Phase 5C-1：验证 userId 从 {@code AsyncParseService.parseAndSave} 一路下传到 普通文本解析 AI 调用 {@code AiParseService.parseWithAi(userId, ...)}。 <p>不真实访问 DeepSeek /

Phase 5C-2：验证 userId 从 {@code AsyncParseService} 的精准解析路径一路下传到 {@link QwenAiParseService#parseDocument(Long, byte[], String, String)} / {@link QwenAiPa

认证接口控制器 <p>提供用户注册、登录、获取个人信息和退出登录接口。 接口路径前缀：{@code /auth}，全部在 SecurityConfig 中设为白名单（无需 Token）。

认证服务 <p>处理用户注册、登录和个人信息查询， 统一通过 {@link #buildAuthResult} 生成包含 Token 和用户信息的响应。

认证用户信息载体 <p>JWT 过滤器解析 Token 后，将用户信息封装为此对象并存入 SecurityContext。 在 Controller 方法中通过 {@code @AuthenticationPrincipal AuthUser authUser} 注解可直接注入当前登录用户，无需再

AI 完形填空生成 & 批改服务 <p>Phase 5B：已接入新 AI Provider 架构，统一走 {@link AiSettingsService#resolve} → {@link AiUsageGuard#checkBeforeCall} → {@link OpenAiCompatib

Phase 5B：{@link ClozeService} 接入新 AI Provider 架构的单元测试。 <p>不真实访问 DeepSeek / Qwen / MiMO： {@link AiSettingsService} / {@link AiUsageGuard} / {@link Ope