# Augment 代码生成审查清单

## 📋 **生成前检查**

### **Swagger 文档验证**
- [ ] swagger.json 文件格式正确
- [ ] OpenAPI 版本为 3.0.x
- [ ] 所有 $ref 引用都存在对应的定义
- [ ] components/schemas 部分完整
- [ ] 所有接口都有明确的 responses 定义
- [ ] 参数定义完整（name, in, schema）
- [ ] requestBody 定义明确（如果需要）

### **环境准备**
- [ ] Dart SDK 版本 >= 3.0.0
- [ ] 依赖包版本正确
- [ ] 网络连接正常（如果从 URL 获取 swagger）
- [ ] 输出目录权限正确

---

## 🔧 **生成过程检查**

### **命令执行**
- [ ] 使用正确的生成命令
- [ ] 参数配置正确
- [ ] 没有错误或警告信息
- [ ] 生成统计信息合理

### **文件生成**
- [ ] API 文件按 tag 正确分组
- [ ] 模型文件命名规范
- [ ] 目录结构正确
- [ ] index.dart 文件更新

---

## ✅ **生成后验证**

### **API 接口检查**

#### **文件结构**
- [ ] 文件头注释完整
- [ ] 导入语句正确且按需导入
- [ ] 类名符合 PascalCase 规范
- [ ] 方法名符合 camelCase 规范

#### **方法定义**
- [ ] HTTP 方法注解正确（@GET, @POST, @PUT, @DELETE）
- [ ] 路径定义与 swagger 一致
- [ ] 返回类型正确提取
- [ ] 参数定义完整且正确

```dart
// ✅ 正确的方法定义示例
/// 用户登录
@POST('/api/v1/Login/userLogin')
Future<BaseResult<UserLoginResult>> userLogin(
  @Body() LoginRequest request
);

// ❌ 错误示例
@POST('/api/v1/Login/userLogin')
Future<BaseResult<TaskInfoResult>> userLogin(  // 错误：不存在的类型
  @Body() Map<String, dynamic> request         // 错误：swagger 中没有定义
);
```

#### **参数检查**
- [ ] 路径参数使用 @Path 注解
- [ ] 查询参数使用 @Query 注解
- [ ] 请求体参数使用 @Body 注解
- [ ] 参数类型与 swagger 定义一致
- [ ] 可空性正确（? 标记）
- [ ] 没有多余的参数

#### **返回类型检查**
- [ ] 使用 BaseResult 包装
- [ ] 分页接口使用 BasePageResult
- [ ] 健康检查接口返回 void
- [ ] 泛型类型存在于 swagger 中
- [ ] 没有硬编码推断的类型

#### **导入检查**
- [ ] 基础类型导入正确
- [ ] 分页类型按需导入
- [ ] 模型类型导入完整
- [ ] 没有未使用的导入
- [ ] 导入路径正确

### **数据模型检查**

#### **类定义**
- [ ] 类名符合 PascalCase 规范
- [ ] @JsonSerializable 注解正确
- [ ] 注解参数配置正确（checked: true, includeIfNull: false）

#### **属性定义**
- [ ] 属性名符合 camelCase 规范
- [ ] 类型映射正确（string -> String, integer -> int）
- [ ] 可空性严格按照 nullable 字段
- [ ] 注释信息完整
- [ ] final 修饰符正确使用

```dart
// ✅ 正确的属性定义
/// 用户ID
final int id;

/// 用户名
final String username;

/// 昵称（可空）
final String? nickname;  // swagger 中 "nullable": true

// ❌ 错误示例
final String? username;  // 错误：swagger 中没有 "nullable": true
final String nickname;   // 错误：swagger 中有 "nullable": true
```

#### **构造函数检查**
- [ ] 使用 const 构造函数
- [ ] 非空字段标记为 required
- [ ] 可空字段不使用 required
- [ ] 参数顺序合理

#### **序列化方法**
- [ ] fromJson 工厂方法存在
- [ ] toJson 方法存在
- [ ] part 文件引用正确
- [ ] 生成的方法名正确

### **代码质量检查**

#### **静态分析**
- [ ] dart analyze 无错误
- [ ] dart analyze 无警告
- [ ] 代码格式化正确
- [ ] 命名规范一致

#### **类型安全**
- [ ] 避免使用 dynamic
- [ ] 泛型类型明确
- [ ] 可空性处理正确
- [ ] 类型转换安全

#### **性能考虑**
- [ ] 使用 const 构造函数
- [ ] 避免不必要的对象创建
- [ ] 导入优化
- [ ] 内存使用合理

---

## 🚫 **常见问题检查**

### **类型相关**
- [ ] 没有生成不存在的类型（如 TaskInfoResult）
- [ ] 没有硬编码的类型映射
- [ ] 没有基于路径关键词的推断
- [ ] 没有基于 tag 的类型推断

### **参数相关**
- [ ] 没有添加 swagger 中未定义的参数
- [ ] 没有遗漏 swagger 中定义的参数
- [ ] 参数位置正确（path, query, body）
- [ ] 参数类型正确

### **导入相关**
- [ ] 没有循环导入
- [ ] 没有未使用的导入
- [ ] 没有缺失的导入
- [ ] 导入路径正确

### **命名相关**
- [ ] 文件名符合 snake_case
- [ ] 类名符合 PascalCase
- [ ] 方法名符合 camelCase
- [ ] 变量名符合 camelCase

---

## 🔄 **集成测试**

### **构建测试**
- [ ] dart pub get 成功
- [ ] dart pub run build_runner build 成功
- [ ] 生成的 .g.dart 文件正确
- [ ] 没有构建错误或警告

### **运行时测试**
- [ ] API 调用正常
- [ ] 序列化/反序列化正常
- [ ] 类型转换正确
- [ ] 错误处理正确

### **兼容性测试**
- [ ] Dart 版本兼容
- [ ] Flutter 版本兼容
- [ ] 依赖包版本兼容
- [ ] 平台兼容性

---

## 📝 **文档检查**

### **代码注释**
- [ ] 类注释完整
- [ ] 方法注释完整
- [ ] 属性注释完整
- [ ] 特殊逻辑有说明

### **生成信息**
- [ ] 文件头信息正确
- [ ] 版本信息正确
- [ ] 生成时间标记
- [ ] 来源信息明确

---

## ✍️ **审查签名**

**审查者**: _______________  
**审查日期**: _______________  
**审查结果**: [ ] 通过 [ ] 需要修改 [ ] 拒绝  
**备注**: _______________

---

**检查清单版本**: v2.0  
**最后更新**: 2025-01-24