# 符号表分析与 DTO 生成需求

## 元数据
- 需求编号：014-2
- 创建时间：2026-01-26
- 创建人：SSOT 架构师
- 状态：已完成
- 优先级：高
- 父需求：[REQ-014](../REQ-014.md)
- 关联代码：`com.sforce.soap.tooling.SymbolTable`, `com.sforce.soap.tooling.ExternalConstructor`

## 需求概述
利用 Tooling API 的 `SymbolTable` 功能，解析 Apex 类的内部结构（内部类、方法、变量），为 Java 端自动生成强类型的 DTO（Data Transfer Object），解决 Partner API 只能传输扁平 SObject 的限制。
**注意**：`SymbolTable` 仅在 Tooling API 中可用，需确保已通过 REQ-014-1 完成 Tooling API 连接。

## 目标
1.  **符号表获取**：通过 `ToolingConnection` 查询 Apex 类的 `SymbolTable`。
2.  **结构解析**：解析 `SymbolTable` 中的 `innerClasses`、`methods` 和 `variables`。
3.  **DTO 生成**：基于解析结果生成 Java POJO 源代码。

## 功能需求
### 核心功能
1.  **符号表获取 (SymbolTable Retriever)**
    - 接口：`getSymbolTable(String className)`
    - 实现：
        - 执行 SOQL: `SELECT SymbolTable FROM ApexClass WHERE Name = 'className'`
        - **关键点**：`SymbolTable` 字段在未编译或无效状态下可能为 null，需处理重新编译逻辑（如果必要）。

2.  **结构解析器 (Structure Parser)**
    - **输入**：`com.sforce.soap.tooling.SymbolTable` 对象。
    - **解析逻辑**：
        - 遍历 `innerClasses`：映射为 Java 的静态内部类。
        - 遍历 `variables`：映射为 Java 字段（注意类型转换：Apex `Decimal` -> Java `BigDecimal`）。
        - 遍历 `methods`：提取 `ExternalMethod` 信息（仅针对 `webservice` 关键字修饰的方法）。

3.  **Java 代码生成器 (Java Code Generator)**
    - **模板引擎**：建议使用 JavaPoet 或 FreeMarker。
    - **输出**：生成符合 Java Bean 规范的源代码，包含 Getter/Setter。
    - **注解支持**：自动添加 Jackson `@JsonProperty` 或 Gson `@SerializedName` 注解。

### 次要功能
- **外部构造函数支持**：处理 `ExternalConstructor`，虽然在 DTO 场景较少用，但需预留扩展。

## 非功能需求
- **类型安全**：生成的 Java 代码应尽可能保留 Apex 的强类型特性。
- **容错性**：对于无法映射的复杂类型（如 `Map<Id, SObject>`），降级为 `Object` 或 `Map<String, Object>`。

## 技术约束
- **依赖**：必须引用 `com.sforce.soap.tooling.SymbolTable` 类。
- **性能**：`SymbolTable` 字段较大，查询时应避免 `SELECT *`，仅查询必要字段。

## 成功标准
1.  能够查询到 `UserSummary` Apex 类的 `SymbolTable`。
2.  生成的 Java 类 `UserSummary.java` 包含 `userName`, `totalSales` 等字段，且类型正确。
3.  生成的 Java 类能够成功反序列化来自 Apex WebService 的响应 JSON。

## 相关文档
- [设计文档](../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)
- [变更日志](../changelog/2026-01-27-014-2-changelog.md)