# 产品API配置管理功能说明

## 功能概述

产品API配置管理功能允许管理员为每个产品配置API接口的请求参数、响应字段和响应示例，这些配置将用于前端的在线调试功能。

## 功能特性

### 1. 请求参数配置
- **参数名称**: 显示给用户的参数名称（如：姓名）
- **字段名**: API接口中使用的字段名（如：name）
- **参数类型**: 支持文本、数字、密码、邮箱、手机号、身份证等类型
- **是否必填**: 标识该参数是否为必填项
- **参数示例**: 提供给用户的输入示例
- **验证规则**: 正则表达式验证规则
- **参数描述**: 参数的详细说明

### 2. 响应字段配置
- **字段名称**: 显示给用户的字段名称（如：姓名）
- **字段路径**: JSON响应中的字段路径（如：data.name）
- **字段类型**: 支持字符串、数字、布尔值、对象、数组等类型
- **是否必填**: 标识该字段是否在响应中必填
- **字段示例**: 字段的示例值
- **字段描述**: 字段的详细说明

### 3. 响应示例
- **JSON格式**: 完整的API响应示例
- **实时验证**: 确保输入的JSON格式正确
- **格式化显示**: 自动格式化JSON内容

## 使用方法

### 1. 访问产品管理页面
1. 登录管理员账户
2. 进入"产品管理"页面
3. 在产品列表中找到需要配置的产品

### 2. 配置API
1. 点击产品行的"配置API"按钮
2. 在弹出的配置窗口中：
   - 查看产品基本信息
   - 添加/编辑请求参数
   - 添加/编辑响应字段
   - 输入JSON响应示例
3. 点击"创建"或"更新"保存配置

### 3. 配置示例

#### 请求参数配置示例
```json
[
  {
    "name": "姓名",
    "field": "name",
    "type": "text",
    "required": true,
    "description": "用户真实姓名",
    "example": "张三",
    "validation": "^[\\u4e00-\\u9fa5]{2,4}$"
  },
  {
    "name": "身份证号",
    "field": "id_card",
    "type": "idcard",
    "required": true,
    "description": "用户身份证号码",
    "example": "110101199001011234",
    "validation": "^[1-9]\\d{5}(18|19|20)\\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx]$"
  }
]
```

#### 响应字段配置示例
```json
[
  {
    "name": "结果",
    "path": "result",
    "type": "string",
    "required": true,
    "description": "查询结果",
    "example": "success"
  },
  {
    "name": "数据",
    "path": "data",
    "type": "object",
    "required": false,
    "description": "查询结果数据",
    "example": "{}"
  }
]
```

#### 响应示例
```json
{
  "result": "success",
  "code": 200,
  "message": "查询成功",
  "data": {
    "name": "张三",
    "id_card": "110101199001011234",
    "mobile": "13800138000",
    "status": "正常",
    "query_time": "2024-01-01 12:00:00"
  }
}
```

## 技术实现

### 后端架构
- **实体层**: `ProductApiConfig` 实体
- **仓库层**: `ProductApiConfigRepository` 接口和实现
- **领域服务层**: `ProductApiConfigService` 业务逻辑
- **应用服务层**: `ProductApiConfigApplicationService` 业务流程
- **HTTP层**: `ProductAdminHandler` 接口处理

### 前端架构
- **组件**: `ProductApiConfigDialog.vue` 配置弹窗
- **页面**: 集成到产品管理页面
- **API**: 通过 `productAdminApi` 调用后端接口

### 数据库设计
```sql
CREATE TABLE product_api_configs (
  id VARCHAR(36) PRIMARY KEY,
  product_id VARCHAR(36) NOT NULL UNIQUE,
  request_params JSON NOT NULL,
  response_fields JSON NOT NULL,
  response_example JSON NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted_at TIMESTAMP NULL,
  FOREIGN KEY (product_id) REFERENCES products(id)
);
```

## 初始化脚本

项目提供了初始化脚本 `scripts/init_product_api_configs.go`，可以为现有产品创建默认的API配置：

```bash
cd tyapi-server-gin
go run scripts/init_product_api_configs.go
```

## 注意事项

1. **唯一性**: 每个产品只能有一个API配置
2. **JSON格式**: 响应示例必须是有效的JSON格式
3. **字段路径**: 响应字段路径使用点号分隔（如：data.name）
4. **验证规则**: 支持正则表达式验证规则
5. **权限控制**: 只有管理员可以配置API

## 扩展功能

未来可以考虑添加的功能：
1. **配置模板**: 提供常用的配置模板
2. **批量导入**: 支持批量导入配置
3. **版本管理**: 支持配置版本管理
4. **测试功能**: 集成API测试功能
5. **文档生成**: 自动生成API文档