# API 文档

## 元数据
- 需求编号：014-2
- 创建时间：2026-01-27
- 创建人：SSOT 架构师
- 版本号：v1.0.0

## API 概述

本 API 提供符号表分析与 DTO 生成功能，利用 Tooling API 的 SymbolTable 功能，解析 Apex 类的内部结构（内部类、方法、变量），为 Java 端自动生成强类型的 DTO（Data Transfer Object），解决 Partner API 只能传输扁平 SObject 的限制。

核心功能包括：
1. 符号表查询：查询指定 Apex 类的符号表信息
2. DTO 生成：基于符号表生成 Java DTO 源代码
3. 批量 DTO 生成：批量生成多个 Apex 类的 Java DTO 源代码

## 接口列表

### 接口 1：获取符号表

- **功能描述**：查询指定 Apex 类的符号表信息，包括内部类、方法、变量等详细信息

- **请求方式**：GET

- **请求路径**：`/tooling/symbol-table/{className}`

- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | className | String | 是 | Apex 类名，路径参数 |
  | orgType | String | 是 | 组织类型，查询参数（如 "source"、"target"、"sandbox"、"production"） |

- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | SymbolTableVo | 符号表信息 VO 对象 |

- **SymbolTableVo 对象结构**：
  | 字段名 | 类型 | 说明 |
  |---------|------|------|
  | className | String | 类名 |
  | innerClassCount | Integer | 内部类数量 |
  | variableCount | Integer | 变量数量 |
  | methodCount | Integer | 方法数量 |
  | status | String | 状态 |

- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "className": "UserSummary",
      "innerClassCount": 2,
      "variableCount": 5,
      "methodCount": 3,
      "status": "success"
    }
  }
  ```

- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "获取符号表失败：类名不存在"
  }
  ```

- **权限要求**：`tooling:symbol-table:query`

- **日志记录**：记录获取符号表的操作日志

### 接口 2：生成 DTO

- **功能描述**：基于指定 Apex 类的符号表生成 Java DTO 源代码

- **请求方式**：POST

- **请求路径**：`/tooling/symbol-table/generate-dto`

- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | className | String | 是 | Apex 类名 |
  | packageName | String | 否 | 包名，默认为 "com.datai.generated" |
  | includeInnerClasses | boolean | 否 | 是否包含内部类，默认为 true |
  | includeMethods | boolean | 否 | 是否包含方法，默认为 true |
  | orgType | String | 是 | 组织类型，查询参数（如 "source"、"target"、"sandbox"、"production"） |

- **请求示例**：
  ```json
  {
    "className": "UserSummary",
    "packageName": "com.datai.generated",
    "includeInnerClasses": true,
    "includeMethods": true
  }
  ```

- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | GenerateDtoResponse | DTO 生成响应对象 |

- **GenerateDtoResponse 对象结构**：
  | 字段名 | 类型 | 说明 |
  |---------|------|------|
  | className | String | 类名 |
  | javaCode | String | Java 源代码 |
  | filePath | String | 文件路径（如果保存到文件系统） |
  | success | boolean | 是否成功 |
  | message | String | 提示信息 |

- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "className": "UserSummary",
      "javaCode": "package com.datai.generated;\n\nimport lombok.Data;\n\n@Data\npublic class UserSummary {\n    private String userName;\n    private BigDecimal totalSales;\n    // ...其他字段\n}",
      "filePath": "datai-salesforce-tooling/src/main/java/com/datai/generated/UserSummary.java",
      "success": true,
      "message": "DTO 生成成功"
    }
  }
  ```

- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "生成 DTO 失败：符号表获取失败"
  }
  ```

- **权限要求**：`tooling:symbol-table:generate`

- **日志记录**：记录生成 DTO 的操作日志

### 接口 3：批量生成 DTO

- **功能描述**：批量生成多个 Apex 类的 Java DTO 源代码

- **请求方式**：POST

- **请求路径**：`/tooling/symbol-table/generate-dto-batch`

- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | classNames | List<String> | 是 | Apex 类名列表 |
  | packageName | String | 否 | 包名，默认为 "com.datai.generated" |
  | includeInnerClasses | boolean | 否 | 是否包含内部类，默认为 true |
  | includeMethods | boolean | 否 | 是否包含方法，默认为 true |
  | orgType | String | 是 | 组织类型，查询参数（如 "source"、"target"、"sandbox"、"production"） |

- **请求示例**：
  ```json
  {
    "classNames": ["UserSummary", "OrderSummary", "ProductSummary"],
    "packageName": "com.datai.generated",
    "includeInnerClasses": true,
    "includeMethods": true
  }
  ```

- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | List<GenerateDtoResponse> | DTO 生成响应对象列表 |

- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": [
      {
        "className": "UserSummary",
        "javaCode": "package com.datai.generated;\n\nimport lombok.Data;\n\n@Data\npublic class UserSummary {\n    private String userName;\n    private BigDecimal totalSales;\n    // ...其他字段\n}",
        "filePath": "datai-salesforce-tooling/src/main/java/com/datai/generated/UserSummary.java",
        "success": true,
        "message": "DTO 生成成功"
      },
      {
        "className": "OrderSummary",
        "javaCode": "package com.datai.generated;\n\nimport lombok.Data;\n\n@Data\npublic class OrderSummary {\n    private String orderId;\n    private BigDecimal totalAmount;\n    // ...其他字段\n}",
        "filePath": "datai-salesforce-tooling/src/main/java/com/datai/generated/OrderSummary.java",
        "success": true,
        "message": "DTO 生成成功"
      },
      {
        "className": "ProductSummary",
        "javaCode": "package com.datai.generated;\n\nimport lombok.Data;\n\n@Data\npublic class ProductSummary {\n    private String productId;\n    private String productName;\n    // ...其他字段\n}",
        "filePath": "datai-salesforce-tooling/src/main/java/com/datai/generated/ProductSummary.java",
        "success": true,
        "message": "DTO 生成成功"
      }
    ]
  }
  ```

- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "批量生成 DTO 失败：部分类名不存在"
  }
  ```

- **权限要求**：`tooling:symbol-table:generate`

- **日志记录**：记录批量生成 DTO 的操作日志

## 错误码

| 错误码 | 说明 | 解决方案 |
|--------|------|---------|
| 200 | 操作成功 | - |
| 500 | 服务器内部错误 | 检查服务器日志，联系管理员 |
| 401 | 未授权 | 检查用户权限，确保具有相应的权限 |
| 403 | 禁止访问 | 检查用户权限，确保具有相应的权限 |
| 404 | 资源不存在 | 检查类名是否正确，确保类名存在 |

## 相关文档

- [需求文档](../requirements/REQ-014-2.md)
- [设计文档](../design/2026-01-27-014-2-符号表分析与DTO生成-设计.md)
- [决策记录](../decisions/adr/2026-01-27-014-2-ADR-符号表分析与DTO生成技术选型.md)
- [提示词文档](../prompts/2026-01-27-014-2-prompt-符号表分析与DTO生成.md)
- [复盘文档](../retros/2026-01-27-014-2-retro.md)
- [变更日志](../changelog/2026-01-27-014-2-changelog.md)