# Warehouse-AgentFlow

**Repository Path**: asurd/warehouse-agent-flow

## Basic Information

- **Project Name**: Warehouse-AgentFlow
- **Description**: 智慧仓储机器人调度系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Warehouse-AgentFlow

智慧仓储多机器人协同作业调度系统 — 基于多智能体架构。

## 项目结构

```
src/
├── main.py              # 启动入口
├── app.py               # FastAPI app 工厂
├── modules/             # 业务模块
│   ├── order/           # 订单拆解与状态管理 ✅ (13 文件)
│   ├── dispatch/        # 任务调度与指派 ✅ (12 文件)
│   ├── trace/           # 全程溯源 ✅ (6 文件: 中间件+EventBus桥接)
│   ├── path/            # 路径规划骨架 🚧
│   ├── conflict/        # 冲突检测骨架 🚧
│   ├── review/          # 多轮审查骨架 🚧
│   ├── qc/              # 智能质控骨架 🚧
│   ├── robot_gateway/   # 机器人通信网关骨架 🚧
│   └── monitor/         # 监控看板骨架 🚧
├── map_service/         # 地图服务 (栅格/拓扑/成本) ✅ (22 文件)
├── dispatch_service/    # 规则引擎调度 ✅ (30 文件)
├── path_service/        # A* 路径规划引擎 ✅ (28 文件)
├── order_service/       # 订单服务 (遗留, 待合并)
├── agents/              # Agent 框架骨架 🚧
├── common/              # 共享模型、适配器、事件总线 ✅
├── api/                 # 统一骨架路由 (501)
└── simulation/          # Pygame 仿真引擎骨架 🚧
```

## 快速开始

### 环境要求

- Python 3.12+
- Docker（运行基础设施）

### 1. 创建虚拟环境

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动基础设施（可选）

Docker 服务端口：MySQL `3307`（宿主机）→ `3306`（容器）、Redis `6379`、MQTT `1883`/`9001`。
无需 Docker 也能启动应用并浏览 API 文档（DB 不可用时降级启动）。需要完整功能时：

```bash
docker compose up -d
```

### 4. 启动应用

```bash
uvicorn src.main:app --reload --port 8000
```

浏览器打开 http://127.0.0.1:8000/docs 查看 Swagger API 文档。



### 5. 运行测试

```bash
pytest tests/ -v
```

## API 端点

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/health` | 健康检查 + DB 状态 | ✅ |
| POST | `/api/v1/orders` | 创建订单 | ✅ |
| GET | `/api/v1/orders` | 订单列表（分页） | ✅ |
| GET | `/api/v1/orders/{id}` | 查询订单 | ✅ |
| POST | `/api/v1/orders/{id}/cancel` | 取消订单 | ✅ |
| GET | `/api/v1/tasks/{id}` | 查询任务 | ✅ |
| POST | `/api/v1/tasks/{id}/intervene` | 人工干预 | ✅ |
| POST | `/internal/dispatch/assign` | 任务指派 | ✅ |
| POST | `/api/v1/maps` | 创建地图 | ✅ |
| GET | `/api/v1/maps/{id}` | 查询地图 | ✅ |
| PUT | `/api/v1/maps/{id}/grids` | 更新栅格数据 | ✅ |
| POST | `/api/v1/maps/{id}/publish` | 发布地图 | ✅ |
| POST | `/api/v1/maps/{id}/archive` | 归档地图 | ✅ |
| DELETE | `/api/v1/maps/{id}` | 删除地图 | ✅ |
| POST | `/api/v1/maps/{id}/locations` | 创建库位 | ✅ |
| POST | `/api/v1/maps/{id}/locations/{lid}/status` | 更新库位状态 | ✅ |
| POST | `/internal/trace/event` | 写入 Trace 事件 | ✅ |
| GET | `/api/v1/traces` | 查询 Trace（分页+过滤） | ✅ |
| GET | `/api/v1/traces/{id}` | Trace 详情 | ✅ |
| GET | `/api/v1/traces/timeline/{id}` | 实体时间线 | ✅ |
| POST | `/internal/path/plan` | 路径规划（A* 引擎独立部署） | 🚧 |
| POST | `/internal/path/replan` | 重规划 | 🚧 |
| POST | `/internal/path/reachability` | 可达性检查（引擎独立部署） | 🚧 |
| GET | `/api/v1/monitor/summary` | 监控摘要 | 🚧 |

> ✅ 可用   🚧 骨架（返回 501）
> 
> **注**: A* 路径规划引擎已完整实现在 `src/path_service/`（28 文件，含 `/api/v1/path/plan`、`/api/v1/path/cost/static` 等端点），作为独立服务运行，待集成到统一 app。

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Python 3.12 |
| Web 框架 | FastAPI |
| ORM | SQLAlchemy 2.0 (async) |
| 数据库 | MySQL 8.0 |
| 缓存 | Redis 7 |
| 消息 | MQTT (Mosquitto) |
| 路径规划 | NumPy + NetworkX |
| 仿真 | Pygame |
| CI | GitHub Actions |

## 文档

- [产品需求文档](docs/PRD-Warehouse-MultiRobot-Scheduling-202607061000.md)
- [架构设计文档](docs/ARCHITECTURE.md)