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：简单查询（推荐，不依赖具体表结构）

SELECT TOP 10 customer_code, customer_name FROM customer_general

方案B：查询系统表（通用）

SELECT TOP 5 TABLE_NAME, COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS

权限配置：

• 是否需要认证：否（方便测试）
• 状态：启用

点击"确定"保存。

Step 5: 测试 API 执行

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

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

点击"执行"，查看结果：

• 应该显示 SQL Server 的数据
• 显示执行时间（毫秒）
• 显示成功状态

如果成功，返回类似：

{
  "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模板：

SELECT customer_code, customer_name FROM customer_general
WHERE #{customerCode} IS NOT NULL THEN customer_code = #{customerCode}

测试参数：

{
  "customerCode": "C001"
}

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

---

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

测试1：无参数查询

# 直接访问动态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

预期返回：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {"customer_code": "xxx", "customer_name": "xxx"}
  ]
}

测试2：带参数查询

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

测试3：API配置管理接口

# 查询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 数据库：

-- 查看创建的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表
• 角色未分配权限

解决：

-- 检查菜单是否插入
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语法错误
• 表不存在

解决：

# 测试SQL Server连接
curl http://localhost:8082/erp/test/connection

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

问题3: 保存配置失败

原因：

• MySQL表未创建
• 字段类型不匹配

解决：

-- 验证表结构
DESC hzhub.erp_api_config;
DESC hzhub.erp_api_param;

---

测试成功后的下一步

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

1. 前端完整界面（Phase 2）

   • API配置列表页（含搜索、分页）
   • 编辑页（基础设置 + 参数配置两Tab）
   • 从表导入弹窗
   • 测试弹窗优化

2. 从表导入功能（Phase 2）

   • 自动生成SQL模板
   • 自动生成参数配置

3. 监控统计功能（Phase 3）

   • API调用统计表记录
   • 统计图表展示

---

请告诉我测试结果

请尝试测试并告诉我：

• ✅ 测试成功，看到了数据
• ❌ 遇到问题，具体错误信息

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