docs/v1.0/architecture/adrs/009-resource-fixtures-separation.md

ADR 009: 资源目录职责分离

状态

✅ 已接受 - 2026-02-02

背景

在项目开发过程中，发现资源目录结构存在以下问题：

1. 职责不清：

   • app/resources/fixtures/ 定义为"测试数据/初始数据"
   • tests/fixtures/ 实际存储测试数据
   • 两者职责重叠，容易混淆

2. 文档不一致：

   • 文档说明测试数据应在 app/resources/fixtures/
   • 实际测试数据在 tests/fixtures/screenplays/

3. 打包问题：

   • 测试数据是否应该打包到生产环境？
   • 如何区分"种子数据"和"测试数据"？

4. 冗余目录：

   • app/resources/docs/ 完全为空
   • FastAPI 已自动生成 API 文档
   • 项目文档统一在根目录 docs/

决策

采用明确分离策略，严格区分应用资源和测试数据：

1. 目录职责定义

app/resources/fixtures/ - 应用初始化数据（种子数据）

• 用途：应用启动时加载的种子数据、配置数据
• 示例：AI 模型配置、定价方案、演示项目
• 特点：会被打包到生产环境 Docker 镜像
• 访问：应用代码可访问

scripts/fixtures/ - 调试样本文件

• 用途：手动调试脚本使用的样本文件
• 示例：剧本样本文件（PDF、DOCX、PPTX）
• 特点：不会被打包到生产环境（通过 .dockerignore 排除）
• 访问：仅调试脚本访问

2. 删除冗余目录

删除 app/resources/docs/ 目录，理由：

• FastAPI 自动生成 API 文档（/docs、/redoc）
• 项目文档已在根目录 docs/ 统一管理
• 当前完全为空，无实际用途
• 符合 YAGNI 原则

3. 最终目录结构

server/
├── app/
│   ├── resources/              # 应用资源（提交 Git，打包到生产）
│   │   ├── templates/          # 邮件/短信模板
│   │   └── fixtures/           # 应用初始化数据（种子数据）
│   ├── uploads/                # 用户上传（不提交 Git）
│   └── storage/                # 本地存储（不提交 Git）
├── scripts/
│   └── fixtures/               # 调试样本（不提交 Git，不打包到生产）
│       └── screenplays/        # 剧本样本文件
└── tests/
    ├── unit/                   # 单元测试
    ├── integration/            # 集成测试
    └── conftest.py             # pytest 配置（代码定义的 fixtures）

理由

1. 符合社区惯例

• Python/FastAPI 社区：pytest fixtures 是代码定义的测试辅助函数
• 调试样本隔离：调试样本不应该被应用代码直接访问
• 关注点分离：应用资源、调试样本、测试代码职责清晰

2. 生产环境优化

• 减少镜像体积：调试样本不会被打包到 Docker 镜像
• 安全性：调试样本不会暴露到生产环境
• 性能：减少不必要的文件复制

3. 开发体验

• 清晰的职责划分：开发者一眼就能区分资源类型
• 易于维护：种子数据和调试样本分开管理
• 避免混淆：不会误将调试样本当作种子数据

4. 文档一致性

• 统一文档位置：项目文档在根目录 docs/
• API 文档自动生成：FastAPI 自动生成，无需手动维护
• 减少冗余：删除空目录，保持结构简洁

影响

正面影响

1. 职责清晰：

   • 种子数据：应用初始化
   • 调试样本：手动调试

2. 生产优化：

   • 镜像体积减小
   • 部署速度提升

3. 开发效率：

   • 目录结构简洁
   • 易于理解和维护

负面影响

1. 需要更新文档：

   • 更新 app/resources/README.md
   • 更新 RESOURCES.md
   • 新增 tests/fixtures/README.md

2. 开发者认知：

   • 需要明确告知开发者两者的区别
   • 需要在文档中清晰说明

实施步骤

1. 更新文档

• 更新 server/app/resources/README.md
• 更新 server/RESOURCES.md
• 新增 server/app/resources/fixtures/README.md
• 新增 server/scripts/fixtures/README.md
• 删除 server/tests/fixtures/ 目录（未使用）

2. 删除冗余目录

• 删除 server/app/resources/docs/
• 更新相关文档引用

3. 创建 ADR

• 记录架构决策
• 说明选择理由
• 提供迁移指南

替代方案

方案 2：统一到 resources（已拒绝）

将所有测试数据移动到 app/resources/fixtures/

拒绝理由：

• ❌ 测试数据会被打包到生产镜像（增加体积）
• ❌ 违反"测试数据应该在 tests/ 目录"的惯例
• ❌ 应用代码不应该依赖测试数据

参考资料

• pytest fixtures 文档
• FastAPI 项目结构最佳实践
• Python 项目结构指南

相关决策

• ADR 001: UUID v7 迁移
• ADR 007: 数据库迁移最佳实践

---

作者: Jointo 开发团队
日期: 2026-02-02
状态: 已接受