# 目录结构迁移步骤清单（方案 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 直到发布后稳定一周