装闭 RenoPit 是一个基于 AI 的装修避坑系统，其数据库与模型设计旨在高效管理装修项目、多媒体素材、

AI 分析结果及最终报告。该系统后端采用 SQLAlchemy ORM 框架，核心数据模型围绕 Project（项目）

展开，通过外键关联形成完整的数据闭环。

核心数据模型架构

系统主要包含六张核心数据表，它们以 Project 为中心进行组织：

Project（项目主表）‌

作用‌：整个数据模型的入口，保存业务状态。

核心字段‌：

id: UUID 类型，主键。

name: 项目名称。

access_token: 访问令牌，用于权限控制。

status: 项目状态，包括 pending（待处理）、analyzing（分析中）、completed（已完成）、failed（失败）。

input_text: 用户补充的装修需求文本。

索引与关系‌：为 access_token、status 和 created_at 建立索引以优化查询性能。与其他表通过 project_id 关联，并设置 cascade="all, delete-orphan" 和数据库级 ON DELETE CASCADE，确保删除项目时自动清理关联数据。

ProjectImage（图片资源表）‌

作用‌：存储装修图纸、现场照片等图片元数据。

核心字段‌：原始文件名、磁盘存储路径、文件大小、宽度、高度。

设计理由‌：图片需进入多模态大模型处理，后端需预先获取尺寸信息并在分析前转换为 Base64 格式。

ProjectFile（文档资源表）‌

作用‌：存储合同、报价单、TXT、Markdown、PDF 等文档。

核心字段‌：

original_filename: 原始文件名。

storage_path: 存储路径。

file_type: 文件类型。

extracted_text: ‌关键字段‌，存储上传阶段提取出的文本内容。

设计理由‌：提取后的文本可直接用于后续的设计分析、合同审查和跨文档核查，避免重复解析 PDF 或 DOCX 文件，提升效率。

Analysis（综合分析表）‌

作用‌：保存设计图分析和综合装修避坑分析结果。

核心字段‌：

raw_result_json: 大模型返回的完整结构化数据。

error_message: 记录分析失败的原因。

特性‌：project_id 无唯一约束，支持重新分析。每次重新分析会创建新记录，业务接口按创建时间倒序获取最新结果。

DocumentAnalysis（文档分析表）‌

作用‌：保存单份合同或报价单的详细分析结果。

核心字段‌：

doc_type: 文档类型（合同、报价单、未知）。

confidence: 分类置信度。

classifications_json: 分类依据和关键片段。

risks_json: 风险项及增项预测。

summary: 摘要。

risks_count: 风险数量，用于快速列表展示。

关系‌：通过 project_file_id 关联具体文件，设置 ON DELETE SET NULL，确保文件删除后分析记录仍可保留（仅失去文件关联）；通过 project_id 关联项目，设置级联删除。

Report（报告表）‌

作用‌：连接分析结果与生成的 PDF 报告。

核心字段‌：引用 project_id 和 analysis_id。

约束‌：analysis_id 设有唯一约束 (unique_constraint)，确保一条分析记录最多对应一份报告。下载接口优先复用已有报告。

数据流与业务逻辑

状态管理‌：Project.status 是前后端同步的关键字段，通过 SSE（Server-Sent Events）接口实时推送分析进度。

数据持久化‌：所有资源（图片、文件、分析结果、报告）均通过 project_id 与主项目关联，API 只需持有项目 UUID 即可检索全套业务数据。

容错与历史‌：分析任务支持重试，新的分析结果会作为新记录插入，保留历史分析轨迹。文档分析独立于整体任务，单份文件解析失败不会阻断其他文件的处理。

这种设计实现了装修项目从素材上传、AI 智能分析到报告生成的全链路数据化管理，兼顾了查询效率、数据一致性和用户体验。