hzhub/docs/erp-api-testing-guide.md

# ERP API 管理平台 - 测试流程

## 当前状态

✅ **后端代码已完成**（Phase 1）
✅ **SQL 文件已创建**：`/data/hzhub/hzhub-erp/docs/sql/erp_api_tables.sql`
✅ **初始化指南已创建**：`/data/hzhub/docs/erp-api-database-init-guide.md`
⏳ **数据库表待创建**（需手动执行）
⏳ **ERP 服务待重启**

---

## 执行步骤

### Step 1: 创建数据库表（需手动执行）

**推荐方式**：通过 Docker MySQL 容器执行

```bash
# 1. 进入 MySQL 容器
docker exec -it hzhub-mysql mysql -u root -phzhub123

# 2. 在 MySQL 命令行中执行
USE hzhub;

# 3. 复制粘贴以下 SQL（或执行 SQL 文件）
-- 见文件：/data/hzhub/hzhub-erp/docs/sql/erp_api_tables.sql

# 4. 验证表创建
SHOW TABLES LIKE 'erp_api_%';
SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'hzhub' AND table_name LIKE 'erp_api_%';

# 5. 验证菜单插入
SELECT menu_id, menu_name, perms FROM sys_menu WHERE menu_name LIKE '%ERP%' OR menu_name LIKE '%API%';

# 6. 退出
exit;
```

**如果 MySQL 容器不可访问**，可使用 Navicat/DBeaver 等工具连接 localhost:3306 执行 SQL。

---

### Step 2: 重启 ERP 服务（自动执行）

执行完 SQL 后，我将继续执行：

```bash
cd /data/hzhub/hzhub-erp
./restart.sh  # 或 ./start.sh
```

---

### Step 3: 验证服务健康（自动执行）

```bash
# 检查健康状态
curl http://localhost:8082/actuator/health

# 检查 ERP 服务进程
cd hzhub-erp && ./status.sh
```

---

### Step 4: 手动测试 API（需你手动执行）

#### 4.1 通过管理后台测试（推荐）

1. **访问管理后台**：http://192.168.120.60:5666
2. **登录**（使用管理员账号）
3. **刷新菜单**（菜单会动态加载，新菜单"ERP管理"应该出现）
4. **进入 ERP管理 > API配置**
5. **点击"新增"创建测试 API**：
   - API名称：`测试客户查询`
   - API路径：`/erp/dynamic/v1/test_customer`
   - HTTP方法：`GET`
   - SQL模板：
     ```sql
     SELECT TOP 10 customer_code, customer_name FROM customer_general
     ```
   - 结果类型：`LIST`
   - 支持分页：`否`
   - 状态：`启用`

6. **点击"测试"按钮**：输入空参数 `{}`，查看执行结果

#### 4.2 通过 curl 直接测试

```bash
# 测试动态 API 执行（无需 Token，因为当前 @SaIgnore）
curl http://localhost:8082/erp/dynamic/v1/test_customer

# 如果通过网关访问（需要 Token）
curl -H "Authorization: Bearer <token>" http://localhost:8080/erp/dynamic/v1/test_customer
```

---

### Step 5: 测试结果验证

**预期结果**：

1. **API 配置保存成功**：能在列表中看到刚创建的 API
2. **测试执行成功**：返回 SQL Server 数据库中的客户数据
3. **执行时间记录**：能看到响应时间（毫秒）
4. **错误处理**：如果 SQL 错误，能看到详细的错误信息

---

## 可能遇到的问题

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

**原因**：菜单 SQL 未执行或角色无权限

**解决**：
1. 检查 sys_menu 表是否插入成功
2. 在角色管理中为管理员角色分配 `erp:api:*` 权限
3. 清除浏览器缓存重新登录

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

**原因**：SQL Server 连接问题或 SQL 语法错误

**解决**：
1. 检查 ERP 服务配置：`hzhub-erp/src/main/resources/application-dev.yml`
2. 确认 SQL Server 地址：`192.168.120.10:8042`
3. 测试 SQL Server 连接：
   ```bash
   curl http://localhost:8082/erp/test/connection
   ```

### 问题 3: 动态 API 返回 404

**原因**：API 配置路径不匹配或服务未重启

**解决**：
1. 确认 ERP 服务已重启
2. 检查 API 配置中的 `api_path` 是否为 `/erp/dynamic/v1/xxx`
3. 确认 `api_method` 和 `api_version` 正确

---

## 下一步计划

测试成功后，我将继续：

1. **创建前端界面**（API 配置列表、编辑页、测试弹窗）
2. **实现从表导入功能**（自动生成 SQL 和参数）
3. **添加缓存和监控功能**
4. **完善安全验证和权限控制**

---

## 准备好了吗？

**请告诉我 SQL 执行完成后的状态**：
- ✅ SQL 执行成功，表和菜单已创建
- ❌ SQL 执行遇到问题，需要帮助

我将根据你的反馈继续后续步骤。