文件结构参考

一个遵循 SOLO 工作模式的项目，其文件结构旨在清晰地反映开发的各个阶段和关注点。本参考提供了一个推荐的、与技术栈无关的通用项目结构。

1. 顶层目录结构

.
├── .github/              # CI/CD 配置 (例如 GitHub Actions)
├── docs/                 # 项目文档 (如果需要)
├── generated/            # 存放自动生成的代码
├── scripts/              # 项目脚本 (构建, 生成, 等)
├── src/                  # 核心源代码
├── tests/                # 测试代码
├── .gitignore            # Git 忽略配置
├── openapi.yaml          # API 核心契约 (ARCHITECT 阶段产出)
├── package.json          # 项目依赖与脚本 (或 pom.xml, pyproject.toml 等)
├── PROJECT_REQUIREMENTS.md # 需求文档 (PRODUCT 阶段产出)
└── README.md             # 项目说明

2. 核心目录详解

a. openapi.yaml

这是整个项目的核心，是 ARCHITECT 阶段的主要产出物。所有 API 的设计、模型和端点都定义在此文件中。它是连接所有开发阶段的“契约”。

b. PROJECT_REQUIREMENTS.md

这是 PRODUCT 阶段的主要产出物。它用人类可读的语言描述了项目的功能需求、用户故事和业务规则，是 openapi.yaml 设计的直接输入。

c. src/

存放手动编写的核心业务逻辑代码，是 ENGINEER 阶段的主要工作区域。其内部结构通常按功能或分层架构来组织。

示例 (Java Spring Boot):

src/main/java/com/example/
├── api/                  # Controllers/API 实现
├── service/              # 业务逻辑层
├── model/                # 业务领域模型 (非 DTO)
├── repository/           # 数据访问层
└── config/               # 应用配置

与 generated/ 的关系: src/ 中的代码会实现或使用 generated/ 目录中由 OpenAPI Generator 生成的接口和数据传输对象 (DTOs)。这确保了业务逻辑与 API 契约的解耦。

d. generated/

此目录不应手动修改，其所有内容都由 OpenAPI Generator 等工具根据 openapi.yaml 自动生成。它通常被添加到 .gitignore 中。

• 内容:
  • 服务端接口定义 (e.g., TasksApi.java)
  • API 数据传输对象 (DTOs) (e.g., TaskRequest.java, TaskResponse.java)
  • 客户端 SDK

e. tests/

存放所有测试代码，是 ENGINEER 和 QA 阶段的产出物。

• 结构:
  • unit/: 单元测试
  • integration/: 集成测试 (例如测试 Service 层与 Repository 层的交互)
  • api/ 或 e2e/: API/端到端测试 (直接调用 API 端点)
• 契约测试: 契约测试的配置和脚本也可能放在这里，或者在 CI/CD 的配置中定义。

f. scripts/

存放用于简化开发流程的辅助脚本。

• 示例:
  • generate-code.sh: 封装了 openapi-generator-cli 命令。
  • run-contract-tests.sh: 启动服务并运行契约测试。
  • db-migrate.js: 数据库迁移脚本。

3. 结构背后的理念

• 关注点分离: openapi.yaml (设计), src/ (实现), tests/ (验证) 各司其职。
• 契约驱动: generated/ 目录的存在强制要求开发遵循 openapi.yaml 契约。
• 自动化: scripts/ 和 .github/ 体现了将重复工作自动化的思想。
• 清晰的阶段产出: PROJECT_REQUIREMENTS.md 和 openapi.yaml 是 SOLO 前两个阶段的明确交付物。