feat: scaffold agentic interior design workflow

2026-08-01 21:07:17 +08:00
parent 77779bd3a9
commit 6a15217d55
42 changed files with 7156 additions and 1 deletions
@@ -0,0 +1,65 @@
+# 系统架构
+
+## 设计原则
+
+1. 几何事实与生成图像分离。模型不能用像素结果覆盖墙、门窗和锁定布局。
+2. 所有修改先转成结构化命令，再调用几何、风格或生图执行器。
+3. 生图供应商通过统一适配器接入，业务流程不感知具体模型。
+4. 每个派生文件都记录输入、配置、模型、版本和父版本，支持回退与分支。
+5. 低置信度识别必须进入人工确认，不能静默猜测。
+
+## 逻辑结构
+
+```text
+Web Studio
+  |-- 图纸清洗
+  |-- 3D 白模与相机
+  |-- Style DNA
+  |-- 对话与版本分支
+  |
+FastAPI Orchestrator
+  |-- Workflow State Machine
+  |-- Project Command Handler
+  |-- Model Router
+  |-- 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。
+- 用户提供的模型 Key 使用 `APP_ENCRYPTION_KEY` 加密后存储。
+- GPU 和内部 Worker 只接受内网请求，并校验内部服务令牌。
@@ -0,0 +1,49 @@
+# 工作流定义
+
+## 阶段
+
+```text
+uploaded
+  -> region_selection
+  -> plan_review
+  -> blockout
+  -> style_brief
+  -> direction_selection
+  -> render_review
+  -> editing
+  -> completed
+```
+
+任意异步阶段都可以进入 `failed`，修正问题后通过 `retry` 回到最近一个可恢复阶段。
+
+## 关键命令
+
+| 命令 | 作用 | 关键约束 |
+|---|---|---|
+| `start_ingestion` | 分析上传文件 | 先判断矢量 PDF、DXF 或扫描图 |
+| `select_region` | 选择目标户型区域 | 一张图纸可能包含多个平面区域 |
+| `confirm_plan` | 确认清洗后的结构 | 必须处理低置信度墙、门窗和比例 |
+| `build_blockout` | 生成 3D 白模与相机 | 不追求施工级构造 |
+| `submit_style_brief` | 建立 Style DNA | 用户意图写入结构化字段 |
+| `select_direction` | 锁定设计方向 | 保留方向分支和父版本 |
+| `request_render` | 生成一个或多个视角 | 携带空间控制图与锁定状态 |
+| `apply_edit` | 执行局部或全局修改 | 只变更受影响的状态与视角 |
+| `complete_project` | 完成当前概念方案 | 输出仍标注为概念效果图 |
+
+## Agent 分工
+
+- Orchestrator：确定下一步、追问缺失条件、调度任务、处理失败和回滚。
+- Plan Interpreter：解析图层、区域、比例和房间语义。
+- Spatial Critic：检查动线、遮挡、焦点和基本几何约束。
+- Style Director：维护 Style DNA，提出差异明确的风格方向。
+- Layout Planner：操作结构化家具占位，不直接修改像素。
+- Render Router：按任务特征选择图像模型，并生成控制输入。
+- Aesthetic Reviewer：比较空间忠实度、配色、材质连续性和多视角一致性。
+
+## 第一版人工确认点
+
+1. 选择图纸中的目标区域。
+2. 确认比例、墙、门窗和需要保留的家具。
+3. 确认层高和关键开口高度。
+4. 从三个风格方向中选择一个主方向。
+5. 对高成本多视角生成进行确认。