# 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`

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

## 当前策略

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

## 删除条件

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

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

## 面试表达

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