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.<id>.<executor>）
│     │  ├─ 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

📚 文档导航

🏗️ 架构文档

• 项目概览 - UdminAI 项目的整体介绍、技术架构和核心功能
• 后端架构 - 后端系统的详细架构设计和模块组织
• 前端架构 - 前端应用的架构设计、技术栈和组件体系

🔧 核心模块

• 流程引擎 - 流程编排引擎的设计原理、执行机制和扩展能力
• 服务层 - 业务服务层的设计模式、核心服务和集成方式
• 路由层 - API 路由的设计规范、接口定义和中间件集成
• 数据模型 - 数据模型的设计原则、实体定义和关系映射
• 中间件 - 中间件系统的设计理念、核心组件和使用方式
• Flow 架构与执行图 - Flow 端到端架构图与执行流程

🛠️ 基础设施

• 数据库 - 数据库连接管理、查询优化和性能调优
• 错误处理 - 统一错误处理机制、错误类型定义和处理策略
• 响应格式 - API 响应格式规范、数据结构和最佳实践
• 工具函数 - 通用工具函数库、辅助工具和实用程序

📋 专项文档

• Redis 集成 - Redis 缓存系统的集成方案和使用指南
• ID 生成分析 - 分布式 ID 生成策略和实现分析

🎯 流程编辑器

• 变量节点使用 - 流程变量节点的使用方法和最佳实践
• 固定布局演示 - 固定布局流程编辑器的演示和说明
• 自由布局演示 - 自由布局流程编辑器的功能展示
• 基础自由布局 - 自由布局的基础功能和操作指南
• 简单自由布局 - 简化版自由布局编辑器的使用说明
• 自由布局 JSON - 自由布局的 JSON 数据结构定义
• SJ 自由布局演示 - SJ 版本自由布局编辑器的特性说明

🚀 快速开始

新手指南

如果你是第一次接触 UdminAI 项目，建议按以下顺序阅读文档：

1. 项目概览 - 了解项目整体架构和核心概念
2. 后端架构 - 理解后端系统的设计思路
3. 前端架构 - 掌握前端应用的组织结构
4. 流程引擎 - 深入了解核心的流程编排能力

开发者指南

对于参与开发的团队成员，重点关注以下文档：

• 服务层 - 业务逻辑的实现规范
• 路由层 - API 接口的设计标准
• 数据模型 - 数据结构的定义规则
• 错误处理 - 错误处理的统一方案

运维指南

对于系统运维和部署，参考以下文档：

• 数据库 - 数据库的配置和优化
• Redis 集成 - 缓存系统的部署和管理
• 中间件 - 中间件的配置和监控

📖 文档约定

文档结构

每个模块文档都遵循统一的结构：

• 概述 - 模块的基本介绍和设计目标
• 设计原则 - 核心的设计理念和约束条件
• 核心功能 - 主要功能特性和实现方式
• 使用示例 - 具体的代码示例和使用方法
• 最佳实践 - 推荐的使用模式和注意事项
• 总结 - 模块特点和价值总结

代码示例

文档中的代码示例都经过验证，可以直接在项目中使用。代码遵循项目的编码规范：

• Rust 代码 - 遵循 Rust 2021 edition 和项目编码规范
• TypeScript 代码 - 遵循 TypeScript 严格模式和 ESLint 规则
• 配置文件 - 使用 YAML/TOML 格式，保持简洁清晰

更新机制

文档与代码同步更新，确保文档的时效性和准确性：

• 版本控制 - 文档与代码使用相同的版本管理
• 持续集成 - 代码变更时自动检查文档的一致性
• 定期审查 - 定期审查和更新文档内容

🤝 贡献指南

文档贡献

欢迎为项目文档做出贡献：

1. 发现问题 - 如果发现文档中的错误或不准确之处，请提交 Issue
2. 改进建议 - 对文档结构或内容有改进建议，欢迎讨论
3. 新增内容 - 可以补充缺失的文档或添加新的使用案例
4. 翻译工作 - 可以帮助将文档翻译成其他语言

文档规范

贡献文档时请遵循以下规范：

• Markdown 格式 - 使用标准的 Markdown 语法
• 中文写作 - 使用简洁明了的中文表达
• 代码高亮 - 为代码块指定正确的语言类型
• 链接检查 - 确保所有链接都是有效的

📞 获取帮助

如果在使用过程中遇到问题，可以通过以下方式获取帮助：

• 查阅文档 - 首先查看相关的模块文档
• 搜索 Issue - 在项目 Issue 中搜索类似问题
• 提交 Issue - 如果问题未解决，请提交新的 Issue
• 社区讨论 - 参与项目的社区讨论

📄 许可证

本文档遵循与项目相同的许可证。详细信息请参考项目根目录的 LICENSE 文件。

---

UdminAI 团队
构建智能化的流程管理平台

💡 提示: 建议将本文档加入浏览器书签，方便随时查阅。文档会持续更新，请关注最新版本。