# AI 集成 - **功能**:约束学习引导与 AI 异步生成链路的实现方式。 - **何时用**:接入或改动 AI 相关功能、新增后台任务、处理生成类能力时。 ## 学习引导(复习-06) 一次引导是一次**复习行为**,有自己的记录实体 `review_guidance_conversations`: - 产出的知识碎片以它作为**记录上下文**(`context_type=REVIEW`),默认内容归属为被引导概念所属任务,并带 `FROM_GUIDANCE` 系统标记。 - 复习耗时记在会话行上(与回忆对比同一口径)。 - 多轮对话复用 AI 异步任务:每轮提交一个 `GUIDANCE` 任务,前端轮询取回复;AI 回复会写回会话轮次,供下一轮作为上下文。 - **没有降级形态**:AI 不可用时该链路直接失败,前端把入口置为不可用。 ## AI 异步链路(AI-02) 生成类能力(回忆对比、标准导图、报告草稿)不在请求线程里等 AI: - 前端 `POST /ai/tasks` 提交,秒级拿到 `taskNum`;随后轮询 `GET /ai/tasks/{taskNum}` 直到 `SUCCEEDED`/`FAILED`。 - 结果写在 `ai_tasks.result_payload`,按 `taskNum` 可重复获取,刷新或离开页面都不丢。 - 同一用户 + 同一类型 + 同一目标已有进行中任务时复用该任务(AI-04),不重复生成。 - 执行器在 `ai-task-*` 线程池里跑;提交后立即投递,`@Scheduled` 兜底扫描接手投递失败或进程重启的任务。 - **后台线程必须显式声明身份**:执行线程没有 Web 上下文,租户拦截器与 `MetaObjectHandler` 字段自动填充都取不到当前用户。执行器用 `TenantContext.callAs(task.createdBy, ...)` 绑定任务所属用户;请求线程不受影响(没有绑定时仍走 `StpUtil`)。新增后台任务时必须照此处理,否则会抛 `NotWebContextException`。 - 禁止在 `@Transactional` 方法内调用 AI:等待 AI 期间不得占用数据库连接。