docs: 新增上游适配器开发指南

面向多渠道多上游适配器愿景的落地文档,分两部分:第一部分逐行核对现有火山适配器的真实契约(包的职责划分、主干对适配器的 7 项硬性依赖、MetricsRecorder 埋点约定、格式降级规则、以及 6 条实测踩过的上游协议坑);第二部分给出 Provider 抽象的目标设计与分阶段实施计划(阶段 0 抽接口零行为变更 -> 阶段 1 provider 入库 -> 阶段 2 配置命名空间化 -> 阶段 3 metrics 加 provider 维度 -> 阶段 4 管理界面 -> 阶段 5 第二个真实适配器)。同时如实记录三处现状缺陷,避免按文档实施时踩坑:voice.resource_id 是火山专属概念却成了全表 NOT NULL 通用列;store/migrate.go 的迁移框架定义了 Migration/migrations 但切片为空、migrate() 从不读取它(实际只做 CREATE TABLE IF NOT EXISTS,对已存在的表不做任何变更),且 schema_version 的 INSERT 未传值、实际写入版本号是 0;setting/config.go 整体耦合 volcano.Options,主干因此无法插入第二个上游。
ci: 新增 build/vet/test 质量门
2026-10-03 23:41:22 +08:00 · 2026-10-03 16:18:54 +08:00 · 2026-10-03 16:13:47 +08:00 · 2026-10-03 16:13:47 +08:00 · 2026-10-03 16:13:47 +08:00
10 changed files with 969 additions and 9 deletions
@@ -0,0 +1,61 @@
 name: CI
 # 触发条件:
 #   - push 到 develop / main
 #   - 针对 develop / main 的 PR
 #
 # 为什么单独有这个 workflow:
 #   之前仓库里唯一的 workflow 是 docker.yml,它只在打 tag 时构建镜像,
 #   既不做 go build 也不跑 go vet,提交能不能编译没人自动盯着。
 #
 # ⚠️ 本 workflow 的实际覆盖范围(务必知悉):
 #   测试源码按项目策略**不入库**(见 .gitignore 的 `*_test.go`),因此干净克隆里
 #   没有任何 *_test.go,下面的 go test 步骤会打印 "no test files" 后通过。
 #   也就是说:**CI 只能守住"编译通过 + 静态检查通过",守不住行为回归。**
 #   行为回归要靠开发者在本地(测试文件所在处)自行执行:
 #       go test ./... -count=1
 #   如果哪天测试重新入库,把下面的 go test 步骤改成会真正跑起来的形态即可。
 on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop, main]
 # 同一分支的重复推送取消上一次未完成的运行,省 CI 时间。
 concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          # 以 go.mod 里的 go 指令为准,避免两处版本漂移
          go-version-file: go.mod
          cache: true
      - name: 下载依赖
        run: go mod download
      - name: 编译检查
        run: go build ./...
      - name: 静态检查
        run: go vet ./...
      # 以下两步在"测试不入库"策略下是空转(no test files),保留是为了:
      #   1. 覆盖 lock 判定 / 损坏回退 / voice 路由等关键路径的测试一旦重新入库,
      #      无需改 workflow 即可直接生效;
      #   2. -count=1 禁用测试缓存,避免"改坏了却因缓存仍显示通过"。
      - name: 测试(测试源码不入库时为空转)
        run: go test ./... -count=1
      - name: 关键路径汇总(integration)
        run: go test ./test/integration/ -count=1 -v
@@ -4,7 +4,10 @@
 *.test
 *.out
-# Go test sources (prevent accidental commit; tests live outside the repo by policy)
+# Go 测试源码:不入库(测试保留在本地磁盘,由开发者自行 go test ./... -count=1)
 # 理由:测试用例会暴露内部实现细节与断言,不作为交付物外流。
 # 注意:本规则会把测试文件挡在 git 之外,因此仓库内不提供自动化测试;
 #      .github/workflows/ci.yml 里的测试步骤在纯净克隆上无测试可跑。
 *_test.go
 # Editor / OS
@@ -33,14 +36,16 @@ bin/
 # Local dev scripts (per-user; not part of repo)
 start-local.ps1
 # Windows / PowerShell 脚本:一律不入库、不外流
 # ui-handoff/serve.ps1 与 start-local.ps1 是本地起服便利脚本(含本机路径与端口),
 # 不属于交付物。这两个文件在文件系统层面删除被拒,因此只能在 git 层屏蔽。
 *.ps1
 # UI handoff bundle(改造前的单文件副本 + 离线 mock 预览;仅本地对照,不部署)
 ui-handoff/
 # Runtime database artifacts (created by M1 installer flow)
 tts.db
 tts.db-*
 tts.db.*
 installed.lock
 # UI handoff bundle (for external AI redesign work; not deployed)
 ui-handoff/
 # Docs (本地草稿,不入库)
 docs/
@@ -2,6 +2,36 @@
 本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。
 ## [未发布]
 ### 修复
 - **指标空指针崩溃**: `metrics` 包的全局指标(`UpstreamTotal` 等)默认是 nil,只有 `main` 调过
  `metrics.Init()` 后才有值。任何**不经过 main** 的调用路径(直接调 handler、复用为库)都会在
  `controller/tts.go` → `adapter/volcano/synthesis.go` → `metrics.AdapterRecorder` 处 nil 解引用 panic。
  现在 `telemetry` 的 `Counter.Add` / `Gauge.Set` / `Gauge.Add` / `Histogram.Observe` 一律
  **空接收者安全**(nil 静默忽略),并在包注释里写成显式设计约定。
 - **上游 client 空指针**: `volcano.(*HTTPClient).PostStream` 在 client 未初始化时 panic。
  现在返回错误,由 controller 归一成 5xx 并记日志——装配错误不该拖垮进程。
 > 上面两个崩溃是**本地测试暴露出来的**:直接调用 handler 而不经过 `main` 的路径,
 > 会跳过 `metrics.Init()` 与 `volcanoClient` 的赋值。生产二进制不受影响。
 ### 变更
 - **测试源码不再入库**: `.gitignore` 恢复整体屏蔽 `*_test.go`。测试用例会暴露内部实现
  细节与断言,不作为交付物外流;测试文件保留在本地磁盘,由开发者自行执行
  `go test ./... -count=1`。
  ⚠️ 代价必须明确:仓库内**不提供自动化测试**,`.github/workflows/ci.yml` 里的
  `go test` 步骤在纯净克隆上无测试可跑(会打印 `no test files` 并通过),
  **CI 只能守住"编译通过 + 静态检查通过",守不住行为回归**。
 - **新增 CI 校验** (`.github/workflows/ci.yml`): push / PR 到 `develop`、`main` 时跑
  `go build` + `go vet` + `go test -count=1`。此前仓库唯一的 workflow 只在打 tag 时构建
  Docker 镜像,不做任何编译或测试校验。
 - **文档订正**: `docs/UI_HANDOFF.md` 原为"单文件换皮"外包任务书,其中的
  "admin.html ≤ 35KB / setup.html ≤ 15KB / 只改两个 .html" 等约束在 admin 拆分多页后已作废,
  现标注为历史文档并补上当前真实文件结构与验收清单。
 ## [0.2.0] - 2026-08-30
 ### 新增
@@ -29,7 +29,14 @@ func NewHTTPClient() *HTTPClient {
 // PostStream 发送一次流式请求,返回带上下文的 *http.Response。
 // 调用方负责关闭 resp.Body。
 //
 // 空接收者(nil *HTTPClient)安全:返回错误而不是 panic。未初始化的 client 属于
 // 装配错误,应当让该次请求以"上游不可用"失败(controller 归一成 5xx 并记日志),
 // 而不是让整个进程崩掉。
 func (h *HTTPClient) PostStream(ctx context.Context, url string, headers map[string]string, body []byte) (*http.Response, error) {
 	if h == nil || h.client == nil {
 		return nil, fmt.Errorf("volcano: HTTPClient 未初始化,无法发起上游请求")
 	}
 	if ctx == nil {
 		ctx = context.Background()
 	}
@@ -0,0 +1,343 @@
 # UI 外包 Handoff · 火山 TTS 管理后台
 > 历史文档。本文档描述的是**外包给 Codex 做视觉改造**那一次任务,目标是"现有功能完全不动, 只换皮"。
 >
 > ⚠️ **状态: 任务已结束, 且路线已变更。** 该任务之后, admin 后台由提交 `9245c13`
 > 自行重构成**多页 SPA**(见下面 §0.1),本文档正文里的"单文件 / 大小上限 / 改这两个 .html"
 > 等约束**均已失效**,保留仅为记录当时的交接内容与设计讨论。
 > 若要再做视觉改造,请以 §0.1 的当前文件结构为准。
 ---
 ## 0.1 当前真实结构(以此为准)
 admin 后台已从单文件拆分为多页面,共享一套 CSS/JS,由 `//go:embed` 逐条嵌入:
 | 文件 | 作用 | 大小 |
 |---|---|---|
 | `router/admin.html` | 后台外壳(导航 / 布局) | 5.5KB |
 | `router/admin-login.html` | 登录页 | 2.1KB |
 | `router/admin-voices.html` | 音色管理页 | 13.5KB |
 | `router/admin-settings.html` | 设置页 | 14.4KB |
 | `router/admin.css` | 共享样式(全部页面) | 20.2KB |
 | `router/admin-shell.js` | 共享脚本: axios 实例 / toast / 外壳挂载 / 401 拦截 | 7.1KB |
 | `router/setup.html` | 安装引导页(仍是单文件) | 24.0KB |
 - URL 路由(非 hash):`/admin` · `/admin/login` · `/admin/voices` · `/admin/settings`
 - 公共逻辑集中在 `admin-shell.js`,通过 `window.admin` 暴露
  `{ http, getKey, setKey, clearKey, toast, mountShell, formatUptime, … }`
 - **已无"单文件 ≤ 35KB"这类约束**;新增页面请复用 `admin.css` + `admin-shell.js`,不要各写一套。
 ---
 ## 0. 任务概览(历史原文)
 | 项 | 说明 |
 |---|---|
 | 改的文件 | `router/admin.html`、`router/setup.html` |
 | 改的部分 | 视觉、布局、组件、交互模式（loading/empty/error/反馈）|
 | 不改的部分 | API 调用、状态管理逻辑、字段名、文案语义 |
 | 期望产物 | 改完后的两个 .html, 总大小 ≤ 64KB（admin ≤ 35KB, setup ≤ 15KB）|
 | 验收 | dev 起服, 浏览器走完所有流程无回归 + 视觉明显更好 |
 ---
 ## 1. 技术栈约束（历史原文；"单文件"部分已失效）
 | 项 | 现状 | 改动空间 |
 |---|---|---|
 | 构建 | **无构建步骤**（`//go:embed` 进 binary）| 不可改 |
 | Vue | 3.4 via `cdn.bootcdn.net` | 可换版本（保持 3.x 即可）|
 | HTTP | axios 1.6（集中在 `admin-shell.js`）| 可换（fetch / ky / 留 axios 都行）|
 | CSS | 手写, 走 CSS 变量, 集中在 `admin.css` | 可换 **Tailwind CDN / DaisyUI / Pico / 手写** 都行 |
 | 图标 | 暂无 | 可加 lucide / heroicons inline SVG / emoji |
 | 字体 | 系统默认 (`-apple-system, "PingFang SC"...`) | 可加 `Noto Sans SC` via Google Fonts, 但要评估大小 |
 | 路由 | 拆分后已改为 **URL 路由**（`/admin/voices` 等）,不再是 hash 三 tab | 保持 URL 路由 |
 **注意（历史约束,已不适用）**: 当时二进制大小敏感 —— admin.html 31.19KB / setup.html 13.01KB。拆分后 admin 侧总量约 63KB(分散在 6 个文件里,浏览器可分页只加载所需部分),embed 进 binary 后大小影响可接受。**仍然建议**: 不要无脑加 UI 库(Tailwind 全量 + DaisyUI 会显著增大 embed 体积);要加就加在 `admin.css` 一处,所有页面共享。
 ---
 ## 2. 路由 & 模式
 ### 2.1 三个 URL
 - `GET /setup` → `router/setup.html`（安装模式才进得去）
 - `GET /admin` → `router/admin.html`（任何模式都返回 HTML, 鉴权由前端 JS 拦截）
 - `GET /` → 重定向到 `/setup` 或 `/admin`
 ### 2.2 状态机（admin.html）
 ```
 未登录 (无 sessionStorage 'ttsAdminKey')
  ├─ 输入 key + 调 GET /api/admin/overview 验证
  └─ 验证通过 → 写入 sessionStorage + 切到登录后视图
 已登录
  ├─ 三个 tab: dashboard / voices / settings（hash 路由）
  ├─ 调任意 API 返 401 → 清 sessionStorage + 回到登录页
  └─ 改完自己 auth_key → 调 PUT /api/settings/auth-key 200 后清 sessionStorage
 ```
 ### 2.3 状态机（setup.html）
 ```
 未提交: 表单 4 必填 + voices 至少 1 条
  └─ onMounted 调 GET /api/setup/prefill 自动填默认值
  └─ 提交 POST /api/setup, 成功后 location.href = '/admin'
 ```
 ---
 ## 3. API 契约（前端用的全部）
 ### 3.1 鉴权
 | 头 | 说明 |
 |---|---|
 | `Authorization: Bearer <key>` | 所有 /api/* 请求必带（除 /api/setup/*）|
 | 401 响应 | 清 sessionStorage `ttsAdminKey`, 回到登录页 |
 **axios 实例已配置**:
 ```js
 const http = axios.create({ baseURL: '/api' });
 http.interceptors.request.use(c => {
  if (apiKey.value) c.headers.Authorization = 'Bearer ' + apiKey.value;
  return c;
 });
 http.interceptors.response.use(r => r, err => {
  if (err.response && err.response.status === 401) {
    sessionStorage.removeItem('ttsAdminKey');
    apiKey.value = '';
  }
  return Promise.reject(err);
 });
 ```
 ### 3.2 端点
 | Method | Path | 请求 body | 响应 | 鉴权 |
 |---|---|---|---|---|
 | GET | `/api/setup/prefill` | — | `{ settings: {default_resource_id, default_speaker, default_format, sample_rate} }` | 否（仅 install 模式）|
 | POST | `/api/setup` | `{token, settings: {auth_key, api_key, default_resource_id, default_speaker, default_format, sample_rate}, voices: [{name, speaker, resource_id, model, language}]}` | `{ok, redirect, settings, voices}` | 否（仅 install 模式）|
 | GET | `/api/admin/overview` | — | `{mode, installed, db_path, lock_path, version, commit, uptime_seconds, start_time, voice_count, voice_enabled_count, memory: {goroutines, heap_alloc, heap_inuse}}` | 是 |
 | GET | `/api/admin/metrics` | — | Prometheus text | 是 |
 | GET | `/api/voices` | — | `{voices: [{ID, Name, Speaker, ResourceID, Model, Language, Description, Enabled, CreatedAt, UpdatedAt}]}` | 是 |
 | POST | `/api/voices` | `{name, speaker, resource_id, model, language?, description?}` | 创建的 voice 对象 | 是 |
 | DELETE | `/api/voices/{name}` | — | `{deleted, ok}` | 是 |
 | PATCH | `/api/voices/{name}/toggle` | `{enabled: bool}` | 更新后的 voice | 是 |
 | GET | `/api/settings` | — | 完整 settings 对象（见 3.3）| 是 |
 | PUT | `/api/settings` | 部分字段（`default_resource_id` / `default_speaker` / `default_format` / `sample_rate` / `model`）| `{ok, updated, updated_at}` | 是 |
 | PUT | `/api/settings/api-key` | `{api_key: string}` | `{ok}` | 是 |
 | PUT | `/api/settings/auth-key` | `{auth_key: string}` | `{ok}` | 是 |
 | PUT | `/api/settings/cors` | `{allow_all?: bool, origins?: string}` | `{ok, allow_all, origins, cors_active}` | 是 |
 ### 3.3 GET /api/settings 完整响应
 ```json
 {
  "api_key": "volc****etup",       // 打码
  "api_key_set": true,
  "auth_key": "my-o****etup",       // 打码
  "auth_key_set": true,
  "cors_allow_all": false,
  "cors_origins": "https://app.example.com\nhttps://other.com",
  "cors_configured": true,          // banner 显示控制
  "default_resource_id": "volc.megatts.icl",
  "default_speaker": "qian",
  "default_format": "mp3",
  "sample_rate": 24000,
  "model": "seed-tts-2.0-standard",
  "model_type": 0,
  "explicit_language": "",
  "enable_subtitle": false,
  "updated_at": "2026-08-29T16:07:49Z"
 }
 ```
 ### 3.4 错误响应格式
 所有错误（除 OpenAI 兼容的 /v1/audio/speech）用同一格式:
 ```json
 { "error": { "code": "bad_request", "message": "...", "type": "invalid_request_error" } }
 ```
 前端用 `e.response?.data?.error?.message` 提取.
 ---
 ## 4. 字段语义（写文案 / placeholder 用）
 ### 4.1 auth_key
 "OpenAI 鉴权 Key"
 - 客户端用这个 Key 调 `/v1/audio/speech`
 - 登录 `/admin` 也用这个 Key
 - 自定字符串, 不是火山给的, **完全自己造**
 - 例: `my-secret-key-2024`
 ### 4.2 api_key
 "火山 TTS API Key" / "上游 API Key"
 - 调火山 v3 上游用的凭证
 - 从 https://console.volcengine.com/ 获取
 - 例: `5b4d7c2a-...`
 ### 4.3 default_resource_id
 - 音色所属的计费资源 ID
 - `volc.megatts.default` 默认音色 / `volc.megatts.icl` 复刻音色
 ### 4.4 default_speaker
 - 未传 `voice` 字段时用
 - 必须是"音色" tab 里已添加的 voice name
 ### 4.5 voices 字段
 - `name`: 短英文 id, 唯一, 不可改
 - `speaker`: 火山给的 speaker id
 - `resource_id`: 同上 default_resource_id
 - `model`: `seed-tts-2.0-standard` (默认) / `seed-tts-2.0-expressive` / `seed-tts-2.0-clone`
 - `language`: ISO 639-1 (`zh` / `en` / `ja` 等)
 ### 4.6 CORS origins
 - 一行一个 origin
 - 必须 `http://` 或 `https://` 开头
 - 末尾 `/` 自动 trim
 ---
 ## 5. 当前 UI 的具体问题（按痛感排序）
 ### 5.1 admin.html
 | # | 问题 | 现状 | 期望 |
 |---|---|---|---|
 | 1 | **登录页太空** | 一个输入框 + 一个按钮 | 加 logo / 提示 / 服务名 / 安装状态提示 |
 | 2 | **dashboard 卡片平** | 4 个数字 + 路径文本, 无图标无图表 | 加 icon, 用 chart mini sparkline (uptime / memory)|
 | 3 | **voices 表格简陋** | 5 列 + 启停 switch + 删除 | 加排序/搜索/批量操作/分页/拖拽改顺序 |
 | 4 | **新增 voice 弹窗原始** | 6 个 input 堆叠 | 分组, 加 help text, 加示例值, 加实时校验 |
 | 5 | **设置页 1 长页** | 4 段串成 1 长 list | 分 tab/分卡片, 加描述/帮助链接/危险操作分离 |
 | 6 | **改 key 后无 feedback** | 改了直接清 session | 加 toast 通知 "Key 已更新, 请用新 Key 重新登录" |
 | 7 | **删除无 undo** | confirm 弹原生 confirm() | 加 inline 二次确认 / undo snackbar |
 | 8 | **loading 无** | 调 API 时按钮不变 | 加 spinner / disabled 状态 / 进度条 |
 | 9 | **error 无专门显示区** | 用 `actionErr.value` 全局串 | 用 toast / inline error / 错误码对照 |
 | 10 | **响应式差** | desktop only | 至少平板能用, 关键操作 (tab 切换) 移动端可点 |
 | 11 | **配色单调** | 1 个 cyan 强调色 | 加二级色, success/warning/danger 用得不够明显 |
 | 12 | **字体单薄** | 14px 全局 | 大字标题 24-32px, 重要数字 monospace 突出 |
 ### 5.2 setup.html
 | # | 问题 | 现状 | 期望 |
 |---|---|---|---|
 | 1 | **4 字段加 voice 列表一锅烩** | 一长页 | 分步骤 (1.凭证 2.默认 3.音色 4.确认) |
 | 2 | **voice 行无复用 UI** | 自己手写的 row | drag-to-reorder + 复制/粘贴/从预置模板加 |
 | 3 | **无进度感** | 一个 "安装" 按钮 | 安装中显示进度 (写 settings → 写 voices → 写 lock) |
 | 4 | **无"安装后会发生什么"** | 提交后只跳 /admin | 加结果页: 装了什么 / 接下来去 admin 干啥 |
 | 5 | **无 reset** | 改了一锅填错没法批量重置 | "恢复默认值" 按钮 |
 | 6 | **移动端糟糕** | 1 长页 | 至少 step indicator 在窄屏可见 |
 ### 5.3 共性问题
 | # | 问题 | 期望 |
 |---|---|---|
 | 1 | 无 dark/light toggle | 加 toggle, 默认跟随系统 |
 | 2 | 无键盘快捷键 | `/` 聚焦搜索, `Esc` 关弹窗, `Ctrl+S` 保存当前表单 |
 | 3 | 无国际化 | 默认 zh-CN, 可加 i18n 但不强制 |
 | 4 | 无 a11y 标签 | aria-label, focus ring, 键盘可达 |
 ---
 ## 6. 设计参考（建议风格, 不是强制)
 | 风格 | 适配场景 | 推荐度 |
 |---|---|---|
 | Linear / Vercel dashboard | 后台工具, dark mode 友好 | ⭐⭐⭐⭐⭐ |
 | Tailscale admin | 简洁, 卡片化, 信息密度高 | ⭐⭐⭐⭐ |
 | Coolify / CasaOS | 自托管, "家用服务器"感 | ⭐⭐⭐ |
 | shadcn/ui | 现代 React 风, 移植到 Vue 略费劲 | ⭐⭐⭐ (参考设计, 不直接用) |
 | Tailadmin | 通用 admin 模板, 选段借鉴 | ⭐⭐ |
 **主调色建议** (如果重做):
 - 背景: 深色 (`#0a0e1a`) 或浅色 (`#f8fafc`), 配 system pref
 - 强调色: cyan / indigo / emerald 之一
 - 字体: 标题用 Inter, 数字用 JetBrains Mono
 ---
 ## 7. 不要做的事
 - ❌ 改 API 路径 / 改字段名 / 改字段语义
 - ❌ 加任何状态管理库 (Pinia) — 单文件 setup() 够用
 - ❌ 加 webpack/vite — 必须保持单文件
 - ❌ 引大 UI 库 (Element Plus / Naive UI) — 单文件塞不下
 - ❌ 把 admin.html 和 setup.html 合并 — 它们是独立页面
 - ❌ 改 axios 实例的 baseURL 或 401 拦截逻辑
 - ❌ 改 hash 路由的 key 命名（`#dashboard` / `#voices` / `#settings`）
 - ❌ **不要把单文件架构当最终形态** — 这是最小可工作版本(MVP),看板有 `ui-arch-debt` 卡片记录拆分计划。Codex 改造时保持单文件以便本次走通,但**不要引入新依赖让单文件更难拆**。例如:不要把 axios 拦截器写得依赖 10 个全局 ref;不要让 CSS 选择器深嵌套到无法抽离。
 ---
 ## 8. 验收清单（已按拆分后的结构更新）
 改完回来, 我会逐项过:
 - [ ] `go build ./...` 通过
 - [ ] `go vet ./...` 通过
 - [ ] `go test ./... -count=1` 全绿
 - [ ] dev 起服后浏览器:
  - [ ] `/setup` 流程能跑完
  - [ ] `/admin` 登录 → dashboard → voices → settings → 增改删全通
  - [ ] 改 auth_key 后自踢 → 重新登录 → 能用新 key
  - [ ] CORS 未配时顶部 banner 出现, 配后消失
  - [ ] 401 错误时自动跳回登录
 - [ ] 视觉: 跟现在的 admin 比有明显提升 (logo / 排版 / 颜色 / 反馈)
 - [ ] 至少在 1024px 宽度下好看
 - [ ] 没有 console error / 404
 - [ ] 新增页面复用了 `admin.css` + `admin-shell.js`,没有复制粘贴出第二套公共逻辑
 > 旧的"`admin.html` ≤ 35KB / `setup.html` ≤ 15KB"两条**已作废**:admin 已拆成多页,
 > 单文件大小不再是约束。
 ---
 ## 9. 回填方式（历史原文） / 当前做法
 历史原文:
 ```
 1. 拿回 router/admin.html + router/setup.html
 2. 放到 D:\项目\Volcano-Engine-TTS-UI\router\
 3. 我 build + 测, 通过后 commit
 4. push, 服务器自动部署
 ```
 拆分之后的做法:改动落在 §0.1 表格里对应的**具体文件**上(外壳/登录/音色/设置,以及共享的
 `admin.css` / `admin-shell.js`),不再有"两个 .html"这一说。改完在**项目里**跑:
 ```
 go build ./...
 go vet ./...
 go test ./... -count=1
 ```
 三条全过再 commit 到 `develop`。
 ---
 ## 10. 关联文件（不需要改, 但可读懂逻辑）
 - `controller/admin.go` — admin API 实现
 - `controller/settings.go` — settings API 实现
 - `controller/setup.go` — setup API 实现
 - `router/router.go` — Go 路由 + 挂载点（看 `//go:embed` 用法）
 - `router/admin-shell.js` — 共享 axios 实例 / toast / 外壳挂载（改交互先看这里）
 - `middleware/admin_auth.go` — RequireAdmin 实现（理解 401 怎么来）
 ---
 ## 11. 当前文件位置（已更新）
 | 文件 | 大小 |
 |---|---|
 | `router/admin.html` | 5.5KB |
 | `router/admin-login.html` | 2.1KB |
 | `router/admin-voices.html` | 13.5KB |
 | `router/admin-settings.html` | 14.4KB |
 | `router/admin.css` | 20.2KB |
 | `router/admin-shell.js` | 7.1KB |
 | `router/setup.html` | 24.0KB |
 `ui-handoff/` 目录里保留的是**改造前**的单文件副本与离线 mock 预览,仅供对照,不要回填。
@@ -0,0 +1,493 @@
 # 上游适配器开发指南
 > 面向对象:要为本项目接入**新上游 TTS 服务**的开发者(也包括未来的你)。
 > 阅读前提:知道 OpenAI `/v1/audio/speech` 的请求/响应形状,能读 Go。
 >
 > ⚠️ **本文档分两部分,请先看清区别**:
 > **第一部分「现状」描述的是代码里已经存在的东西**,可以直接照着读代码。
 > **第二部分「目标架构」是待实施的设计**,代码里**还不存在** ——
 > 里面的接口、表结构、目录都是提案,需要先按 §4 的分阶段计划落地。
 > 不要把第二部分的接口名当成现有 API 去调用。
 ---
 ## 1. 愿景与现状
 ### 1.1 愿景
 把本服务做成**多渠道多上游聚合层**:对外始终是一个 OpenAI 兼容接口,
 对内可以挂火山、OpenAI、Azure、阿里云、自建 GPT-SoVITS / IndexTTS……等任意上游。
 调用方不需要知道音频是哪个厂商合成的 —— 换上游对客户端应当**透明**。
 ### 1.2 现状(第一部分)
 目前**只有火山一个适配器**,且不是"插件式"的,而是**硬编码进主干**的。
 这一点必须说清楚,因为它决定了新上游不能"只写一个文件就完事"。
 ```
 入口         controller/tts.go        OpenaiTTSHandler
                 │
                 │  opts := setting.GetTTSOptions()      ← 类型是 volcano.Options
                 │  volcano.Synthesis(ctx, volcanoClient, opts, ...)   ← 直接调实现,无接口
                 ▼
 适配器       adapter/volcano/         Options / Synthesis / ParseStream / UpstreamError
                 ▲
                 │  setting.LoadRuntimeConfig 直接构造 volcano.Options / volcano.Additions
 配置         setting/config.go
 ```
 **关键事实**:主干里有一处 `import "…/adapter/volcano"`,不是注解式的,
 而是**类型级耦合**。所以"多上游"不是加文件,而是一次重构(见 §4)。
 当前只有火山适配器时,以下代码是合理的;接第二个上游时必须逐个处理,
 否则会出现"配置是火山的、路由是 OpenAI 的"这种错配。
 ---
 ## 2. 现有火山适配器契约(照此实现即可)
 新适配器要能替代火山适配器,就必须满足下面这些**已经被主干依赖**的契约。
 先读这一节,再读 §3 的接口设计。
 ### 2.1 包的职责划分
 | 文件 | 职责 | 新适配器对应物 |
 |---|---|---|
 | `adapter/volcano/options.go` | 调用参数集合(`Options`)+ 上游扩展参数(`Additions`)+ `IsZero()` | provider 私有 opts |
 | `adapter/volcano/request.go` | `Options` → 上游请求体;`buildRequest` 做必填校验;`convertSpeedToSpeechRate` 做 OpenAI speed 换算 | 请求构造 |
 | `adapter/volcano/client.go` | 复用连接的 `*HTTPClient`(keep-alive 调优);`PostStream` 发流式请求 | 传输层 |
 | `adapter/volcano/synthesis.go` | **唯一入口** `Synthesis(...)`;编排 埋点 → 构造 → 发送 → 解析 → 收尾 | `Synthesize(...)` |
 | `adapter/volcano/response.go` | `ParseStream` 解析 NDJSON 流;`ParsedStream` 累计结果 | 响应解析 |
 | `adapter/volcano/errors.go` | `UpstreamError{Code,Message,Stage,Wrapped}` + `IsAuth()` | 错误类型 |
 | `adapter/volcano/audio.go` | `WrapWAVHeader` —— 上游只给 PCM 时本地拼标准 wav 头 | 格式收尾 |
 ### 2.2 主干对适配器的硬性依赖(必须逐条满足)
 | # | 主干行为 | 位置 | 新适配器必须 |
 |---|---|---|---|
 | 1 | 用包级 `*HTTPClient` 发请求,连接复用 | `controller/tts.go:27,32` | 提供可复用的 client,不要每次 new |
 | 2 | 可用 `ctx` 控制超时 | `controller/tts.go:203` | `Synthesize` 必须接受 `context.Context` |
 | 3 | 埋点接口 **3 个方法** | `adapter/volcano/synthesis.go:20-24` | 见 §2.3 |
 | 4 | 错误按 `Stage` 分类成 status label | `controller/tts.go:242-256` | 错误必须携带阶段:`request`/`http`/`stream`/`wrap` |
 | 5 | 错误码进 metrics label | `metrics/metrics.go:160-172` | 非零 code 会被聚合成 `client`/`server`/`upstream` |
 | 6 | 返回结果结构 | `dto.SynthesisResult` | 见 §2.4 |
 | 7 | 上游不支持的输出格式要**降级** | `synthesis.go:63-65`、`README` 格式表 | 见 §2.5 |
 ### 2.3 埋点接口(MetricsRecorder)
 适配器**不 import telemetry 包**,而是由主干注入一个接口实现
 (`controller/tts.go:28` 注入 `metrics.AdapterRecorder{}`)。这是刻意的解耦,新适配器请沿用。
 ```go
 type MetricsRecorder interface {
    UpstreamStarted(speaker, model, format string)
    UpstreamFinished(speaker, model, format, status string,
        duration, ttfb time.Duration, chunks, audioBytes, errCode int)
    UpstreamUsage(model string, textWords int)
 }
 ```
 现状实现里 `speaker` 是**语料无关的上游音色 ID**,会被 `telemetry.SpeakerLabel`
 做 `sha1[:8]` 哈希后才当 label(隐私保护,见 `metrics/metrics.go:127`)。
 新适配器传自己的音色标识即可,主干不解释它的含义。
 `status` 的取值约定(沿用即可,聚合看板依赖它们):
 `ok` / `request_error` / `transport_error` / `http_<code>` / `stream_error` / `wrap_error`。
 ### 2.4 返回结果(dto.SynthesisResult)
 ```go
 type SynthesisResult struct {
    AudioData  []byte        // 最终可直接回给客户端的音频字节(已收尾,如 wav 拼好头)
    Format     string        // 真实输出格式,决定 Content-Type
    SampleRate int
    ReqID      string        // 回写 X-Request-Id,排障用
    TextWords  int           // 上游计费字符数(取不到填 0)
    Chunks     int
    AudioBytes int
    TTFB       time.Duration // 首字节耗时
    Duration   time.Duration
 }
 ```
 `Format` 必须是主干认识的取值(见 `controller/tts.go:258` `contentTypeFor`):
 `mp3` / `wav` / `pcm` / `ogg_opus`(别名 `opus`)。填别的会导致 Content-Type 错。
 ### 2.5 格式降级规则(容易踩)
 客户端要的 `response_format` 和上游能给的格式**往往不一致**,必须显式降级:
 | 客户端要 | 火山做法 | 为什么 |
 |---|---|---|
 | `wav` | 上游请求 `pcm`,本地 `WrapWAVHeader` 拼头 | 流式 wav 每 chunk 带独立头,拼接即坏 |
 | `aac` / `flac` | **降级成 mp3**,Content-Type 报 `audio/mpeg` | 火山不支持 |
 | `opus` | 上游 `ogg_opus` | 命名差异 |
 新适配器同样要回答这个问题:**你要的格式上游给不了时,降级到什么?**
 并且必须在 `Format` 字段里如实回报真实格式,否则客户端拿到的是"声明 mp3 实际 pcm"。
 ### 2.6 实测踩过的坑(上游协议层面)
 这些是火山适配器真实修过的 bug,接新上游时同类问题大概率复现:
 1. **事件分发必须白名单**:`ParseStream` 只把 `event == "sentence"` 或事件为空的帧
   当音频,未知事件只记日志**绝不拼进音频**(`response.go:71-113`)。
   早期实现把 `TTSSubtitle` 也当音频,导致音频流被污染。
 2. **结束帧要提前 break**:上游用 `code == 20000000` 表示流正常结束,收到后要
   把剩余行读完再 break,否则连接不释放。
 3. **单行可能很长**:`scanner.Buffer` 上限要放大(火山设到 8MB),否则大 chunk 会 EOF。
 4. **所有音频帧 base64 解码失败要**返回错误,**不能跳过** —— 跳过等于静默产出半截音频。
 5. **一个字节音频都没收到要报错**,不能返回空切片当成功(`response.go:125-131`)。
 6. **错误响应体可能含换行**:直接拼进错误消息会伪造日志行,火山做了
   `\n`/`\r` 转义(`synthesis.go:99-101`),新适配器照做。
 ---
 ## 3. 目标架构:Provider 抽象(待实施)
 以下代码**当前不存在**,是建议落地的设计。
 ### 3.1 接口定义
 建议新增 `adapter/provider/provider.go`(新包,**不放在** `adapter/volcano` 里,
 避免主干继续依赖具体实现):
 ```go
 // Provider 是一个上游 TTS 服务的统一抽象。
 // 实现者只需要关心:把我的能力说清楚、把一次合成做完。
 type Provider interface {
    // Name 稳定标识,用于配置键、库表字段、metrics label。
    // 约定全小写无空格:volcano / openai / azure / aliyun / gpt-sovits。
    Name() string
    // Capabilities 声明本适配器支持什么。
    // 主干据此做校验与降级,不靠 if-else 猜实现。
    Capabilities() Capabilities
    // Synthesize 执行一次合成,阻塞到完成。
    // 必须遵守:ctx 取消即返回;上游不支持 clientFormat 时按 Capabilities 降级,
    // 并在 Result.Format 里如实回报真实格式。
    Synthesize(ctx context.Context, req Request, mtr MetricsRecorder) (*dto.SynthesisResult, error)
 }
 type Capabilities struct {
    // 上游原生能产出的格式;客户端要的格式不在其中时,主干负责降级或拒绝。
    Formats []string
    // 是否支持用倍率控制语速。不支持时主干忽略 speed 而不是报错。
    Speed bool
    // 是否按字符计费并回传用量(决定 UpstreamUsage 是否有意义)。
    Usage bool
    // 是否支持多音色路由。不支持时该 provider 只能配一个默认音色。
    Voices bool
    // 是否需要资源/部署/项目 ID 这类额外维度(火山需要,OpenAI 不需要)。
    ExtraScopes bool
 }
 // Request 是主干交给适配器的、已归一化的合成请求。
 // 注意:这里刻意不出现任何厂商专属字段。
 type Request struct {
    Text         string
    VoiceKey     string            // voices 表的主键语义(对外 voice 名或上游音色 ID)
    Model        string
    Format       string            // 客户端期望格式(主干已归一化:mp3/wav/pcm/ogg_opus)
    SampleRate   int
    Speed        float64           // 1.0 = 原速
    Language     string
    Extra        map[string]string // 厂商专属配置,从 voices/settings 的 JSON 列读
    // Credentials 由 provider 自己解释:
    // 火山读 api_key + resource_id;OpenAI 只读 api_key。
    Credentials Credentials
 }
 type Credentials struct {
    APIKey string
    // 厂商额外凭证/路由维度。火山: resource_id;Azure: region;自建: base_url。
    Scope map[string]string
 }
 ```
 ### 3.2 注册表
 ```go
 // adapter/provider/registry.go
 func Register(p Provider)        // 通常在包的 init() 里调用
 func Get(name string) (Provider, bool)
 func Names() []string            // admin UI 下拉框用
 ```
 **要点**:注册要放在**主干之外**。建议 `main.go` 显式空导入:
 ```go
 import (
    _ "github.com/volcano-tts/tts-api/adapter/volcano"  // 注册 volcano
    _ "github.com/volcano-tts/tts-api/adapter/openai"   // 注册 openai
 )
 ```
 这样主干只依赖 `provider` 包,**新增上游不需要改主干任何一行** —— 这是本架构的核心收益,
 请务必守住。`controller/tts.go` 里不应再出现 `adapter/volcano`。
 ---
 ## 4. 分阶段实施计划
 **强烈建议按阶段做,每阶段结束都能编译、能跑、行为不变。**
 一次性重构"配置 + 路由 + 库表 + 前端 + metrics"五个面,几乎必然做出半成品。
 ### 阶段 0 · 抽出接口,零行为变更(纯重构)
 目标:主干不再依赖具体实现,但**行为完全不变**,回归风险最低。
 - [ ] 新增 `adapter/provider` 包,放 `Provider` / `Capabilities` / `Request` / `Credentials` / `MetricsRecorder`
 - [ ] 让 `volcano` 包实现 `Provider`(本质是把 `Options` 包一层适配,`Synthesis` 改成方法)
 - [ ] `controller/tts.go`:把 `volcanoClient` + `volcano.Synthesis` 换成 `provider.Get(name).Synthesize`
 - [ ] `MetricsRecorder` 从 `adapter/volcano` **移出**到 `provider` 包(否则接口还是火山专属)
 - [ ] `setting.LoadRuntimeConfig` 暂时继续构造 `volcano.Options`,通过一个
      「volcano provider 的配置映射函数」转成 `provider.Request`
 - [ ] 验收:`go build ./... && go vet ./... && go test ./... -count=1` 全绿,
      且 `/v1/audio/speech` 行为与重构前逐字节一致(拿同一段文本对比音频长度与格式)
 > 这一阶段**不要**动库表、不要动前端。目标只有一个:主干里那行
 > `import adapter/volcano` 消失。
 ### 阶段 1 · 数据结构:provider 维度入库
 > ⚠️ **先纠正一个常见误解:本项目的迁移框架其实没有接线。**
 > `store/migrate.go` 里定义了 `Migration` 结构体和 `migrations` 切片,但那个切片是
 > **空的**,`store/db.go` 的 `migrate()` 也从**不**读取它 —— 注释里写得很明白:
 > "本期 M0 阶段 schemaVersion=1,migrate() 在 db.go 内做基础建表,**未触发 migrations 调度**"。
 > 所以 `migrate()` 目前**只做 `CREATE TABLE IF NOT EXISTS`**,没有任何版本比较,
 > 对已存在的表**完全不做变更**。
 >
 > 还有一个既有瑕疵:`db.go:148-150` 的 `INSERT OR IGNORE INTO schema_version (version) VALUES (?)`
 > 语句里既没有字面量也没传参,绑定到 `?` 的是**零值**,所以表里实际写入的版本号是 **0**,
 > 不是常量 `schemaVersion`(=1)。做 v2 迁移时请一并修掉,否则版本判断从一开始就是错的。
 >
 > **结论**:给 `voices` 加列**不会**自动发生,你必须自己写 `ALTER TABLE`,
 > 并且在启动时能被重复执行而不报错(老库、新库都要能跑)。
 本阶段要做:
 - [ ] 在 `migrate()`(或新启用的迁移调度)里实现**幂等**加列:
      先 `PRAGMA table_info(voices)` 查现有列,缺哪个 `ALTER TABLE ... ADD COLUMN` 哪个
      (SQLite 的 `ADD COLUMN` 不支持 `IF NOT EXISTS`,重复执行会报错,必须先查)
 - [ ] `voices` 表加列(见 §5.1),老库回填 `provider='volcano'`
 - [ ] 修正 `schema_version` 写入零值的瑕疵,并写出真实版本号
 - [ ] 若确实要启用 `migrate.go` 的调度框架,则把 `schemaVersion`(db.go,`=1`)
      与 `schemaVersionRequested`(migrate.go,`=1`)一并提升到 2;
      注意 `installer/lock.go` 里的 `schemaVersion = "1"`(字符串)**是另一套东西**——
      它写在 `installed.lock` 里做安装标记,与库表结构版本是两回事,
      两者要一起提升就一起提升,不要只改一边造成语义分裂
 - [ ] `store.Voice` 结构体加字段 + JSON tag
 - [ ] `store.GetVoiceForTTS` 返回值扩展(见 §5.2),`setting.Store` 接口同步改
 - [ ] `cmd/dumpdb` 输出新列
 - [ ] 验收:**用一个装了老数据的 `tts.db`** 启动服务(不要用全新库测),
      确认自动加列成功、数据不丢、`/v1/audio/speech` 仍可用;
      再重启一次确认迁移幂等(第二次不报错)
 ### 阶段 2 · 配置:按 provider 命名空间化
 现状是 `settings` 表用**扁平键**,且键名全是火山语义(`default_resource_id`、
 `default_speaker`、`model_type`…)。多上游后必须命名空间化。
 - [ ] 保留全局键:`auth_key` / `cors_*` / `timeout` / `default_provider`
 - [ ] 厂商专属键改为 `provider.<name>.<key>`,例如
      `provider.volcano.api_key`、`provider.volcano.resource_id`、
      `provider.openai.api_key`、`provider.openai.base_url`
 - [ ] `LoadRuntimeConfig` 只装配**当前 `default_provider`** 的 `Request`,
      不再构造 `volcano.Options`
 - [ ] `setting.CheckEnvironmentVariables` / `LogStartupSummary` 去掉
      `BYTEDANCE_TTS_*` 硬编码名,改成遍历 provider 的必填项(否则 `/health` 会误导运维)
 - [ ] 迁移:老键 `api_key` → `provider.volcano.api_key` 等,一次性搬完并保留旧键只读兜底一轮
 - [ ] 验收:除火山外没有任何 provider 时,服务行为仍与阶段 1 相同
 ### 阶段 3 · 观测:metrics 加 provider 维度
 - [ ] `tts_upstream_total` / `tts_upstream_duration_seconds` / `tts_upstream_errors_total`
      等**全部上游指标加 `provider` label**
 - [ ] `metrics.AdapterRecorder` 增加 provider 字段(构造时注入 name)
 - [ ] 仪表盘 PromQL 补 `by (provider)`
 - [ ] ⚠️ **破坏性变更**:加 label 会让现有告警规则里的
      `tts_upstream_total{...}` 聚合口径变化,发布说明里要写明
 - [ ] 验收:`/metrics` 上能按 provider 拆分成功率与 P95
 ### 阶段 4 · 管理界面:provider 选择与音色归属
 - [ ] `/setup` 向导第 1 步加"上游类型"选择,后续步骤按所选 provider 动态渲染字段
      (火山显示 resource_id,**OpenAI 显示 base_url 且不显示 resource_id**)
 - [ ] `router/admin-voices.html` 新增/编辑音色时选 provider 与 model
 - [ ] `/api/voices` 的请求/响应加 `provider` 字段,`controller/admin.go` 校验
      "provider 必须已注册",否则 400(不要留到合成时才 500)
 - [ ] 删除 provider 最后一个音色时的保护逻辑(现在的 `ErrInUse` 只管 `default_speaker`)
 - [ ] 验收:UI 上能并存火山与 OpenAI 音色,各自路由正确
 ### 阶段 5 · 第二个真实适配器(OpenAI 兼容)
 **这一步才是对抽象的真正验收**。选 OpenAI 兼容上游(或其代理)最省事,因为
 本项目对外就是 OpenAI 形状 —— 可以直接验证"请求/响应穿透"是否正确。
 - [ ] 新建 `adapter/openai/`,只实现 §3.1 的接口
 - [ ] 全程**不改** `controller/` `setting/` `store/` 任何一行
 - [ ] 如果为了实现它而必须改主干,说明 §3.1 的抽象漏了维度 —— **回头修接口,而不是打补丁**
 - [ ] 验收:同一份 `voices` 配置里两个 provider 可同时服务,
      客户端只看到 `voice` 名不同
 ---
 ## 5. 数据模型改动细节
 ### 5.1 voices 表
 现状(真实 schema,`store/db.go:129-142`):
 ```sql
 CREATE TABLE IF NOT EXISTS voices (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    name        TEXT NOT NULL UNIQUE,
    speaker     TEXT NOT NULL,      -- 上游音色 ID
    resource_id TEXT NOT NULL,      -- ← 火山专属概念,却写成 NOT NULL 通用列
    model       TEXT DEFAULT '',
    language    TEXT DEFAULT '',
    description TEXT DEFAULT '',
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
 );
 ```
 **问题**:`resource_id` 是火山独有概念(决定模型版本与计费),却成了全表必填列。
 OpenAI 上游根本没有这个字段 —— 这正是"单上游假设"渗进数据模型的典型症状。
 建议改为:
 ```sql
 ALTER TABLE voices ADD COLUMN provider TEXT NOT NULL DEFAULT 'volcano';
 ALTER TABLE voices ADD COLUMN vendor_params TEXT NOT NULL DEFAULT '{}';  -- JSON,厂商私有
 -- resource_id 保留但放宽为可空(或整体搬进 vendor_params,看迁移成本)
 ```
 - `provider` 建索引:`CREATE INDEX idx_voices_provider ON voices(provider)`
 - `vendor_params` 存厂商私有键值(火山:`{"resource_id":"seed-icl-2.0","model_type":4}`),
  主干**不解释**它的内容,原样交给对应 provider
 - 迁移:`UPDATE voices SET provider='volcano' WHERE provider IS NULL OR provider=''`
 ### 5.2 GetVoiceForTTS 的签名
 现状(`setting/config.go:426-436`,刻意用 5 个返回值避免循环 import):
 ```go
 GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error)
 ```
 多上游后要扩成:
 ```go
 // 返回该 voice 的 provider 名 + 厂商私有参数,主干据此把请求路由给对应适配器。
 GetVoiceForTTS(name string) (providerName, speakerID, model string, vendorParams map[string]string, found bool, err error)
 ```
 **注意**:当年之所以不用 `(VoiceRef, error)`,是为了让 `store` 不 import `setting`
 (避免循环 import)。加字段时**别再引入新的结构体依赖**,继续用扁平返回值或
 定义在 `store` 包里的中性结构体。
 ---
 ## 6. 新增一个适配器的完整清单
 假设要加 `foo` 上游:
 **代码**
 1. `adapter/foo/foo.go` —— 实现 `provider.Provider`(`Name()` 返回 `"foo"`)
 2. `adapter/foo/request.go` —— `provider.Request` → foo 的 HTTP 请求体
 3. `adapter/foo/response.go` —— 解析 foo 的响应;严格遵守 §2.6 的 6 条协议纪律
 4. `adapter/foo/errors.go` —— 错误要带阶段,`Stage` 用统一枚举
 5. `adapter/foo/foo_test.go` —— 至少覆盖:正常流、未知事件不污染音频、空音频报错、
   base64 解码失败报错、格式降级回报正确 `Format`、`ctx` 取消能及时返回
   (测试文件按项目策略不入库,本地保留并在合并前手动跑)
 6. 在 `foo.go` 的 `init()` 里 `provider.Register(...)`
 7. `main.go` 加一行空导入
 **配置**
 8. 定义必填项清单(供 `/health` 与启动摘要显示),不要写死在前端
 9. 在 `/setup` 向导里加该 provider 的字段定义(阶段 4 之后是数据驱动,只需加配置)
 **验收**
 10. `go build ./... && go vet ./... && go test ./... -count=1` 全绿
 11. 起服 → `/setup` 选 foo → 填凭证 → 加一个音色 → `curl /v1/audio/speech` 出声
 12. 故意填错凭证 → 客户端应拿到明确的 4xx/5xx 与 `code`,日志里凭证是**打码**的
 13. 不支持的 `response_format` → 按 `Capabilities` 降级,且 Content-Type 与真实字节一致
 ---
 ## 7. 测试策略(注意本项目的特殊约束)
 **本项目测试文件不入库**(`.gitignore` 里的 `*_test.go`),
 测试保留在本地磁盘。这带来两个直接后果,必须知道:
 1. **CI 跑不到你的测试**。`.github/workflows/ci.yml` 里的 `go test` 步骤在干净克隆上
   只会打印 `no test files` 然后通过 —— 它只能守住"编译 + vet"。
   所以适配器测试**必须在本地跑过再合并**:
   ```bash
   go test ./... -count=1
   ```
 2. **不要依赖测试文件来传递知识**。协议细节、踩坑记录要写进**代码注释**和本文档,
   否则对下一个人(以及在 CI 里)等于不存在。
 适配器测试的**最小可用集合**(按 §2.6 的坑逐条覆盖):
 | 用例 | 断言 |
 |---|---|
 | 正常流 | 音频字节非空;`Chunks` / `TTFB` / `Format` 合理 |
 | 未知事件帧 | 不进入音频;不报错;不改变 `Chunks` |
 | 字幕帧 | 进 `Subtitles`,**不进** `AudioData` |
 | 全流无音频 | 返回错误,不是"成功 + 空字节" |
 | base64 损坏 | 返回错误,不是跳过继续 |
 | 超长单行(>1MB) | 不 EOF |
 | 上游 HTTP 4xx/5xx | 错误 `Stage == "http"`,携带 code |
 | `ctx` 取消 | 及时返回,不泄漏 goroutine |
 | 格式降级 | `Result.Format` 是真实格式,不是客户端要的格式 |
 ---
 ## 8. 反模式清单(明确不要做)
 - ❌ **不要在 `controller/` 里写 `switch providerName` 分发**。
  分发只能走注册表,否则每加一个上游都要改主干,抽象就白做了。
 - ❌ **不要让 `provider` 包 import 任何具体适配器**。依赖方向永远是
  `具体适配器 → provider 包 ← 主干`。
 - ❌ **不要在 `provider.Request` 里加厂商专属字段**(如 `ResourceID`)。
  厂商私有参数一律走 `Credentials.Scope` / `Request.Extra` / `voices.vendor_params`。
 - ❌ **不要把上游返回的原始音频直接当结果返回而不收尾**。
  PCM 要拼头,降级要如实回报 `Format`(见 §2.5)。
 - ❌ **不要静默跳过解析失败的帧**(§2.6 第 4 条)。
 - ❌ **不要在日志里打印明文凭证或音色 ID**。沿用
  `telemetry.MaskSpeaker` / `MaskResourceID`,新适配器的私有敏感字段也要加等价打码。
 - ❌ **不要用一个 `settings` 键名承载多个 provider 的配置**。
 - ❌ **不要为了省事把 provider 名写进 `settings` 的扁平键里当"事实上的路由"**,
  路由的唯一权威是 `voices.provider` 与 `default_provider`。
 ---
 ## 9. 关键文件索引
 | 关注点 | 文件 | 说明 |
 |---|---|---|
 | 请求入口 / 校验 / 路由 | `controller/tts.go` | `resolveClientFormat`、voice 查库、错误归一 |
 | 合成编排参考实现 | `adapter/volcano/synthesis.go` | 埋点顺序、格式降级、错误分阶段 |
 | 流解析参考实现 | `adapter/volcano/response.go` | 事件白名单、结束帧、base64 |
 | 传输层参考实现 | `adapter/volcano/client.go` | 连接复用、nil 安全 |
 | 配置装配 | `setting/config.go` | `LoadRuntimeConfig`、`setting.Store` 接口 |
 | 库表与迁移 | `store/db.go`、`store/migrate.go` | `schemaVersion`、`migrate()`(**迁移框架未接线,见阶段 1 警示**);`installer/lock.go` 的 `schemaVersion` 是另一套 |
 | 音色模型 | `store/voices.go` | `Voice`、`GetVoiceForTTS` |
 | 指标 | `metrics/metrics.go` | `AdapterRecorder`、`codeLabel` |
 | 结果类型 | `dto/tts.go` | `SynthesisResult`、`SubtitleEntry` |
 | 未来抽象落点 | `adapter/provider/` | **尚不存在,待阶段 0 创建** |
 ---
 *文档版本:v1 · 对应代码基线:`develop` @ `ad342ec`(2026-10-03)*
 *本文「现状」部分与代码逐行核对过;「目标架构」为提案,实施时请同步更新本文档。*
@@ -36,8 +36,12 @@ func newCounter(name, help string, labelNames []string) *Counter {
 func (c *Counter) Inc(labels Labels) { c.Add(1, labels) }
 // Add 累加 v(v 必须 >= 0)。
 //
 // 空接收者(nil *Counter)安全:未初始化的全局指标(如 metrics.Init() 尚未调用时
 // 的 metrics.UpstreamTotal)会被静默忽略,而不是 panic。
 // 这让"直接调用 handler"的测试/复用场景不会因为漏掉指标初始化而崩溃。
 func (c *Counter) Add(v float64, labels Labels) {
-	if v < 0 {
+	if c == nil || v < 0 {
 		return
 	}
 	child := c.getOrCreate(labels)
@@ -33,7 +33,11 @@ func newGauge(name, help string, labelNames []string) *Gauge {
 }
 // Set 直接设置当前值。
 // 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
 func (g *Gauge) Set(v float64, labels Labels) {
 	if g == nil {
 		return
 	}
 	child := g.getOrCreate(labels)
 	child.bits.Store(float64bits(v))
 }
@@ -45,7 +49,11 @@ func (g *Gauge) Inc(labels Labels) { g.Add(1, labels) }
 func (g *Gauge) Dec(labels Labels) { g.Add(-1, labels) }
 // Add 累加 v(可负)。
 // 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
 func (g *Gauge) Add(v float64, labels Labels) {
 	if g == nil {
 		return
 	}
 	child := g.getOrCreate(labels)
 	for {
 		bits := child.bits.Load()
@@ -47,7 +47,11 @@ func newHistogram(name, help string, buckets []float64, labelNames []string) *Hi
 }
 // Observe 记录一个观测值。
 // 空接收者(nil *Histogram)安全,见 Counter.Add 的说明。
 func (h *Histogram) Observe(v float64, labels Labels) {
 	if h == nil {
 		return
 	}
 	child := h.getOrCreate(labels)
 	for {
 		bits := child.sumBits.Load()
@@ -5,7 +5,12 @@
 //   - 零外部依赖,只使用标准库;
 //   - label key 在指标注册时锁定,运行期不可新增(避免 cardinality 爆炸);
 //   - 所有并发安全由实现保证,调用方无需加锁;
-//   - Meter 是高层入口,NoopMeter 用于测试。
+//   - Meter 是高层入口,NoopMeter 用于测试;
 //   - **空接收者安全**: 未初始化的 *Counter / *Gauge / *Histogram(即 nil 指针)
 //     上的 Inc/Add/Set/Observe 一律静默忽略,不 panic。
 //     这条约定是为 metrics 包的全局指标变量服务的 —— 它们默认为 nil,只有 main
 //     调用过 metrics.Init() 之后才有值;直接复用 handler 的场景(集成测试、
 //     未来做成库)不应该因为漏掉指标初始化而崩掉整个请求处理。
 package telemetry
 import (
Author	SHA1	Message	Date
sun	49f57e4d28	docs: 新增上游适配器开发指南 CI / build-and-test (push) Canceled after 0s Details 面向多渠道多上游适配器愿景的落地文档,分两部分:第一部分逐行核对现有火山适配器的真实契约(包的职责划分、主干对适配器的 7 项硬性依赖、MetricsRecorder 埋点约定、格式降级规则、以及 6 条实测踩过的上游协议坑);第二部分给出 Provider 抽象的目标设计与分阶段实施计划(阶段 0 抽接口零行为变更 -> 阶段 1 provider 入库 -> 阶段 2 配置命名空间化 -> 阶段 3 metrics 加 provider 维度 -> 阶段 4 管理界面 -> 阶段 5 第二个真实适配器)。同时如实记录三处现状缺陷,避免按文档实施时踩坑:voice.resource_id 是火山专属概念却成了全表 NOT NULL 通用列;store/migrate.go 的迁移框架定义了 Migration/migrations 但切片为空、migrate() 从不读取它(实际只做 CREATE TABLE IF NOT EXISTS,对已存在的表不做任何变更),且 schema_version 的 INSERT 未传值、实际写入版本号是 0;setting/config.go 整体耦合 volcano.Options,主干因此无法插入第二个上游。	2026-10-03 23:41:22 +08:00
sun	ad342ec8f1	ci: 新增 build/vet/test 质量门 CI / build-and-test (push) Canceled after 0s Details 此前仓库唯一的 workflow 只在打 tag 时构建 Docker 镜像,不做任何编译或测试校验,加上测试源码不入库,导致 go test 全绿从来没有被自动化校验过。新增 ci.yml:push / PR 到 develop、main 时跑 go build ./... / go vet ./... / go test ./... -count=1,再单跑一遍集成测试并输出明细。版本以 go-version-file 跟随 go.mod;-count=1 禁用测试缓存。	2026-10-03 16:18:54 +08:00
sun	24f8accf71	chore: 测试源码不入库,订正过期的 UI handoff 文档与 CHANGELOG .gitignore 恢复整体屏蔽 *_test.go:测试只保留在本地磁盘供开发者执行,不作为交付物外流。因此仓库内不提供自动化测试。 docs/UI_HANDOFF.md 标注为历史文档:它是改造两个单文件 .html、admin <= 35KB 的外包任务书,而 admin 后台此后已重构成多页 SPA(admin-shell.js / admin.css + 登录/音色/设置三页),原约束与验收标准全部失效。补上当前真实文件结构与新的验收清单。	2026-10-03 16:13:47 +08:00
sun	6ac2473099	fix(volcano): PostStream 对未初始化 client 返回错误而不是 panic Synthesis 里 client 是包级 volcanoClient,只在启动时赋值。不经过 main 的调用路径拿到 nil client 时,(*HTTPClient).PostStream 在 h.client.Do 处 nil 解引用崩溃。装配错误应该让这一次请求以上游不可用失败:controller 会归一成 5xx 并记日志,而不是拖垮整个进程。	2026-10-03 16:13:47 +08:00
sun	1e2be0cd5b	fix(telemetry): 指标写入对空接收者安全,修 nil 解引用 panic metrics 包的全局指标(UpstreamTotal 等)默认是 nil,只有 main 调过 metrics.Init() 之后才有值。任何不经过 main 的调用路径都会在 controller/tts.go -> adapter/volcano/synthesis.go -> metrics.AdapterRecorder 处 nil 解引用,整个进程崩掉。生产路径本来没问题(二进制一定先 Init),但这类崩溃只在运行时暴露,且漏掉指标初始化属于很容易踩的装配错误,不该以 panic 收场。改动: Counter.Add / Gauge.Set / Gauge.Add / Histogram.Observe 增加空接收者判断,nil 时静默忽略(与 noop 语义一致);在包注释里写成显式设计约定,避免以后被当成冗余代码删掉。	2026-10-03 16:13:47 +08:00