new

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

@@ -0,0 +1,176 @@
+# 组合包动态处理机制说明
+
+## 🎉 重大更新
+
+组合包系统现在支持**动态处理机制**！这意味着：
+- ✅ **零编码**：大部分组合包无需编写任何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控制响应顺序
+- **错误隔离**：每个子产品的错误独立处理
+
+现在，创建一个新的组合包就像配置数据库一样简单！🎉