120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
# 会话记录 - 描述和列出元数据
|
||
|
||
## 元数据
|
||
- 需求编号：003-08
|
||
- 需求名称：描述和列出元数据
|
||
- 开始时间：2026-02-03
|
||
- 结束时间：2026-02-03
|
||
- 当前阶段：阶段 4：数据库结构生成
|
||
|
||
## 阶段记录
|
||
|
||
### 阶段 1：需求定义
|
||
- 状态：已完成
|
||
- 需求文档：[2026-01-28-003-08-描述和列出元数据.md](../requirements/sub/2026-01-28-003-08-描述和列出元数据.md)
|
||
|
||
### 阶段 2：方案设计
|
||
- 状态：已完成
|
||
- 设计文档：[2026-02-03-003-08-描述和列出元数据-设计.md](../design/2026-02-03-003-08-描述和列出元数据-设计.md)
|
||
- 关键设计决策：
|
||
1. **架构设计**：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
|
||
2. **核心功能**：
|
||
- 描述元数据：`describeMetadata(apiVersion)` → `DescribeMetadataResult`
|
||
- 列出元数据：`listMetadata(queries)` → `ListMetadataResult[]`
|
||
3. **技术选型**：
|
||
- Spring Boot 2.7+ (配合若依框架)
|
||
- MyBatis Plus 进行数据库交互
|
||
- Salesforce Metadata API (WSC/Partner JAR)
|
||
- MySQL 8.0 数据库
|
||
4. **数据模型**：创建 `datai_metadata_describe` 表，包含 14 个字段和 2 个索引
|
||
- 字段：id, operation_type, metadata_type, folder, server_version, namespace_prefix, metadata_object_count, result_count, status, error_message, query_time, user_id, create_time, created_by
|
||
- 索引：idx_metadata_describe_op_type, idx_metadata_describe_time
|
||
5. **核心算法**：
|
||
- **描述元数据**：获取连接 → 调用 `describeMetadata(apiVersion)` → 记录元数据对象数量 → 保存审计日志 → 返回结果
|
||
- **列出元数据**：获取连接 → 处理批量查询（最多3个Query）→ 调用 `listMetadata(queries)` → 对每个Query记录审计日志 → 返回结果
|
||
6. **接口设计**：3 个 REST API 接口
|
||
- `GET /salesforce/metadata/describe?apiVersion={double}` - 描述元数据
|
||
- `POST /salesforce/metadata/list` - 列出元数据
|
||
- `GET /salesforce/metadata/describe/history` - 查询历史
|
||
7. **实体类设计**：`MetadataDescribeEntity` 使用 MyBatis Plus 注解映射数据库表
|
||
8. **异常处理**：
|
||
- 捕获 `ConnectionException`，转换为 `SalesforceAuthException` 或 `SalesforceOperationException`
|
||
- 即使 API 调用失败，也要记录失败状态到数据库
|
||
9. **性能优化**：
|
||
- 批量查询处理：Metadata API 限制每次调用最多3个Query，需要分批处理
|
||
- 审计日志：对每个Query记录一条审计日志，保证审计细粒度
|
||
10. **安全设计**：
|
||
- 接口需要鉴权（依赖 Spring Security / 若依框架）
|
||
- 敏感信息（如 Session ID）不记录在日志或数据库中
|
||
|
||
### 阶段 3：方案决策
|
||
- 状态：已完成
|
||
- 决策记录：[2026-02-03-003-08-ADR-描述和列出元数据技术选型.md](../decisions/2026-02-03-003-08-ADR-描述和列出元数据技术选型.md)
|
||
- 关键决策：
|
||
1. **API 交互方式**：直接调用 WSC (Web Service Connector)
|
||
- 使用 `MetadataConnection.describeMetadata()` 和 `MetadataConnection.listMetadata()` 方法
|
||
- 理由：类型安全，与项目其他模块保持一致
|
||
2. **ListMetadata 批处理策略**：服务层自动分批
|
||
- Service 层接收 `List<ListMetadataQuery>`，自动拆分为多个子列表（每组 3 个）
|
||
- 理由：客户端无需关注 API 限制，提升用户体验
|
||
3. **审计记录策略**：同步数据库审计
|
||
- 调用 API 后立即将查询信息写入 `datai_metadata_describe` 表
|
||
- 理由：数据完整性，确保每次 API 调用都有据可查
|
||
|
||
### 阶段 4：数据库结构生成
|
||
- 状态：已完成（重新生成）
|
||
- 涉及数据库变更：是
|
||
- SQL 脚本：[2026-02-03-003-08-describe-metadata.sql](../sql/2026-02-03-003-08-describe-metadata.sql)
|
||
- 重新生成时间：2026-02-04
|
||
- 重新生成原因：原 SQL 文件丢失，重新进入阶段 4 生成
|
||
- 数据库变更内容：
|
||
1. **创建表 `datai_metadata_describe`**
|
||
- 用途：元数据查询审计表
|
||
- 引擎：InnoDB
|
||
- 字符集：utf8mb4
|
||
- 字段数：18 个
|
||
- 索引数：5 个
|
||
2. **字段详情**：
|
||
- `id` (BIGINT, PRIMARY KEY, AUTO_INCREMENT) - 主键
|
||
- `operation_type` (VARCHAR(20), NOT NULL) - 操作类型（describe/list）
|
||
- `metadata_type` (VARCHAR(50)) - 元数据类型
|
||
- `folder` (VARCHAR(255)) - 文件夹
|
||
- `server_version` (VARCHAR(50)) - 服务器版本
|
||
- `namespace_prefix` (VARCHAR(50)) - 命名空间前缀
|
||
- `metadata_object_count` (INT, DEFAULT 0) - 元数据对象数量
|
||
- `result_count` (INT, DEFAULT 0) - 结果数量
|
||
- `status` (VARCHAR(50), NOT NULL) - 状态（Succeeded/Failed）
|
||
- `error_message` (TEXT) - 错误信息
|
||
- `query_time` (DATETIME, NOT NULL) - 查询时间
|
||
- `user_id` (VARCHAR(50)) - 操作用户ID
|
||
- `create_time` (DATETIME, NOT NULL, DEFAULT CURRENT_TIMESTAMP) - 创建时间
|
||
- `created_by` (VARCHAR(64)) - 创建者
|
||
- `update_time` (DATETIME, NOT NULL, DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP) - 更新时间
|
||
- `update_by` (VARCHAR(64)) - 更新者
|
||
- `del_flag` (TINYINT(1), DEFAULT 0) - 删除标志
|
||
3. **索引设计**：
|
||
- `idx_metadata_describe_op_type` (`operation_type`) - 按操作类型查询
|
||
- `idx_metadata_describe_time` (`query_time`) - 按查询时间查询
|
||
- `idx_metadata_describe_type` (`metadata_type`) - 按元数据类型查询
|
||
- `idx_metadata_describe_user` (`user_id`) - 按操作用户查询
|
||
- `idx_metadata_describe_status` (`status`) - 按状态查询
|
||
|
||
## 待完成阶段
|
||
- [x] 阶段 1：需求定义
|
||
- [x] 阶段 2：方案设计
|
||
- [x] 阶段 3：方案决策
|
||
- [x] 阶段 4：数据库结构生成
|
||
- [ ] 阶段 5：提示词生成
|
||
- [ ] 阶段 6：代码生成
|
||
- [ ] 阶段 7：会话记录
|
||
- [ ] 阶段 8：变更日志
|
||
- [ ] 阶段 9：复盘和 API 文档
|
||
- [ ] 阶段 10：代码提交
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-003-08-描述和列出元数据.md)
|
||
- [设计文档](../design/2026-02-03-003-08-描述和列出元数据-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-003-08-ADR-描述和列出元数据技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-003-08-describe-metadata.sql)
|
||
- [连接管理设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|