dreamweaver/docs/technical/api-compatibility.md

API 兼容层策略

这份文档用于说明 DreamWeaver 求职版如何处理旧生成接口。目标不是立刻删除所有旧 API，而是把主线收敛到统一生成工作流，并让历史入口变成可迁移、可监控、可解释的兼容层。

背景

项目早期分别提供过普通故事、完整故事、绘本、封面生成和资产重试接口：

• POST /api/stories/generate
• POST /api/stories/generate/full
• POST /api/storybook/generate
• POST /api/image/generate/{story_id}
• POST /api/stories/{story_id}/assets/retry

这些接口都能工作，但对前端和面试讲解不够友好：故事、绘本和资产补全看起来像多条产品链路，容易掩盖真正的核心能力。

目标入口

求职版主入口统一为：

• POST /api/generations
• GET /api/generations/{story_id}
• POST /api/generations/{story_id}/retry-assets
• GET /api/generations/jobs/{job_id}
• GET /api/generations/{story_id}/jobs
• GET /api/generations/{story_id}/provider-stats

前端创建弹窗、绘本阅读器、故事详情页的资产重试应优先使用这些入口。

当前策略

1. 保留旧接口，避免破坏已有测试和潜在调用方。
2. 旧接口内部继续复用同一套 service workflow，不复制业务逻辑。
3. 旧接口响应增加迁移提示 header：
   • Deprecation: true
   • X-DreamWeaver-Successor-Endpoint: <target>
   • Link: <target>; rel="successor-version"
4. 新前端不再新增对旧生成接口的依赖。

删除条件

旧接口可以在同时满足以下条件后删除：

• 用户端和管理端都已切到 /api/generations。
• smoke 脚本只依赖统一入口。
• 后端测试覆盖统一入口的故事、绘本、资产重试和失败降级。
• 至少一个迭代周期没有发现旧接口新增调用。

面试表达

我不会为了“代码看起来干净”直接删掉旧接口，因为这会引入不可见风险。更稳妥的做法是先定义目标 API，再把旧入口降级为带迁移信号的兼容层，最后通过测试和调用方收敛来决定删除时机。