# asdm-ddl-context-analysis action 使用说明

## 目的
本指令指导 AI 模型分析数据库 DDL（数据定义语言）文件，并为数据库架构生成全面的上下文文档。

## 语言检测

在分析任何 DDL 文件之前，必须检测并使用当前环境的响应语言：

1. **检测响应语言**：分析环境设置以确定主要语言：
   - 检查系统/用户语言设置或环境配置
   - 识别项目文档和注释中使用的主要语言
   - 根据工作区上下文确定语言偏好

2. **应用语言一致性**：确保所有生成的上下文文件使用检测到的语言：
   - 所有 markdown 文件、注释和文档使用相同语言
   - 在所有生成的上下文文件中保持语言一致性
   - 遵循检测到的语言的写作约定和格式

3. **支持的语言**：
   - 英语 (en)
   - 中文 (zh)
   - 根据环境检测需要其他语言

**重要提示**：语言检测是任何 DDL 分析之前的**第一步**。所有输出必须在整个过程中始终使用检测到的语言。

## DDL 上下文分析步骤

### 1. 定位 DDL 文件
扫描工作区以识别所有 DDL 文件。默认情况下，DDL 文件位于 `pre-context/**/*` 目录。

**搜索模式**：
- 查找包含 DDL 语句的 `.sql` 扩展名文件
- 搜索包含 `CREATE TABLE`、`ALTER TABLE`、`DROP TABLE` 语句的文件
- 检查常见位置的数据库模式文件

### 2. 分析 DDL 结构
对每个 DDL 文件进行结构分析：

#### 2.1 表分析
- 识别所有表定义
- 提取表名、列、数据类型、约束
- 分析主键、外键、索引
- 识别唯一约束和默认值

#### 2.2 关系分析
- 映射表之间的外键关系
- 识别一对一、一对多、多对多关系
- 分析关系基数和约束

#### 2.3 模式元数据
- 提取数据库引擎规范
- 识别字符集和排序规则
- 分析表级注释和约束

### 3. 生成数据模型文档

#### 3.1 创建实体关系图
使用 Mermaid 语法生成全面的 ER 图：

```mermaid
erDiagram
    [根据实际DDL生成实体关系图]
    [包含所有表、字段和关系]
```

#### 3.2 实体定义
为每个表创建详细的实体定义：

**表结构**：
- 表名和用途
- 带数据类型和约束的列定义
- 主键和外键关系
- 索引和唯一约束

**实体接口**（TypeScript/Java 风格）：
```typescript
interface [实体名称] {
  [根据DDL生成接口定义]
}
```

### 4. 业务领域分析

#### 4.1 领域识别
基于表关系和命名模式，识别业务领域：

- **用户管理领域**：与用户、认证、配置文件相关的表
- **订单管理领域**：用于订单、订单项、支付的表
- **产品目录领域**：用于产品、类别、库存的表
- **系统管理领域**：用于日志、配置、设置的表

#### 4.2 领域关系
映射已识别领域之间的关系：

```mermaid
graph LR
    [根据表关系生成领域依赖图]
```

### 5. 数据验证规则
从 DDL 约束中提取并记录数据验证规则：

#### 5.1 字段级约束
- 数据类型约束（INT、VARCHAR、DATE 等）
- 长度约束（VARCHAR(255) 等）
- 可空性约束（NOT NULL）
- 默认值

#### 5.2 表级约束
- 主键约束
- 外键关系
- 唯一约束
- 检查约束

### 6. 数据访问模式

#### 6.1 常见查询模式
基于索引和关系识别可能的查询模式：
- 通过邮箱/用户名查找用户
- 按类别搜索产品
- 按用户查看订单历史
- 库存管理查询

#### 6.2 性能考虑
- 分析现有索引以进行优化
- 识别可能缺失的索引
- 记录查询性能建议

### 7. 生成单一上下文文件

将所有分析结果生成到单一的综合文档中：

**输出文件**：`.asdm/contexts/ddl-context.md`

**内容结构**：
1. **数据库概览**
   - 数据库类型和版本
   - 表总数和关系
   - 业务领域摘要

2. **实体关系图**
   - 完整的 ER 图
   - 表关系可视化

3. **实体定义**
   - 详细的表描述
   - 列定义和约束
   - 关系映射

4. **业务领域分析**
   - 已识别的业务领域
   - 领域关系和依赖

5. **数据验证规则**
   - 字段级约束
   - 表级约束
   - 业务规则验证

6. **数据访问模式**
   - 常见查询模式
   - 性能考虑
   - 索引优化建议

### 8. 质量保证

#### 8.1 验证检查
- 验证 DDL 中的所有表都已记录
- 确保关系映射准确
- 确认约束文档完整

#### 8.2 一致性审查
- 检查所有文档中的术语一致性
- 确保语言一致性（使用检测到的语言）
- 根据实际 DDL 验证图表准确性

## 使用示例

### 示例 1：分析 DDL 文件
```bash
/asdm-ddl-context-analysis
# 分析 pre-context/*/ 目录下的所有DDL文件
# 生成完整的数据模型文档
```

### 示例 2：模式变更后更新
```bash
# 当DDL文件更新后，重新分析
/asdm-ddl-context-analysis
# 更新现有的数据模型文档
```

## 输出结构

```
.asdm/contexts/
└── ddl-context.md                    # 单一的DDL上下文文档
```

## 重要说明

1. **语言一致性**：所有生成的内容必须使用语言检测步骤中检测到的语言
2. **准确性**：DDL 分析必须准确并反映实际的数据库模式
3. **完整性**：记录 DDL 文件中找到的所有表、关系和约束
4. **简洁性**：所有内容输出到单一文件，便于查阅和维护
5. **集成性**：确保 DDL 上下文与现有项目上下文正确集成

## 错误处理

- 如果未找到 DDL 文件，提供清晰的放置位置指导
- 如果 DDL 语法无效，报告具体的解析错误
- 如果关系不明确，记录假设并寻求澄清

---

*此 DDL 上下文分析 action 使 AI 模型能够全面理解数据库模式，支持更好的代码生成和数据感知开发。*