装闭 RenoPit 源码解析（03）：AI装修项目的创建、复制与删除流程

在装闭 RenoPit 中，用户不是直接上传一批文件并调用 AI，而是先创建“装修项目”，再围绕项目管理素材和分析结果。本篇对照开源仓库 fthux/RenoPit，从 React 页面一路追踪到 FastAPI 和 SQLAlchemy。

一、项目列表是业务入口

ProjectsPage.tsx 请求 GET /api/projects?page=1&page_size=8，把返回的 projects、total 和 total_pages 分别写入页面状态。

后端 list_projects() 先统计总数，再计算偏移量：

offset = (page - 1) * page_size
projects_orm = (db.query(Project).order_by(Project.created_at.desc()).offset(offset).limit(page_size).all()
)

每条 ORM 记录经过 _project_to_response() 转换，同时计算图片和文件数量。前端根据 status 显示待分析、分析中、已完成或失败等状态。如果当前页存在 analyzing 项目，页面会启动定时刷新，等待后台任务改变项目状态。

二、创建项目分成两次请求

CreateProjectPage 同时收集项目名称、描述、补充说明和待上传文件，但提交时并没有把所有数据塞进一个请求。

第一步向 POST /api/projects 发送 JSON：

const createRes = await fetch(`${API}/projects`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ name, description, input_text: inputText }),
})

后端创建 UUID、访问令牌和 pending 状态，提交后返回项目 ID。第二步前端把选中的文件放进 FormData，请求 /api/projects/{id}/upload。上传完成后才跳转到项目详情页。

这种调用顺序决定了项目是文件的归属入口：即使没有图片，用户只填写补充说明，也能得到一个可以启动纯文本分析的项目。

三、项目详情页如何加载数据

ProjectPage.tsx 从路由参数取得 projectId，并行请求三组数据：

• /projects/{id} 获取项目元数据；
• /projects/{id}/files 获取文档；
• /projects/{id}/images 获取图片。

项目名称、描述和补充说明支持行内编辑。保存时，页面根据当前字段构造局部 JSON，再调用 PUT /api/projects/{id}。后端只修改请求体中不为 None 的字段，更新 updated_at 后返回新的 ProjectResponse。

四、复制项目同时复制数据库和磁盘

项目列表中的复制操作会先显示确认对话框：

确认后，前端调用 POST /api/projects/{id}/duplicate。后端创建新的项目 UUID，并把名称默认改成“原名称（副本）”。新项目会继承描述和补充说明，但状态重新设为 pending，分析结果和报告不会复制。

当 copy_files=true 时，复制过程有两层：

1. 为每个 ProjectImage 和 ProjectFile 创建新的数据库记录；
2. 把存储路径中的旧项目 ID 替换为新 ID，再通过 shutil.copy2() 复制物理文件。

extracted_text 也会跟随 ProjectFile 复制，因此新项目不必重新解析原文档。所有记录添加完成后统一 commit，再把新项目返回给前端。

五、删除项目依赖关联关系

删除操作同样先经过确认：

前端请求 DELETE /api/projects/{id}，后端检查项目存在后只执行两步：

db.delete(project)
db.commit()

图片、文件、分析和报告的数据行由 SQLAlchemy 的 delete-orphan 和数据库外键级联处理。这个接口本身没有逐个删除关联记录，也没有在函数中遍历磁盘目录。请求成功后，前端清空确认状态并重新请求当前页，让列表数量和分页数据回到后端的最新结果。

六、项目状态贯穿整个生命周期

项目创建和复制时状态都是 pending；触发分析后变成 analyzing；Celery 任务结束后写为 completed 或 failed。项目列表、详情页、按钮可用性和报告入口都读取同一个字段。

因此项目生命周期不仅是 CRUD，还承担了前端和异步任务之间的状态协议。React 不需要理解 Celery 的内部细节，只要持续读取项目状态，就能决定显示“开始分析”“停止分析”还是“查看报告”。

七、项目调用链小结

RenoPit 的项目操作形成了一条稳定主线：先创建项目，再关联文件；编辑只更新元数据；复制创建新的项目边界并复制素材；删除通过 ORM 关系清理数据；AI 状态则持续写回同一条项目记录。

上述页面和接口均来自 fthux/RenoPit。下一篇将进入 /upload 接口内部，继续分析装修图片、合同和报价单上传后如何落盘、压缩并提取文本。