# UdminAI 项目文档 欢迎来到 UdminAI 项目文档中心。本文档集合提供了项目的完整技术文档，涵盖了架构设计、模块说明、API 文档和最佳实践等内容。 ## 🗂 项目结构 ``` udmin_ai/ ├─ backend/ # Rust 后端（axum + tokio + sea-orm） │ └─ src/ │ ├─ flow/ # 流程执行核心 │ │ ├─ mod.rs │ │ ├─ domain.rs # ChainDef/Node/Link/Group 等领域模型 │ │ ├─ context.rs # 执行选项/流式事件 │ │ ├─ engine.rs # FlowEngine 引擎（并发/分支/屏障/事件） │ │ ├─ dsl.rs # Design JSON/DSL 解析与构建 │ │ ├─ mappers.rs # 设计映射到 ctx（nodes..） │ │ ├─ log_handler.rs # 运行日志与事件推送抽象 │ │ ├─ task.rs # 任务注册表与执行器抽象 │ │ └─ executors/ # http/db/variable/script_* / condition │ ├─ routes/ # API 路由层 │ │ ├─ flows.rs # /flows CRUD 与运行（同步/SSE/WS） │ │ └─ flow_run_logs.rs # /flow_run_logs 查询与删除 │ ├─ services/ # 业务编排与持久化 │ │ ├─ flow_service.rs # 流程加载/解析/驱动与日志 │ │ └─ flow_run_log_service.rs # 运行日志分页与批量删除 │ ├─ middlewares/ # 中间件服务 │ │ ├─ sse.rs # SSE 服务与事件封装 │ │ ├─ ws.rs # WebSocket 服务与转发 │ │ ├─ jwt.rs # 认证鉴权与用户提取 │ │ └─ http_client.rs # HTTP 客户端封装（reqwest） │ ├─ models/ # SeaORM 数据模型 │ │ ├─ flow.rs # flows 表 │ │ └─ flow_run_log.rs # flow_run_logs 表 │ ├─ db.rs # 数据库初始化与全局句柄 │ └─ redis.rs # Redis 访问与令牌校验 │ ├─ frontend/ # TypeScript 前端（React + Vite） │ └─ src/ │ ├─ flows/ # 可视化流程编辑器与运行面板 │ │ ├─ editor.tsx # 设计器入口（自由布局） │ │ ├─ services/custom-service.ts # 保存与运行（HTTP/SSE/WS） │ │ └─ components/testrun/... # 测试运行面板与实时输出 │ ├─ pages/ │ │ ├─ FlowList.tsx # 流程列表/新建/编辑 │ │ └─ FlowRunLogs.tsx # 运行日志列表 │ ├─ utils/ │ │ ├─ axios.ts # 统一请求拦截（401 刷新/跳转登录） │ │ └─ token.ts # 本地令牌与用户信息管理 │ ├─ App.tsx / main.tsx # 入口与路由 │ └─ styles / layouts ... # 样式与布局 │ ├─ docs/ # 文档 │ ├─ flow_architecture.md # Flow 架构与执行图（Mermaid） │ └─ ... # 其他专题文档（概览/后端/前端/示例） │ └─ .trae/rules/project_rules.md # 项目代码规范（Rust 文件顺序等） ``` ## ⚙️ 快速启动 - 后端启动（默认读取 `.env`，端口：HTTP 9898，SSE 8866，WS 8855） - `cd backend && ENV_FILE=dev cargo run` - 前端启动（默认开发端口 8888） - `cd frontend && npm install && npm run dev` ## 🔌 主要接口 - 流程管理 - `POST /api/flows` 新建流程（支持 YAML 与 design_json） - `GET /api/flows` 分页查询 - `GET/PUT/DELETE /api/flows/{id}` 详情/更新/删除 - `POST /api/flows/{id}/run` 同步运行，返回 `{ ok, ctx, logs }` - `POST /api/flows/{id}/run/stream` SSE 流式运行，推送节点事件与完成事件 - `GET /api/flows/{id}/run/ws` WebSocket 流式运行 - 运行日志 - `GET /api/flow_run_logs` 分页查询（支持按 flow_id/flow_code/user/ok 过滤） - `DELETE /api/flow_run_logs/{ids}` 批量删除 ## 🧩 架构与执行 - 引擎：自研 `FlowEngine`（递归驱动图，合流屏障，分支并行，组等待） - 模式：`sync`（同步）/ `async`（组内异步）/ `queued`（组队列）/ `bounded`（组限并发） - 条件：JSON 条件集合或 `rhai` 表达式；无匹配时回退无条件边 - 执行器：`http`、`db`、`variable`、`script_rhai/js/python`、`condition` - 文档详见：`docs/flow_architecture.md` ## 📚 文档导航 ### 🏗️ 架构文档 - **[项目概览](docs/PROJECT_OVERVIEW.md)** - UdminAI 项目的整体介绍、技术架构和核心功能 - **[后端架构](docs/BACKEND_ARCHITECTURE.md)** - 后端系统的详细架构设计和模块组织 - **[前端架构](docs/FRONTEND_ARCHITECTURE.md)** - 前端应用的架构设计、技术栈和组件体系 ### 🔧 核心模块 - **[流程引擎](docs/FLOW_ENGINE.md)** - 流程编排引擎的设计原理、执行机制和扩展能力 - **[服务层](docs/SERVICES.md)** - 业务服务层的设计模式、核心服务和集成方式 - **[路由层](docs/ROUTES.md)** - API 路由的设计规范、接口定义和中间件集成 - **[数据模型](docs/MODELS.md)** - 数据模型的设计原则、实体定义和关系映射 - **[中间件](docs/MIDDLEWARES.md)** - 中间件系统的设计理念、核心组件和使用方式 - **[Flow 架构与执行图](docs/flow_architecture.md)** - Flow 端到端架构图与执行流程 ### 🛠️ 基础设施 - **[数据库](docs/DATABASE.md)** - 数据库连接管理、查询优化和性能调优 - **[错误处理](docs/ERROR_HANDLING.md)** - 统一错误处理机制、错误类型定义和处理策略 - **[响应格式](docs/RESPONSE.md)** - API 响应格式规范、数据结构和最佳实践 - **[工具函数](docs/UTILS.md)** - 通用工具函数库、辅助工具和实用程序 ### 📋 专项文档 - **[Redis 集成](docs/REDIS_INTEGRATION.md)** - Redis 缓存系统的集成方案和使用指南 - **[ID 生成分析](docs/ID_GENERATION_ANALYSIS.md)** - 分布式 ID 生成策略和实现分析 ### 🎯 流程编辑器 - **[变量节点使用](docs/variable-node-usage.md)** - 流程变量节点的使用方法和最佳实践 - **[固定布局演示](docs/flow-fixed-layout-demo.md)** - 固定布局流程编辑器的演示和说明 - **[自由布局演示](docs/flow-free-layout-demo.md)** - 自由布局流程编辑器的功能展示 - **[基础自由布局](docs/flow-free-layout-base-demo.md)** - 自由布局的基础功能和操作指南 - **[简单自由布局](docs/flow-free-layout-simple-demo.md)** - 简化版自由布局编辑器的使用说明 - **[自由布局 JSON](docs/flow-free-layout-json.md)** - 自由布局的 JSON 数据结构定义 - **[SJ 自由布局演示](docs/flow-free-layout-sj-demo.md)** - SJ 版本自由布局编辑器的特性说明 ## 🚀 快速开始 ### 新手指南 如果你是第一次接触 UdminAI 项目，建议按以下顺序阅读文档： 1. **[项目概览](docs/PROJECT_OVERVIEW.md)** - 了解项目整体架构和核心概念 2. **[后端架构](docs/BACKEND_ARCHITECTURE.md)** - 理解后端系统的设计思路 3. **[前端架构](docs/FRONTEND_ARCHITECTURE.md)** - 掌握前端应用的组织结构 4. **[流程引擎](docs/FLOW_ENGINE.md)** - 深入了解核心的流程编排能力 ### 开发者指南 对于参与开发的团队成员，重点关注以下文档： - **[服务层](docs/SERVICES.md)** - 业务逻辑的实现规范 - **[路由层](docs/ROUTES.md)** - API 接口的设计标准 - **[数据模型](docs/MODELS.md)** - 数据结构的定义规则 - **[错误处理](docs/ERROR_HANDLING.md)** - 错误处理的统一方案 ### 运维指南 对于系统运维和部署，参考以下文档： - **[数据库](docs/DATABASE.md)** - 数据库的配置和优化 - **[Redis 集成](docs/REDIS_INTEGRATION.md)** - 缓存系统的部署和管理 - **[中间件](docs/MIDDLEWARES.md)** - 中间件的配置和监控 ## 📖 文档约定 ### 文档结构 每个模块文档都遵循统一的结构： - **概述** - 模块的基本介绍和设计目标 - **设计原则** - 核心的设计理念和约束条件 - **核心功能** - 主要功能特性和实现方式 - **使用示例** - 具体的代码示例和使用方法 - **最佳实践** - 推荐的使用模式和注意事项 - **总结** - 模块特点和价值总结 ### 代码示例 文档中的代码示例都经过验证，可以直接在项目中使用。代码遵循项目的编码规范： - **Rust 代码** - 遵循 Rust 2021 edition 和项目编码规范 - **TypeScript 代码** - 遵循 TypeScript 严格模式和 ESLint 规则 - **配置文件** - 使用 YAML/TOML 格式，保持简洁清晰 ### 更新机制 文档与代码同步更新，确保文档的时效性和准确性： - **版本控制** - 文档与代码使用相同的版本管理 - **持续集成** - 代码变更时自动检查文档的一致性 - **定期审查** - 定期审查和更新文档内容 ## 🤝 贡献指南 ### 文档贡献 欢迎为项目文档做出贡献： 1. **发现问题** - 如果发现文档中的错误或不准确之处，请提交 Issue 2. **改进建议** - 对文档结构或内容有改进建议，欢迎讨论 3. **新增内容** - 可以补充缺失的文档或添加新的使用案例 4. **翻译工作** - 可以帮助将文档翻译成其他语言 ### 文档规范 贡献文档时请遵循以下规范： - **Markdown 格式** - 使用标准的 Markdown 语法 - **中文写作** - 使用简洁明了的中文表达 - **代码高亮** - 为代码块指定正确的语言类型 - **链接检查** - 确保所有链接都是有效的 ## 📞 获取帮助 如果在使用过程中遇到问题，可以通过以下方式获取帮助： - **查阅文档** - 首先查看相关的模块文档 - **搜索 Issue** - 在项目 Issue 中搜索类似问题 - **提交 Issue** - 如果问题未解决，请提交新的 Issue - **社区讨论** - 参与项目的社区讨论 ## 📄 许可证 本文档遵循与项目相同的许可证。详细信息请参考项目根目录的 LICENSE 文件。 --- **UdminAI 团队** *构建智能化的流程管理平台* > 💡 **提示**: 建议将本文档加入浏览器书签，方便随时查阅。文档会持续更新，请关注最新版本。