# 重构检查清单

生成时间：2025-11-22（请在执行前更新）

| 状态 | 文件 | 主要痛点 | 首要行动 |
| --- | --- | --- | --- |
| [x]（2025-11-22：拆分 models 子模块 + 补齐 SwaggerDocument/path 覆盖测试，全量 `dart test` 通过） | lib/core/models.dart（2550 行） | 所有 Swagger 数据结构堆在同一文件，路径解析丢失同一路径的不同方法。 | 拆分为 `models/` 子模块（服务器/路径/组件等），为路径增加 `path + method` 组合键并补充 `toJson`/序列化能力。 |
| [x]（2025-11-22：拆分文档合并、过滤与输出服务，GenerateCommand 仅负责编排） | lib/commands/generate_command.dart（231 行） | `execute` 过度膨胀，混合网络、合并、文件写入，没有可测试的服务边界。 | 拆出文档合并器、生成任务调度器与文件写入服务，`GenerateCommand` 仅负责参数解析和 orchestration。 |
| [x]（2025-11-22：重构 RetrofitApiGenerator 使用 Mustache 模板） | lib/generators/retrofit_api_generator.dart | 代码生成逻辑硬编码，难以维护和扩展。 | 引入 Mustache 模板引擎，分离数据准备与代码生成逻辑，支持更灵活的定制。 |
| [x]（2025-11-22：构建 ValidationRule/ValidationContext 体系，拆分路径/模型/安全等规则） | lib/validators/schema_validator.dart（1104 行） | 所有校验逻辑耦合在单类中，依赖可变全局状态 `_errors/_warnings`，无法选择性启用规则。 | 构建 `ValidationRule`/`ValidationContext` 体系，拆分路径/模型/安全等规则，结果结构化返回。 |
| [x]（2025-11-22：引入 ConfigRepository 实例，提取 PathResolver） | lib/core/config_loader.dart（641 行） | 静态缓存直接暴露可变 Map，路径查找逻辑与 FileUtils 重复。 | 引入 `ConfigRepository` 实例，返回只读视图；提取公共路径查找工具供 Config/FileUtils 共用。 |
| [x]（2025-11-22：复用 SchemaValidator 结果模型，统一验证逻辑） | lib/utils/type_validator.dart（620 行） | 自定义 `ValidationResult`/`ValidationError` 与其它验证器同名易冲突，且 `_isValidPropertyType` 恒返回 true，实际未验证。 | 将类型验证拆成 `ModelRules`/`PropertyRules` 并复用 schema validator 的结果模型，补齐类型枚举校验与引用完整性。 |
| [x]（2025-11-22：重构为装饰器，复用 SchemaValidator） | lib/validators/enhanced_validator.dart（593 行） | 与 `SchemaValidator` 大量重复规则，仅输出格式不同，维护成本高。 | 做成装饰器：在基础验证通过后由 `ErrorReporter` 转换消息，复用统一规则集。 |
| [x]（2025-11-22：提取 SwaggerFetcher，实现异步 IO 和内容哈希缓存） | lib/parsers/swagger_data_parser.dart（586 行） | 缓存 key 使用 `jsonData.hashCode`，同内容命中率不可控；IO 均为同步调用阻塞事件循环。 | 抽出 `SwaggerFetcher`（文件/HTTP 分离）+ 流式解析器，使用内容哈希或 URL 作为缓存键并切换到 `await File.readAsString`。 |
| [x]（2025-11-22：全异步 IO 改造，集成 PathResolver） | lib/utils/file_utils.dart（531 行） | 多个方法（目录检查、配置查找）与 ConfigLoader 重复；异步 API 内部大量 `existsSync/listSync` 阻塞。 | 提供 `PathResolver` + 异步文件抽象，底层统一使用 `FileStat`/`await`，并直接复用 ConfigLoader 的路径缓存。 |
| [x]（2025-11-22：使用 Isolate.run 实现真并行解析） | lib/core/performance_parser.dart（486 行） | “并行”解析只是 `Future.wait` 包裹同步逻辑，且 `_parsePathsSequential` 吞掉异常。 | 使用 isolate/worker 池真正并行解析，并在 chunk 解析失败时返回上下文信息；提供策略配置。 |
| [x]（2025-11-22：迁移到 YAML 配置，运行时加载） | lib/core/error_rules.dart（479 行） | 大量硬编码规则与 EnhancedValidator 描述重复，难以扩展/本地化。 | 将规则迁移到可配置的 YAML/JSON，运行时加载并支持版本化、分组与动态开关。 |
| [x]（2025-11-22：拆分为 exceptions/ 子目录，使用 mixin 共享格式化） | lib/core/exceptions.dart（478 行） | 聚合了十余个异常定义和处理逻辑，`ExceptionHandler` 只支持完全匹配类型且无法取消注册。 | 拆分为 `exceptions/` 子目录，提供 mixin/基类共享格式化，并让处理器支持层级匹配与作用域注册。 |
| [x]（2025-11-22：拆分为 error_reporter/ 子目录，包含 models/reporter/renderers） | lib/core/error_reporter.dart（460 行） | 数据类型定义、收集逻辑、报告渲染全部揉在同一文件，难以测试和替换输出格式。 | 拆成 data model / reporter / renderer 三部分，可插拔 JSON、文本、CI 输出器，并引入不可变 `DetailedError`. |
| [x]（2025-11-22：拆分为 string_utils/ 子目录，包含 naming_converter/text_cleaner/template_service，主文件作为统一导出接口） | lib/utils/string_utils.dart（421 行） | 单文件包含命名转换、注释模板、复数化等杂项，并频繁同步读取配置。 | 根据职责拆分（命名转换/注释模板/文本清理），缓存配置项并提供可注入模板服务。 |

> 勾选项请在对应文件完成重构后更新为 `[x]` 并补充简短说明。