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:
146
docs/CLAUDE_API_CONFIG.md
Normal file
146
docs/CLAUDE_API_CONFIG.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Claude API 配置指南
|
||||
|
||||
## 概述
|
||||
|
||||
本项目支持自定义 Anthropic API 的 base URL，允许您使用代理服务或自托管服务。
|
||||
|
||||
## 配置方法
|
||||
|
||||
### 1. 使用官方 Anthropic API（默认）
|
||||
|
||||
在 `.env` 文件中配置：
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=your-api-key-here
|
||||
# 不需要设置 ANTHROPIC_BASE_URL，将自动使用官方 API
|
||||
```
|
||||
|
||||
### 2. 使用代理服务
|
||||
|
||||
如果您使用代理服务（例如 OpenRouter、AWS Bedrock 代理等），配置如下：
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=your-api-key-here
|
||||
ANTHROPIC_BASE_URL=https://your-proxy-service.com/v1
|
||||
```
|
||||
|
||||
### 3. 使用自托管服务
|
||||
|
||||
如果您部署了自托管的 Claude API 兼容服务：
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=your-custom-key
|
||||
ANTHROPIC_BASE_URL=http://localhost:8080/v1
|
||||
```
|
||||
|
||||
## 配置参数说明
|
||||
|
||||
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `ANTHROPIC_API_KEY` | string | ✅ 是 | - | Anthropic API 密钥或自定义密钥 |
|
||||
| `ANTHROPIC_BASE_URL` | string | ❌ 否 | `None` | 自定义 API 端点 URL |
|
||||
| `CLAUDE_MODEL` | string | ❌ 否 | `claude-sonnet-4-6` | 使用的模型名称 |
|
||||
| `CLAUDE_MAX_TOKENS` | int | ❌ 否 | `8192` | 最大生成 token 数 |
|
||||
| `CLAUDE_TEMPERATURE` | float | ❌ 否 | `0.7` | 生成温度（0-2） |
|
||||
|
||||
## 支持的代理服务示例
|
||||
|
||||
### OpenRouter
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=sk-or-xxx
|
||||
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
|
||||
CLAUDE_MODEL=anthropic/claude-sonnet-4-6
|
||||
```
|
||||
|
||||
### AWS Bedrock (通过代理)
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=your-aws-key
|
||||
ANTHROPIC_BASE_URL=https://bedrock.us-east-1.amazonaws.com
|
||||
CLAUDE_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
|
||||
```
|
||||
|
||||
### Azure OpenAI (Claude 兼容)
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=your-azure-key
|
||||
ANTHROPIC_BASE_URL=https://your-resource.openai.azure.com
|
||||
CLAUDE_MODEL=claude-sonnet-4-6
|
||||
```
|
||||
|
||||
## 代码实现
|
||||
|
||||
配置在以下文件中实现：
|
||||
|
||||
1. **配置定义**: `backend/app/config.py`
|
||||
```python
|
||||
ANTHROPIC_BASE_URL: str | None = None # Optional custom base URL
|
||||
```
|
||||
|
||||
2. **API 客户端初始化**: `backend/app/core/ai_engine.py`
|
||||
```python
|
||||
client_kwargs = {"api_key": settings.ANTHROPIC_API_KEY}
|
||||
if settings.ANTHROPIC_BASE_URL:
|
||||
client_kwargs["base_url"] = settings.ANTHROPIC_BASE_URL
|
||||
self.client = anthropic.AsyncAnthropic(**client_kwargs)
|
||||
```
|
||||
|
||||
## 验证配置
|
||||
|
||||
启动后端服务后，检查日志输出：
|
||||
|
||||
```
|
||||
[INFO] Using custom Anthropic base URL: https://your-proxy.com
|
||||
```
|
||||
|
||||
如果看到此日志，说明自定义 base URL 已生效。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题 1: 连接超时
|
||||
|
||||
**症状**: API 调用超时或连接失败
|
||||
|
||||
**解决方案**:
|
||||
- 检查 `ANTHROPIC_BASE_URL` 是否正确
|
||||
- 确认代理服务可访问
|
||||
- 检查网络防火墙设置
|
||||
|
||||
### 问题 2: 认证失败
|
||||
|
||||
**症状**: 401 Unauthorized 错误
|
||||
|
||||
**解决方案**:
|
||||
- 验证 `ANTHROPIC_API_KEY` 是否正确
|
||||
- 确认代理服务的认证方式
|
||||
- 检查 API key 是否有权限访问指定模型
|
||||
|
||||
### 问题 3: 模型不存在
|
||||
|
||||
**症状**: 404 Not Found - Model not found
|
||||
|
||||
**解决方案**:
|
||||
- 确认代理服务支持您指定的 `CLAUDE_MODEL`
|
||||
- 检查模型名称格式（不同服务可能使用不同的命名）
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **不要提交 `.env` 文件到 Git**
|
||||
- `.env` 文件已在 `.gitignore` 中
|
||||
- 只提交 `.env.example` 模板
|
||||
|
||||
2. **生产环境配置**
|
||||
- 使用环境变量或密钥管理服务
|
||||
- 不要在代码中硬编码 API key
|
||||
|
||||
3. **API Key 权限**
|
||||
- 使用最小权限原则
|
||||
- 定期轮换 API key
|
||||
- 监控 API 使用情况
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Anthropic API 文档](https://docs.anthropic.com/)
|
||||
- [OpenRouter 文档](https://openrouter.ai/docs)
|
||||
- [项目 README](./README.md)
|
||||
288
docs/DEPENDENCY_FIXES.md
Normal file
288
docs/DEPENDENCY_FIXES.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 依赖问题修复指南
|
||||
|
||||
## 🐛 已知问题及解决方案
|
||||
|
||||
### 问题 1: NumPy 2.0 兼容性错误 ✅ 已修复
|
||||
|
||||
**错误信息:**
|
||||
```
|
||||
AttributeError: `np.float_` was removed in the NumPy 2.0 release. Use `np.float64` instead.
|
||||
```
|
||||
|
||||
**原因:**
|
||||
- ChromaDB 0.4.18 依赖旧版 NumPy API
|
||||
- NumPy 2.0 移除了 `np.float_` 等类型别名
|
||||
- 版本冲突导致运行失败
|
||||
|
||||
**解决方案:**
|
||||
已在 `requirements.txt` 中添加约束：
|
||||
```txt
|
||||
numpy<2.0.0
|
||||
```
|
||||
|
||||
### 问题 2: Sentence-Transformers 与 HuggingFace Hub 不兼容 ✅ 已修复
|
||||
|
||||
**错误信息:**
|
||||
```
|
||||
ImportError: cannot import name 'cached_download' from 'huggingface_hub'
|
||||
```
|
||||
|
||||
**原因:**
|
||||
- sentence-transformers 2.2.2 使用了已弃用的 `cached_download` API
|
||||
- 新版 huggingface_hub 移除了该 API
|
||||
|
||||
**解决方案:**
|
||||
已升级到兼容版本：
|
||||
```txt
|
||||
sentence-transformers==2.7.0 # 从 2.2.2 升级
|
||||
```
|
||||
|
||||
**修复步骤:**
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# 卸载当前 numpy
|
||||
pip uninstall numpy -y
|
||||
|
||||
# 重新安装依赖（会安装 numpy 1.x）
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 验证 numpy 版本
|
||||
python -c "import numpy; print(numpy.__version__)"
|
||||
# 应输出: 1.x.x (小于 2.0)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 依赖版本说明
|
||||
|
||||
### 核心依赖版本
|
||||
|
||||
| 包名 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| numpy | < 2.0.0 | 降级以兼容 chromadb |
|
||||
| chromadb | 0.4.18 | 向量数据库 |
|
||||
| sentence-transformers | 2.2.2 | 文本嵌入模型 |
|
||||
| fastapi | 0.104.1 | Web 框架 |
|
||||
| anthropic | 0.18.1 | Claude API SDK |
|
||||
| pydantic | 2.5.0 | 数据验证 |
|
||||
|
||||
### 为什么锁定版本？
|
||||
|
||||
1. **兼容性保证**: 避免主版本升级引入破坏性更改
|
||||
2. **可重现构建**: 确保开发和生产环境一致
|
||||
3. **安全性**: 便于安全审计和漏洞修复
|
||||
|
||||
---
|
||||
|
||||
## 🔄 更新依赖
|
||||
|
||||
### 更新单个包
|
||||
|
||||
```bash
|
||||
pip install --upgrade package-name
|
||||
pip freeze > requirements.txt # 更新版本
|
||||
```
|
||||
|
||||
### 更新所有包（谨慎）
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
pip-review --auto # 需要 pip-review 工具
|
||||
```
|
||||
|
||||
### 安全更新
|
||||
|
||||
仅更新补丁版本（修复 bug 和安全漏洞）：
|
||||
```bash
|
||||
pip install --upgrade package-name==1.2.* # 保持在 1.2.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见依赖问题
|
||||
|
||||
### 问题 1: pip 安装超时
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 使用国内镜像
|
||||
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
|
||||
# 或配置全局镜像
|
||||
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
```
|
||||
|
||||
### 问题 2: pyodbc 安装失败
|
||||
|
||||
**原因:** 缺少 ODBC 驱动开发包
|
||||
|
||||
**解决方案:**
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt-get install unixodbc-dev
|
||||
pip install pyodbc
|
||||
```
|
||||
|
||||
**CentOS/RHEL:**
|
||||
```bash
|
||||
sudo yum install unixODBC-devel
|
||||
pip install pyodbc
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
无需额外操作，直接安装即可。
|
||||
|
||||
### 问题 3: sentence-transformers 下载模型慢
|
||||
|
||||
**原因:** HuggingFace 模型下载速度慢
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 使用镜像站
|
||||
export HF_ENDPOINT=https://hf-mirror.com
|
||||
|
||||
# 或在 Python 代码中设置
|
||||
import os
|
||||
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
|
||||
```
|
||||
|
||||
### 问题 4: ChromaDB 初始化错误
|
||||
|
||||
**可能原因:**
|
||||
- 权限问题
|
||||
- SQLite 版本过低
|
||||
- 磁盘空间不足
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 检查目录权限
|
||||
chmod -R 755 backend/knowledge_base/
|
||||
|
||||
# 检查 SQLite 版本（需要 >= 3.35.0）
|
||||
python -c "import sqlite3; print(sqlite3.sqlite_version)"
|
||||
|
||||
# 清理并重新初始化
|
||||
rm -rf backend/knowledge_base/chroma_db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 依赖诊断命令
|
||||
|
||||
### 检查已安装版本
|
||||
|
||||
```bash
|
||||
# 列出所有包
|
||||
pip list
|
||||
|
||||
# 查看特定包信息
|
||||
pip show numpy
|
||||
|
||||
# 检查过时的包
|
||||
pip list --outdated
|
||||
|
||||
# 检查安全漏洞
|
||||
pip audit # 需要 pip-audit 工具
|
||||
```
|
||||
|
||||
### 依赖树分析
|
||||
|
||||
```bash
|
||||
# 安装 pipdeptree
|
||||
pip install pipdeptree
|
||||
|
||||
# 查看依赖树
|
||||
pipdeptree
|
||||
|
||||
# 查看反向依赖（谁依赖了这个包）
|
||||
pipdeptree -r -p numpy
|
||||
```
|
||||
|
||||
### 冲突检测
|
||||
|
||||
```bash
|
||||
# 检查依赖冲突
|
||||
pip check
|
||||
|
||||
# 查看版本约束
|
||||
pip-compile --dry-run requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 最佳实践
|
||||
|
||||
### 1. 使用虚拟环境
|
||||
|
||||
```bash
|
||||
# 创建虚拟环境
|
||||
python3 -m venv venv
|
||||
|
||||
# 激活虚拟环境
|
||||
source venv/bin/activate # Linux/Mac
|
||||
venv\Scripts\activate # Windows
|
||||
|
||||
# 确认使用虚拟环境
|
||||
which python # Linux/Mac
|
||||
where python # Windows
|
||||
```
|
||||
|
||||
### 2. 定期更新依赖
|
||||
|
||||
```bash
|
||||
# 每月检查更新
|
||||
pip list --outdated
|
||||
|
||||
# 更新前查看变更日志
|
||||
pip install --upgrade package-name --dry-run
|
||||
```
|
||||
|
||||
### 3. 锁定依赖版本
|
||||
|
||||
```bash
|
||||
# 生成精确版本
|
||||
pip freeze > requirements.txt
|
||||
|
||||
# 或使用 pip-tools
|
||||
pip-compile requirements.in
|
||||
```
|
||||
|
||||
### 4. 分离开发和生产依赖
|
||||
|
||||
创建 `requirements-dev.txt`:
|
||||
```txt
|
||||
-r requirements.txt
|
||||
|
||||
pytest==7.4.3
|
||||
pytest-asyncio==0.21.1
|
||||
pytest-cov==4.1.0
|
||||
pytest-mock==3.12.0
|
||||
httpx==0.25.2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 依赖问题排查流程
|
||||
|
||||
1. **确认错误信息** → 找到具体的包名和错误类型
|
||||
2. **检查版本冲突** → `pip check`
|
||||
3. **查看依赖关系** → `pipdeptree -r -p package-name`
|
||||
4. **搜索已知问题** → GitHub Issues / Stack Overflow
|
||||
5. **尝试降级/升级** → 调整版本约束
|
||||
6. **清理重新安装** → `pip cache purge && pip install -r requirements.txt`
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [NumPy 2.0 迁移指南](https://numpy.org/doc/stable/numpy_2_0_migration_guide.html)
|
||||
- [ChromaDB 文档](https://docs.trychroma.com/)
|
||||
- [Python 依赖管理最佳实践](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
|
||||
|
||||
---
|
||||
|
||||
**更新时间**: 2026-03-21
|
||||
**适用版本**: v1.0.0+
|
||||
236
docs/FRONTEND_UPDATE.md
Normal file
236
docs/FRONTEND_UPDATE.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# 前端功能完善说明
|
||||
|
||||
## 🎉 已完成的功能
|
||||
|
||||
### 1. 完整的工作流程
|
||||
|
||||
前端现在支持完整的三个步骤工作流程：
|
||||
|
||||
**步骤 1: 需求分析**
|
||||
- 输入自然语言需求
|
||||
- 调用后端 `/api/v1/analyze` 接口
|
||||
- 展示结构化的分析结果
|
||||
|
||||
**步骤 2: 配置生成**
|
||||
- 基于分析结果生成 SQL 配置
|
||||
- 调用后端 `/api/v1/generate` 接口
|
||||
- 展示 SQL 配置语句（只读预览）
|
||||
|
||||
**步骤 3: 执行配置**
|
||||
- 确认对话框（带安全警告）
|
||||
- 调用后端 `/api/v1/execute` 接口
|
||||
- 展示执行结果（成功/失败）
|
||||
|
||||
### 2. 新增功能组件
|
||||
|
||||
#### 📦 API 服务 (`frontend/src/api/index.js`)
|
||||
|
||||
封装了三个核心 API 调用：
|
||||
```javascript
|
||||
analyzeRequirement(data) // 分析需求
|
||||
generateConfig(data) // 生成配置
|
||||
executeConfig(data) // 执行配置
|
||||
```
|
||||
|
||||
#### 🗃️ 状态管理 (`frontend/src/stores/function.js`)
|
||||
|
||||
使用 Pinia 管理全局状态：
|
||||
- `currentSession`: 当前会话 ID
|
||||
- `analysisResult`: 需求分析结果
|
||||
- `configResult`: 配置生成结果
|
||||
- `executeResult`: 执行结果
|
||||
- `loading`: 各步骤加载状态
|
||||
|
||||
#### 🎨 UI 组件增强 (`frontend/src/views/CreateFunction.vue`)
|
||||
|
||||
**步骤指示器:**
|
||||
- 清晰展示当前进度
|
||||
- 三步流程可视化
|
||||
|
||||
**需求分析结果展示:**
|
||||
- 使用 `el-descriptions` 展示基本信息
|
||||
- 使用 `el-table` 展示字段列表
|
||||
- 支持标签显示（功能类型、必填项等）
|
||||
|
||||
**SQL 配置预览:**
|
||||
- 使用等宽字体显示 SQL
|
||||
- 15 行高度文本框
|
||||
- 只读模式，防止误修改
|
||||
|
||||
**执行确认对话框:**
|
||||
- 醒目的安全警告
|
||||
- 列出注意事项
|
||||
- 确认/取消按钮
|
||||
|
||||
**执行结果展示:**
|
||||
- 成功/失败状态图标
|
||||
- 详细消息展示
|
||||
- "创建新功能"按钮重新开始
|
||||
|
||||
### 3. 交互优化
|
||||
|
||||
✅ **加载状态**: 所有异步操作都有 loading 状态
|
||||
✅ **错误处理**: 友好的错误提示消息
|
||||
✅ **表单验证**: 必填项验证
|
||||
✅ **操作确认**: 危险操作二次确认
|
||||
✅ **状态重置**: 支持重新开始整个流程
|
||||
|
||||
## 📋 使用指南
|
||||
|
||||
### 启动前端服务
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 访问应用
|
||||
|
||||
- 本地: http://localhost:5173
|
||||
- 局域网: http://192.168.1.100:5173
|
||||
|
||||
### 完整操作流程
|
||||
|
||||
1. **输入需求**
|
||||
```
|
||||
创建一个销售订单管理页面，包含订单号、客户、订单日期、金额字段
|
||||
```
|
||||
|
||||
2. **点击"开始分析需求"**
|
||||
- 等待 1-3 秒（取决于 Claude API 响应时间）
|
||||
- 查看分析结果（功能名称、类型、字段等）
|
||||
|
||||
3. **点击"生成配置方案"**
|
||||
- 等待 AI 生成 SQL 配置
|
||||
- 仔细检查 SQL 语句
|
||||
|
||||
4. **点击"确认并执行"**
|
||||
- 阅读安全警告
|
||||
- 点击"确认执行"按钮
|
||||
- 查看执行结果
|
||||
|
||||
5. **完成**
|
||||
- 成功: 显示成功消息
|
||||
- 失败: 显示错误详情
|
||||
|
||||
## 🔧 技术实现
|
||||
|
||||
### 状态管理流程
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
分析需求 → 保存 analysisResult + sessionId
|
||||
↓
|
||||
生成配置 → 保存 configResult (包含 SQL)
|
||||
↓
|
||||
执行配置 → 保存 executeResult (成功/失败)
|
||||
```
|
||||
|
||||
### API 调用示例
|
||||
|
||||
```javascript
|
||||
// 1. 分析需求
|
||||
const analyzeResult = await analyzeRequirement({
|
||||
content: '创建销售订单管理页面',
|
||||
session_id: null // 后端自动生成
|
||||
})
|
||||
|
||||
// 2. 生成配置
|
||||
const configResult = await generateConfig({
|
||||
session_id: analyzeResult.session_id,
|
||||
requirements: analyzeResult.data
|
||||
})
|
||||
|
||||
// 3. 执行配置
|
||||
const executeResult = await executeConfig({
|
||||
session_id: analyzeResult.session_id,
|
||||
confirmed: true,
|
||||
backup_enabled: true
|
||||
})
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 1. 后端必须先启动
|
||||
|
||||
前端依赖后端 API，请确保：
|
||||
```bash
|
||||
cd backend
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
### 2. 环境配置
|
||||
|
||||
确保后端 `.env` 已配置：
|
||||
- `ANTHROPIC_API_KEY`: Claude API 密钥
|
||||
- `DB_*`: 数据库连接信息
|
||||
|
||||
### 3. 测试数据
|
||||
|
||||
首次测试建议使用简单的需求：
|
||||
```
|
||||
创建一个简单的用户管理页面
|
||||
```
|
||||
|
||||
### 4. 跨域问题
|
||||
|
||||
开发环境已配置 CORS：
|
||||
- 后端允许所有来源 (`DEBUG=True`)
|
||||
- 前端代理 `/api` 到后端
|
||||
|
||||
## 🐛 已知问题
|
||||
|
||||
### 问题 1: API 超时
|
||||
|
||||
**现象**: 分析需求时超时
|
||||
|
||||
**原因**: Claude API 响应慢或网络问题
|
||||
|
||||
**解决**:
|
||||
- 检查网络连接
|
||||
- 确认 API Key 有效
|
||||
- 查看后端日志
|
||||
|
||||
### 问题 2: 数据库连接失败
|
||||
|
||||
**现象**: 执行配置失败
|
||||
|
||||
**原因**: 数据库配置错误或服务未启动
|
||||
|
||||
**解决**:
|
||||
- 检查 `.env` 数据库配置
|
||||
- 确认 SQL Server 运行中
|
||||
- 测试数据库连接
|
||||
|
||||
## 🚀 后续优化建议
|
||||
|
||||
### 功能增强
|
||||
- [ ] SQL 语法高亮
|
||||
- [ ] 配置导出功能
|
||||
- [ ] 历史记录查看
|
||||
- [ ] 配置模板库
|
||||
- [ ] 批量操作
|
||||
|
||||
### UI/UX 优化
|
||||
- [ ] 深色模式
|
||||
- [ ] 响应式布局优化
|
||||
- [ ] 加载动画优化
|
||||
- [ ] 快捷键支持
|
||||
|
||||
### 性能优化
|
||||
- [ ] API 响应缓存
|
||||
- [ ] 长文本虚拟滚动
|
||||
- [ ] 懒加载优化
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [后端 API 文档](http://localhost:8000/docs)
|
||||
- [局域网访问配置](./LAN_ACCESS.md)
|
||||
- [依赖问题修复](./DEPENDENCY_FIXES.md)
|
||||
|
||||
---
|
||||
|
||||
**更新时间**: 2026-03-21
|
||||
**版本**: v1.1.0
|
||||
266
docs/GIT_GUIDE.md
Normal file
266
docs/GIT_GUIDE.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Git 操作指南 - 撤回和重新添加文件
|
||||
|
||||
## ✅ 已完成的操作
|
||||
|
||||
### 1. 撤回暂存区
|
||||
|
||||
已执行 `git reset` 命令，清空了暂存区的所有文件。
|
||||
|
||||
## 📝 修改的 .gitignore
|
||||
|
||||
已在 `.gitignore` 中添加以下规则：
|
||||
|
||||
```gitignore
|
||||
# Project specific - 忽略知识库文档
|
||||
backend/knowledge_base/documents/*.docx
|
||||
backend/knowledge_base/documents/*.xlsx
|
||||
backend/knowledge_base/documents/*.pdf
|
||||
backend/knowledge_base/documents/*.pptx
|
||||
backend/knowledge_base/documents/*.vsdx
|
||||
backend/knowledge_base/documents/*.xls
|
||||
|
||||
# Temporary files - 忽略临时文件
|
||||
*.tmp
|
||||
*.temp
|
||||
*.bak
|
||||
*.swp
|
||||
*~
|
||||
|
||||
# Archives - 忽略压缩包
|
||||
*.zip
|
||||
*.tar.gz
|
||||
*.rar
|
||||
*.7z
|
||||
```
|
||||
|
||||
## 🔍 下一步操作
|
||||
|
||||
### 1. 查看将要提交的文件
|
||||
|
||||
先查看哪些文件会被添加：
|
||||
|
||||
```bash
|
||||
# 查看所有未跟踪的文件
|
||||
git status
|
||||
|
||||
# 或者更详细地查看
|
||||
git status --short
|
||||
```
|
||||
|
||||
### 2. 重新添加文件
|
||||
|
||||
确认文件列表无误后：
|
||||
|
||||
```bash
|
||||
# 方式 1: 添加所有文件（推荐）
|
||||
git add .
|
||||
|
||||
# 方式 2: 逐个添加文件类型（更安全）
|
||||
git add backend/app/
|
||||
git add backend/tests/
|
||||
git add backend/*.txt backend/*.ini
|
||||
git add backend/.env.example
|
||||
git add frontend/src/
|
||||
git add frontend/*.json frontend/*.js frontend/*.html
|
||||
git add *.md .gitignore
|
||||
```
|
||||
|
||||
### 3. 检查暂存区
|
||||
|
||||
添加后再次检查：
|
||||
|
||||
```bash
|
||||
# 查看暂存区状态
|
||||
git status
|
||||
|
||||
# 查看暂存区的文件列表
|
||||
git diff --cached --name-only
|
||||
|
||||
# 查看具体改动
|
||||
git diff --cached
|
||||
```
|
||||
|
||||
### 4. 提交
|
||||
|
||||
确认无误后提交：
|
||||
|
||||
```bash
|
||||
git commit -m "feat: implement ERP AI Assistant Phase 1
|
||||
|
||||
- Backend: FastAPI + SQLAlchemy + Claude API + RAG
|
||||
- Frontend: Vue 3 + Element Plus + Pinia
|
||||
- Features: requirement analysis, config generation, safe execution
|
||||
- Security: SQL injection prevention, parameterized queries
|
||||
- Support: LAN access, custom API endpoint"
|
||||
```
|
||||
|
||||
## 🎯 建议忽略的文件
|
||||
|
||||
如果发现还有其他不需要提交的文件，可以在 `.gitignore` 中添加：
|
||||
|
||||
### 常见需要忽略的文件类型
|
||||
|
||||
```gitignore
|
||||
# 大文件
|
||||
*.dmg
|
||||
*.iso
|
||||
*.img
|
||||
|
||||
# 编译产物
|
||||
*.class
|
||||
*.exe
|
||||
*.dll
|
||||
*.so
|
||||
*.dylib
|
||||
|
||||
# 包文件
|
||||
*.jar
|
||||
*.war
|
||||
*.ear
|
||||
|
||||
# 日志文件
|
||||
logs/
|
||||
*.log
|
||||
|
||||
# 数据文件
|
||||
*.csv
|
||||
*.dat
|
||||
*.out
|
||||
|
||||
# 模型文件（如果很大的话）
|
||||
*.model
|
||||
*.pkl
|
||||
*.h5
|
||||
*.pt
|
||||
*.pth
|
||||
```
|
||||
|
||||
### 项目特定的忽略规则
|
||||
|
||||
```gitignore
|
||||
# 知识库向量数据库（可能很大）
|
||||
backend/knowledge_base/chroma_db/
|
||||
|
||||
# 用户上传的文档
|
||||
backend/knowledge_base/documents/
|
||||
|
||||
# 测试覆盖率报告
|
||||
htmlcov/
|
||||
.coverage
|
||||
|
||||
# 本地配置
|
||||
.env.local
|
||||
.env.*.local
|
||||
```
|
||||
|
||||
## 🔧 Git 常用命令
|
||||
|
||||
### 撤回操作
|
||||
|
||||
```bash
|
||||
# 撤回所有已 add 的文件
|
||||
git reset
|
||||
|
||||
# 撤回特定文件
|
||||
git reset <file>
|
||||
|
||||
# 撤回最近一次 commit（保留修改）
|
||||
git reset --soft HEAD~1
|
||||
|
||||
# 撤回最近一次 commit（丢弃修改，慎用）
|
||||
git reset --hard HEAD~1
|
||||
```
|
||||
|
||||
### 查看状态
|
||||
|
||||
```bash
|
||||
# 查看当前状态
|
||||
git status
|
||||
|
||||
# 查看简洁状态
|
||||
git status -s
|
||||
|
||||
# 查看分支信息
|
||||
git branch -a
|
||||
|
||||
# 查看提交历史
|
||||
git log --oneline --graph
|
||||
```
|
||||
|
||||
### 删除已跟踪的文件
|
||||
|
||||
如果某个文件已经被 git 跟踪，想要从版本控制中移除：
|
||||
|
||||
```bash
|
||||
# 从 Git 中移除但保留本地文件
|
||||
git rm --cached <file>
|
||||
|
||||
# 从 Git 和本地都删除
|
||||
git rm <file>
|
||||
|
||||
# 从 Git 中移除整个文件夹
|
||||
git rm -r --cached <directory>
|
||||
```
|
||||
|
||||
## 📋 快速检查清单
|
||||
|
||||
提交前检查：
|
||||
|
||||
- [ ] 是否包含 `.env` 文件？（不应包含）
|
||||
- [ ] 是否包含 `venv/` 或 `node_modules/`？（不应包含）
|
||||
- [ ] 是否包含大文件？（不应包含）
|
||||
- [ ] 是否包含临时文件？（不应包含）
|
||||
- [ ] 是否包含日志文件？（不应包含）
|
||||
- [ ] 是否包含个人配置？（不应包含）
|
||||
|
||||
## 🚨 常见问题
|
||||
|
||||
### 问题 1: 文件已经在 .gitignore 中，但仍然被跟踪
|
||||
|
||||
**原因**: 文件在添加 .gitignore 规则之前就已经被 git 跟踪了
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 从 Git 中移除但保留本地文件
|
||||
git rm --cached <file>
|
||||
|
||||
# 然后提交
|
||||
git commit -m "chore: remove tracked file from version control"
|
||||
```
|
||||
|
||||
### 问题 2: 添加了不该添加的文件
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 1. 撤回添加
|
||||
git reset
|
||||
|
||||
# 2. 更新 .gitignore
|
||||
|
||||
# 3. 重新添加
|
||||
git add .
|
||||
```
|
||||
|
||||
### 问题 3: 如何只提交特定文件
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 只提交代码文件
|
||||
git add *.py *.vue *.js
|
||||
|
||||
# 只提交特定目录
|
||||
git add backend/app/ frontend/src/
|
||||
|
||||
# 交互式添加
|
||||
git add -p
|
||||
```
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [Git 官方文档](https://git-scm.com/doc)
|
||||
- [.gitignore 模板集合](https://github.com/github/gitignore)
|
||||
- [Git Flow 工作流](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
|
||||
|
||||
---
|
||||
|
||||
**更新时间**: 2026-03-21
|
||||
289
docs/IMPLEMENTATION_REPORT.md
Normal file
289
docs/IMPLEMENTATION_REPORT.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# ERP AI Assistant - Phase 1 实施完成报告
|
||||
|
||||
## 📋 项目概述
|
||||
|
||||
已完成 Phase 1 的所有核心任务，建立了 ERP AI 助手的基础架构和核心功能。
|
||||
|
||||
## ✅ 已完成任务
|
||||
|
||||
### 后端基础设施 (Tasks 1-7)
|
||||
|
||||
1. **项目初始化和配置管理** ✓
|
||||
- 创建 `backend/requirements.txt` - 所有 Python 依赖
|
||||
- 创建 `backend/.env.example` - 环境变量模板
|
||||
- 创建 `backend/app/config.py` - Pydantic v2 配置管理
|
||||
- 实现配置验证和安全编码
|
||||
|
||||
2. **Pytest 配置和测试基础设施** ✓
|
||||
- 创建 `backend/pytest.ini` - pytest 配置
|
||||
- 创建 `backend/tests/conftest.py` - 测试固件和 mocks
|
||||
- 配置 asyncio 支持和覆盖率报告
|
||||
|
||||
3. **数据库引擎实现** ✓
|
||||
- 创建 `backend/app/core/db_engine.py`
|
||||
- 实现连接池管理 (pool_size=20, max_overflow=10)
|
||||
- 实现上下文管理器会话管理
|
||||
- **安全加固**: 使用参数化查询防止 SQL 注入
|
||||
|
||||
4. **AI 引擎基础实现** ✓
|
||||
- 创建 `backend/app/core/ai_engine.py`
|
||||
- 集成 Claude API (Anthropic SDK)
|
||||
- 实现 JSON 响应解析（支持纯 JSON、markdown 代码块、{} 块）
|
||||
|
||||
5. **Prompt 模板设计** ✓
|
||||
- 创建 `backend/app/core/prompts.py`
|
||||
- 定义系统 Prompt 和分析/生成模板
|
||||
|
||||
6. **RAG 引擎基础实现** ✓
|
||||
- 创建 `backend/app/core/rag_engine.py`
|
||||
- 集成 ChromaDB 向量数据库
|
||||
- 集成 sentence-transformers 嵌入模型
|
||||
- 实现文档分块、嵌入和语义搜索
|
||||
|
||||
7. **需求解析服务实现** ✓
|
||||
- 创建 `backend/app/services/requirement_service.py`
|
||||
- 整合 AI 引擎 + RAG 引擎 + 数据库引擎
|
||||
- 实现需求分析流程（知识检索 → 表结构查询 → AI 分析）
|
||||
|
||||
8. **执行引擎实现** ✓
|
||||
- 创建 `backend/app/core/executor.py`
|
||||
- 实现 SQL 安全验证（拦截 DROP/TRUNCATE/DELETE 等）
|
||||
- 实现事务执行和错误处理
|
||||
|
||||
### API 层实现 (Tasks 8-10)
|
||||
|
||||
9. **API 基础结构** ✓
|
||||
- 创建 `backend/app/models/request.py` - 请求模型
|
||||
- 创建 `backend/app/models/response.py` - 响应模型
|
||||
- 创建 `backend/app/main.py` - FastAPI 应用入口
|
||||
- 配置 CORS 中间件
|
||||
|
||||
10. **需求解析 API** ✓
|
||||
- 创建 `backend/app/api/analyze.py`
|
||||
- POST `/api/v1/analyze` - 分析用户需求
|
||||
|
||||
### 前端实现 (Tasks 11-12)
|
||||
|
||||
11. **前端项目初始化** ✓
|
||||
- 创建 `frontend/package.json` - Vue 3 + Vite
|
||||
- 创建 `frontend/vite.config.js` - 开发服务器和代理配置
|
||||
- 创建 `frontend/src/main.js` - 应用入口
|
||||
- 创建 `frontend/src/App.vue` - 根组件
|
||||
|
||||
12. **前端路由和布局** ✓
|
||||
- 创建 `frontend/src/router/index.js` - 路由配置
|
||||
- 创建 `frontend/src/views/Layout.vue` - 主布局（侧边栏 + 头部）
|
||||
- 创建 `frontend/src/views/CreateFunction.vue` - 功能创建页面
|
||||
- 创建 `frontend/src/views/History.vue` - 历史记录页面
|
||||
|
||||
### 执行和配置服务 (Tasks 13-15)
|
||||
|
||||
13. **配置生成服务** ✓
|
||||
- 创建 `backend/app/services/config_service.py`
|
||||
- 创建 `backend/tests/test_config_service.py`
|
||||
- 实现基于需求的 SQL 配置生成
|
||||
|
||||
14. **执行配置 API** ✓
|
||||
- 创建 `backend/app/api/generate.py` - POST `/api/v1/generate`
|
||||
- 创建 `backend/app/api/execute.py` - POST `/api/v1/execute`
|
||||
- 更新 `backend/app/main.py` 注册路由
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
/data/erp-ass/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── api/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── analyze.py
|
||||
│ │ │ ├── generate.py
|
||||
│ │ │ └── execute.py
|
||||
│ │ ├── core/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── db_engine.py
|
||||
│ │ │ ├── ai_engine.py
|
||||
│ │ │ ├── prompts.py
|
||||
│ │ │ ├── rag_engine.py
|
||||
│ │ │ └── executor.py
|
||||
│ │ ├── models/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── request.py
|
||||
│ │ │ └── response.py
|
||||
│ │ ├── services/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── requirement_service.py
|
||||
│ │ │ └── config_service.py
|
||||
│ │ ├── config.py
|
||||
│ │ └── main.py
|
||||
│ ├── tests/
|
||||
│ │ ├── conftest.py
|
||||
│ │ ├── test_db_engine.py
|
||||
│ │ ├── test_ai_engine.py
|
||||
│ │ ├── test_prompts.py
|
||||
│ │ ├── test_rag_engine.py
|
||||
│ │ ├── test_requirement_service.py
|
||||
│ │ ├── test_config_service.py
|
||||
│ │ └── test_executor.py
|
||||
│ ├── knowledge_base/
|
||||
│ │ └── documents/
|
||||
│ ├── scripts/
|
||||
│ ├── requirements.txt
|
||||
│ ├── pytest.ini
|
||||
│ └── .env.example
|
||||
└── frontend/
|
||||
├── src/
|
||||
│ ├── router/
|
||||
│ │ └── index.js
|
||||
│ ├── views/
|
||||
│ │ ├── Layout.vue
|
||||
│ │ ├── CreateFunction.vue
|
||||
│ │ └── History.vue
|
||||
│ ├── main.js
|
||||
│ └── App.vue
|
||||
├── index.html
|
||||
├── vite.config.js
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## 🔐 安全特性
|
||||
|
||||
1. **SQL 注入防护**
|
||||
- 所有数据库查询使用参数化查询
|
||||
- 危险 SQL 操作拦截（DROP、TRUNCATE、DELETE without WHERE）
|
||||
|
||||
2. **配置安全**
|
||||
- 数据库密码 URL 编码（支持特殊字符）
|
||||
- 环境变量管理敏感信息
|
||||
- Pydantic 配置验证
|
||||
|
||||
3. **事务保护**
|
||||
- 自动提交/回滚机制
|
||||
- 上下文管理器管理会话
|
||||
|
||||
## 🚀 后续步骤
|
||||
|
||||
### 立即需要完成
|
||||
|
||||
1. **安装依赖**
|
||||
```bash
|
||||
cd backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
cd ../frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **配置环境变量**
|
||||
```bash
|
||||
cd backend
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，填入真实的数据库和 Claude API 配置
|
||||
```
|
||||
|
||||
3. **局域网访问配置** ✅ 已完成
|
||||
- 前端已配置 `host: '0.0.0.0'`
|
||||
- 后端已配置 `host="0.0.0.0"` 和 CORS 策略
|
||||
- 详细配置参考: [docs/LAN_ACCESS.md](LAN_ACCESS.md)
|
||||
|
||||
4. **初始化知识库**
|
||||
- 将平台文档放入 `backend/knowledge_base/documents/`
|
||||
- 运行知识库初始化脚本（需要创建）
|
||||
|
||||
5. **Git 版本控制**
|
||||
```bash
|
||||
git init
|
||||
git add .
|
||||
git commit -m "feat: implement Phase 1 - ERP AI Assistant foundation"
|
||||
```
|
||||
|
||||
### Phase 2 功能增强
|
||||
|
||||
1. **执行日志和审计系统**
|
||||
- 创建 ExecutionLog 数据模型
|
||||
- 实现审计服务记录所有操作
|
||||
- 前端展示执行历史
|
||||
|
||||
2. **数据库元数据 API**
|
||||
- 提供表结构查询接口
|
||||
- 支持智能表推荐
|
||||
|
||||
3. **知识库管理界面**
|
||||
- 文档上传和管理
|
||||
- 知识库更新和版本控制
|
||||
|
||||
4. **配置预览组件**
|
||||
- SQL 高亮显示
|
||||
- Monaco Editor 集成
|
||||
- 配置对比和修改
|
||||
|
||||
5. **执行监控组件**
|
||||
- 实时进度显示
|
||||
- 错误详情展示
|
||||
- 回滚功能实现
|
||||
|
||||
### Phase 3 高级功能
|
||||
|
||||
1. **错误排查系统**
|
||||
- SQL 日志监控
|
||||
- 智能错误诊断
|
||||
- 修复建议生成
|
||||
|
||||
2. **系统优化**
|
||||
- 性能分析
|
||||
- 缓存管理
|
||||
- 权限优化
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
1. **环境限制**
|
||||
- 当前环境无法执行 bash 命令（权限超时）
|
||||
- 需要手动执行依赖安装和测试
|
||||
|
||||
2. **数据库配置**
|
||||
- 需要 SQL Server 数据库连接
|
||||
- 确保数据库有 SYS_FORM、SYS_MENU 等系统表
|
||||
|
||||
3. **Claude API**
|
||||
- 需要有效的 Anthropic API Key
|
||||
- 推荐使用 `claude-sonnet-4-6` 模型
|
||||
|
||||
4. **测试覆盖**
|
||||
- 所有测试文件已创建
|
||||
- 使用 mock 避免真实 API 调用
|
||||
- 需要配置环境后运行集成测试
|
||||
|
||||
## 🎯 技术栈总结
|
||||
|
||||
**后端:**
|
||||
- Python 3.10+
|
||||
- FastAPI 0.104.1
|
||||
- SQLAlchemy 2.0.23
|
||||
- Anthropic SDK 0.18.1
|
||||
- ChromaDB 0.4.18
|
||||
- sentence-transformers 2.2.2
|
||||
- Pydantic 2.5.0
|
||||
|
||||
**前端:**
|
||||
- Vue 3.3.8
|
||||
- Vite 5.0.4
|
||||
- Vue Router 4.2.5
|
||||
- Pinia 2.1.7
|
||||
- Element Plus 2.4.3
|
||||
- Axios 1.6.2
|
||||
|
||||
**数据库:**
|
||||
- SQL Server (通过 pyodbc 5.0.1)
|
||||
- ChromaDB (向量数据库)
|
||||
|
||||
**AI 引擎:**
|
||||
- Claude Sonnet 4.6
|
||||
- all-MiniLM-L6-v2 (嵌入模型)
|
||||
|
||||
---
|
||||
|
||||
**实施日期:** 2026-03-21
|
||||
**完成状态:** Phase 1 全部完成 ✓
|
||||
**下一阶段:** Phase 2 - 功能增强
|
||||
319
docs/LAN_ACCESS.md
Normal file
319
docs/LAN_ACCESS.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 局域网访问配置指南
|
||||
|
||||
## 🌐 配置说明
|
||||
|
||||
本项目已配置支持局域网访问，允许团队在同一局域网内访问前端和后端服务。
|
||||
|
||||
## ✅ 已完成的配置
|
||||
|
||||
### 1. 前端配置 (Vite)
|
||||
|
||||
**文件**: `frontend/vite.config.js`
|
||||
|
||||
```javascript
|
||||
server: {
|
||||
host: '0.0.0.0', // 监听所有网络接口，允许局域网访问
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8000',
|
||||
changeOrigin: true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 后端配置 (FastAPI)
|
||||
|
||||
**文件**: `backend/app/main.py`
|
||||
|
||||
- **服务监听**: `host="0.0.0.0"` (已配置，监听所有网络接口)
|
||||
- **CORS 策略**:
|
||||
- 开发模式 (`DEBUG=True`): 允许所有来源 (`allow_origins=["*"]`)
|
||||
- 生产模式: 仅允许 localhost
|
||||
|
||||
## 🚀 使用步骤
|
||||
|
||||
### 1. 获取服务器 IP 地址
|
||||
|
||||
在运行服务的机器上执行：
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
ipconfig
|
||||
```
|
||||
查找 "IPv4 地址"，例如：`192.168.1.100`
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
ifconfig
|
||||
# 或
|
||||
ip addr show
|
||||
```
|
||||
查找 `inet` 地址，例如：`inet 192.168.1.100`
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
**启动后端:**
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
后端将监听：
|
||||
- `http://0.0.0.0:8000` (所有网络接口)
|
||||
- 可通过 `http://localhost:8000` 或 `http://192.168.1.100:8000` 访问
|
||||
|
||||
**启动前端:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Vite 将输出：
|
||||
```
|
||||
VITE v5.0.4 ready in xxx ms
|
||||
|
||||
➜ Local: http://localhost:5173/
|
||||
➜ Network: http://192.168.1.100:5173/
|
||||
```
|
||||
|
||||
### 3. 局域网访问
|
||||
|
||||
在同一局域网的其他设备上，使用服务器 IP 地址访问：
|
||||
|
||||
- **前端**: `http://192.168.1.100:5173`
|
||||
- **后端 API**: `http://192.168.1.100:8000`
|
||||
- **API 文档**: `http://192.168.1.100:8000/docs`
|
||||
|
||||
## 🔥 防火墙配置
|
||||
|
||||
如果局域网内无法访问，需要检查防火墙设置。
|
||||
|
||||
### Windows 防火墙
|
||||
|
||||
**方法 1: 允许端口**
|
||||
```powershell
|
||||
# 以管理员身份运行 PowerShell
|
||||
netsh advfirewall firewall add rule name="ERP AI Assistant - Frontend" dir=in action=allow protocol=tcp localport=5173
|
||||
netsh advfirewall firewall add rule name="ERP AI Assistant - Backend" dir=in action=allow protocol=tcp localport=8000
|
||||
```
|
||||
|
||||
**方法 2: 允许应用**
|
||||
1. 打开 "Windows Defender 防火墙"
|
||||
2. 点击 "允许应用通过防火墙"
|
||||
3. 添加 `node.exe` 和 `python.exe`
|
||||
|
||||
### Linux 防火墙
|
||||
|
||||
**UFW (Ubuntu):**
|
||||
```bash
|
||||
sudo ufw allow 5173/tcp
|
||||
sudo ufw allow 8000/tcp
|
||||
sudo ufw reload
|
||||
```
|
||||
|
||||
**Firewalld (CentOS/RHEL):**
|
||||
```bash
|
||||
sudo firewall-cmd --permanent --add-port=5173/tcp
|
||||
sudo firewall-cmd --permanent --add-port=8000/tcp
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
### 云服务器安全组
|
||||
|
||||
如果运行在云服务器上，需要在安全组中开放端口：
|
||||
- 入站规则: 允许 TCP 端口 5173 和 8000
|
||||
|
||||
## 📱 测试访问
|
||||
|
||||
### 1. 本地测试
|
||||
|
||||
在服务器机器上测试：
|
||||
|
||||
```bash
|
||||
# 测试后端
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# 测试前端（浏览器访问）
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
### 2. 局域网测试
|
||||
|
||||
在其他设备上测试：
|
||||
|
||||
```bash
|
||||
# 测试后端（替换为实际 IP）
|
||||
curl http://192.168.1.100:8000/health
|
||||
|
||||
# 测试前端（浏览器访问）
|
||||
http://192.168.1.100:5173
|
||||
```
|
||||
|
||||
## ⚠️ 安全注意事项
|
||||
|
||||
### 开发环境
|
||||
|
||||
当前配置适合开发环境：
|
||||
- ✅ CORS 允许所有来源 (`allow_origins=["*"]`)
|
||||
- ✅ 方便团队协作和测试
|
||||
|
||||
### 生产环境
|
||||
|
||||
**强烈建议**生产环境进行以下调整：
|
||||
|
||||
1. **设置 `DEBUG=False`**
|
||||
```bash
|
||||
# .env
|
||||
DEBUG=False
|
||||
```
|
||||
|
||||
2. **配置具体允许的域名**
|
||||
修改 `backend/app/main.py`:
|
||||
```python
|
||||
allow_origins=[
|
||||
"https://your-domain.com",
|
||||
"https://erp.your-company.com",
|
||||
]
|
||||
```
|
||||
|
||||
3. **使用 HTTPS**
|
||||
- 配置 SSL 证书
|
||||
- 使用 Nginx 反向代理
|
||||
|
||||
4. **使用环境变量管理 CORS**
|
||||
在 `.env` 中配置：
|
||||
```bash
|
||||
ALLOWED_ORIGINS=https://domain1.com,https://domain2.com
|
||||
```
|
||||
|
||||
## 🔧 高级配置
|
||||
|
||||
### 自定义端口
|
||||
|
||||
如果默认端口被占用，可以修改：
|
||||
|
||||
**前端** (`frontend/vite.config.js`):
|
||||
```javascript
|
||||
server: {
|
||||
host: '0.0.0.0',
|
||||
port: 3000, // 自定义端口
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**后端** (`backend/app/main.py`):
|
||||
```python
|
||||
uvicorn.run(
|
||||
"app.main:app",
|
||||
host="0.0.0.0",
|
||||
port=8888, # 自定义端口
|
||||
reload=settings.DEBUG
|
||||
)
|
||||
```
|
||||
|
||||
### 使用 Nginx 反向代理
|
||||
|
||||
生产环境推荐使用 Nginx：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name erp.your-company.com;
|
||||
|
||||
# 前端
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:5173;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
|
||||
# 后端 API
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:8000/api/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 访问日志
|
||||
|
||||
查看访问日志，确认服务正常运行：
|
||||
|
||||
**前端日志:**
|
||||
```bash
|
||||
# Vite 会显示访问日志
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**后端日志:**
|
||||
```bash
|
||||
# FastAPI/Uvicorn 会显示请求日志
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 问题 1: 无法访问
|
||||
|
||||
**症状**: 局域网内其他设备无法访问
|
||||
|
||||
**检查清单:**
|
||||
- ✅ 服务器 IP 地址是否正确
|
||||
- ✅ 防火墙是否开放端口
|
||||
- ✅ 服务是否正在运行
|
||||
- ✅ 是否在同一局域网内
|
||||
|
||||
**诊断命令:**
|
||||
```bash
|
||||
# 测试端口是否开放
|
||||
telnet 192.168.1.100 5173
|
||||
telnet 192.168.1.100 8000
|
||||
|
||||
# 或使用 nc
|
||||
nc -zv 192.168.1.100 5173
|
||||
nc -zv 192.168.1.100 8000
|
||||
```
|
||||
|
||||
### 问题 2: CORS 错误
|
||||
|
||||
**症状**: 浏览器控制台显示 CORS 错误
|
||||
|
||||
**解决方案:**
|
||||
- 确认 `DEBUG=True` 在 `.env` 中
|
||||
- 检查后端 CORS 配置
|
||||
- 查看浏览器控制台错误详情
|
||||
|
||||
### 问题 3: API 代理失败
|
||||
|
||||
**症状**: 前端无法调用后端 API
|
||||
|
||||
**解决方案:**
|
||||
- 检查后端是否在 `localhost:8000` 运行
|
||||
- 确认 Vite proxy 配置正确
|
||||
- 查看浏览器网络请求
|
||||
|
||||
## 📝 快速命令参考
|
||||
|
||||
```bash
|
||||
# 查看本机 IP
|
||||
ipconfig # Windows
|
||||
ifconfig # Linux/Mac
|
||||
ip addr show # Linux
|
||||
|
||||
# 测试端口
|
||||
netstat -an | grep 5173 # Linux/Mac
|
||||
netstat -an | findstr 5173 # Windows
|
||||
|
||||
# 开放防火墙端口
|
||||
sudo ufw allow 5173/tcp # Ubuntu
|
||||
sudo firewall-cmd --add-port=5173/tcp # CentOS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**更新时间**: 2026-03-21
|
||||
**适用版本**: v1.0.0+
|
||||
58
docs/QUICK_REFERENCE.md
Normal file
58
docs/QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 快速配置卡片
|
||||
|
||||
## 🎯 局域网访问配置
|
||||
|
||||
### ✅ 已配置项目
|
||||
|
||||
1. **前端** - `frontend/vite.config.js`
|
||||
```javascript
|
||||
host: '0.0.0.0' // ✓ 已添加
|
||||
```
|
||||
|
||||
2. **后端** - `backend/app/main.py`
|
||||
```python
|
||||
host="0.0.0.0" // ✓ 已配置
|
||||
allow_origins=["*"] if settings.DEBUG // ✓ 开发模式允许所有来源
|
||||
```
|
||||
|
||||
### 📋 使用步骤
|
||||
|
||||
```bash
|
||||
# 1. 查看服务器 IP
|
||||
ipconfig # Windows
|
||||
ifconfig # Linux/Mac
|
||||
|
||||
# 2. 启动后端
|
||||
cd backend && python -m app.main
|
||||
|
||||
# 3. 启动前端
|
||||
cd frontend && npm run dev
|
||||
|
||||
# 4. 局域网访问
|
||||
# 前端: http://192.168.1.100:5173
|
||||
# 后端: http://192.168.1.100:8000
|
||||
```
|
||||
|
||||
### 🔥 防火墙快速配置
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
# 管理员 PowerShell
|
||||
netsh advfirewall firewall add rule name="ERP Frontend" dir=in action=allow protocol=tcp localport=5173
|
||||
netsh advfirewall firewall add rule name="ERP Backend" dir=in action=allow protocol=tcp localport=8000
|
||||
```
|
||||
|
||||
**Linux (Ubuntu):**
|
||||
```bash
|
||||
sudo ufw allow 5173/tcp
|
||||
sudo ufw allow 8000/tcp
|
||||
```
|
||||
|
||||
### ⚠️ 安全提醒
|
||||
|
||||
- **开发环境**: `DEBUG=True` (允许所有来源)
|
||||
- **生产环境**: `DEBUG=False` + 配置具体域名
|
||||
|
||||
---
|
||||
|
||||
详细说明: [docs/LAN_ACCESS.md](LAN_ACCESS.md)
|
||||
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. 💬 联系项目负责人
|
||||
|
||||
---
|
||||
|
||||
**祝您使用愉快！🎉**
|
||||
2460
docs/superpowers/plans/2026-03-21-erp-ai-assistant-phase1.md
Normal file
2460
docs/superpowers/plans/2026-03-21-erp-ai-assistant-phase1.md
Normal file
File diff suppressed because it is too large
Load Diff
1077
docs/superpowers/specs/2026-03-21-erp-ai-assistant-design.md
Normal file
1077
docs/superpowers/specs/2026-03-21-erp-ai-assistant-design.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user