diff --git a/README.md b/README.md index 280cc04..c70b5ad 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ - [后续执行计划](docs/EXECUTION_PLAN.md) - [Phase 1 阶段报告](docs/phase-1-report.md) - [Phase 2 阶段报告](docs/phase-2-report.md) +- [Phase 3 阶段报告](docs/phase-3-report.md) - [TTS 上游资料请求清单](docs/TTS_UPSTREAM_REQUEST.md) 项目根目录:`E:\RD\Kaotings\www_site`,以本次新仓库为准。 diff --git a/docs/EXECUTION_PLAN.md b/docs/EXECUTION_PLAN.md index ec5d6cc..b706645 100644 --- a/docs/EXECUTION_PLAN.md +++ b/docs/EXECUTION_PLAN.md @@ -69,6 +69,8 @@ Phase 1 当前可在本地继续开发,也可在测试机仅部署官网骨架 进入条件:Phase 2 认证/归属/权益可用,且获得真实上游联调权限和测试额度。 +当前状态:任务、Worker、额度失败释放、历史和受控音频接口已部署;真实成功联调被 TTS API Key 阻断,详见 `docs/phase-3-report.md` 和 `docs/TTS_UPSTREAM_REQUEST.md`。 + - `P3-01` 依据 `API_CONTRACT.md` 建立音色、任务、音频模型和上游适配器。 - `P3-02` 实现幂等、文本校验、限流、并发控制和额度冻结事务。 - `P3-03` 实现 Worker 租约、超时、结果核对和有限重试。 diff --git a/docs/phase-3-report.md b/docs/phase-3-report.md new file mode 100644 index 0000000..6b14e3c --- /dev/null +++ b/docs/phase-3-report.md @@ -0,0 +1,54 @@ +# Phase 3 TTS 任务与额度闭环报告 + +日期:2026-09-08 +范围:P3-01 至 P3-07 +状态:任务持久化、额度冻结/释放、Worker 失败路径、历史和访问接口已部署;真实上游成功生成、回放和下载待 API Key/鉴权资料。 + +## 1. 已实现 + +- `002_tts.sql` 建立 `tts_voices`、`tts_tasks`、`audio_files`,并保留版本化迁移。 +- 代码默认音色 `default` 作为旧工程提供的标识写入测试库;不代表完整真实音色清单。 +- `POST /api/v1/tts/tasks` 支持文本长度、格式、语速、音色、幂等键、Plan 和额度校验。 +- 任务先入库为 `queued` 并冻结额度,再由 API 进程内持久化 Worker 领取。 +- 同一用户同一幂等键同请求返回原任务,不同请求返回冲突。 +- Worker 调用固定配置的 `/v1/audio/speech`,不接受用户 URL;支持 WAV/MP3 和 Bearer API Key 环境注入。 +- 成功路径写入私有本地音频目录,登记 checksum 和文件元数据,冻结转消费。 +- 失败路径写入错误码、释放冻结,并保留历史任务。 +- `/api/v1/tts/tasks`、详情、音频播放和下载接口已实现资源归属检查。 +- `/tts` 页面已接入真实任务、轮询、历史、回放和下载控件。 + +## 2. 真实测试 + +测试入口:`https://192.168.199.22/`,使用临时用户和最小文本 `测试`。 + +| 项目 | 结果 | +| --- | --- | +| 任务创建 | `202`, 初始 `queued` | +| Worker 处理 | `failed`,错误码 `UPSTREAM_NOT_CONFIGURED` | +| 历史查询 | 返回 1 条任务 | +| 额度冻结前可用 | `10000` | +| 失败后可用 | `10000` | +| 失败后冻结 | `0` | +| 真实上游最小请求 | `401 Unauthorized` | + +当前没有成功音频,因此本轮不能声称真实回放、下载、音频校验和成功消费已通过。不能用 Mock 音频替代。 + +## 3. P3 工作包状态 + +| 编号 | 状态 | 说明 | +| --- | --- | --- | +| P3-01 | 部分完成 | 模型、适配调用和配置边界已实现;缺上游凭据和真实音色资料 | +| P3-02 | 已完成负向/基础路径 | 幂等、校验、额度冻结已真实测试;并发争用测试待补 | +| P3-03 | 部分完成 | 持久化 Worker 已运行;任务租约、重启恢复和有限重试待加强验证 | +| P3-04 | 部分完成 | 私有存储和结算代码已实现;成功音频路径待真实上游 | +| P3-05 | 已完成布局和任务调用 | 页面已提交、轮询和显示失败;成功音频待联调 | +| P3-06 | 部分完成 | 历史和资源归属接口已实现;回放/下载需成功音频验证 | +| P3-07 | 未完成 | 缺少上游凭据,尚不能完成成功、重启、争用和存储异常全矩阵 | + +## 4. 阻断项 + +- 旧工程默认上游 `http://43.248.188.28:44480` 的最小请求返回 `401`,需要测试 API Key 或其他鉴权凭据。 +- 旧工程没有真实音色语言清单;当前只保留代码默认 `default` 标识。 +- 旧工程同步返回音频,没有 provider task ID、异步查询或幂等能力;业务 Worker 不能假设上游可安全重试。 + +凭据补齐后,必须重新执行成功生成、音频校验、私有回放/下载、重复请求、上游超时、存储失败、Worker 重启和额度争用测试。凭据只进入服务器 `/etc/kaotings/api.env`,不进入 Git、前端构建或日志。