# 后端代理层（server/）

为浏览器/Tauri 前端代理 TypeSafe AI（Jev）与 ASR 请求。key 只存在于服务端，
前端不需要 `VITE_TYPESAFE_API_KEY`，也解决了浏览器直连 `api.typesafe.ai` 的 CORS 问题。

独立子包：自己的 `package.json` 与 lockfile，与根仓库前端互不干扰。Node ≥ 22。

## 怎么跑

```bash
pnpm --dir server install
cp server/.env.example server/.env   # 填入 TYPESAFE_API_KEY
pnpm --dir server dev                # tsx watch，默认 http://localhost:8787
pnpm --dir server smoke              # 冒烟：代理调一次真实 Jev + /api/asr 自测
```

前端侧在根 `.env` 里加一行即切换到代理模式（此时前端无需 key）：

```
VITE_JEV_PROXY_URL=http://localhost:8787
```

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `TYPESAFE_API_KEY` | Jev API key，**只在服务端**，绝不下发前端、不打印日志 |
| `PORT` | 监听端口，默认 `8787` |

## 路由

- `POST /api/jev`：请求体原样透传到 `https://api.typesafe.ai/v1/systemone`，
  上游状态码（401/422/429/529 等）与响应体原样返回。
- `POST /api/asr`：multipart/form-data，文件字段名 `audio`，返回
  `{ transcript, prosody }`。`prosody` 暂为空数组占位，后续接声学特征提取
  （语速/停顿/音高/能量等，见 ADR-0004）。
- `GET /healthz`：存活检查。

CORS 仅放行 `http://localhost:1420`（Tauri dev）与 `http://localhost:5173`（Vite dev）。

## 接入真实 ASR provider

当前 `/api/asr` 走 `MockAsrProvider`（占位转写）。换真实 provider 只需两步：

1. 在 `src/asr/provider.ts` 新增实现 `AsrProvider` 接口的类，输入是
   `input.data`（内存 buffer，**不要写盘**——ADR-0004"特征提取后即焚"）：
   - **阿里云 NLS**：一句话识别 RESTful API，`input.data` 直接作请求体，
     appkey/token 从 `process.env` 读（加到 `server/.env`）；
   - **讯飞语音听写**：WebSocket/REST 端点，同样以 `input.data` 为输入；
   - **Whisper 兼容端点**（OpenAI / Groq / 自托管 faster-whisper）：
     `fetch(url, { method: 'POST', body: FormData(file=Blob(input.data)) })`，
     取返回 JSON 的 `text` 字段。
2. 在 `src/routes/asr.ts` 把 `new MockAsrProvider()` 换成新 provider 实例。

韵律特征提取（ADR-0004 的 (b) 类产物）接入点同上：在 provider 内对
`input.data` 提取统计向量填入 `prosody`，音频 buffer 在请求结束后即弃。