# Project Resource 路由注册修复

**日期**: 2026-02-04  
**类型**: Bug 修复  
**影响范围**: API 路由

## 问题描述

`project_resources` 模块的 API 路由未注册到 FastAPI 主应用，导致所有相关端点返回 404。

## 根本原因

1. **双重路由配置文件**:
   - `app/api/v1/__init__.py`: 新版本，包含完整路由注册
   - `app/api/v1/router.py`: 旧版本，被 `main.py` 实际使用

2. **导入顺序问题**:
   - `main.py` 从 `router.py` 导入 `api_router`
   - `router.py` 未更新，缺少新增模块的路由注册

## 修复方案

**方案 1: 更新 router.py（临时方案）**

更新 `server/app/api/v1/router.py`，添加所有缺失的路由模块。

**方案 2: 统一路由配置（最终方案）✅**

删除 `router.py`，直接使用 `__init__.py` 的完整配置：

```python
# server/app/main.py
from app.api.v1 import api_router  # 直接从 __init__.py 导入
```

**优势**:
- ✅ 单一配置源，避免维护两份代码
- ✅ 不会再出现路由注册遗漏
- ✅ 符合 Python 模块惯例

**实施步骤**:
1. 修改 `main.py` 导入语句
2. 删除 `server/app/api/v1/router.py`
3. 重启应用验证

## 验证结果

修复后，路由成功注册到主应用：

```bash
$ docker exec jointo-server-app python -c "
from app.main import app
routes = [r.path for r in app.routes if hasattr(r, 'path') and 'projects' in r.path and 'resources' in r.path]
print(f'找到 {len(routes)} 个 project_resources 路由')
"
# 输出: 找到 4 个 project_resources 路由
```

注册的路由：
- `POST /api/v1/projects/{project_id}/resources` - 上传素材
- `GET /api/v1/projects/{project_id}/resources` - 获取素材列表
- `GET /api/v1/resources/{resource_id}` - 获取素材详情
- `PATCH /api/v1/resources/{resource_id}` - 更新素材
- `DELETE /api/v1/resources/{resource_id}` - 删除素材
- `GET /api/v1/resources/{resource_id}/usage` - 检查使用情况
- `GET /api/v1/tags/{tag_id}/resources` - 获取标签的素材列表

## 影响范围

- ✅ `project_resources` 路由现已可用
- ✅ `resource_library` 路由现已可用
- ✅ `storyboard_resources` 路由现已可用
- ✅ `screenplays` 路由现已可用
- ✅ `screenplay_tags` 路由现已可用
- ✅ `recharge` 路由现已可用
- ✅ `wechat` 路由现已可用

## 后续建议

1. ✅ **统一路由配置（已完成）**:
   - 已删除 `router.py`
   - `main.py` 现在直接从 `__init__.py` 导入 `api_router`
   - 单一配置源，避免重复维护

2. **添加路由注册测试**:
   - 自动检测新增路由模块是否已注册
   - 防止类似问题再次发生

3. **文档更新**:
   - 在开发指南中说明路由注册流程
   - 提醒开发者在 `__init__.py` 中注册新路由

## 相关文件

- `server/app/api/v1/__init__.py` - 统一的路由配置文件
- `server/app/main.py` - 路由挂载点（已更新导入）
- ~~`server/app/api/v1/router.py`~~ - 已删除（过时文件）
- `server/app/api/v1/project_resources.py` - 受影响的路由模块

## 测试验证

```bash
# 验证路由注册
docker exec jointo-server-app python -c "from app.main import app; print([r.path for r in app.routes if 'resources' in r.path])"

# 运行 API 集成测试
docker exec jointo-server-app pytest tests/integration/test_project_resource_api.py -v
```