zhuangxiu/docs/architecture.md

系统架构

设计原则

1. 几何事实与生成图像分离。模型不能用像素结果覆盖墙、门窗和锁定布局。
2. 所有修改先转成结构化命令，再调用几何、风格或生图执行器。
3. 生图供应商通过统一适配器接入，业务流程不感知具体模型。
4. 每个派生文件都记录输入、配置、模型、版本和父版本，支持回退与分支。
5. 低置信度识别必须进入人工确认，不能静默猜测。

逻辑结构

Web Studio
  |-- 图纸清洗
  |-- 3D 白模与相机
  |-- Style DNA
  |-- 对话与版本分支
  |
FastAPI Orchestrator
  |-- Workflow State Machine
  |-- Project Command Handler
  |-- Model Router
  |-- Encrypted Settings Store
  |-- Readiness Gate
  |-- Signed Upload Service
  |
Workers
  |-- Vector PDF Parser
  |-- OCR Adapter
  |-- Geometry Builder
  |-- GPU Vision Service
  |-- Image Generation Adapter
  |
Storage
  |-- PostgreSQL: 状态与版本
  |-- Redis: 队列、缓存和锁
  |-- MinIO: PDF、SVG、GLB、控制图和效果图

核心状态

Plan State

保存可验证的空间事实：页面区域、比例、房间多边形、墙线、门窗、柱、楼梯、原始家具层和识别置信度。

Scene State

保存 3D 白模、家具类别级占位、相机、可见性以及用户锁定对象。局部修改必须尊重锁定项。

Style State

保存概念描述、色板、材质、灯光、形态、空间密度、禁用项和用户确认的设计决定。它是跨视角和跨轮次的一致性来源。

部署建议

• NAS MinIO：保存项目大文件，按应用和 Langfuse 分离 bucket 与账号。
• Linux Docker 服务器：运行 API、PostgreSQL、Redis、Langfuse 和普通 Worker。
• Linux GPU 服务器：运行户型分割、视觉评审、深度估计和可选本地模型。
• 百度 OCR：仅在 PDF 文字层失效或输入为扫描图时使用。

安全边界

• 浏览器不接触 MinIO、OCR 或模型服务的永久密钥。
• 上传和下载通过短期预签名 URL。
• 可视化设置中的密钥整体使用 Fernet 加密，接口只返回“是否已配置”，不返回原文。
• 主加密密钥在首次启动时自动生成到私有数据卷，迁移服务器必须连同该卷一起备份。
• GPU 和内部 Worker 只接受内网请求，并校验内部服务令牌。