AI 装修闭坑分析可能包含多张图片、多份合同以及多次大模型调用，不适合让 FastAPI 请求一直阻塞。装闭 RenoPit 在 fthux/RenoPit 中使用 Celery 和 Redis 编排这条长任务链，本篇分析任务从入队到结束的全过程。

一、FastAPI 只负责启动任务

用户点击“开始分析”后，ProjectPage向POST /api/projects/{id}/analyze发送请求。trigger_analysis()首先查询项目、图片和文件，并判断三类输入是否至少存在一种：

• 可分析图片；
• 已上传文档；
• 非空的用户补充说明。

输入为空时返回 400；项目已经处于analyzing时返回 409。校验通过后，接口先把项目状态提交为analyzing，再投递任务：

from..tasks.analysisimportrun_analysis_task run_analysis_task.delay(project_id)

如果入队失败，接口会把状态恢复为pending。因此浏览器收到成功响应时，数据库已经记录了分析中的状态，任务也已经进入 Redis。

二、Celery 如何连接 Redis

tasks/celery_app.py创建 Celery 实例，Broker 使用 Redis 0 号库，结果后端使用 1 号库：

celery_app=Celery("renovation_analyzer",broker=settings.CELERY_BROKER_URL,backend=settings.CELERY_RESULT_BACKEND,include=["app.tasks.analysis"],)

任务消息和结果采用 JSON 序列化。task_acks_late=True表示任务执行完成后才确认消息，worker_prefetch_multiplier=1让 Worker 每次只预取一个长任务。软、硬时间限制都设置为 1200 秒，以容纳串行的图片和文档分析。

Docker Compose 中的backend与celery_worker使用同一份代码和环境变量，但启动命令不同。Worker 不接收 HTTP 请求，只监听 Redis 队列。

三、run_analysis_task 是总编排器

Celery 实际执行的是run_analysis_task(project_id)。它不是直接调用一次 LLM 就结束，而是按六个阶段组织任务：

第三步调用run_analysis_sync()处理图片、已提取文本和用户说明。设计图分析失败不会立刻终止整个任务，因为合同与报价单分析可以独立完成。

四、文档分析按文件串行执行

任务会查询当前项目中extracted_text非空，且类型为 PDF、DOCX、TXT 或 Markdown 的文件。每份文件调用一次run_document_analysis_sync()，结果追加到doc_results。

单份文档异常会被捕获并记录为失败，不会阻断下一份文件。这样一份无法解析的合同不会让其他报价单全部失去分析机会。

当文档结果数量不少于两份时，任务继续调用run_cross_check_sync()。该阶段会比较合同和报价单中的金额、项目、责任条款等信息，并把差异写回综合分析结果。

五、项目完成状态如何判定

任务结束时分别计算：

design_ok=result.get("status")=="completed"doc_ok_count=sum(1foritemindoc_resultsifitem.get("status")=="completed")

只要设计分析成功，或者至少一份文档分析成功，项目就被标记为completed。完成消息会汇总设计问题数、文档成功数和跨文档差异数。

只有设计分析与全部文档分析都失败时，项目状态才写为failed。最外层异常同样会落入失败分支，并把错误信息提供给后续 SSE 接口读取。

六、停止分析如何改变状态

POST /projects/{id}/stop只接受当前状态为analyzing的项目。接口把项目恢复为pending，再找到最近一条processing或pending的Analysis，将其标为failed，错误信息写成“用户手动停止”。

状态提交后，SSE 轮询会观察到pending并发送stopped事件。项目页据此关闭进度条并恢复开始分析按钮。

七、异步任务调用链小结

RenoPit 把 HTTP 请求和 AI 计算分成两个进程：FastAPI 完成输入校验、状态更新和任务投递；Celery Worker 完成设计分析、文档分析、交叉核查和最终状态汇总。Redis 负责传递任务，PostgreSQL 则是两个进程共同认可的业务状态来源。

这条任务链的完整代码可以在 fthux/RenoPit 中查看。下一篇将继续分析浏览器如何通过 SSE 观察数据库状态，并把后台任务转换为实时进度条和完成跳转。