# 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. 更新文档

- [x] 更新 `server/app/resources/README.md`
- [x] 更新 `server/RESOURCES.md`
- [x] 新增 `server/app/resources/fixtures/README.md`
- [x] 新增 `server/scripts/fixtures/README.md`
- [x] 删除 `server/tests/fixtures/` 目录（未使用）

### 2. 删除冗余目录

- [x] 删除 `server/app/resources/docs/`
- [x] 更新相关文档引用

### 3. 创建 ADR

- [x] 记录架构决策
- [x] 说明选择理由
- [x] 提供迁移指南

## 替代方案

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

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

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

## 参考资料

- [pytest fixtures 文档](https://docs.pytest.org/en/stable/fixture.html)
- [FastAPI 项目结构最佳实践](https://fastapi.tiangolo.com/tutorial/bigger-applications/)
- [Python 项目结构指南](https://docs.python-guide.org/writing/structure/)

## 相关决策

- [ADR 001: UUID v7 迁移](001-uuid-v7-migration.md)
- [ADR 007: 数据库迁移最佳实践](007-database-migration-best-practices.md)

---

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