# alpha-program

**Repository Path**: lingfengsu/alpha-program

## Basic Information

- **Project Name**: alpha-program
- **Description**: 宜昌两网
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-28
- **Last Updated**: 2025-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SchedulerAI Simplified - 简化项目调度优化系统

基于Google OR-Tools的轻量级项目调度系统，专注于核心调度优化功能，提供简洁高效的API接口。

## 🌟 核心功能

- **智能调度算法**: 基于CP-SAT求解器的全局优化
- **标准约束支持**: FS、SS、FF、SF四种前后置关系
- **资源约束优化**: 多种资源类型的容量限制
- **简化分区逻辑**: 基于CSV"划分条件"列的分区判断
- **RESTful API**: FastAPI驱动的现代化API接口
- **统一错误处理**: 标准化的错误响应和日志记录

### 🚀 简化设计理念

**系统优势:**
- **代码精简**: 移除复杂逻辑，代码量减少30%+
- **易于维护**: 统一的工序处理，简化的架构设计
- **高效求解**: 专注核心优化算法，提升求解性能
- **标准接口**: RESTful API，易于集成和扩展

**快速使用:**
```python
import requests

# 通过API优化项目调度
with open("project.csv", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/optimize",
        files={"csv_file": f}
    )

result = response.json()
print(f"优化工期: {result['makespan']} 天")
```

## 系统架构

```mermaid
graph TB
    subgraph "API层 (API Layer)"
        API[FastAPI接口<br/>simplified_api.py]
    end
    
    subgraph "业务逻辑层 (Business Layer)"
        SVC[调度服务<br/>simplified_scheduler_service.py]
        PARSER[数据解析器<br/>simplified_data_parser.py]
    end
    
    subgraph "计算层 (Compute Layer)"
        SOLVER[CP-SAT求解器<br/>simplified_cpsat_solver.py]
    end
    
    subgraph "外部接口"
        CSV[CSV文件输入]
        JSON[JSON结果输出]
    end
    
    API --> SVC
    SVC --> PARSER
    SVC --> SOLVER
    PARSER --> CSV
    API --> JSON
```

### 简化架构特点

- **三层架构**: API层、业务逻辑层、计算层清晰分离
- **统一处理**: 所有工序使用相同的处理逻辑
- **简化分区**: 只依赖CSV"划分条件"列判断分区
- **标准接口**: RESTful API，支持文件上传和JSON响应

## 快速开始

### 环境要求

- **Python**: 3.8 或更高版本
- **操作系统**: Windows, macOS, Linux
- **内存**: 建议 4GB 以上
- **磁盘空间**: 至少 200MB 可用空间

### 安装步骤

#### 1. 克隆或下载项目

```bash
# 使用 Git 克隆（推荐）
git clone https://github.com/schedulerai/scheduler-ai-simplified.git
cd scheduler-ai-simplified

# 或者下载 ZIP 文件并解压
```

#### 2. 创建虚拟环境

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

# 激活虚拟环境
# Windows
venv\Scripts\activate

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

#### 3. 安装依赖

```bash
# 升级 pip（推荐）
python -m pip install --upgrade pip

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

# 验证安装
python -c "import ortools; print('OR-Tools 安装成功')"
```

#### 4. 启动API服务

```bash
# 启动API服务
python run_api.py

# 或者使用uvicorn直接启动
uvicorn scheduler_ai.simplified_api:app --host 0.0.0.0 --port 8000 --reload
```

#### 5. 验证安装

```bash
# 检查API健康状态
curl http://localhost:8000/health

# 查看API文档
# 浏览器访问: http://localhost:8000/docs
```

### 基本使用

#### API接口调用

##### 1. 健康检查

```bash
# 检查API服务状态
curl http://localhost:8000/health

# 获取系统信息
curl http://localhost:8000/api/v1/info
```

##### 2. 项目调度优化

```bash
# 使用curl上传CSV文件进行优化
curl -X POST "http://localhost:8000/api/v1/optimize" \
     -H "accept: application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "csv_file=@project.csv"
```

##### 3. Python客户端调用

```python
import requests

# 优化项目调度
with open("project.csv", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/optimize",
        files={"csv_file": f}
    )

if response.status_code == 200:
    result = response.json()
    if result["success"]:
        print(f"优化成功！工期: {result['makespan']} 天")
        print(f"求解时间: {result['solve_time']:.3f} 秒")
        
        # 查看调度详情
        for activity_id, activity in result["schedule"].items():
            print(f"工序{activity_id}: {activity['name']} "
                  f"({activity['start_time']}-{activity['end_time']}天)")
    else:
        print(f"优化失败: {result['error_message']}")
```

##### 4. CSV文件验证

```python
import requests

# 验证CSV文件格式
with open("project.csv", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/validate-csv",
        files={"csv_file": f}
    )

result = response.json()
print(f"工序总数: {result['statistics']['total_activities']}")
print(f"可分区工序: {result['statistics']['subdividable_activities']}")
print("建议:", result['recommendations'])
```

## CSV文件格式规范

### 必需列

项目数据CSV文件**必须**包含以下列（支持中英文列名）：

| 列名 | 别名 | 数据类型 | 说明 | 示例 |
|------|------|----------|------|------|
| `ID` | - | 整数 | 工序唯一标识符 | 1, 2, 75 |
| `Name` | `名称` | 字符串 | 工序名称描述 | "基础混凝土浇筑" |
| `Duration` | `工期` | 正整数 | 工序持续时间（天） | 1, 3, 7 |
| `Predecessors` | `前置任务` | 字符串 | 前置依赖关系 | "74FS+1", "81SS-2, 77" |
| `划分条件` | - | 字符串 | 是否可分区 | "是", "否" |

### 资源列

资源列以 `Resource_` 开头，系统会自动识别：

| 列名格式 | 说明 | 示例 |
|----------|------|------|
| `Resource_Worker` | 工人需求数量 | 5, 10 |
| `Resource_Excavator` | 挖掘机需求数量 | 1, 2 |
| `Resource_Crane` | 起重机需求数量 | 1 |
| `Resource_[类型]` | 自定义资源类型 | 任意正整数 |

### 分区逻辑说明

**简化分区判断**：
- 系统只检查"划分条件"列的值
- "是" → 工序可以分区优化
- "否"或空值 → 工序不可分区
- 完全移除了复杂的文本识别逻辑

### 前置关系格式详解

#### 基本格式

```
[工序ID][依赖类型][延时]
```

#### 依赖类型说明

| 类型 | 全称 | 含义 | 示例 |
|------|------|------|------|
| `FS` | Finish-to-Start | 前置工序完成后开始 | `75FS` - 工序75完成后开始 |
| `SS` | Start-to-Start | 与前置工序同时开始 | `81SS` - 与工序81同时开始 |
| `FF` | Finish-to-Finish | 与前置工序同时完成 | `88FF` - 与工序88同时完成 |
| `SF` | Start-to-Finish | 前置工序开始后完成 | `90SF` - 工序90开始后完成 |

#### 延时格式

| 格式 | 含义 | 示例 |
|------|------|------|
| `+数字` | 正延时（延后） | `FS+3` - 完成后3天开始 |
| `-数字` | 负延时（提前） | `SS-2` - 提前2天同时开始 |
| 无延时 | 默认为0 | `FS` - 完成后立即开始 |

#### 多依赖关系

使用逗号分隔多个依赖关系：

```
"74FS+1, 73SS-2, 72FF"
```

#### 完整示例

```csv
ID,Name,Duration,Predecessors,划分条件,Resource_Worker,Resource_Excavator
1,场地清理,2,,否,4,1
2,基础开挖,3,1FS+1,是,6,2
3,基础钢筋绑扎,2,2FS,是,8,0
4,基础模板安装,1,3FS,否,4,0
5,基础混凝土浇筑,1,4FS,是,6,0
6,基础养护,3,5FS,否,2,0
7,地下室墙体钢筋,4,6FS,是,10,0
8,地下室墙体模板,2,7FS,否,6,0
9,地下室墙体浇筑,2,8FS,是,8,0
10,地下室顶板钢筋,3,"9SS+2",是,8,0
```

**说明**：
- 工序2、3、5、7、9、10标记为"是"，可以进行分区优化
- 工序1、4、6、8标记为"否"，作为整体处理
- 系统会根据"划分条件"列自动判断分区策略

### 数据验证规则

1. **ID唯一性**: 每个工序ID必须唯一
2. **正整数约束**: Duration和资源需求必须为正整数
3. **依赖关系有效性**: Predecessors中引用的ID必须存在
4. **循环依赖检测**: 系统会自动检测并拒绝循环依赖
5. **编码格式**: 文件必须使用UTF-8编码

## API响应格式

### 优化结果响应

```json
{
  "success": true,
  "makespan": 15,
  "schedule": {
    "1": {
      "id": 1,
      "name": "基础开挖",
      "start_time": 0,
      "end_time": 5,
      "duration": 5,
      "resource_info": "worker:3, excavator:1"
    },
    "2": {
      "id": 2,
      "name": "钢筋绑扎",
      "start_time": 5,
      "end_time": 8,
      "duration": 3,
      "resource_info": "worker:2"
    }
  },
  "duration_comparison": {
    "original_makespan": 18,
    "optimized_makespan": 15,
    "improvement": 3,
    "improvement_percentage": 16.7
  },
  "solve_time": 0.025,
  "status": "OPTIMAL",
  "timestamp": "2025-08-25T10:30:00.000000"
}
```

### 错误响应格式

```json
{
  "success": false,
  "error_message": "CSV文件缺少必需列: Duration",
  "timestamp": "2025-08-25T10:30:00.000000"
}
```

### 验证响应格式

```json
{
  "success": true,
  "file_info": {
    "filename": "project.csv",
    "size": 1024
  },
  "statistics": {
    "total_activities": 10,
    "subdividable_activities": 6,
    "resource_types": ["worker", "excavator"],
    "activities_with_resources": 10
  },
  "validation_results": {
    "has_required_columns": true,
    "has_subdivision_column": true,
    "has_resource_columns": true,
    "has_precedences": true
  },
  "recommendations": [
    "CSV文件格式良好，可以进行调度优化"
  ]
}
```

## 开发指南

### 运行测试

```bash
# 运行所有测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=scheduler_ai --cov-report=html

# 运行特定测试文件
pytest tests/test_data_models.py -v

# 运行特定测试方法
pytest tests/test_data_parser.py::test_parse_predecessors -v
```

### 代码质量检查

```bash
# 代码格式化
black scheduler_ai/ tests/ main.py

# 代码风格检查
flake8 scheduler_ai/ tests/ main.py

# 类型检查
mypy scheduler_ai/

# 运行所有质量检查
black . && flake8 . && mypy scheduler_ai/
```

### 性能测试

```bash
# 运行性能测试
python test_data/performance_test.py

# 运行简单性能测试
python test_data/simple_performance_test.py
```

## 项目结构

```
scheduler-ai-simplified/
├── scheduler_ai/                      # 核心包
│   ├── __init__.py                   # 包初始化
│   ├── simplified_data_models.py     # 简化数据模型
│   ├── exceptions.py                 # 异常类定义
│   ├── simplified_data_parser.py     # 简化CSV解析器
│   ├── simplified_cpsat_solver.py    # 简化CP-SAT求解器
│   ├── simplified_scheduler_service.py # 简化调度服务
│   ├── simplified_api.py             # FastAPI接口
│   ├── error_handlers.py             # 错误处理器
│   └── logging_config.py             # 日志配置
├── tests/                            # 单元测试
│   ├── test_simplified_data_models.py
│   ├── test_simplified_data_parser.py
│   ├── test_simplified_cpsat_solver.py
│   ├── test_simplified_scheduler_service.py
│   └── test_simplified_api.py
├── docs/                             # 文档
│   ├── API_USAGE.md                  # API使用指南
│   ├── CSV_FORMAT_GUIDE.md           # CSV格式指南
│   └── DEPLOYMENT_GUIDE.md           # 部署指南
├── examples/                         # 使用示例
│   └── api_usage_example.py          # API使用示例
├── test_data/                        # 测试数据
│   └── example_project.csv           # 示例项目数据
├── run_api.py                        # API启动脚本
├── Dockerfile                        # Docker配置
├── docker-compose.yml                # Docker Compose配置
├── requirements.txt                  # 项目依赖
├── setup.py                         # 安装配置
├── pyproject.toml                   # 项目配置
└── README.md                        # 项目说明
```

## 常见问题解答 (FAQ)

### 安装问题

**Q: 安装OR-Tools时出现错误怎么办？**

A: 尝试以下解决方案：
```bash
# 升级pip
python -m pip install --upgrade pip

# 使用国内镜像源
pip install ortools -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 如果仍有问题，尝试安装特定版本
pip install ortools==9.8.3296
```

**Q: API服务无法启动怎么办？**

A: 检查以下问题：
```bash
# 检查端口占用
netstat -tlnp | grep 8000

# 检查Python环境
python -c "import ortools, fastapi; print('依赖正常')"

# 使用调试模式启动
python run_api.py --log-level debug
```

### 数据格式问题

**Q: CSV文件编码错误怎么办？**

A: 系统支持多种编码格式：
- 支持UTF-8、GBK、GB2312编码
- Excel: 另存为 → CSV UTF-8 (逗号分隔)
- 系统会自动检测并转换编码

**Q: "划分条件"列如何设置？**

A: 简化的分区逻辑：
- "是" → 工序可以分区优化
- "否"或空值 → 工序不可分区
- 系统完全依赖此列判断，无需复杂设置

**Q: 前置关系格式错误怎么办？**

A: 检查Predecessors列格式：
- 正确: `1FS+3`, `2SS-2, 3FS`
- 错误: `1 FS +3`（多余空格）
- 错误: `1XS+3`（无效依赖类型）

### API使用问题

**Q: 如何验证CSV文件格式？**

A: 使用验证接口：
```bash
curl -X POST "http://localhost:8000/api/v1/validate-csv" \
     -F "csv_file=@project.csv"
```

**Q: 优化结果为什么不理想？**

A: 检查以下方面：
1. **分区设置**: 确认"划分条件"列设置正确
2. **资源约束**: 检查资源需求是否合理
3. **依赖关系**: 验证前置关系是否正确
4. **数据质量**: 确保工期和资源数据准确

**Q: 如何处理大型项目？**

A: 系统优化建议：
- 工序数量 < 1000: 直接处理
- 工序数量 > 1000: 考虑分阶段处理
- 使用批量处理接口处理多个项目

## 故障排除指南

### API服务问题

#### 1. 服务启动失败

```bash
# 检查端口占用
netstat -tlnp | grep 8000

# 检查Python环境
python -c "import ortools, fastapi; print('依赖正常')"

# 使用调试模式启动
python run_api.py --log-level debug
```

#### 2. 连接问题

```bash
# 检查服务状态
curl http://localhost:8000/health

# 检查防火墙设置
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-ports  # CentOS
```

### 数据格式问题

#### 1. CSV文件错误

**错误**: "只支持CSV文件格式"
**解决方案**: 确保上传的是.csv文件

**错误**: "CSV文件缺少必需列: Duration"
**解决方案**: 检查CSV文件包含所有必需列：ID, Name, Duration, Predecessors, 划分条件

**错误**: "工序ID重复"
**解决方案**: 确保ID列中每个值唯一

#### 2. 编码问题

**错误**: "无法解析CSV文件编码"
**解决方案**: 
- 系统支持UTF-8、GBK、GB2312编码
- 使用Excel另存为CSV UTF-8格式
- 或使用文本编辑器转换编码

#### 3. 依赖关系错误

**错误**: "检测到循环依赖关系"
**解决方案**:
- 检查前置关系是否形成循环
- 绘制依赖关系图识别问题
- 重新设计工序依赖关系

### 优化问题

#### 1. 求解失败

**错误**: "求解器无法找到可行解"
**解决方案**:
- 检查资源约束是否过严
- 验证依赖关系是否合理
- 确认工期设置是否正确

#### 2. 性能问题

**问题**: 求解时间过长
**解决方案**:
- 减少工序数量（建议<1000个）
- 简化资源类型
- 分阶段处理大型项目

### 调试技巧

#### 1. 使用验证接口

```bash
# 先验证CSV文件格式
curl -X POST "http://localhost:8000/api/v1/validate-csv" \
     -F "csv_file=@project.csv"
```

#### 2. 检查API响应

```python
import requests

response = requests.post(
    "http://localhost:8000/api/v1/optimize",
    files={"csv_file": open("project.csv", "rb")}
)

print(f"状态码: {response.status_code}")
print(f"响应: {response.json()}")
```

#### 3. 查看服务日志

```bash
# 如果使用systemd服务
sudo journalctl -u scheduler-ai -f

# 如果使用Docker
docker logs scheduler-ai -f
```

## 文档和支持

### 详细文档

- **[API使用指南](docs/API_USAGE.md)**: 详细的API接口说明
- **[CSV格式指南](docs/CSV_FORMAT_GUIDE.md)**: CSV文件格式要求
- **[部署指南](docs/DEPLOYMENT_GUIDE.md)**: 生产环境部署说明
- **[使用指南](docs/USAGE_GUIDE.md)**: 完整的使用教程

### 获取帮助

1. **查看文档**: 首先查阅相关文档和API说明
2. **使用验证接口**: 通过`/api/v1/validate-csv`检查数据格式
3. **检查API响应**: 查看详细的错误信息和建议
4. **运行示例**: 使用`examples/api_usage_example.py`验证环境

### 报告问题

提交Issue时请包含：
- 操作系统和Python版本
- API响应的完整错误信息
- 输入CSV文件样本（脱敏后）
- 重现步骤和预期结果

### 联系方式

- **项目主页**: https://github.com/schedulerai/scheduler-ai-simplified
- **问题报告**: https://github.com/schedulerai/scheduler-ai-simplified/issues
- **API文档**: http://localhost:8000/docs (服务启动后)

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 开发规范

- 遵循PEP 8代码风格
- 添加适当的类型注解
- 编写单元测试
- 更新相关文档

## 版本历史

- **v1.0.0** (2024-01-01): 初始版本发布
  - 基础CSV解析功能
  - CP-SAT求解器集成
  - 命令行界面
  - 完整的测试套件