fix(api): 加 editor/drafts、editor/clips/from-assets、api/health 路径别名，修复前端 404 导致的 10s 超时 #2033

Merged

auto-approve-bot merged 3 commits from fix/editor-route-aliases-2033 into develop 2026-09-25 01:27:22 +08:00

Conversation 2 Commits 3 Files Changed 3

+157 -9

xiaoxia commented 2026-09-25 01:03:10 +08:00

Owner

Copy Link

Copy Source

背景

前端智能剪辑流程报 2 个 10s 超时错误：

• [useDraftAutoSave] 自动保存草稿 timeout 10s
• [useStep2Materials] 智能选片 timeout 10s

排查发现不是 API 性能问题（health 100ms、连接池/队列正常），是前端请求路径和后端路由不匹配，全部 404：

前端调的路径	后端实际路径	结果
GET/PUT /api/v1/editor/drafts	/api/v1/templates/{template_id}/editor/draft（单数+要 template_id）	404
POST /api/v1/editor/clips/from-assets	/api/v1/clips/from-assets（无 editor 前缀）或 /api/v1/templates/{template_id}/editor/clips/from-assets（要 template_id）	404
GET /api/health（前端探针）	/health（根路径）	404

staging DB 当前为空库（昨天 alembic 重建），需要测试用户重新注册上传素材，ingest pipeline 会自动跑场景切分和标签。

修改

1. 新增 apps/api/app/api/routes/drafts_standalone.py：参照已有 clips_standalone.py 模式，提供无 template_id 路径参数的 GET/PUT /drafts 别名端点，template_id 缺省时通过 _default_template.get_or_create_default_template_id 兜底到用户默认模板，内部复用 templates_editor/draft.py 的 get_editor_draft / update_editor_draft 核心逻辑。

2. 修改 apps/api/app/api/router.py：

   • 新增 editor_legacy_router（prefix=/editor），同时挂载 clips_standalone_router 和 drafts_standalone_router，一次性覆盖：
     • POST /api/v1/editor/clips/from-assets
     • GET /api/v1/editor/drafts / PUT /api/v1/editor/drafts
   • 新增 api_health_router（prefix=/api）挂载 health_check_router，提供 /api/health、/api/ready、/api/startup 别名。
   • 原有正式路径 /api/v1/templates/{template_id}/editor/* 和 /api/v1/clips/from-assets、/health 保持不变，向后兼容。

兼容性

• 新增的别名端点是纯增量，旧前端/旧客户端继续用原路径不受影响
• 前端无需等改版，后端兼容上线即生效
• 已通过 Python AST 语法检查

验证

CI 通过后部署到 staging，预期：

• GET/PUT /api/v1/editor/drafts 返回 200（template_id 缺省时自动兜底默认模板）
• POST /api/v1/editor/clips/from-assets 返回 200/正常业务响应
• GET /api/health 返回 200
• GET /health、GET /api/v1/clips/from-assets、GET /api/v1/templates/{tid}/editor/draft 等旧路径继续正常

## 背景 前端智能剪辑流程报 2 个 10s 超时错误： - `[useDraftAutoSave] 自动保存草稿 timeout 10s` - `[useStep2Materials] 智能选片 timeout 10s` 排查发现不是 API 性能问题（health 100ms、连接池/队列正常），是**前端请求路径和后端路由不匹配，全部 404**： | 前端调的路径 | 后端实际路径 | 结果 | |---|---|---| | `GET/PUT /api/v1/editor/drafts` | `/api/v1/templates/{template_id}/editor/draft`（单数+要 template_id） | 404 | | `POST /api/v1/editor/clips/from-assets` | `/api/v1/clips/from-assets`（无 editor 前缀）或 `/api/v1/templates/{template_id}/editor/clips/from-assets`（要 template_id） | 404 | | `GET /api/health`（前端探针） | `/health`（根路径） | 404 | staging DB 当前为空库（昨天 alembic 重建），需要测试用户重新注册上传素材，ingest pipeline 会自动跑场景切分和标签。 ## 修改 1. **新增 `apps/api/app/api/routes/drafts_standalone.py`**：参照已有 `clips_standalone.py` 模式，提供无 `template_id` 路径参数的 `GET/PUT /drafts` 别名端点，template_id 缺省时通过 `_default_template.get_or_create_default_template_id` 兜底到用户默认模板，内部复用 `templates_editor/draft.py` 的 `get_editor_draft` / `update_editor_draft` 核心逻辑。 2. **修改 `apps/api/app/api/router.py`**： - 新增 `editor_legacy_router`（prefix=`/editor`），同时挂载 `clips_standalone_router` 和 `drafts_standalone_router`，一次性覆盖： - `POST /api/v1/editor/clips/from-assets` - `GET /api/v1/editor/drafts` / `PUT /api/v1/editor/drafts` - 新增 `api_health_router`（prefix=`/api`）挂载 health_check_router，提供 `/api/health`、`/api/ready`、`/api/startup` 别名。 - 原有正式路径 `/api/v1/templates/{template_id}/editor/*` 和 `/api/v1/clips/from-assets`、`/health` 保持不变，向后兼容。 ## 兼容性 - 新增的别名端点是纯增量，旧前端/旧客户端继续用原路径不受影响 - 前端无需等改版，后端兼容上线即生效 - 已通过 Python AST 语法检查 ## 验证 CI 通过后部署到 staging，预期： - `GET/PUT /api/v1/editor/drafts` 返回 200（template_id 缺省时自动兜底默认模板） - `POST /api/v1/editor/clips/from-assets` 返回 200/正常业务响应 - `GET /api/health` 返回 200 - `GET /health`、`GET /api/v1/clips/from-assets`、`GET /api/v1/templates/{tid}/editor/draft` 等旧路径继续正常

xiaoxia added 2 commits 2026-09-25 01:03:18 +08:00

feat(api): 新增 drafts_standalone 兼容无 template_id 的 GET/PUT /api/v1/editor/drafts 路径 ... bb52e502d4

根因：前端 useDraftAutoSave 调 /api/v1/editor/drafts（复数、无 template_id），
后端只有 /api/v1/templates/{template_id}/editor/draft（单数、要路径参数），导致 404 并触发前端 10s 超时。
参照 clips_standalone.py 模式提供别名端点，template_id 缺省时兜底到用户默认模板。

feat(api): 为 clips/drafts/health 加旧路径别名 ... 35845a86af

- clips_standalone 额外挂到 /api/v1/editor/clips/from-assets，兼容前端 Step2 智能选片
- drafts_standalone 挂到 /api/v1/editor/drafts（GET/PUT），兼容 auto-save 10s 超时
- health_check_router 额外挂 /api/health，兼容把 health 放在 /api 前缀下的探针

gitea-actions bot commented 2026-09-25 01:09:00 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#2033
预览链接	https://pr-2033.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #2033 | | 预览链接 | [https://pr-2033.preview.xiaoxiajianji.com](https://pr-2033.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot added 1 commit 2026-09-25 01:14:18 +08:00

style: auto-format with black + isort + ruff + prettier [skip ci-format-check] e68556b7b2

auto-approve-bot merged commit 9039fcaea9 into develop 2026-09-25 01:27:22 +08:00

auto-approve-bot deleted branch fix/editor-route-aliases-2033 2026-09-25 01:27:24 +08:00

gitea-actions bot commented 2026-09-25 01:28:32 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #2033 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #2033 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#2033