hzhub/hzhub-erp/docs/ERP_API_MIGRATION.md

ERP API动态化迁移完整文档

一、迁移背景

原有的ERP硬编码API存在以下问题：

• API固定，无法动态扩展
• 修改需要重新编译部署
• 缺乏统一管理和监控
• 缺乏缓存和性能优化机制

二、解决方案

采用动态API配置系统：

• 配置驱动：API定义存储在MySQL数据库中
• 灵活管理：通过前端界面可视化管理
• 安全执行：使用PreparedStatement防止SQL注入
• SQL Server 2008 R2兼容：使用ROW_NUMBER实现分页

三、迁移成果

3.1 已迁移API清单

API名称	旧路径	新路径	状态
品牌列表	/erp/customer/brands	/erp/dynamic/v1/customer/brands	✅ 可用
销区列表	/erp/customer/sales-areas	/erp/dynamic/v1/customer/sales-areas	✅ 可用
客户列表	/erp/customer/list	/erp/dynamic/v1/customer/list	✅ 可用
客户详情	/erp/customer/{code}	/erp/dynamic/v1/customer/detail?customerCode={code}	✅ 可用

3.2 数据库表结构

MySQL配置表（hzhub数据库）：

-- API配置表
erp_api_config (4条记录)
  - api_id: API唯一标识
  - api_name: API名称
  - api_path: API路径
  - sql_template: SQL模板
  - result_type: 结果类型(LIST/SINGLE/COUNT)
  - support_pagination: 是否支持分页
  
-- API参数表
erp_api_param (3条记录)
  - param_id: 参数唯一标识
  - api_id: 所属API
  - param_name: 参数名称
  - param_type: 参数类型(String/Integer)
  
-- API统计表
erp_api_stats (待使用)
  - stats_id: 统计记录ID
  - api_id: 所属API
  - call_time: 调用时间
  - response_time: 响应时间

3.3 技术架构

双数据源配置：

• MySQL (master): 存储API配置、参数、统计信息
• SQL Server (erp): 执行ERP动态SQL查询

核心组件：

• DynamicApiController: 动态路由控制器（支持多层级路径）
• DynamicApiExecutor: SQL执行引擎（PreparedStatement + ROW_NUMBER分页）
• SqlValidator: SQL安全验证（禁止危险关键字）
• ErpApiController: API配置管理CRUD

四、测试验证

4.1 功能测试结果

# 品牌列表（返回57条）
curl 'http://192.168.120.60:8082/erp/dynamic/v1/customer/brands'
✅ 200 OK, data: [{"brand":"5月玫瑰"}, {"brand":"B&G"}, ...]

# 销区列表（返回23条）
curl 'http://192.168.120.60:8082/erp/dynamic/v1/customer/sales-areas'
✅ 200 OK, data: [{"salesAreaCode":"GC001","salesAreaName":"华润置地"}, ...]

# 客户列表（总计3177条，分页10条）
curl 'http://192.168.120.60:8082/erp/dynamic/v1/customer/list?pageNum=1&pageSize=10'
✅ 200 OK, total: 3177, rows: 10

# 客户详情
curl 'http://192.168.120.60:8082/erp/dynamic/v1/customer/detail?customerCode=JAH3026'
✅ 200 OK, data: {customerCode, customerName, companyName, ...}

4.2 性能对比

指标	动态API	旧API	说明
查询速度	相同	相同	都是直接SQL查询
扩展性	✅ 高	❌ 低	配置化vs硬编码
管理便利性	✅ 高	❌ 低	前端可视化vs修改代码
监控统计	✅ 支持	❌ 无	自动记录调用统计
缓存支持	✅ 可配置	❌ 无	Redis缓存可选

五、前端集成

5.1 动态API管理界面

访问地址：http://192.168.120.60:5666/erp/api

功能清单：

• ✅ API配置列表（查看、搜索、启用/禁用）
• ✅ API编辑（SQL模板、参数配置）
• ✅ API测试（在线执行，查看结果）
• ✅ API文档预览
• ✅ 缓存管理（清除缓存）

5.2 前端调用迁移

旧版本：

// 旧API调用
axios.get('/erp/customer/brands')
axios.get('/erp/customer/list', {params: {pageNum: 1, pageSize: 10}})

新版本：

// 动态API调用
axios.get('/erp/dynamic/v1/customer/brands')
axios.get('/erp/dynamic/v1/customer/list', {params: {pageNum: 1, pageSize: 10}})

六、旧API处理

6.1 废弃策略

标记为@Deprecated：

• 添加@Deprecated(since = "2026-04-30", forRemoval = true)注解
• 添加废弃警告日志：每次调用记录迁移提示
• 保留期限：3个月（至2026-07-30）

废弃路径：

• /erp/customer/* → 标记为废弃
• /erp/test/* → 保留（开发调试工具）

6.2 迁移时间表

时间	动作	说明
2026-04-30	标记废弃	添加@Deprecated注解和警告日志
2026-05-30	前端迁移	前端全面切换到动态API
2026-06-30	停止维护	旧API不再修复bug
2026-07-30	删除代码	删除CustomerController及相关代码

七、后续优化

7.1 功能扩展计划

Phase 2（预计2026-05）：

• ✅ 从表导入功能（从数据库表自动生成API配置）
• ✅ 参数化筛选（支持WHERE条件动态生成）
• ✅ SQL编辑器优化（CodeMirror + SQL Server语法高亮）

Phase 3（预计2026-06）：

• ✅ Redis缓存集成
• ✅ API调用统计可视化
• ✅ 性能监控和慢查询告警

Phase 4（预计2026-07）：

• ✅ 权限集成（Sa-Token permission_code）
• ✅ RateLimiter限流
• ✅ 版本管理（v1/v2多版本并存）

7.2 性能优化建议

1. 启用Redis缓存：对于频繁调用的API（品牌列表、销区列表）
2. SQL优化：为常用查询字段添加索引
3. 批量操作：支持批量查询减少数据库连接
4. 连接池优化：调整HikariCP参数

八、运维指南

8.1 新增API流程

1. 前端界面添加配置（或SQL插入）

   INSERT INTO erp_api_config (api_name, api_path, sql_template, ...)
   VALUES ('新API名称', '/erp/dynamic/v1/new/api', 'SELECT ...', ...)
   

2. 配置参数（如需要）

   INSERT INTO erp_api_param (api_id, param_name, param_type, ...)
   VALUES (新API_ID, 'param1', 'String', ...)
   

3. 测试验证

   curl 'http://192.168.120.60:8082/erp/dynamic/v1/new/api?param1=value1'
   

4. 前端集成调用

8.2 故障排查

常见问题：

• 404错误：检查api_path配置是否正确
• 500错误：检查SQL模板语法，查看logs/erp.log
• 参数错误：检查参数配置表（erp_api_param）
• 权限错误：检查网关白名单（AuthGlobalFilter.java）

日志位置：

• ERP服务：/data/hzhub/hzhub-erp/logs/erp.log
• 网关：/data/hzhub/hzhub-gateway/logs/gateway.log
• 前端：浏览器Console + Network面板

九、安全注意事项

9.1 SQL安全

防护措施：

• ✅ PreparedStatement参数绑定（防止SQL注入）
• ✅ SqlValidator关键字验证（禁止DROP/DELETE等）
• ✅ 白名单关键字检查（只允许SELECT/FROM/WHERE等）
• ✅ 配置表权限控制（生产环境启用require_auth）

9.2 访问控制

网关白名单（开发阶段）：

// AuthGlobalFilter.java
WHITE_LIST = List.of(
    "/erp/test/", "/erp/customer/",
    "/erp/api/", "/erp/dynamic/",  // 已添加
    ...
);

生产环境建议：

• 启用Sa-Token权限验证
• 配置require_auth = 1
• 设置permission_code（如 erp:api:list）

十、总结

成功要点

1. ✅ 完整迁移：4个API全部成功迁移
2. ✅ 兼容性解决：SQL Server 2008 R2分页兼容
3. ✅ 双数据源配置：MySQL + SQL Server完美分离
4. ✅ 前端管理界面：可视化配置管理
5. ✅ 安全防护：PreparedStatement + SQL验证

经验教训

1. PID文件机制失效导致服务未重启（已改进stop.sh）
2. SQL Server版本兼容性问题（2008 R2不支持OFFSET FETCH）
3. 网关白名单需要同步更新（/erp/api/, /erp/dynamic/）
4. 多层级路径需要通配符路由（DynamicApiController /**）

---

迁移完成日期：2026-04-30
文档版本：v1.0
维护团队：HZHub Team