tyapi-server/docs/组合包动态处理机制说明.md

# 组合包动态处理机制说明

## 🎉 重大更新

组合包系统现在支持**动态处理机制**！这意味着：
- ✅ **零编码**：大部分组合包无需编写任何Go代码
- ✅ **配置驱动**：只需在数据库配置即可立即使用
- ✅ **灵活扩展**：特殊需求仍可通过自定义处理器实现

## 🔧 工作原理

### 处理优先级
1. **自定义处理器优先**：如果注册了专门的处理器，优先使用
2. **通用处理器兜底**：COMB开头的API自动使用通用组合包处理器
3. **数据库驱动**：根据数据库配置自动调用子产品处理器

### 系统架构
```
API请求 (COMBXXXX)
    ↓
优先查找自定义处理器
    ↓ (未找到)
检查是否COMB开头
    ↓ (是)
通用组合包处理器
    ↓
查询数据库获取子产品配置
    ↓
并发调用子产品处理器
    ↓
聚合结果并返回
```

## 📋 使用方法

### 方案1：纯配置组合包（推荐）

**步骤1：创建组合包产品**
```sql
INSERT INTO products (
    id, code, name, description, 
    is_package, is_enabled, is_visible, 
    price, category_id
) VALUES (
    'uuid1', 'COMB1234', '身份验证组合包', '包含身份证二要素和手机三要素验证',
    true, true, true,
    5.00, 'category_id'
);
```

**步骤2：配置子产品**
```sql
INSERT INTO product_package_items (package_id, product_id, sort_order) VALUES 
('uuid1', 'product_id_1', 1),  -- FLXG162A 身份证二要素
('uuid1', 'product_id_2', 2);  -- FLXG54F5 手机三要素
```

**步骤3：直接使用**
```bash
# 立即可用，无需任何代码编写！
POST /api/v1/COMB1234
{
  "id_card": "123456789012345678",
  "name": "张三",
  "mobile_no": "13800138000"
}
```

### 方案2：自定义逻辑组合包

如果需要对结果进行后处理，才需要编写代码：

**步骤1：创建处理器文件**
```go
// internal/domains/api/services/processors/comb/comb1234_processor.go
func ProcessCOMB1234Request(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
    // 参数验证
    var paramsDto dto.COMB1234Req
    if err := json.Unmarshal(params, &paramsDto); err != nil {
        return nil, errors.Join(processors.ErrSystem, err)
    }

    if err := deps.Validator.ValidateStruct(paramsDto); err != nil {
        return nil, errors.Join(processors.ErrInvalidParam, err)
    }

    // 调用组合包服务
    combinedResult, err := deps.CombService.ProcessCombRequest(ctx, params, deps, "COMB1234")
    if err != nil {
        return nil, err
    }

    // 自定义后处理逻辑
    for _, resp := range combinedResult.Responses {
        if resp.ApiCode == "FLXG162A" && resp.Success {
            // 添加自定义字段
            if data, ok := resp.Data.(map[string]interface{}); ok {
                data["processed_by"] = "COMB1234"
            }
        }
    }

    return json.Marshal(combinedResult)
}
```

**步骤2：注册处理器**
```go
// api_request_service.go 中添加
"COMB1234": comb.ProcessCOMB1234Request, // 有自定义逻辑
```

**步骤3：添加DTO（如需要）**
```go
// dto/api_request_dto.go 中添加
type COMB1234Req struct {
    IDCard   string `json:"id_card" validate:"required,validIDCard"`
    Name     string `json:"name" validate:"required,min=1,validName"`
    MobileNo string `json:"mobile_no" validate:"required,min=11,max=11,validMobileNo"`
}
```

## 📊 现有组合包状态

### ✅ 已迁移到动态处理
- **COMB298Y**：删除了专门的处理器文件，现在使用通用处理器

### 🔧 保留自定义处理器
- **COMB86PM**：有特殊逻辑（重命名ApiCode），保留自定义处理器

## 🎯 响应格式

所有组合包都返回统一的响应格式：

```json
{
  "responses": [
    {
      "api_code": "FLXG162A",
      "success": true,
      "data": {
        // 子产品的响应数据
      }
    },
    {
      "api_code": "FLXG54F5", 
      "success": true,
      "data": {
        // 子产品的响应数据
      }
    },
    {
      "api_code": "YYSY4B37",
      "success": false,
      "error": "数据源异常"
    }
  ]
}
```

## 🚀 优势总结

1. **开发效率**：90%的组合包无需编写代码
2. **维护成本**：减少重复代码，统一处理逻辑
3. **业务灵活**：数据库配置即时生效
4. **向后兼容**：现有自定义处理器继续工作
5. **扩展性强**：特殊需求仍可通过自定义处理器实现

## ⚡ 性能特性

- **并发处理**：所有子产品并发调用
- **独立失败**：单个子产品失败不影响其他
- **智能排序**：通过sort_order控制响应顺序
- **错误隔离**：每个子产品的错误独立处理

现在，创建一个新的组合包就像配置数据库一样简单！🎉