hzhub/docs/erp-api-quick-test-guide.md

# ERP API 管理平台 - 快速测试指南

## 当前状态确认

✅ **ERP 服务运行正常**（Health: UP）
✅ **SQL Server 数据库连接正常**
✅ **数据库表已创建**（需要在 MySQL hzhub 数据库中验证）

---

## 测试方案一：通过管理后台测试（推荐）

### Step 1: 访问管理后台

访问地址：http://192.168.120.60:5666 或 http://localhost:5666

登录管理员账号

### Step 2: 检查新菜单

刷新页面后，左侧菜单应该出现：
```
系统管理
工具
监控
ERP管理          ← 新增
  ├── API配置    ← 点击进入列表页
  └── API监控
```

如果菜单未显示，可能需要：
- 重新登录
- 清除浏览器缓存
- 检查角色权限是否包含 `erp:api:list`

### Step 3: 进入 API 配置页面

点击"ERP管理 > API配置"，应该看到：
- 空列表（因为还没有创建任何 API 配置）
- 工具栏有"新增"按钮

### Step 4: 创建测试 API

点击"新增"按钮，填写以下信息：

**基础信息**：
- API名称：`测试客户列表查询`
- API路径：`/erp/dynamic/v1/test_customer_list`
- HTTP方法：`GET`
- API描述：`测试SQL Server客户数据查询`
- API版本：`v1`
- 数据源：`erp`（默认）
- 结果类型：`LIST`
- 支持分页：`否`（先测试不分页）

**SQL模板**（选择一个测试）：

**方案A：简单查询（推荐，不依赖具体表结构）**
```sql
SELECT TOP 10 customer_code, customer_name FROM customer_general
```

**方案B：查询系统表（通用）**
```sql
SELECT TOP 5 TABLE_NAME, COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS
```

**权限配置**：
- 是否需要认证：`否`（方便测试）
- 状态：`启用`

点击"确定"保存。

### Step 5: 测试 API 执行

在列表中找到刚创建的 API，点击"测试"按钮。

**测试参数**：输入空对象 `{}`（因为SQL没有参数）

点击"执行"，查看结果：
- 应该显示 SQL Server 的数据
- 显示执行时间（毫秒）
- 显示成功状态

如果成功，返回类似：
```json
{
  "success": true,
  "data": [
    {"customer_code": "C001", "customer_name": "客户A"},
    {"customer_code": "C002", "customer_name": "客户B"}
  ],
  "executionTime": 156,
  "executedSql": "SELECT TOP 10 customer_code, customer_name FROM customer_general"
}
```

### Step 6: 测试带参数的 API（可选）

创建第二个测试 API：

**信息**：
- API名称：`测试带参数查询`
- API路径：`/erp/dynamic/v1/test_param_query`
- SQL模板：
```sql
SELECT customer_code, customer_name FROM customer_general
WHERE #{customerCode} IS NOT NULL THEN customer_code = #{customerCode}
```

**测试参数**：
```json
{
  "customerCode": "C001"
}
```

查看结果，应该只返回指定客户的数据。

---

## 测试方案二：通过 curl 直接测试 API

### 测试1：无参数查询

```bash
# 直接访问动态API（不需要Token，因为配置了@SaIgnore）
curl http://localhost:8082/erp/dynamic/v1/test_customer_list

# 或通过网关访问（需要先获取Token）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8080/erp/dynamic/v1/test_customer_list
```

**预期返回**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {"customer_code": "xxx", "customer_name": "xxx"}
  ]
}
```

### 测试2：带参数查询

```bash
curl -X POST http://localhost:8082/erp/dynamic/v1/test_param_query \
  -H "Content-Type: application/json" \
  -d '{"customerCode":"C001"}'
```

### 测试3：API配置管理接口

```bash
# 查询API配置列表（需要Token）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8080/erp/api/config/list?pageNum=1&pageSize=10

# 测试API（需要Token）
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8080/erp/api/config/test/1 \
  -d '{}'
```

---

## 测试验证清单

### 功能验证

✅ **菜单显示**：ERP管理菜单正常显示
✅ **列表页面**：API配置列表正常加载
✅ **新增功能**：能成功保存API配置到MySQL数据库
✅ **测试功能**：API测试弹窗正常工作
✅ **SQL执行**：动态SQL能成功查询SQL Server数据
✅ **参数处理**：带参数的SQL能正确执行
✅ **错误处理**：错误的SQL能显示详细错误信息

### 数据验证

检查 MySQL 数据库：

```sql
-- 查看创建的API配置
SELECT * FROM hzhub.erp_api_config;

-- 查看参数配置（如果有）
SELECT * FROM hzhub.erp_api_param;

-- 查看菜单配置
SELECT menu_id, menu_name, menu_type, visible, perms
FROM hzhub.sys_menu
WHERE menu_name LIKE '%ERP%' OR menu_name LIKE '%API%';
```

---

## 可能遇到的问题

### 问题1: 菜单不显示

**原因**：
- SQL未执行到sys_menu表
- 角色未分配权限

**解决**：
```sql
-- 检查菜单是否插入
SELECT * FROM sys_menu WHERE menu_name='ERP管理';

-- 给管理员角色分配权限（假设角色ID=1）
INSERT INTO sys_role_menu (role_id, menu_id)
SELECT 1, menu_id FROM sys_menu WHERE perms LIKE 'erp:api:%';
```

### 问题2: API执行失败

**原因**：
- SQL Server连接问题
- SQL语法错误
- 表不存在

**解决**：
```bash
# 测试SQL Server连接
curl http://localhost:8082/erp/test/connection

# 查看错误详情
# 在测试弹窗中查看完整的错误信息和堆栈
```

### 问题3: 保存配置失败

**原因**：
- MySQL表未创建
- 字段类型不匹配

**解决**：
```sql
-- 验证表结构
DESC hzhub.erp_api_config;
DESC hzhub.erp_api_param;
```

---

## 测试成功后的下一步

测试成功后，我将继续创建：

1. **前端完整界面**（Phase 2）
   - API配置列表页（含搜索、分页）
   - 编辑页（基础设置 + 参数配置两Tab）
   - 从表导入弹窗
   - 测试弹窗优化

2. **从表导入功能**（Phase 2）
   - 自动生成SQL模板
   - 自动生成参数配置

3. **监控统计功能**（Phase 3）
   - API调用统计表记录
   - 统计图表展示

---

## 请告诉我测试结果

请尝试测试并告诉我：
- ✅ 测试成功，看到了数据
- ❌ 遇到问题，具体错误信息

我将根据测试结果继续优化或创建前端代码！