erp-ass/docs/QUICK_START.md

🚀 快速上手指南

📋 前置条件

1. 后端配置

确保已完成后端配置和依赖安装：

cd backend

# 安装依赖（如果遇到问题，参考 docs/DEPENDENCY_FIXES.md）
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库和 Claude API

关键配置项:

# 数据库配置
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. 前端配置

cd frontend

# 安装依赖
npm install

🎯 启动服务

启动后端

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.

启动前端

新终端窗口:

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 预览示例:

-- 创建功能号
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 端点

如需使用代理或自托管服务：

# .env
ANTHROPIC_BASE_URL=https://your-proxy.com/v1

参考 Claude API 配置指南

局域网访问

团队成员可通过局域网访问：

# 查看服务器 IP
ipconfig  # Windows
ifconfig  # Linux/Mac

# 其他设备访问
http://192.168.1.100:5173

参考 局域网访问配置

查看历史记录

"历史记录"页面（即将推出）:

• 查看所有执行记录
• 重新执行历史配置
• 导出配置方案

🎓 最佳实践

1. 开发流程

需求分析 → 代码评审 → 测试环境验证 → 生产环境执行

2. 命名规范

建议在需求中说明：

• 功能号格式：模块-序号 (如：11-001)
• 表名前缀：业务含义 (如：SA_ 销售)
• 字段名：有意义的英文

3. 版本管理

使用 Git 记录配置变更：

# 执行成功后
git add .
git commit -m "feat: add 销售订单管理功能"

4. 团队协作

• 使用相同的测试数据库
• 共享需求模板
• 定期同步配置规范

📞 获取帮助

遇到问题时：

1. 📖 查看本文档
2. 🔍 检查日志文件
3. 📋 查看后端 API 文档: http://localhost:8000/docs
4. 💬 联系项目负责人

---

祝您使用愉快！🎉