erp-ass/README.md

# ERP AI Assistant - 一零软件智能配置助手

基于 Claude AI 的 ERP 平台智能配置助手，支持自然语言需求分析、自动化配置生成和安全执行。

## 🌟 核心功能

- **智能需求分析**: 自然语言输入 → 结构化需求文档
- **自动配置生成**: 基于需求自动生成 SQL 配置语句
- **安全执行机制**: SQL 安全验证 + 人工审核 + 事务保护
- **知识库增强**: RAG 技术提供平台配置知识检索

## 🚀 快速上手

**首次使用请阅读**: [快速上手指南](docs/QUICK_START.md)

### 一键启动（推荐）

```bash
# 1. 首次配置
cd backend && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
cd ../frontend && npm install
# 配置环境变量
cd ../backend && cp .env.example .env  # 编辑填入数据库和 API 配置

# 2. 启动项目（一个命令启动前后端）
cd ..
./start.sh        # Linux/Mac
# 或
start.bat         # Windows
```

访问 http://localhost:5173 开始使用！

**管理命令**:
- 查看状态: `./status.sh`
- 停止服务: `./stop.sh`
- 重启服务: `./restart.sh`
- 查看日志: `tail -f logs/backend.log`

**详细说明**: [一键启动指南](docs/ONE_CLICK_START.md)

### 手动启动（开发模式）

如果你需要分别启动前后端：

```bash
# 终端 1: 启动后端
cd backend && source venv/bin/activate && python -m app.main

# 终端 2: 启动前端
cd frontend && npm run dev
```

### 1. 环境要求

- Python 3.10+
- Node.js 18+
- SQL Server 数据库
- Anthropic API Key

### 2. 后端安装

```bash
cd backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入配置信息
```

### 3. 前端安装

```bash
cd frontend

# 安装依赖
npm install
```

### 4. 启动服务

**启动后端:**
```bash
cd backend
source venv/bin/activate
python -m app.main
```

后端服务运行在 http://localhost:8000

**启动前端:**
```bash
cd frontend
npm run dev
```

前端服务运行在 http://localhost:5173

### 5. 访问应用

**本地访问:**
打开浏览器访问 http://localhost:5173

**局域网访问:**
其他设备可通过服务器 IP 访问：http://192.168.1.100:5173

详细配置请参考 [局域网访问指南](docs/LAN_ACCESS.md)

## 📚 API 文档

启动后端后访问:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 核心 API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/v1/analyze` | POST | 分析用户需求 |
| `/api/v1/generate` | POST | 生成 SQL 配置 |
| `/api/v1/execute` | POST | 执行 SQL 配置 |
| `/health` | GET | 健康检查 |

## 🏗️ 项目结构

```
erp-ass/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/            # API 路由
│   │   ├── core/           # 核心引擎
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务服务
│   │   ├── config.py       # 配置管理
│   │   └── main.py         # 应用入口
│   ├── tests/              # 测试文件
│   ├── knowledge_base/     # 知识库文档
│   └── requirements.txt    # Python 依赖
├── frontend/               # 前端应用
│   ├── src/
│   │   ├── router/        # 路由配置
│   │   ├── views/         # 页面组件
│   │   ├── main.js        # 应用入口
│   │   └── App.vue        # 根组件
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
└── docs/                   # 项目文档
```

## 🔧 配置说明

### 后端环境变量 (.env)

```bash
# 应用配置
APP_NAME=ERP AI Assistant
APP_ENV=development
DEBUG=True
SECRET_KEY=your-secret-key

# 数据库配置
DB_DRIVER=ODBC Driver 17 for SQL Server
DB_SERVER=localhost
DB_PORT=1433
DB_NAME=ERP_DB
DB_USER=sa
DB_PASSWORD=your-password

# Claude API 配置
ANTHROPIC_API_KEY=your-api-key
# ANTHROPIC_BASE_URL=https://your-proxy.com  # Optional: custom base URL for proxy or self-hosted
CLAUDE_MODEL=claude-sonnet-4-6
CLAUDE_MAX_TOKENS=8192
CLAUDE_TEMPERATURE=0.7

# 知识库配置
KNOWLEDGE_BASE_PATH=./knowledge_base
CHROMA_DB_PATH=./knowledge_base/chroma_db
EMBEDDING_MODEL=all-MiniLM-L6-v2
CHUNK_SIZE=500
CHUNK_OVERLAP=50
```

## 🧪 运行测试

```bash
cd backend
source venv/bin/activate
pytest tests/ -v --cov=app
```

## 📖 使用流程

### 1. 创建新功能

1. 访问前端页面，进入"新建功能"
2. 输入自然语言需求，例如：
   ```
   创建一个销售订单管理页面，包含订单号、客户、订单日期、金额字段
   ```
3. 点击"分析需求"，系统自动生成结构化需求文档

### 2. 生成配置

1. 查看需求分析结果
2. 确认需求正确后，点击"生成配置"
3. 系统自动生成 SQL 配置语句

### 3. 执行配置

1. 预览生成的 SQL 语句
2. 确认无误后，点击"执行"
3. 系统安全执行配置，记录执行日志

## 🔐 安全特性

- ✅ SQL 注入防护（参数化查询）
- ✅ 危险操作拦截（DROP、TRUNCATE）
- ✅ 事务保护（自动回滚）
- ✅ 人工审核机制
- ✅ 密码安全编码

## 📋 开发计划

### Phase 1 (已完成) ✅
- 基础架构搭建
- 核心引擎实现
- API 层开发
- 前端基础界面

### Phase 2 (计划中)
- 执行日志和审计系统
- 数据库元数据 API
- 知识库管理界面
- 配置预览组件
- 执行监控组件

### Phase 3 (计划中)
- 错误排查系统
- 系统优化功能
- 性能分析工具

## 🛠️ 技术栈

**后端:**
- FastAPI - 现代 Web 框架
- SQLAlchemy - ORM
- Anthropic Claude - AI 引擎
- ChromaDB - 向量数据库
- sentence-transformers - 文本嵌入

**前端:**
- Vue 3 - 渐进式框架
- Vite - 构建工具
- Element Plus - UI 组件库
- Vue Router - 路由管理
- Pinia - 状态管理

**数据库:**
- SQL Server - 业务数据库
- ChromaDB - 知识库向量数据库

## 📄 许可证

本项目仅供内部使用。

## 🤝 贡献

暂不接受外部贡献。

## 📞 联系方式

如有问题，请联系项目负责人。

---

**版本:** 1.0.0
**更新日期:** 2026-03-21