erp-ass/docs/QUICK_START.md

# 🚀 快速上手指南

## 📋 前置条件

### 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. 💬 联系项目负责人

---

**祝您使用愉快！🎉**