docs: record successful TTS upstream integration

docs/API_CONTRACT.md

@@ -21,7 +21,7 @@
 | 超时和大小限制 | 上游超时 `120000ms`；请求体最多 `1 MiB`；文本最多 `5000` 字符；未见上游响应大小限制 | `body()` 与 `AbortSignal.timeout(120000)` |
 | 幂等支持 | 未实现 | 无幂等键、provider task ID 或重复请求去重 |
 
-代码契约已核实；对默认地址的真实最小文本联调返回 `401 Unauthorized`，说明地址可达但当前请求缺少有效鉴权。不能把代码默认值写成已确认的实际部署地址。当前测试服务器没有 TTS 监听端口。
+代码契约已核实；首次无鉴权请求返回 `401 Unauthorized`，配置服务端凭据后最小文本请求已返回 `200 audio/wav`。当前测试服务器没有 TTS 上游监听端口，业务 API 通过固定环境地址访问外部上游。
 
 旧工程自身的业务接口为：登录后 `GET /api/config` 获取模型/音色元数据，`POST /api/tts` 同步返回音频，`GET /api/history` 返回当前用户最多 100 条历史；管理员配置接口为 `/api/admin/config`。Phase 3 只复用上游边界，不复制旧工程用户体系或整套工程。
 

docs/TTS_UPSTREAM_REQUEST.md

@@ -1,6 +1,6 @@
 # TTS 上游资料请求清单
 
-状态：已取得旧工程代码契约；实际部署状态、完整音色资料和联调授权仍待确认。
+状态：旧工程代码契约和一次真实成功联调已完成；完整音色资料、计量规则和上游高级能力仍待确认。
 日期：2026-09-08
 
 ## 已核查范围
@@ -12,7 +12,7 @@
 - 测试服务器：当前仅有 PostgreSQL、API、Web、Caddy 和 SSH 监听；未发现 TTS 监听端口或 TTS 服务配置。
 - `services/api`：仅实现认证、会话、权益和额度基础；没有 Phase 3 生成路由或上游调用。
 - 旧工程没有真实音色语言元数据、异步任务查询、provider task ID 或幂等键实现。
-- 代码默认地址的最小文本联调已执行：返回 `401 Unauthorized`；地址可达，但缺少有效测试鉴权凭据。
+- 代码默认地址首次无鉴权请求返回 `401 Unauthorized`；配置服务端凭据后最小文本请求返回 `200 audio/wav`，地址和凭据当前可用。
 - `www_site` 不增加网页端上游地址/API Key 配置后台；Phase 3 只从服务端环境变量 `TTS_UPSTREAM_URL`、`TTS_API_KEY` 和 `TTS_TIMEOUT_SECONDS` 加载配置。
 - 测试服务器的配置文件为 root-only `/etc/kaotings/api.env`；API Key 原文不进入响应、前端构建、Git 或普通日志。
 
@@ -34,8 +34,7 @@
 
 当前最具体阻断是：
 
-- 需要确认 `43.248.188.28:44480` 是否仍是授权测试地址。
-- 需要提供该地址的有效测试 API Key，或明确其他鉴权方式和服务端注入名称。
-- 需要提供当前可用音色 ID/语言清单和计量规则。
+- 需要提供完整当前音色 ID/语言清单和计量规则；目前只确认代码默认 `default` 可用。
+- 需要确认上游是否支持异步任务、查询、取消、provider task ID、幂等和重试；旧工程代码未实现这些能力。
 
 资料补齐前，Phase 3 不固定生产音色和计量策略，不创建伪造音色，不使用 Mock 成功替代真实联调，不扫描或猜测其他服务地址。

docs/phase-3-report.md

@@ -2,7 +2,7 @@
 
 日期：2026-09-08
 范围：P3-01 至 P3-07
-状态：任务持久化、额度冻结/释放、Worker 失败路径、历史和访问接口已部署；真实上游成功生成、回放和下载待 API Key/鉴权资料。
+状态：任务持久化、额度冻结/释放、Worker、历史、真实音频回放和下载已部署并完成最小成功联调；高级异常矩阵和上游异步/幂等能力仍待补充。
 
 ## 1. 已实现
 
@@ -31,23 +31,35 @@
 | 失败后冻结 | `0` |
 | 真实上游最小请求 | `401 Unauthorized` |
 
-当前没有成功音频，因此本轮不能声称真实回放、下载、音频校验和成功消费已通过。不能用 Mock 音频替代。
+配置服务端凭据后重新联调：
+
+| 项目 | 结果 |
+| --- | --- |
+| 上游精确路径 | `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 | 部分完成 | 模型、适配调用和配置边界已实现；缺上游凭据和真实音色资料 |
+| P3-01 | 已完成最小真实路径 | 模型、适配调用、默认音色和最小 WAV 联调已通过；完整音色资料待补 |
 | P3-02 | 已完成负向/基础路径 | 幂等、校验、额度冻结已真实测试；并发争用测试待补 |
 | P3-03 | 部分完成 | 持久化 Worker 已运行；任务租约、重启恢复和有限重试待加强验证 |
-| P3-04 | 部分完成 | 私有存储和结算代码已实现；成功音频路径待真实上游 |
-| P3-05 | 已完成布局和任务调用 | 页面已提交、轮询和显示失败；成功音频待联调 |
-| P3-06 | 部分完成 | 历史和资源归属接口已实现；回放/下载需成功音频验证 |
-| P3-07 | 未完成 | 缺少上游凭据，尚不能完成成功、重启、争用和存储异常全矩阵 |
+| P3-04 | 已完成最小真实路径 | 私有存储、checksum、成功消费和失败释放已验证 |
+| P3-05 | 已完成最小真实路径 | 页面提交、轮询、成功音频和失败状态已验证 |
+| P3-06 | 已完成最小真实路径 | 历史、资源归属、回放和下载已验证 |
+| P3-07 | 部分完成 | 正常、上游未配置和成功路径已验证；并发争用、重启恢复、存储失败待补 |
 
 ## 4. 阻断项
 
-- 旧工程默认上游 `http://43.248.188.28:44480` 的最小请求返回 `401`，需要测试 API Key 或其他鉴权凭据。
 - 旧工程没有真实音色语言清单；当前只保留代码默认 `default` 标识。
 - 旧工程同步返回音频，没有 provider task ID、异步查询或幂等能力；业务 Worker 不能假设上游可安全重试。
 

infra/scripts/probe-tts-upstream.py

@@ -0,0 +1,16 @@
+import os
+
+import httpx
+
+
+url = os.environ["TTS_UPSTREAM_URL"].rstrip("/") + "/v1/audio/speech"
+headers = {"Content-Type": "application/json"}
+if os.environ.get("TTS_API_KEY"):
+    headers["Authorization"] = f"Bearer {os.environ['TTS_API_KEY']}"
+response = httpx.post(
+    url,
+    headers=headers,
+    json={"model": "qwen3-tts", "input": "测试", "voice": "default", "response_format": "wav", "speed": 1},
+    timeout=40,
+)
+print(f"status={response.status_code} content_type={response.headers.get('content-type', '')} bytes={len(response.content)}")

infra/scripts/update-tts-env.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+import sys
+
+
+path = Path("/etc/kaotings/api.env")
+url = sys.stdin.readline().rstrip()
+key = sys.stdin.readline().rstrip()
+values = {"TTS_UPSTREAM_URL": url, "TTS_API_KEY": key}
+lines = path.read_text().splitlines()
+output = []
+seen = set()
+for line in lines:
+    name = line.split("=", 1)[0]
+    if name in values:
+        output.append(f"{name}={values[name]}")
+        seen.add(name)
+    else:
+        output.append(line)
+for name, value in values.items():
+    if name not in seen:
+        output.append(f"{name}={value}")
+path.write_text("\n".join(output) + "\n")
+path.chmod(0o600)