www_site/docs/phase-3-report.md

Phase 3 TTS 任务与额度闭环报告

日期：2026-09-08 范围：P3-01 至 P3-07 状态：任务持久化、额度冻结/释放、Worker、历史、真实音频回放和下载已部署并完成最小成功联调；高级异常矩阵和上游异步/幂等能力仍待补充。

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

配置服务端凭据后重新联调：

项目	结果
上游精确路径	POST http://43.248.188.28:44480/v1/audio/speech
最小上游探测	200 audio/wav
业务任务创建	202
Worker 最终状态	succeeded
回放接口	200，返回音频字节
下载接口	200，返回音频字节
历史查询	1 条记录
额度	10000 -> 9998，已用 2，冻结 0

成功音频路径已通过最小文本验证；并发争用、Worker 重启、存储失败和上游超时矩阵仍需补测。

3. P3 工作包状态

编号	状态	说明
P3-01	已完成最小真实路径	模型、适配调用、默认音色和最小 WAV 联调已通过；完整音色资料待补
P3-02	已完成负向/基础路径	幂等、校验、额度冻结已真实测试；并发争用测试待补
P3-03	部分完成	持久化 Worker 已运行；任务租约、重启恢复和有限重试待加强验证
P3-04	已完成最小真实路径	私有存储、checksum、成功消费和失败释放已验证
P3-05	已完成最小真实路径	页面提交、轮询、成功音频和失败状态已验证
P3-06	已完成最小真实路径	历史、资源归属、回放和下载已验证
P3-07	部分完成	正常、上游未配置和成功路径已验证；并发争用、重启恢复、存储失败待补

4. 阻断项

• 旧工程没有真实音色语言清单；当前只保留代码默认 default 标识。
• 旧工程同步返回音频，没有 provider task ID、异步查询或幂等能力；业务 Worker 不能假设上游可安全重试。

凭据补齐后，必须重新执行成功生成、音频校验、私有回放/下载、重复请求、上游超时、存储失败、Worker 重启和额度争用测试。凭据只进入服务器 /etc/kaotings/api.env，不进入 Git、前端构建或日志。