# rule_ai

**Repository Path**: wangpinglala/rule_ai

## Basic Information

- **Project Name**: rule_ai
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FlowForge 项目启动文档

## 项目简介

FlowForge 是一个轻量级工作流引擎，支持 DAG（有向无环图）定义、异步调度和可观测性。包含后端 API、调度器、执行器与前端仪表板。

### 核心特性

- **轻量级**: 单体应用架构，简化部署
- **可观测**: 完整的运行状态追踪和可视化
- **可扩展**: 支持多种任务类型，易于添加新类型
- **可靠**: 任务持久化，支持失败重试

---

## 技术栈

### 后端
- **框架**: FastAPI
- **数据库**: SQLite
- **ORM**: SQLAlchemy 2.0
- **任务队列**: Celery + Redis
- **验证**: Pydantic

### 前端
- **框架**: React 18 + TypeScript
- **构建工具**: Vite
- **样式**: TailwindCSS
- **状态管理**: React Query + Zustand
- **DAG 可视化**: React-Flow

### 基础设施
- **消息队列**: Redis
- **容器化**: Docker + Docker Compose

---

## 环境要求

### 必需
- Docker Desktop 20.10+
- Docker Compose 2.0+

### 可选（本地开发）
- Node.js 18+
- Python 3.11+
- Redis 7+

---

## 快速启动

### 方式一：Docker Compose（推荐）

```bash
# 克隆项目
git clone <repository-url>
cd FlowForge

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps
```

服务启动后：
- 前端: http://localhost:5173
- 后端 API: http://localhost:8000
- API 文档: http://localhost:8000/docs
- Redis: localhost:6379

### 方式二：本地开发

#### 1. 启动 Redis

```bash
# 使用 Docker 启动 Redis
docker run -d --name redis -p 6379:6379 redis:7-alpine
```

#### 2. 启动后端

```bash
cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动 API 服务
uvicorn app.main:app --reload --port 8000
```

#### 3. 启动 Celery Worker（新终端）

```bash
cd backend

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 启动 Worker
celery -A app.core.celery_app worker --loglevel=info
```

#### 4. 启动 Celery Beat（新终端，可选，用于定时任务）

```bash
cd backend

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 启动 Beat
celery -A app.core.celery_app beat --loglevel=info
```

#### 5. 启动前端（新终端）

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

---

## 项目结构

```
FlowForge/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── main.py            # FastAPI 入口
│   │   ├── core/              # 核心配置
│   │   │   ├── config.py      # 配置管理
│   │   │   ├── database.py    # 数据库连接
│   │   │   └── celery_app.py  # Celery 配置
│   │   ├── models/            # 数据模型
│   │   ├── schemas/           # Pydantic 模型
│   │   ├── api/               # API 路由
│   │   ├── services/          # 业务逻辑
│   │   └── tasks/             # Celery 任务
│   │       └── handlers/      # 任务处理器
│   ├── tests/                 # 测试
│   ├── requirements.txt       # Python 依赖
│   └── Dockerfile
├── frontend/                   # 前端服务
│   ├── src/
│   │   ├── main.tsx           # 入口文件
│   │   ├── App.tsx            # 根组件
│   │   ├── components/        # 组件
│   │   ├── pages/             # 页面
│   │   ├── api/               # API 客户端
│   │   └── hooks/             # 自定义 Hooks
│   ├── package.json           # Node 依赖
│   └── Dockerfile
├── tests/                      # E2E 测试
├── docker-compose.yml          # Docker Compose 配置
└── README.md
```

---

## 常用命令

### Docker 命令

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 查看日志
docker-compose logs -f

# 重新构建
docker-compose build --no-cache

# 进入容器
docker-compose exec backend bash
docker-compose exec frontend sh
```

### 后端命令

```bash
# 运行测试
pytest

# 代码格式化
ruff check .

# 数据库迁移
alembic revision --autogenerate -m "description"
alembic upgrade head
```

### 前端命令

```bash
# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产版本
npm run preview

# 代码检查
npm run lint

# 运行测试
npm run test

# 测试监听模式
npm run test:watch
```

---

## 环境变量

### 后端环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `DATABASE_URL` | `sqlite:///./flowforge.db` | 数据库连接 |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接 |

### 前端环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `VITE_API_URL` | `http://localhost:8000` | 后端 API 地址 |

---

## API 端点

### 工作流管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/workflows` | 创建工作流 |
| GET | `/api/v1/workflows` | 获取工作流列表 |
| GET | `/api/v1/workflows/{id}` | 获取工作流详情 |
| PUT | `/api/v1/workflows/{id}` | 更新工作流 |
| DELETE | `/api/v1/workflows/{id}` | 删除工作流 |
| POST | `/api/v1/workflows/{id}/validate` | 验证 DAG |

### 运行管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/workflows/{id}/runs` | 启动运行 |
| GET | `/api/v1/runs` | 获取运行列表 |
| GET | `/api/v1/runs/{id}` | 获取运行详情 |
| GET | `/api/v1/runs/{id}/tasks` | 获取任务列表 |
| POST | `/api/v1/runs/{id}/cancel` | 取消运行 |

### WebSocket

| 路径 | 说明 |
|------|------|
| `ws://localhost:8000/ws/runs/{run_id}` | 订阅运行状态更新 |

---

## 支持的任务类型

### 网络交互
- `http_request` - HTTP 请求
- `send_email` - SMTP 邮件发送

### 数据处理
- `json_transform` - JSON 转换
- `template_render` - 模板渲染
- `data_merge` - 数据合并

### 文件操作
- `file_read` - 读取文件
- `file_write` - 写入文件

### 外部集成
- `shell_command` - Shell 命令执行

---

## 测试

### E2E 测试

```bash
# 安装 Playwright
npx playwright install

# 运行 E2E 测试
npx playwright test

# 带 UI 运行测试
npx playwright test --ui
```

---

## 故障排除

### 常见问题

1. **端口被占用**
   ```bash
   # Windows 查看端口占用
   netstat -ano | findstr :8000
   netstat -ano | findstr :5173

   # 结束进程
   taskkill /PID <pid> /F
   ```

2. **Redis 连接失败**
   - 确保 Redis 已启动
   - 检查 `REDIS_URL` 环境变量

3. **前端无法连接后端**
   - 检查后端是否正常运行
   - 检查 CORS 配置
   - 确认 `VITE_API_URL` 设置正确

4. **Celery 任务不执行**
   - 确保 Worker 已启动
   - 检查 Redis 连接
   - 查看 Worker 日志

---

## 相关文档

- [需求分析与设计](./需求分析与设计.md)
- [API 文档](http://localhost:8000/docs) - 启动后端后访问

---

## 许可证

ISC