结构治理文档：

- 新增 STRUCTURE_AUDIT.md（目录结构审计报告：问题、依赖/关系图、风险点） - 新增 STRUCTURE_PROPOSAL.md（3 套候选方案：保守/平衡/激进，推荐采纳方案 B） - 新增 STRUCTURE_MIGRATION_CHECKLIST.md（可执行、可回滚的迁移步骤清单） - 同步与现有 docs/PROJECT_OVERVIEW.md、check_list.md、迁移基线文档保持一致不涉及行为改动，仅文档与结构治理计划。
2025-11-22 20:27:01 +08:00 · 2025-11-22 20:27:01 +08:00 · fd7975c1c4
parent 48863c6255
commit fd7975c1c4
3 changed files with 368 additions and 0 deletions
--- a/STRUCTURE_AUDIT.md
+++ b/STRUCTURE_AUDIT.md
@ -0,0 +1,132 @@
+# 目录结构审计报告（Dart/Flutter OpenAPI 代码生成器）
+
+最后更新：2025-11-22
+适用范围：lib/**、templates/**、docs/**、test/**、example/**（忽略 build/.dart_tool 等生成产物）
+
+## 一、lib/ 目录结构（第二层深度）
+
+```
+lib/
+  commands/
+    base_command.dart
+    generate_command.dart
+    services/
+  config/
+    error_rules.yaml
+  core/
+    config.dart
+    config_repository.dart
+    error_reporter/        # models / reporter / renderers
+    error_reporter.dart    # 聚合导出
+    error_rules.dart
+    exceptions/           # 细分异常定义
+    exceptions.dart        # 聚合导出
+    models/                # Swagger 核心模型
+    models.dart            # 聚合导出
+    performance_parser.dart
+    template/              # TemplateLoader (part of template_renderer)
+    template_renderer.dart
+  generators/
+    base_generator.dart
+    model/
+    model_code_generator.dart
+    retrofit_api/
+    retrofit_api_generator.dart
+  parsers/
+    swagger_data_parser.dart
+    swagger_fetcher.dart
+  templates/
+    api/
+    common/
+    models/
+  utils/
+    cache_manager.dart
+    file_utils.dart
+    logger.dart
+    path_resolver.dart
+    performance_monitor.dart
+    reference_resolver.dart
+    string_utils.dart       # 统一导出
+    string_utils/           # naming_converter / template_service / text_cleaner
+    type_validator.dart
+  validators/
+    core/
+    rules/
+    enhanced_validator.dart
+    schema_validator.dart
+  swagger_cli_new.dart
+  swagger_generator_flutter.dart  # 顶层聚合导出
+```
+
+关键聚合导出文件：
+- lib/swagger_generator_flutter.dart（对外公共 API 入口）
+- lib/core/error_reporter.dart（聚合导出 models/reporter/renderers）
+- lib/core/models.dart（聚合导出核心模型）
+- lib/utils/string_utils.dart（聚合导出 naming_converter/template_service/text_cleaner）
+
+## 二、职责边界与潜在问题
+
+- commands：参数解析 + 流程编排（解析→验证→生成→落盘），OK
+- config：以 ConfigRepository 为主，SwaggerConfig 静态 getter 兼容，OK
+- core：通用核心（模型/异常/错误报告/模板渲染/并行解析），OK
+- parsers：SwaggerFetcher/SwaggerDataParser（获取与解析），OK
+- validators：SchemaValidator 基础规则 + EnhancedValidator 装饰增强（依赖 ErrorReporter），OK
+- generators：ModelCodeGenerator / RetrofitApiGenerator + Mustache 模板，OK
+- utils：通用工具（I/O/路径/引用解析/字符串处理），OK
+- templates：Mustache 模板，OK
+
+发现与建议：
+1) 依赖方向基本自上而下，无循环依赖。TemplateLoader 依赖 PathResolver，合理。
+2) 工具分层已明确：string_utils（面向生成）与 file/path（基础设施）分离，良好。
+3) validators 下“增强 vs 基础”是装饰关系，不应合并；已在文档中明确。
+4) 顶层导出 swagger_generator_flutter.dart 已聚合核心能力，但 generators/validators/core/utils 的暴露范围建议仅保留聚合导出，避免深层路径泄漏。
+
+## 三、跨层依赖与改进机会
+
+- 配置注入点：
+  - TemplateRenderer/GenerationOutputService 等处已采用 ConfigRepository.loadSync()，建议命令层集中创建单例并向下传递（可选优化）。
+- 模板上下文基线：
+  - TemplateRenderer._buildBaseContext 固化生成器名称/作者/版权，已统一。
+- 输出服务边界：
+  - GenerationOutputService 已与生成器/文件写入解耦，清晰。
+
+## 四、重复与冗余排查（enhanced/improved/v2）
+
+- validators：EnhancedValidator（装饰器）与 SchemaValidator（基础）——场景互补，保留两者。
+- config：已迁移至 ConfigRepository，ConfigLoader 已移除（docs/MIGRATION_CONFIG_LOADER.md 已提供映射）。
+- 其他 v2/Enhanced 字样多为注释/示例，不构成并行实现。
+
+结论：无须删除新增模块；已冗余项（ConfigLoader）已处置。
+
+## 五、风险点
+- 外部引用深层路径的风险：建议对外仅使用 swagger_generator_flutter.dart 和若干聚合导出；在 USAGE 指南提示。
+- 模板根目录查找优先级：TemplateLoader 的向上搜集策略需在文档中明确（建议：自定义根 > 配置目录 > 工作目录链）。
+
+## 六、关系示意（Mermaid）
+
+```mermaid
+flowchart TD
+  CLI[CLI / Command] --> CFG[ConfigRepository]
+  CLI --> PF[SwaggerFetcher]
+  PF --> SDP[SwaggerDataParser]
+  SDP --> VAL[SchemaValidator]
+  VAL -->|decorate| EV[EnhancedValidator]
+  EV --> ER[ErrorReporter]
+  SDP --> MODELS[Core Models]
+  CLI --> GEN[Generators]
+  GEN --> MC[ModelCodeGenerator]
+  GEN --> RG[RetrofitApiGenerator]
+  RG --> TR[TemplateRenderer]
+  TR --> TS[TemplateService]
+  CLI --> OUT[GenerationOutputService]
+  subgraph Utils
+    FU[FileUtils]
+    PR[PathResolver]
+    RR[ReferenceResolver]
+    SU[StringUtils]
+  end
+  GEN -.-> Utils
+  SDP -.-> Utils
+  CLI -.-> Utils
+```
+
--- a/STRUCTURE_MIGRATION_CHECKLIST.md
+++ b/STRUCTURE_MIGRATION_CHECKLIST.md
@ -0,0 +1,85 @@
+# 目录结构迁移步骤清单（方案 B：平衡，推荐）
+
+最后更新：2025-11-22
+目标：不改变行为与产物，在保持现有分层的基础上，补强聚合导出与依赖边界，减少深层路径依赖。
+质量门禁：每一步都需满足
+- dart analyze：0 errors / 0 warnings（info 可忽略）
+- dart test：全部通过
+- CLI 行为与生成结果一致（如有差异必须回滚）
+回滚策略：任一步失败，git revert 最近一次提交，恢复到上一步。
+
+---
+
+## 预备
+- 建立工作分支：feature/structure-governance
+- 基线验证：`dart analyze`、`dart test`
+
+## 步骤 1：导入路径治理（聚合导出优先）
+- 动作：检查对外导入，尽量使用聚合导出入口
+  - 外部仅推荐导入：
+    - `package:swagger_generator_flutter/swagger_generator_flutter.dart`
+    - `package:swagger_generator_flutter/core/models.dart`
+    - `package:swagger_generator_flutter/core/error_reporter.dart`
+    - `package:swagger_generator_flutter/utils/string_utils.dart`
+- 验证：`grep -R "lib/core/.*\.dart" example/` 无直接深层导入；构建与示例运行通过
+- 提交信息（示例）：
+  - chore(structure): 规范外部导入路径，统一使用聚合导出入口
+
+## 步骤 2：为关键子系统补齐/校验聚合导出（如需）
+- 动作：核对各子系统对外的唯一入口（index/聚合文件）
+  - validators：已有 schema/enhanced 两者并存，保持不变（装饰器与基础）
+  - core：error_reporter.dart / models.dart 已存在
+  - utils：string_utils.dart 已存在
+- 验证：对外导入不依赖深层文件；现有单测与示例仍可编译运行
+- 提交：
+  - chore(structure): 校验与补齐聚合导出入口（无行为改动）
+
+## 步骤 3：模板上下文基线与模板搜索优先级固化（文档）
+- 动作：在 PROJECT_OVERVIEW.md 增加：
+  - 仅在 TemplateRenderer 构建一次基础上下文（generatorName/author/copyright）
+  - 模板搜索优先级：自定义根 > 配置目录/templates > 配置目录/lib/templates > 工作目录向上搜集
+- 验证：无代码变更；生成行为一致
+- 提交：
+  - docs: 明确模板上下文构建点与模板搜索优先级
+
+## 步骤 4（可选）：命令层集中注入 ConfigRepository 单例
+- 动作：在 GenerateCommand 执行期创建单个 config 实例，下传到 Renderer/Services（当前已通过懒加载避免多次 I/O，可暂缓）
+- 验证：性能对比日志（可选），行为一致
+- 提交：
+  - perf(config): 命令层集中注入单例 ConfigRepository 减少 I/O
+
+## 步骤 5：文档与指南同步
+- 动作：
+  - 更新 USAGE_GUIDE.md：新增“导入路径规范（只用聚合导出）”“模板加载优先级”
+  - 在 README（或 QUICK_REFERENCE）加入 1 页速览
+- 验证：示例按照指南可跑通
+- 提交：
+  - docs: 增补导入路径规范与模板加载优先级
+
+## 验收与合并
+- 运行：`dart analyze`、`dart test`
+- grep 校验：
+  - `grep -R "package:swagger_generator_flutter/.*/.*\.dart" example/` 不应出现深层路径
+- 提交：
+  - chore(release): 目录结构治理（方案 B）— 聚合导出与导入规范
+- PR 检查项：
+  - 无行为变化；仅结构/文档治理
+  - 附运行截图或日志
+
+---
+
+## 提交信息模板（中文）
+- chore(structure): 规范外部导入路径，统一使用聚合导出入口
+- docs: 明确模板上下文构建点与模板搜索优先级
+- perf(config): 命令层集中注入单例 ConfigRepository 减少 I/O（可选）
+- chore(release): 目录结构治理（方案 B）— 聚合导出与导入规范
+
+## PR 拆分建议
+1) docs-only：新增/更新 STRUCTURE_* 文档与 PROJECT_OVERVIEW 补充
+2) structure-exports：聚合导出与导入路径治理（不改逻辑）
+3) perf-config（可选）：命令层注入单例 ConfigRepository
+
+## 回滚策略
+- 任一 PR 合并后出现行为偏差：`git revert <commit>` 回滚到上一步
+- 保留分支 feature/structure-governance 直到发布后稳定一周
+
--- a/STRUCTURE_PROPOSAL.md
+++ b/STRUCTURE_PROPOSAL.md
@ -0,0 +1,151 @@
+# 目录组织候选方案与推荐方案（Dart/Flutter OpenAPI 代码生成器）
+
+最后更新：2025-11-22
+适用范围：lib/**、templates/**、docs/**、test/**、example/**
+不改变现有行为与生成结果；仅优化结构与依赖方向。
+
+## 现状简述（基于 STRUCTURE_AUDIT）
+- 分层清晰：commands/config/core/parsers/validators/generators/utils/templates
+- 聚合导出：swagger_generator_flutter.dart、core/error_reporter.dart、core/models.dart、utils/string_utils.dart
+- EnhancedValidator 为装饰器，依赖 SchemaValidator；ConfigRepository 为配置主入口
+- 主要改进空间：
+  1) 统一对外“index.dart”聚合导出，避免深层路径泄漏
+  2) 命令层集中注入单个 ConfigRepository 实例以减少 I/O（可选）
+  3) 明确模板搜索优先级与上下文基线的构建点
+
+---
+
+## 方案 A（保守）：最小改动，快速落地
+目标：基本不动现有目录，仅补充聚合导出与文档约束。
+
+建议目录（节选）
+```
+lib/
+  core/
+    models/
+    models.dart        # 已有：聚合导出
+    error_reporter/
+    error_reporter.dart# 已有：聚合导出
+  utils/
+    string_utils/
+    string_utils.dart  # 已有：聚合导出
+  swagger_generator_flutter.dart # 对外主入口
+```
+措施
+- 在 docs/USAGE_GUIDE.md 强化“仅从聚合入口导入”的约束
+- 在 analysis_options.yaml 添加禁止深层导入的 lint（可选）
+
+优点
+- 变更最小，零风险，立刻可用
+缺点
+- 不能进一步降低跨层依赖；规范依赖于文档与自觉
+影响面
+- 对外零影响；测试与 CLI 行为不变
+
+---
+
+## 方案 B（平衡，推荐）：完善聚合导出与依赖边界
+目标：降低跨层耦合，巩固入口文件，保留现有分层和命名
+
+建议目录（节选）
+```
+lib/
+  commands/
+    base_command.dart
+    generate_command.dart
+    services/
+      document_merge_service.dart
+      document_filter_service.dart
+      generation_output_service.dart
+  core/
+    config.dart
+    config_repository.dart
+    template_renderer.dart
+    template/
+      template_loader.dart (part)
+    models/
+    models.dart
+    error_reporter/
+    error_reporter.dart
+    exceptions/
+    exceptions.dart
+  parsers/
+    swagger_fetcher.dart
+    swagger_data_parser.dart
+  validators/
+    core/
+    rules/
+    schema_validator.dart
+    enhanced_validator.dart
+  generators/
+    base_generator.dart
+    model/
+    model_code_generator.dart
+    retrofit_api/
+    retrofit_api_generator.dart
+  utils/
+    file_utils.dart
+    path_resolver.dart
+    reference_resolver.dart
+    string_utils/
+    string_utils.dart
+  templates/
+    api/
+    models/
+    common/
+  swagger_generator_flutter.dart
+```
+执行要点
+- 为 commands/core/parsers/validators/generators/utils 分别补齐/校验聚合导出（需要时新增 index.dart）
+- 内部互相依赖仅经聚合文件或上层入口（避免跨层直连深文件）
+- TemplateRenderer 中的上下文构建固化（已完成）：仅从 ConfigRepository 构建一次
+- 命令层（GenerateCommand）可选集中创建单例 config 并下传
+
+优点
+- 依赖边界更清晰；可渐进治理深层导入
+- 变更成本适中，兼容性强
+缺点
+- 需少量导入路径梳理（指向聚合文件）
+影响面
+- 对外零影响；测试与 CLI 行为不变
+
+---
+
+## 方案 C（激进）：按业务流分区
+目标：以 Parse → Validate → Generate → Render → Output 的流水线重组目录
+
+建议目录草案（节选）
+```
+lib/
+  pipeline/
+    parse/ (swagger_fetcher, swagger_data_parser)
+    validate/ (schema_validator, enhanced_validator, error_reporter)
+    generate/
+      models/
+      apis/
+      templates/ (renderer, loader, services)
+    output/ (generation_output_service, file_utils)
+  core/ (models, exceptions, config_repository)
+  commands/
+  utils/
+```
+优点
+- 强业务流程导向；定位问题成本更低
+缺点
+- 变动大，PR 体积大；回滚复杂
+影响面
+- 需要系统性迁移与长时间稳定验证
+
+---
+
+## 推荐方案
+- 采纳方案 B（平衡）：
+  - 当前分层已合理，主要补强聚合导出与导入规范
+  - 最小代价减少未来跨层依赖与“深层路径”侵蚀
+
+---
+
+## 对测试与命令行为的影响
+- 三个方案均“不改变行为”；仅目录/导入治理
+- 质量门禁：每步迁移后确保 `dart analyze` 0 error / 0 warning、`dart test` 全绿
+