hzhub/docs/erp-api-management-plan.md

ERP API 管理平台实现方案

Context

需求背景：用户需要一个界面来查看和管理 ERP 数据库的定制 API 封装，并提供手动创建 API 的功能。当前 ERP 服务只有少量固定的 API（CustomerController），缺乏灵活的 API 管理能力。

重要决策：完全集成到管理后台（hzhub-admin）中，作为系统管理的一个新模块，实现统一管理：

• 前端界面集成在 hzhub-admin 的标准管理界面中（左侧菜单 + 右侧功能页面）
• 通过后端菜单系统动态添加菜单项（类似"系统管理"、"工具"等模块）
• 使用统一的权限体系（通过 Sa-Token 和 permission_code）
• 使用统一的认证体系（JWT Token 共享）
• 与现有的系统管理、代码生成器等模块保持一致的界面风格和操作体验

设计目标：

1. 查看 ERP 数据库中的所有表结构
2. 从数据库表一键生成 API 配置
3. 手动创建和编辑 API（配置 SQL、参数、权限等）
4. API 测试功能（在线测试执行）
5. API 文档预览
6. API 调用统计和监控（完整功能）
7. Redis 缓存支持（完整功能）
8. 版本管理支持（完整功能）

参考架构：

• 基于代码生成器（gen_table + gen_table_column）的两表元数据管理模式
• 使用 JdbcTemplate 执行动态 SQL（安全、简单）
• 参考 Vben Admin 的标准 CRUD 界面模式

---

一、架构设计

1.1 数据库表设计

创建两张元数据表存储 API 配置：

erp_api_config（API 配置主表）：

CREATE TABLE erp_api_config (
    api_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT 'API ID',
    api_name VARCHAR(100) NOT NULL COMMENT 'API名称',
    api_path VARCHAR(200) NOT NULL COMMENT 'API路径（如 /erp/dynamic/customer/list）',
    api_method VARCHAR(10) NOT NULL DEFAULT 'GET' COMMENT 'HTTP方法（GET/POST）',
    api_desc VARCHAR(500) COMMENT 'API描述',
    api_version VARCHAR(10) DEFAULT 'v1' COMMENT 'API版本号（v1/v2）',

    -- 数据源配置
    data_source VARCHAR(50) DEFAULT 'erp' COMMENT '数据源名称',

    -- SQL配置
    sql_template TEXT NOT NULL COMMENT 'SQL模板（支持参数占位符 #{paramName}）',
    result_type VARCHAR(20) NOT NULL DEFAULT 'LIST' COMMENT '结果类型（LIST/SINGLE/COUNT）',

    -- 分页配置
    support_pagination TINYINT(1) DEFAULT 0 COMMENT '是否支持分页',
    page_param_name VARCHAR(50) DEFAULT 'pageNum' COMMENT '页码参数名',
    size_param_name VARCHAR(50) DEFAULT 'pageSize' COMMENT '页大小参数名',

    -- 权限配置
    require_auth TINYINT(1) DEFAULT 0 COMMENT '是否需要认证',
    permission_code VARCHAR(100) COMMENT '权限标识（如 erp:customer:list）',

    -- 缓存配置
    enable_cache TINYINT(1) DEFAULT 0 COMMENT '是否启用缓存',
    cache_key_template VARCHAR(200) COMMENT '缓存键模板（支持参数占位符）',
    cache_ttl INT DEFAULT 300 COMMENT '缓存过期时间（秒）',

    -- 来源表信息
    source_table VARCHAR(100) COMMENT '来源表名',
    source_table_comment VARCHAR(500) COMMENT '来源表描述',

    -- 状态
    status TINYINT(1) DEFAULT 1 COMMENT '状态（0禁用 1启用）',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    create_by VARCHAR(50),
    update_by VARCHAR(50),
    remark VARCHAR(500)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='ERP动态API配置表';

CREATE INDEX idx_api_path_method ON erp_api_config(api_path, api_method, api_version);
CREATE INDEX idx_status ON erp_api_config(status);

erp_api_param（API 参数配置表）：

CREATE TABLE erp_api_param (
    param_id BIGINT PRIMARY KEY AUTO_INCREMENT,
    api_id BIGINT NOT NULL COMMENT '所属API ID',

    -- 参数基本信息
    param_name VARCHAR(100) NOT NULL COMMENT '参数名称',
    param_desc VARCHAR(500) COMMENT '参数描述',
    param_type VARCHAR(20) NOT NULL DEFAULT 'String' COMMENT '参数类型（String/Integer/Long/Date/Boolean）',

    -- 参数位置
    param_position VARCHAR(20) NOT NULL DEFAULT 'QUERY' COMMENT '参数位置（QUERY/BODY）',

    -- 参数验证
    is_required TINYINT(1) DEFAULT 0 COMMENT '是否必填',
    default_value VARCHAR(200) COMMENT '默认值',

    -- SQL映射
    sql_param_name VARCHAR(100) COMMENT 'SQL参数名',

    -- 排序
    sort INT DEFAULT 0,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='ERP动态API参数配置表';

CREATE INDEX idx_api_id ON erp_api_param(api_id);
ALTER TABLE erp_api_param ADD CONSTRAINT fk_api_param_api
    FOREIGN KEY (api_id) REFERENCES erp_api_config(api_id) ON DELETE CASCADE;

erp_api_stats（API 调用统计表）：

CREATE TABLE erp_api_stats (
    stats_id BIGINT PRIMARY KEY AUTO_INCREMENT,
    api_id BIGINT NOT NULL COMMENT 'API ID',

    -- 调用信息
    call_time DATETIME NOT NULL COMMENT '调用时间',
    call_params TEXT COMMENT '调用参数（JSON）',
    response_time INT COMMENT '响应时间（ms）',
    call_status VARCHAR(10) COMMENT '调用状态（SUCCESS/ERROR）',

    -- 错误信息
    error_message TEXT COMMENT '错误消息',
    error_stack TEXT COMMENT '错误堆栈',

    -- 客户端信息
    client_ip VARCHAR(50) COMMENT '客户端IP',
    user_id VARCHAR(50) COMMENT '用户ID',

    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='ERP动态API调用统计表';

CREATE INDEX idx_api_id_time ON erp_api_stats(api_id, call_time);
CREATE INDEX idx_call_status ON erp_api_stats(call_status);

1.2 核心技术选型

动态 SQL 执行：JdbcTemplate

• 优点：简单、安全、支持 PreparedStatement 参数绑定
• 避免复杂的 MyBatis 动态 SQL（不适合动态生成场景）

参数类型转换：自定义 ParamTypeConverter

• 支持 String、Integer、Long、Date、Boolean 类型
• 自动转换前端参数到 SQL 参数类型

结果映射：动态 RowMapper → Map<String, Object>

• 避免硬编码 VO 类，灵活适配不同表结构

安全防护：

• SQL 注入防护：强制 PreparedStatement 参数绑定（#{param} → ?）
• SQL 关键字白名单：只允许 SELECT、FROM、WHERE、AND、OR、ORDER、BY 等安全关键字
• 禁止危险操作：DROP、DELETE、TRUNCATE、ALTER、CREATE 等
• 可选权限控制：通过 Sa-Token 的 permission_code 验证

1.3 后端架构

文件结构：

hzhub-erp/src/main/java/org/hzhub/erp/
├── controller/
│   ├── ErpApiController.java          # API 配置管理 CRUD
│   └── DynamicApiController.java      # 动态 API 执行入口（通配符路由）
├── service/
│   ├── IErpApiService.java            # API 配置 Service 接口
│   ├── impl/
│   │   ├── ErpApiServiceImpl.java     # API 配置管理 + 从表导入
│   │   ├── DynamicApiExecutor.java    # 核心 SQL 执行引擎
│   │   ├── ApiCacheService.java       # Redis 缓存服务
│   │   └── ApiMonitorService.java     # 监控统计服务
│   └── ParamTypeConverter.java        # 参数类型转换器
├── domain/
│   ├── ErpApiConfig.java              # API 配置实体
│   ├── ErpApiParam.java               # API 参数实体
│   └── vo/
│   │   ├── ErpApiConfigVO.java        # API 配置 VO
│   │   └── ApiTestResultVO.java       # API 测试结果 VO
├── mapper/
│   ├── ErpApiConfigMapper.java        # API 配置 Mapper
│   ├── ErpApiParamMapper.java         # API 参数 Mapper
│   └── ErpApiStatsMapper.java         # API 统计 Mapper
└── util/
    └── SqlValidator.java               # SQL 安全验证工具

关键模块设计：

1. DynamicApiExecutor（核心执行引擎）：

   • 处理 SQL 模板：将 #{param} 转换为 ? 占位符
   • 参数绑定：按照参数顺序提取值并绑定到 PreparedStatement
   • 分页处理：自动添加 OFFSET FETCH（SQL Server 语法）
   • 结果封装：LIST → TableDataInfo，SINGLE → R，COUNT → R
   • 缓存检查：检查 Redis 缓存，如果存在直接返回
   • 统计记录：记录执行时间、调用参数到 erp_api_stats

2. ApiCacheService（缓存服务）：

   • 缓存键生成：根据 cache_key_template 和参数生成缓存键
   • 缓存操作：get、set、delete、clear
   • 缓存过期处理：支持 TTL 配置
   • 缓存命中率统计：记录缓存命中和未命中次数

3. ApiMonitorService（监控服务）：

   • 调用记录：记录每次调用到 erp_api_stats
   • 统计查询：按 API ID、时间段查询调用统计
   • 错误分析：查询错误日志、错误率统计
   • 性能分析：响应时间趋势、慢查询告警

4. ErpApiController（配置管理）：

   • CRUD 接口：list、getInfo、add、edit、remove
   • 从表导入：importFromTable（调用 ErpExploreController 获取表结构）
   • API 测试：testApi（执行并返回结果 + 执行时间）
   • 状态切换：changeStatus
   • 统计查询：getApiStats、getApiErrorLog
   • 版本管理：支持 v1/v2 版本号，路径自动包含版本（/erp/dynamic/v1/xxx）

5. DynamicApiController（动态路由）：

   • 通配符路径：@GetMapping("/erp/dynamic/{version}/{apiPath}")
   • 根据请求路径、版本和方法查询 API 配置
   • 权限检查（如果 require_auth = 1）
   • 参数验证和类型转换
   • 缓存检查（如果 enable_cache = 1）
   • 调用 DynamicApiExecutor 执行
   • 记录统计信息

---

二、功能模块详细设计

2.1 API 配置管理（CRUD）

后端接口：

Method	Path	功能
GET	/erp/api/config/list	分页查询 API 配置列表
GET	/erp/api/config/{apiId}	获取配置详情（含参数列表）
POST	/erp/api/config	新增 API 配置
PUT	/erp/api/config	修改 API 配置
DELETE	/erp/api/config/{apiIds}	删除配置
PUT	/erp/api/config/changeStatus	启用/禁用
POST	/erp/api/config/importFromTable	从表导入
GET	/erp/api/config/syncTable/{apiId}	同步表结构
POST	/erp/api/config/test/{apiId}	API 测试
GET	/erp/api/config/preview/{apiId}	API 文档预览
GET	/erp/api/config/stats/{apiId}	查询调用统计
GET	/erp/api/config/errorLog/{apiId}	查询错误日志
DELETE	/erp/api/config/cache/{apiId}	清除缓存

2.2 从数据库表导入

流程：

1. 前端调用 ErpExploreController 获取表列表（/erp/test/explore）
2. 用户选择要导入的表（多选）
3. 后端 importFromTable 方法：
   • 查询表的列信息（调用 /erp/test/explore/table?tableName=xxx）
   • 生成默认查询 SQL：SELECT * FROM tableName WHERE 1=1
   • 为每个列创建参数配置（paramName、paramType、paramDesc）
   • 保存到 erp_api_config 和 erp_api_param

自动生成逻辑：

• API 名称：{tableName}列表查询
• API 路径：/erp/dynamic/{tableName}
• SQL 类型：根据列数据类型推断 Java 类型（varchar → String, int → Integer, datetime → Date）
• 支持分页：默认启用

2.3 API 测试功能

设计：

• 输入：apiId + testParams（Map<String, Object>）
• 输出：ApiTestResultVO（包含执行结果、执行时间、SQL、错误信息）

ApiTestResultVO 结构：

public class ApiTestResultVO {
    private String apiPath;
    private String testMethod;
    private Map<String, Object> requestParams;
    private Boolean success;
    private Object data;                  // 执行结果
    private Long executionTime;           // 执行时间（ms）
    private String executedSql;           // 实际执行的 SQL
    private String errorMessage;          // 错误信息（如果失败）
    private String errorStack;            // 错误堆栈
}

2.4 API 文档预览

生成内容：

• 基本信息：API 名称、路径、方法、描述
• 参数说明表：参数名、类型、必填、默认值、描述
• SQL 模板说明
• 响应格式示例
• 使用示例（请求 URL + 参数示例）

---

三、前端界面设计

3.1 文件结构

hzhub-admin/apps/web-antd/src/
├── api/erp/
│   ├── api/
│   │   ├── index.ts                   # API 函数定义
│   │   └── model.d.ts                 # TypeScript 类型
│   └── explore/
│   │   ├── index.ts                   # 数据库探查 API
│   │   └── model.d.ts
├── views/erp/api/
│   ├── index.vue                      # API 配置列表页
│   ├── data.tsx                       # 列定义、搜索表单 schema
│   ├── edit-api.vue                   # 编辑页（两 Tab）
│   ├── edit-tabs/
│   │   ├── basic-setting.vue          # 基础设置 Tab
│   │   └── params-config.vue          # 参数配置 Tab（VxeGrid inline-editable）
│   ├── table-import-modal.vue         # 从表导入弹窗
│   ├── test-modal.vue                 # API 测试弹窗
│   ├── doc-preview-modal.vue          # 文档预览弹窗
│   └── stats-modal.vue                # 统计监控弹窗

3.2 列表页（index.vue）

参考：tenant/index.vue（完整 CRUD）

功能：

• VxeGrid 表格展示 API 配置（apiName、apiPath、apiMethod、status、createTime）
• 搜索表单：apiName、apiPath、status
• 操作列：测试、编辑、删除、启用/禁用、查看统计
• 工具栏：从表导入、新增 API

3.3 编辑页（edit-api.vue）

参考：generator/edit-gen.vue（两 Tab 设计）

Tab 1 - 基础设置：

• API 名称、路径、方法（下拉选择 GET/POST）
• SQL 模板（使用 CodeMirror 编辑器，支持 SQL Server 语法高亮）
• 数据源（下拉选择）
• 结果类型（LIST/SINGLE/COUNT）
• 分页配置（是否支持分页、参数名）
• 权限配置（是否需要认证、权限标识）
• 缓存配置（是否启用缓存、缓存键模板、TTL）
• 版本号（下拉选择 v1/v2）
• 来源表信息（只读，显示来源表名和描述）

Tab 2 - 参数配置：

• VxeGrid inline-editable 表格
• 列：paramName、paramType（下拉）、paramPosition（下拉）、isRequired（复选框）、defaultValue、paramDesc
• 工具栏：新增参数、删除参数、同步表结构

3.4 从表导入弹窗（table-import-modal.vue）

参考：generator/table-import-modal.vue

功能：

• 调用 /erp/test/explore 获取表列表
• VxeGrid 表格展示：tableName、schemaName、rowCount、columnCount、hasPrimaryKey
• 多选框选择要导入的表
• 确认导入：调用 /erp/api/config/importFromTable

3.5 API 测试弹窗（test-modal.vue）

设计：

• 上半部分：参数输入表单（根据参数配置动态生成）
• 下半部分：执行结果展示
  • 元信息：执行时间、状态（成功/失败）
  • 结果数据：JSON 格式化展示（使用 CodeMirror）
  • 错误信息：如果失败，显示错误消息和堆栈

3.6 文档预览弹窗（doc-preview-modal.vue）

参考：generator/code-preview-modal.vue（多 Tab 展示）

Tab 内容：

• API 说明：名称、路径、方法、描述
• 参数说明：表格形式展示参数列表
• SQL 模板：代码高亮显示
• 响应示例：JSON 示例
• 使用示例：完整的请求 URL 和参数示例

3.7 统计监控弹窗（stats-modal.vue）

设计：

• 上部分：统计概览（总调用次数、平均响应时间、错误率）
• 中部分：调用次数趋势图（使用 Charts）
• 下部分：响应时间趋势图
• 错误日志列表：最近的错误调用记录

---

四、SQL 模板设计

4.1 参数占位符语法

使用 #{paramName} 作为参数占位符，自动转换为 PreparedStatement 的 ?：

示例 SQL 模板：

-- 简单查询
SELECT * FROM customer
WHERE #{customerCode} IS NOT NULL THEN customer_code = #{customerCode}
  AND #{companyCode} IS NOT NULL THEN company_code = #{companyCode}

-- 带分页查询
SELECT customer_code, customer_name, company_code
FROM customer
WHERE #{keyword} IS NOT NULL THEN customer_name LIKE '%#{keyword}%'
ORDER BY customer_code
-- 分页参数自动添加：OFFSET #{pageNum} ROWS FETCH NEXT #{pageSize} ROWS ONLY

-- 聚合查询
SELECT COUNT(*) AS total
FROM customer
WHERE #{salesAreaCode} IS NOT NULL THEN sales_area_code = #{salesAreaCode}

4.2 SQL 安全验证

白名单关键字：

Set<String> ALLOWED_KEYWORDS = Set.of(
    "SELECT", "FROM", "WHERE", "AND", "OR", "ORDER", "BY", "GROUP", "HAVING",
    "OFFSET", "FETCH", "NEXT", "ROWS", "ONLY", "AS", "COUNT", "SUM", "AVG"
);

禁止关键字：

Set<String> DANGEROUS_KEYWORDS = Set.of(
    "DROP", "DELETE", "TRUNCATE", "ALTER", "CREATE", "GRANT", "INSERT", "UPDATE"
);

---

五、安全考虑

5.1 SQL 注入防护

1. 强制参数绑定：禁止拼接 SQL，必须使用 PreparedStatement
2. 关键字验证：执行前验证 SQL 只包含白名单关键字
3. 参数值验证：基于配置的正则表达式验证参数格式

5.2 权限控制

1. 可选认证：通过 require_auth 字段控制
2. 权限标识：通过 permission_code 配置（如 erp:customer:list）
3. Sa-Token 验证：

   if (config.getRequireAuth() == 1) {
       StpUtil.checkPermission(config.getPermissionCode());
   }
   

5.3 访问控制

• 所有动态 API 默认需要通过网关验证（X-Gateway-Verified header）
• 可选启用 Sa-Token 权限检查
• 支持 RateLimiter 限流（后续添加）

---

六、实现步骤（分阶段）

根据用户确认的设计决策：

• 路由机制：使用通配符路由（/erp/dynamic/{version}/{apiPath}）
• SQL 编辑器：基础版本（CodeMirror + 语法高亮）
• 高级功能：第一版实现完整功能（缓存、监控、版本管理）

Phase 1：核心功能 + 基础增强（第 1-2 周）

目标：实现最小可用版本 + 基础高级功能

1. 数据库表创建（hzhub-erp）：

   • 创建 erp_api_config 和 erp_api_param 表（包含缓存、版本字段）
   • 创建 erp_api_stats 表（监控统计）
   • 添加索引和外键约束

2. 后端基础架构：

   • 创建 Domain 实体类（ErpApiConfig、ErpApiParam、ErpApiStats）
   • 创建 Mapper 接口和 XML（基础 CRUD）
   • 创建 Service 接口和实现（ErpApiServiceImpl）
   • 创建 DynamicApiExecutor（核心 SQL 执行引擎）
   • 创建 ParamTypeConverter（参数类型转换）
   • 创建 ApiCacheService（Redis 缓存服务）
   • 创建 ApiMonitorService（调用统计服务）

3. Controller 实现：

   • ErpApiController（CRUD 接口 + 缓存配置 + 版本管理）
   • DynamicApiController（通配符路由 + 缓存检查 + 统计记录）

4. 前端基础页面：

   • 列表页（index.vue）
   • 基础的增删改查功能
   • CodeMirror SQL 编辑器（语法高亮）

Phase 2：导入和编辑功能 + 版本管理（第 3 周）

目标：完善配置管理功能 + 版本支持

1. 从表导入：

   • Service：importFromTable 方法
   • SQL 模板自动生成
   • 参数自动生成

2. 编辑页：

   • 两 Tab 设计（基础设置 + 参数配置）
   • VxeGrid inline-editable 参数编辑
   • SQL 编辑器（CodeMirror + SQL Server 语法高亮）
   • 版本管理字段（api_version，支持 v1/v2）

3. 前端弹窗：

   • 从表导入弹窗
   • 基础设置表单（包含缓存配置）
   • 版本选择下拉框

Phase 3：测试和文档 + 监控统计（第 4 周）

目标：增强可用性 + 监控功能

1. API 测试功能：

   • Service：testApi 方法
   • 执行日志和错误处理
   • 前端测试弹窗

2. API 文档预览：

   • Service：generateApiDoc 方法
   • 前端文档预览弹窗

3. 监控统计功能：

   • 创建 erp_api_stats 表（记录调用次数、响应时间、错误率）
   • ApiMonitorService：记录每次调用（调用时间、参数、响应时间）
   • 统计接口：getApiStats、getApiErrorLog
   • 前端统计页面：调用次数图表、响应时间趋势

4. 优化体验：

   • JSON 格式化展示
   • 执行时间统计
   • 调用统计可视化

Phase 4：安全增强和稳定性（第 5 周）

目标：提升安全性和稳定性

1. 安全增强：

   • SQL 安全验证（SqlValidator）
   • 权限控制集成
   • 参数验证

2. 缓存优化：

   • Redis 缓存键生成策略
   • 缓存过期处理（TTL）
   • 缓存命中率统计

3. 同步表结构：

   • syncTableStructure 方法

4. 状态管理：

   • 启用/禁用功能
   • API 状态验证

5. 监控告警：

   • 响应时间阈值告警
   • 错误率告警
   • 调用异常记录

---

七、关键文件清单

后端关键文件（需创建）

1. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/service/impl/DynamicApiExecutor.java - 核心 SQL 执行引擎
2. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/service/impl/ApiCacheService.java - Redis 缓存服务
3. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/service/impl/ApiMonitorService.java - 监控统计服务
4. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/controller/DynamicApiController.java - 动态路由入口
5. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/service/impl/ErpApiServiceImpl.java - API 配置管理核心业务
6. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/controller/ErpApiController.java - API 配置管理 Controller
7. /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/util/SqlValidator.java - SQL 安全验证工具

前端关键文件（需创建）

1. /data/hzhub/hzhub-admin/apps/web-antd/src/views/erp/api/index.vue - API 配置列表页
2. /data/hzhub/hzhub-admin/apps/web-antd/src/views/erp/api/edit-api.vue - 编辑页（两 Tab）
3. /data/hzhub/hzhub-admin/apps/web-antd/src/views/erp/api/test-modal.vue - API 测试弹窗
4. /data/hzhub/hzhub-admin/apps/web-antd/src/views/erp/api/stats-modal.vue - 统计监控弹窗
5. /data/hzhub/hzhub-admin/apps/web-antd/src/api/erp/api/index.ts - API 函数定义

需复用的现有文件

• /data/hzhub/hzhub-erp/src/main/java/org/hzhub/erp/controller/ErpExploreController.java - 数据库探查功能
• /data/hzhub/hzhub-admin/apps/web-antd/src/views/tool/gen/edit-gen.vue - 编辑页设计参考
• /data/hzhub/hzhub-admin/apps/web-antd/src/views/system/tenant/index.vue - CRUD 页面参考

---

八、验证方式

8.1 后端测试

1. 单元测试：

   • DynamicApiExecutor SQL 执行测试
   • ParamTypeConverter 类型转换测试
   • SqlValidator 安全验证测试

2. 集成测试：

   • 从表导入流程测试
   • API 执行流程测试（完整流程）
   • 权限控制测试

3. 手动测试：

   • 启动 hzhub-erp 服务
   • 访问 Actuator 健康检查：curl http://localhost:8082/actuator/health
   • 测试动态 API：curl http://localhost:8082/erp/dynamic/v1/customer/list?pageNum=1&pageSize=10

8.2 前端测试

1. 页面功能测试：

   • 启动前端：cd hzhub-admin && pnpm dev
   • 访问 API 管理页面：http://localhost:5666/#/erp/api
   • 测试列表查询、新增、编辑、删除功能
   • 测试从表导入功能
   • 测试 API 测试功能

2. API 执行测试：

   • 创建一个测试 API
   • 输入参数执行测试
   • 查看执行结果和执行时间
   • 测试错误场景（错误的 SQL、缺少参数）

8.3 端到端测试

1. 通过网关访问动态 API：

   • 先登录获取 Token
   • 访问：http://localhost:8080/erp/dynamic/v1/customer/list?pageNum=1&pageSize=10
   • 验证返回数据格式和分页信息

2. 权限测试：

   • 创建一个需要权限的 API（require_auth=1, permission_code='erp:test:list')
   • 未登录访问应该返回 401
   • 无权限用户访问应该返回 403

---

九、用户确认的设计决策

根据用户反馈，最终确定的设计决策：

1. 动态路由机制：使用通配符路由（/erp/dynamic/{version}/{apiPath}）

   • 简单稳定，所有动态 API 共享统一前缀
   • 支持版本号（v1/v2），路径自动包含版本

2. SQL 编辑器：基础版本（CodeMirror + SQL Server 语法高亮）

   • 第一版使用代码编辑器 + 语法高亮
   • 快速实现核心功能，后续可扩展可视化构建器

3. 高级功能：第一版实现完整功能

   • Redis 缓存：支持缓存配置、缓存键模板、TTL、缓存清除
   • API 监控：调用统计、响应时间记录、错误日志
   • 版本管理：支持 v1/v2 版本号，可同时运行多版本 API
   • 统计可视化：调用次数图表、响应时间趋势、错误率统计

这些决策已整合到实现步骤和数据库表设计中。

---

十、集成到管理后台的具体方案

10.1 菜单配置

需要在 hzhub-system 的菜单表中添加 ERP 管理菜单（通过 SQL 插入）：

-- ERP 管理菜单（一级菜单）
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time, remark)
VALUES ('ERP管理', 0, 5, '/erp', NULL, 1, 0, 'M', '0', '0', '', 'monitor', 'admin', NOW(), 'ERP API管理目录');

-- API 配置管理菜单（二级菜单）
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time, remark)
VALUES ('API配置', (SELECT menu_id FROM sys_menu WHERE menu_name='ERP管理'), 1, 'api', 'erp/api/index', 1, 0, 'C', '0', '0', 'erp:api:list', 'tool', 'admin', NOW(), 'API配置管理菜单');

-- API 配置按钮权限
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES ('API查询', (SELECT menu_id FROM sys_menu WHERE menu_name='API配置'), 1, '', NULL, 1, 0, 'F', '0', '0', 'erp:api:query', '#', 'admin', NOW());

INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES ('API新增', (SELECT menu_id FROM sys_menu WHERE menu_name='API配置'), 2, '', NULL, 1, 0, 'F', '0', '0', 'erp:api:add', '#', 'admin', NOW());

INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES ('API修改', (SELECT menu_id FROM sys_menu WHERE menu_name='API配置'), 3, '', NULL, 1, 0, 'F', '0', '0', 'erp:api:edit', '#', 'admin', NOW());

INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES ('API删除', (SELECT menu_id FROM sys_menu WHERE menu_name='API配置'), 4, '', NULL, 1, 0, 'F', '0', '0', 'erp:api:remove', '#', 'admin', NOW());

INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES ('API测试', (SELECT menu_id FROM sys_menu WHERE menu_name='API配置'), 5, '', NULL, 1, 0, 'F', '0', '0', 'erp:api:test', '#', 'admin', NOW());

-- API 监控统计菜单（二级菜单）
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, is_cache, menu_type, visible, status, perms, icon, create_by, create_time, remark)
VALUES ('API监控', (SELECT menu_id FROM sys_menu WHERE menu_name='ERP管理'), 2, 'stats', 'erp/stats/index', 1, 0, 'C', '0', '0', 'erp:api:stats', 'monitor', 'admin', NOW(), 'API调用统计监控');

10.2 权限体系集成

• 所有 API 配置管理接口都需要权限验证（通过 Sa-Token）
• 前端按钮使用 v-access:code="['erp:api:add']" 控制权限
• 动态 API 本身的权限通过配置表的 require_auth 和 permission_code 字段控制
• 与现有的系统管理、监控等模块共享统一的 JWT Token

10.3 组件复用

复用 hzhub-admin 的标准组件和适配器：

• useVbenVxeGrid - 表格组件（列表页）
• useVbenForm - 表单组件（搜索、编辑）
• useVbenDrawer / useVbenModal - 抽屉/弹窗组件
• TableSwitch - 状态切换组件
• CodeMirror - SQL 编辑器（复用代码生成器的编辑器）

10.4 API 函数集成

在 /data/hzhub/hzhub-admin/apps/web-antd/src/api/erp/ 目录下新增 API 模块，遵循现有的 API 定义模式：

• 使用 requestClient 统一请求客户端
• 使用 postWithMsg / putWithMsg / deleteWithMsg 自动提示消息
• 定义 TypeScript 类型（model.d.ts）

---

本方案提供了一个完整的 ERP API 管理平台设计，完全集成到管理后台中，实现统一管理。从数据库表设计、后端架构、前端界面到安全防护都有详细规划，包含缓存、监控、版本管理等完整功能。实现步骤按优先级分阶段推进，确保核心功能优先完成，逐步增强功能和安全性。