3.3 KiB

Raw Blame History

Project Resource 路由注册修复

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

问题描述

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

根本原因

双重路由配置文件:
- app/api/v1/__init__.py: 新版本，包含完整路由注册
- app/api/v1/router.py: 旧版本，被 main.py 实际使用
导入顺序问题:
- main.py 从 router.py 导入 api_router
- router.py 未更新，缺少新增模块的路由注册

修复方案

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

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

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

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

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

优势:

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

实施步骤:

修改 main.py 导入语句
删除 server/app/api/v1/router.py
重启应用验证

验证结果

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

$ 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 路由现已可用

后续建议

✅ 统一路由配置（已完成）:
- 已删除 router.py
- main.py 现在直接从 __init__.py 导入 api_router
- 单一配置源，避免重复维护
添加路由注册测试:
- 自动检测新增路由模块是否已注册
- 防止类似问题再次发生
文档更新:
- 在开发指南中说明路由注册流程
- 提醒开发者在 __init__.py 中注册新路由

测试验证

# 验证路由注册
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

3.3 KiB Raw Blame History