feat: implement ERP AI Assistant Phase 1
Backend (FastAPI + SQLAlchemy + Claude API + RAG): - Config management with Pydantic v2 - Database engine with connection pooling and SQL injection prevention - AI engine with Claude API integration (support custom base URL) - RAG engine with ChromaDB and sentence-transformers - Requirement analysis service - Config generation service - Executor engine with SQL validation - REST API endpoints: /analyze, /generate, /execute Frontend (Vue 3 + Element Plus + Pinia): - Complete 3-step workflow: analyze → generate → execute - Step indicator with progress visualization - Analysis result display with field table - SQL preview with monospace font - Execute confirmation dialog with safety warning - Execution result display - State management with Pinia - API service integration Security: - SQL injection prevention with parameterized queries - Dangerous SQL operation blocking - Database password URL encoding - Transaction auto-rollback - Pydantic config validation Features: - Natural language requirement analysis - Automated SQL configuration generation - Safe execution with human review - LAN access support - Custom Claude API endpoint support Documentation: - README with quick start guide - Quick start guide - LAN access configuration - Dependency fixes guide - Claude API configuration - Git operation guide - Implementation report Dependencies fixed: - numpy<2.0.0 for chromadb compatibility - sentence-transformers==2.7.0 for huggingface_hub compatibility Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
386
docs/QUICK_START.md
Normal file
386
docs/QUICK_START.md
Normal file
@@ -0,0 +1,386 @@
|
||||
# 🚀 快速上手指南
|
||||
|
||||
## 📋 前置条件
|
||||
|
||||
### 1. 后端配置
|
||||
|
||||
确保已完成后端配置和依赖安装：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# 安装依赖（如果遇到问题，参考 docs/DEPENDENCY_FIXES.md）
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 配置环境变量
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，配置数据库和 Claude API
|
||||
```
|
||||
|
||||
**关键配置项:**
|
||||
```bash
|
||||
# 数据库配置
|
||||
DB_SERVER=192.168.120.19
|
||||
DB_PORT=1433
|
||||
DB_NAME=DMPF_HY
|
||||
DB_USER=sa
|
||||
DB_PASSWORD=your-password
|
||||
|
||||
# Claude API 配置
|
||||
ANTHROPIC_API_KEY=your-claude-api-key
|
||||
# 可选：使用自定义 API 端点
|
||||
# ANTHROPIC_BASE_URL=https://your-proxy.com/v1
|
||||
```
|
||||
|
||||
### 2. 前端配置
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
```
|
||||
|
||||
## 🎯 启动服务
|
||||
|
||||
### 启动后端
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
**成功输出:**
|
||||
```
|
||||
INFO: Uvicorn running on http://0.0.0.0:8000
|
||||
INFO: Application startup complete.
|
||||
```
|
||||
|
||||
### 启动前端
|
||||
|
||||
**新终端窗口:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**成功输出:**
|
||||
```
|
||||
➜ Local: http://localhost:5173/
|
||||
➜ Network: http://192.168.1.100:5173/
|
||||
```
|
||||
|
||||
## 📱 使用流程
|
||||
|
||||
### 步骤 1: 访问应用
|
||||
|
||||
打开浏览器访问：
|
||||
- **本地**: http://localhost:5173
|
||||
- **局域网**: http://192.168.1.100:5173 （替换为实际 IP）
|
||||
|
||||
### 步骤 2: 输入需求
|
||||
|
||||
在"步骤 1: 输入需求"卡片中，输入自然语言需求，例如：
|
||||
|
||||
```
|
||||
创建一个销售订单管理页面，包含订单号、客户、订单日期、金额、备注字段
|
||||
```
|
||||
|
||||
**示例需求:**
|
||||
|
||||
**简单示例:**
|
||||
```
|
||||
创建一个部门管理页面，包含部门名称、负责人、联系电话
|
||||
```
|
||||
|
||||
**中等复杂度:**
|
||||
```
|
||||
创建一个客户档案管理页面，包含客户名称、联系人、电话、地址、客户类型，支持按客户类型筛选
|
||||
```
|
||||
|
||||
**复杂示例:**
|
||||
```
|
||||
创建一个采购申请单，单据类型，包含申请单号、申请日期、申请人、部门、总金额，明细表包含物料编码、物料名称、数量、单价、金额
|
||||
```
|
||||
|
||||
### 步骤 3: 分析需求
|
||||
|
||||
点击 **"开始分析需求"** 按钮：
|
||||
|
||||
- ⏳ 等待 1-3 秒（取决于 API 响应时间）
|
||||
- ✅ 成功后显示结构化分析结果
|
||||
- 📊 包含：功能名称、功能类型、窗体类型、字段列表等
|
||||
|
||||
**示例输出:**
|
||||
```
|
||||
功能名称: 销售订单管理
|
||||
功能类型: 列表页面
|
||||
功能号建议: 11-001
|
||||
窗体类型: 5
|
||||
|
||||
主表字段:
|
||||
- 订单号 (varchar(50), 必填)
|
||||
- 客户 (varchar(100), 必填)
|
||||
- 订单日期 (datetime, 必填)
|
||||
- 金额 (decimal(18,2), 必填)
|
||||
- 备注 (varchar(500), 选填)
|
||||
```
|
||||
|
||||
### 步骤 4: 生成配置
|
||||
|
||||
确认分析结果无误后，点击 **"生成配置方案"** 按钮：
|
||||
|
||||
- ⏳ 等待 2-5 秒
|
||||
- ✅ 成功后显示生成的 SQL 配置
|
||||
- 📝 可以预览所有 SQL 语句
|
||||
|
||||
**SQL 预览示例:**
|
||||
```sql
|
||||
-- 创建功能号
|
||||
INSERT INTO SYS_FUNCTION (FUNCTION_ID, FUNCTION_NAME, ...)
|
||||
VALUES ('11-001', '销售订单管理', ...);
|
||||
|
||||
-- 创建页面配置
|
||||
INSERT INTO SYS_FORM (FORM_ID, FORM_NAME, ...)
|
||||
VALUES (...);
|
||||
|
||||
-- 创建表结构
|
||||
CREATE TABLE SA_ORDER (
|
||||
IKEY INT IDENTITY(1,1) PRIMARY KEY,
|
||||
ORDER_NO VARCHAR(50) NOT NULL,
|
||||
...
|
||||
);
|
||||
```
|
||||
|
||||
### 步骤 5: 执行配置
|
||||
|
||||
仔细检查 SQL 语句后，点击 **"确认并执行"** 按钮：
|
||||
|
||||
1. **安全警告对话框**
|
||||
- ⚠️ 阅读警告信息
|
||||
- ✅ 确认无误后点击"确认执行"
|
||||
|
||||
2. **执行过程**
|
||||
- ⏳ 等待执行完成
|
||||
- 📊 实时显示执行结果
|
||||
|
||||
3. **执行结果**
|
||||
- ✅ 成功: 显示"执行成功"消息
|
||||
- ❌ 失败: 显示错误详情
|
||||
|
||||
### 步骤 6: 完成
|
||||
|
||||
- 🎉 查看执行结果
|
||||
- 🔄 点击"创建新功能"开始下一个功能
|
||||
|
||||
## 🎨 界面说明
|
||||
|
||||
### 步骤指示器
|
||||
|
||||
顶部显示当前进度：
|
||||
```
|
||||
○ 需求分析 → ○ 配置生成 → ○ 执行配置
|
||||
```
|
||||
|
||||
- **当前步骤**: 高亮显示
|
||||
- **已完成**: 绿色勾选
|
||||
- **未完成**: 灰色
|
||||
|
||||
### 卡片区域
|
||||
|
||||
#### 需求输入卡片
|
||||
- 文本框：输入自然语言需求
|
||||
- "开始分析需求"按钮
|
||||
|
||||
#### 分析结果卡片
|
||||
- 基本信息：功能名称、类型等
|
||||
- 字段列表：表格展示
|
||||
- 操作按钮：重新分析、生成配置
|
||||
|
||||
#### 配置方案卡片
|
||||
- SQL 预览：只读文本框
|
||||
- 操作按钮：返回修改、确认执行
|
||||
|
||||
#### 执行结果卡片
|
||||
- 成功/失败图标
|
||||
- 详细消息
|
||||
- "创建新功能"按钮
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 1. 需求描述建议
|
||||
|
||||
**✅ 好的描述:**
|
||||
- 清晰说明功能目的
|
||||
- 列出主要字段
|
||||
- 说明特殊需求
|
||||
|
||||
**示例:**
|
||||
```
|
||||
创建一个库存预警设置页面，包含物料编码、物料名称、安全库存、预警阈值，
|
||||
当库存低于预警阈值时自动标记为红色
|
||||
```
|
||||
|
||||
**❌ 不好的描述:**
|
||||
```
|
||||
做一个库存页面
|
||||
```
|
||||
（太模糊，缺少关键信息）
|
||||
|
||||
### 2. 检查分析结果
|
||||
|
||||
在生成配置前，务必检查：
|
||||
- ✅ 功能名称是否正确
|
||||
- ✅ 字段是否完整
|
||||
- ✅ 字段类型是否合理
|
||||
- ✅ 必填项标记是否正确
|
||||
|
||||
如有问题，点击"重新分析"修改需求。
|
||||
|
||||
### 3. SQL 审查
|
||||
|
||||
执行前必须检查：
|
||||
- ✅ 表名是否合理
|
||||
- ✅ 字段名是否符合规范
|
||||
- ✅ 数据类型是否正确
|
||||
- ✅ 外键关联是否正确
|
||||
|
||||
### 4. 数据库备份
|
||||
|
||||
**强烈建议：**
|
||||
- 在生产环境执行前备份数据库
|
||||
- 先在测试环境验证
|
||||
- 记录执行的 SQL 语句
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### 问题 1: 分析需求超时
|
||||
|
||||
**现象:** 点击按钮后一直加载
|
||||
|
||||
**可能原因:**
|
||||
- Claude API 响应慢
|
||||
- 网络连接问题
|
||||
- API Key 无效
|
||||
|
||||
**解决方案:**
|
||||
1. 检查网络连接
|
||||
2. 验证 `ANTHROPIC_API_KEY` 是否有效
|
||||
3. 查看后端日志：`tail -f backend/logs/app.log`
|
||||
4. 尝试更简单的需求
|
||||
|
||||
### 问题 2: 数据库执行失败
|
||||
|
||||
**现象:** 执行配置时显示失败
|
||||
|
||||
**可能原因:**
|
||||
- 数据库连接失败
|
||||
- SQL 语法错误
|
||||
- 权限不足
|
||||
- 表已存在
|
||||
|
||||
**解决方案:**
|
||||
1. 检查 `.env` 数据库配置
|
||||
2. 确认数据库服务运行中
|
||||
3. 检查 SQL Server 日志
|
||||
4. 使用数据库管理工具测试 SQL
|
||||
|
||||
### 问题 3: 前端无法连接后端
|
||||
|
||||
**现象:** 前端显示网络错误
|
||||
|
||||
**解决方案:**
|
||||
1. 确认后端已启动：访问 http://localhost:8000/health
|
||||
2. 检查前端代理配置：`frontend/vite.config.js`
|
||||
3. 查看浏览器控制台网络请求
|
||||
4. 确认 CORS 配置：后端 `DEBUG=True`
|
||||
|
||||
### 问题 4: 分析结果不准确
|
||||
|
||||
**现象:** 生成的字段或类型不符合预期
|
||||
|
||||
**解决方案:**
|
||||
- 更详细地描述需求
|
||||
- 在需求中明确字段类型
|
||||
- 使用更具体的业务术语
|
||||
- 多次尝试不同的描述方式
|
||||
|
||||
## 📚 进阶使用
|
||||
|
||||
### 自定义 API 端点
|
||||
|
||||
如需使用代理或自托管服务：
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ANTHROPIC_BASE_URL=https://your-proxy.com/v1
|
||||
```
|
||||
|
||||
参考 [Claude API 配置指南](./CLAUDE_API_CONFIG.md)
|
||||
|
||||
### 局域网访问
|
||||
|
||||
团队成员可通过局域网访问：
|
||||
|
||||
```bash
|
||||
# 查看服务器 IP
|
||||
ipconfig # Windows
|
||||
ifconfig # Linux/Mac
|
||||
|
||||
# 其他设备访问
|
||||
http://192.168.1.100:5173
|
||||
```
|
||||
|
||||
参考 [局域网访问配置](./LAN_ACCESS.md)
|
||||
|
||||
### 查看历史记录
|
||||
|
||||
"历史记录"页面（即将推出）:
|
||||
- 查看所有执行记录
|
||||
- 重新执行历史配置
|
||||
- 导出配置方案
|
||||
|
||||
## 🎓 最佳实践
|
||||
|
||||
### 1. 开发流程
|
||||
|
||||
```
|
||||
需求分析 → 代码评审 → 测试环境验证 → 生产环境执行
|
||||
```
|
||||
|
||||
### 2. 命名规范
|
||||
|
||||
建议在需求中说明：
|
||||
- 功能号格式：`模块-序号` (如：`11-001`)
|
||||
- 表名前缀：业务含义 (如：`SA_` 销售)
|
||||
- 字段名：有意义的英文
|
||||
|
||||
### 3. 版本管理
|
||||
|
||||
使用 Git 记录配置变更：
|
||||
|
||||
```bash
|
||||
# 执行成功后
|
||||
git add .
|
||||
git commit -m "feat: add 销售订单管理功能"
|
||||
```
|
||||
|
||||
### 4. 团队协作
|
||||
|
||||
- 使用相同的测试数据库
|
||||
- 共享需求模板
|
||||
- 定期同步配置规范
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
遇到问题时：
|
||||
|
||||
1. 📖 查看本文档
|
||||
2. 🔍 检查日志文件
|
||||
3. 📋 查看后端 API 文档: http://localhost:8000/docs
|
||||
4. 💬 联系项目负责人
|
||||
|
||||
---
|
||||
|
||||
**祝您使用愉快！🎉**
|
||||
Reference in New Issue
Block a user