# 接口清点（在用 / 死代码）

> **核对时间**：2026-09-24（用户要求「查看当前项目的接口情况，列出来我来判断哪些可以删」）
> **核对方法**：全仓库 grep 网络调用点（`fetch` / `WebSocket` / `EventSource`）+
> 逐个数 `VITE_*` 环境变量的引用数 → **逐个反查调用方**。复核命令见文末。
>
> 下面 §0 是**一张全量表**（含"建议"列）；§一/§二 是旧版按功能写的细节，仍有效，保留。

## 0. 全量接口清单（2026-09-24）

### A. 在用（核心链路，别删）

| # | 接口 | 用途 | 调用点 |
|---|---|---|---|
| 1 | `POST {VITE_CHAT_API}/api/chat`（SSE） | 对话主链路 | `src/components/api-chat-coordinator.ts` |
| 2 | `POST {同一后端}/api/company/classify` | 企业多标签分类 | `src/network/api/company-classification.ts` |
| 3 | `{VITE_DMS_API}/content/*` | DMS 读写（1886/1887/1888/1889 会话·问答·反馈·企业信息） | `src/network/api/dms/client.ts` |
| 4 | `POST {VITE_DMS_API}/file/uploadFile` | 附件上传到 DMS 文件服务 | `src/network/api/dms/file-upload.ts` |
| 5 | `GET {VITE_NLS_TOKEN_API}`（→ `http://121.43.55.7:10011/proxy/verify/getALYToken`） | 语音识别的 token（后端网关签发） | `src/network/api/nls-token.ts` |
| 6 | `wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1` | 实时语音识别（阿里云 NLS） | `src/three-libs/asr/nls.ts` |
| 7 | `GET {VITE_IP_API}/proxy/verify/getIPByBrowser`（→ 同上 10011） | 取本机 IP（DMS 访客归属） | `src/utils/client-ip.ts` |
| 8 | `POST {VITE_API}/enterprise/login`、`GET {VITE_API}/fta_ent_policy/enterprise_info` | 企业登录换码 / 拉企业信息（**老接口**） | `src/network/api/enterprise.ts` |
| 9 | `POST {modelServer}/open/openid_to_token`（带 `app_key=VITE_APP_KEY`）+ 助手卡片信息 | 免登引导、卡片配置 | `index.html`（脚本段） |
| 10 | `GET {VITE_DOWNLOAD_URL}merchant-agent/policies_public.v1.json` | 惠企政策库（本地 `/merchant-agent/…` 兜底；`VITE_POLICY_LOCAL_FIRST` 决定远端/本地优先级） | `index.html` + `Chat/PolicyMatch.vue` |
| 11 | `GET {VITE_MODEL_SERVER}/v1/policies?…` | 政策「更多」面板列表（远端优先，取不到退本地库） | `Chat/PolicyMatch.vue` |
| 12 | `postMessage(…, VITE_PARENT_ORIGIN)` | 与父页面通信（嵌 iframe 场景） | `index.html` |
| 13 | `VITE_REDIRECT_MAP` | 跳转映射页 | `redirect.html` |

> 📌 **更正一条旧说法**：`VITE_APP_KEY` **不是死配置** —— `index.html` 的 `openid_to_token` 在用。
> （`asr-realtime.md` §8 曾写它是死配置，因为只 grep 了 `src/`，没看 `index.html`。）

### B. 已停用 / 死代码 —— **✅ 2026-09-24 已按用户要求全部删除**

删除清单与验证见 `progress.md` 续 37。删掉的东西（想看旧实现翻 git 历史）：
厂商 OSS 上传（含 `VITE_UPLOAD_SIGN_URL`）· 旧厂商 ASR（`three-libs/asr/index.ts` + `VITE_ASR`
+ `VITE_XF_ASR` + vite `/asr/` 代理 + `index.html` 的 `globalThis.isXF`）·
`stream-message-coordinator.ts` 整个类（`MessageState` 枚举已搬到 `src/types/record.ts`）·
`utils/scope-stream-boundary.ts` · `updateSessionInfo` · `getModelServerUrl` / `isKnowledgeApi` ·
三个空目录 · `syncSessionTitleToServer` 注释块 · 变成孤儿的 npm 依赖 `qs` /
`@microsoft/fetch-event-source`（`components/utils.ts` 一度被误删，因为 `ScrollList.vue` /
`BusinessRecord.vue` 直接用它导出的 `sleep` / `getQueryObj` / `computedOriginContentPosition`，已恢复）。

<details><summary>原清单（2026-09-24 早些时候列的，留作对照）</summary>


| # | 东西 | 现状 | 删了会怎样 |
|---|---|---|---|
| 14 | 厂商 OSS 上传：`POST {VITE_UPLOAD_SIGN_URL}` + 直传 host | 已被 DMS 文件服务取代；实现整段**块注释**保留，`VITE_UPLOAD_SIGN_URL` 仍在四份 env 里 | 只会失去"翻旧实现"的便利；`uploadDmsAttachment` 不受影响 |
| 15 | 旧厂商 ASR：`wss://{VITE_ASR host}/common/asr_hub`、讯飞分支 `VITE_XF_ASR` + vite `/asr/` 代理 | 已被 NLS 取代；`src/three-libs/asr/index.ts` 保留 | **删了就不能"一键切回"**（那正是当初保留它的理由） |
| 16 | `stream-message-coordinator.ts` 整个类（含 `TTSURL=//llm-api.test.metamaker.cn/knowledge/tts`、老 SSE 地址、`{VITE_MODEL_SERVER}/v1/chat/completions`、`CensorURL`） | **没有任何活引用**；只有 `MessageState` 枚举被 `BusinessRecord.vue` / `types/record.ts` 引用 | 需要先把 `MessageState` 挪到别处（枚举本身**不能删**） |
| 17 | `updateSessionInfo()`（1887 标题同步的包装） | 已停用，只有注释引用 | 无 |
| 18 | `getModelServerUrl()` / `isKnowledgeApi()`（`utils/runtime-config.ts`） | 无活调用点（后者只被 #16 用） | 无 |
| 19 | 空目录：`src/three-libs/metamaker`（0 文件）、`global`、`cache`、`assets` | 空壳 | 无 |
| 20 | `syncSessionTitleToServer()` | 已停用（注释保留） | 无 |

</details>

### C. 已经删干净的（只作提示，不用动）

- 使用统计埋点（`assistant-statistics.ts` + `VITE_ASSISTANT_STATISTICS_BASE_URL`，2026-09-18 删）
- 数字人视频流：`/stream/` 代理 + `VITE_STREAM_SERVER` / `VITE_STREAM_TOKEN` / `VITE_HUMAN_IDLE_MP4_URL`
  （只剩 `vite.config.ts` 里一条说明注释）
- dev 期自签 NLS token 的 `/nls-token/` 中间件（2026-09-24 被网关端点取代）

### D. 仍在用、别误删的环境变量

`VITE_API`（#8 + index.html 的 modelServer）· `VITE_CHAT_API` · `VITE_DMS_API` · `VITE_IP_API` ·
`VITE_NLS_TOKEN_API` · `VITE_NLS_APPKEY` · `VITE_DOWNLOAD_URL` · `VITE_POLICY_LOCAL_FIRST` ·
`VITE_MODEL_SERVER` · `VITE_PARENT_ORIGIN` · `VITE_REDIRECT_MAP` · `VITE_APP_KEY` · `VITE_VERSION` ·
四个 `*_TARGET`（vite 代理用）· `VITE_USE_KNOWLEDGE_API`（经 `globalThis.isKnowledgeApi`，
**`index.html` 在用它切「政策解读」卡片** —— 2026-09-24 更正：只 grep `src/` 会把它误判成死配置）。
（`VITE_ASR` / `VITE_XF_ASR` 已随旧 ASR 删除。）

## 一、已经迁到新接口的（不用管）

> ⚠️ 下面这段是 2026-09-17 的版本 + 后续更正，细节仍有效；**未完成/待删的项以 §0 为准**。

老接口 = `{VITE_API}`（`//qingpu-data-api.metamaker.cn`）。

| 功能 | 接口 | 备注 |
|---|---|---|
| 对话（SSE） | `POST {VITE_CHAT_API}/api/chat` | |
| 问答记录（历史）**写入 + 读取** | DMS 栏目 **1889** | 一问一答一条；`title` = 问题文本 |
| 点赞/点踩/取消 | DMS 1889 的 `c_feedback_*` | |
| 删除会话 | DMS（清 1889 记录 + 1887 旧行） | |
| 政策卡片与协议内容 | 随 `/api/chat` 下发 | |
| 惠企政策库数据 | 静态 json `policies_public.v1.json` | |

> ⚠️ **1887 助手会话的写入范围（2026-09-23 时的准）**
>
> - **仍然写**，但只有一处：回答**正常完成**（`totalResponse`）时写一次，见 `useBusinessAssistantChat.ts`
>   的 `void upsertDmsSession(...)`；有源码级断言钉着「活跃调用点只有 1 处、且在 totalResponse 内」
>   （`verify-dms-payload-fields.mjs` 第 4 节）。**中断/报错的轮次不写**。
> - **新建会话、改名不再同步**（2026-09-18 的决定只废了这两条），所以前端会话列表仍是纯本地为主，
>   登录后另按 `c_credit_code` 拉远端会话合并（读侧会排除 `c_is_login="0"` 的访客行）。
> - **建行策略**：2026-09-18 曾是「访客且本轮没有企业信息就不建行」，**2026-09-23 由用户推翻**——
>   只要对话就建行；那种情况下行里放 `c_ip` / `c_is_login="0"` / 时间戳 / 标题与四个必填运营位，
>   **`c_credit_code` 留空**（不写访客标签）。
> - 停用的调用点（`updateSessionInfo` / `syncSessionTitleToServer`）按约定注释保留在
>   `useBusinessAssistantChat.ts`。

## 二、还在用老接口的功能

### 1. 企业身份识别（登录 + 拉企业信息）—— **在用，且牵连最广**

**用户看到什么**：右上角账号区。未登录显示「青浦区区内企业登录」（可点，跳一网通办），
登录后显示**企业名 + 首字母头像 + 退出登录**，还会飘一个气泡「识别到您为我们区内企业，推荐登录」。

**怎么走到老接口**：
| 入口 | 接口 |
|---|---|
| 从一网通办带 `?access_token=` 跳回来 | `POST /enterprise/login` 换 `credit_code` + `authToken` |
| 带 `?credit_code=` 跳回来 | `GET /fta_ent_policy/enterprise_info` 直接拉企业信息 |

**这个身份一共被 5 处依赖**（所以它不只是"显示个名字"）：
1. 账号区显示企业名与头像
2. 判断"是否登录"（`isEnterpriseLoggedIn`）
3. **历史数据分家**：登录 → `ba_chat_history`；访客 → `ba_temp_chat_history`
4. **会话列表**：登录后按 credit_code 拉远端会话（现走 DMS）
5. **DMS 记录归属**：`c_credit_code` = 企业信用代码，未登录则 `访客_<访客id>`

> ⚠️ 前端**只用企业信息的 `name` 与 `credit_code` 两个字段**（其余 19 个字段零引用）——
> 所以真要用 DMS 的企业信息（栏目 1888）替换它，成本很低。

### ~~2. 使用统计（页面浏览 / 回答反馈）~~ —— **已删除（2026-09-18）**

用户要求删掉统计埋点的老接口。已删除：
- 调用点：`BusinessAssistant.vue`（页面浏览）、`BusinessRecord.vue`（反馈统计）
- 整个模块 `src/network/api/assistant-statistics.ts`（连同 `VITE_ASSISTANT_STATISTICS_BASE_URL` 这个已无人用的 env）
- ⚠️ **只留下了访客 id 的读写**（`getOrCreateAssistantVisitorId`），因为 **DMS 记录访客归属
  （`访客_<id>`）在用它** —— 已搬进 `src/network/api/dms/chat-sessions-dms.ts`。
  **localStorage 的 key 字符串保持原样**（`assistant_statistics_visitor_id`）：
  改了会让已存在的访客全部换新 id，同一浏览器在 DMS 里就变成两个访客了。
- 现在**点赞只写 DMS**（原先双写）

### 3. 语音输入 —— ~~在用~~ **2026-09-23 起换成阿里云 NLS，见 [`asr-nls.md`](asr-nls.md)**

> 下面这段是**换之前**的实现记录（厂商 `asr_hub` 中转）。旧实现代码仍在
> `src/three-libs/asr/index.ts`（切回去的退路），所以细节保留；但它已不在链路上。

- 触发：点输入框的麦克风
**实际只依赖 1 个接口：**

```
wss://qingpu-data-api.metamaker.cn/common/asr_hub
    ?project=qingpu&engine=aliyun_dashscope&is_long_connection=true&heartbeat=true
    （移动端多一个 &max_sentence_silence=5000）
```

- host 取自 `VITE_ASR`；**引擎是 `aliyun_dashscope`（阿里云百炼），不是讯飞**
- **鉴权不需要调接口**：token 硬编码在 [asr/index.ts](../../../src/three-libs/asr/index.ts) 里
  （JWT `iss: human-large-screen`，**exp 2034-12-29**）—— 所以 ASR 没有 DMS 那种每天换 token 的问题
- 调用方还硬编码传了一个 `appKey`（`new ASR("<key>", {audio:true,video:false})`），
  但它在当前分支用不到（只在讯飞分支的 `gen_auth` 里用）

**未启用的讯飞分支**（`index.html` 硬编码 `globalThis.isXF = false`，走不到）：

```
POST {VITE_XF_ASR}/api/human_asr/v2/asr/gen_auth     取鉴权
wss://{VITE_XF_ASR}/api/human_asr/v2/asr?Authorization=...
```

与对话协议无关，历次迁移没碰它。

#### 📋 ASR 协议契约（从 [asr/index.ts](../../../src/three-libs/asr/index.ts) 反推，供「换成自建服务」时照做）

**连接**：`wss://<host>/common/asr_hub?project=qingpu&engine=aliyun_dashscope&is_long_connection=true&heartbeat=true`

| 步骤 | 内容 |
|---|---|
| 1. 握手 | 客户端发**一帧 JSON 文本**：`{"card_id": <id>}`（注意：**不是**上面 XF 分支那套 `business/data` 参数） |
| 2. 上行 | **二进制帧**，裸 PCM：格式声明为 `audio/L16;rate=16000`、`encoding: raw`，按 `CHUNK_LENGTH` 切片、`CHECK_INTERVAL` 定时发（`new Int8Array(data)` 直接 `send`） |
| 3. 下行 | JSON：`{"data": {"result": {…}}}`，关键字段 `text`（识别文本）、`pgs`（`"apd"` 等分段标识）、`command`（`"start"` / `"stop"`）、`is_sentence`、`is_quit`、`ls`、`ws` |
| 4. 收尾 | 非讯飞分支用 `{"command": "close"}`；讯飞分支用 `{"data": {"status": 2}}` |

> 要实现自建网关，**照这张表实现即可**——前端不用改，只要把 `VITE_ASR` 指向新地址。
> 引擎侧可以接你自己的阿里云百炼 / 讯飞 / 本地模型。

### 4. 图片 / 附件上传 —— **用户触发不到（入口被注释）**

- 原设计：输入框的上传按钮（图片、pdf/doc/xlsx 等）→ `POST /common/qp_signed_url`
  取 OSS 签名 → 直传 OSS
- 现状：新协议 `/api/chat` 只收 `{thread_id, question}`，附件传不上去，
  **上传入口整块被注释**（`BusinessAssistantMobileInputShell.vue` 里有说明）
- 但代码与 OSS 地址仍活着（地址还是**硬编码**在 `useBusinessAssistantUpload.ts` 里的），
  等后端定了附件契约才能接上

### 5. 政策事项列表的「远端查询」—— **几乎不可达**

- 原设计：列表数据本地都没有时，去模型服务查 `{VITE_MODEL_SERVER}/v1/policies`
- 现状：`fetchPolicyList` 里前面两档（惠企政策库 262 条 / 本轮卡片兜底）**几乎总能命中**，
  第三档基本走不到

### 6. `openid` 换 token —— **只在 test 构建**

- 触发：页面初始化的内联脚本
- 现状：只在 `VITE_USE_KNOWLEDGE_API === false` 时执行，四份 env 里**只有 `.env.test` 是 false**

### 6b. 附件上传 —— **已改走 DMS 文件服务（2026-09-23）**

- **现在**：`POST {VITE_DMS_API}/file/uploadFile`（→ `http://121.43.55.7:10081/dms/file/uploadFile`，
  经 `/dms-api` 代理）。`multipart/form-data`，**五个字段都必填**：
  `file` / `type`（0 图·1 音·2 视·3 文件）/ `columnId`(1889) / `contentId`(0) / `paraName`(c_question)。
  返回 `{"code":200,"content":"/static/photo/1889-c_question-<uuid>.png"}` —— **相对路径**，
  它随聊天请求体的 `pictures` / `files` 发给后端（见 `api-chat.md` 的多模态节）
  - 缩略图预览：相对路径本身取不到，要拼代理前缀 →
    `{VITE_DMS_API}/static/photo/…` 实测 200（`buildDmsFileDisplayUrl()` 干这个）
  - 验证脚本：`harness/tools/verify-dms-file-upload.mjs`
- **[已停用] 原路**：厂商 metamaker 的 OSS 直传 —— `POST {VITE_UPLOAD_SIGN_URL}/common/qp_signed_url`
  取签名 → 直传 OSS → 得到**绝对地址**。2026-09-23 用户要求改用 DMS 存储，代码整段注释保留
  （`useBusinessAssistantUpload.ts`），`VITE_UPLOAD_SIGN_URL` 这个 env 也一并未用

### 7. 取本机 IP（DMS 访客归属用）—— **在用（2026-09-22 新增）**

- 触发：应用启动时预热一次（`main.ts`），写 DMS 前会 `await` 一次（内部缓存 + 并发去重）
- 接口：`GET {VITE_IP_API}/proxy/verify/getIPByBrowser` → **纯文本 IP**
  （响应头 Content-Type 标的是 `application/json`，但正文就是裸 IP —— 按 text 读，别 JSON.parse）
- **必须走同源代理**：接口是 `http://121.43.55.7:10011`，页面是 HTTPS ——
  接口带 `Access-Control-Allow-Origin: *`（跨域没问题），但**混合内容**会被浏览器拦掉。
  dev 见 `vite.config.ts` 的 `/ip-api/`；生产需要 nginx 把 `/ip-api/` 转发到
  `http://121.43.55.7:10011/`（**去掉前缀**）
- 用途：DMS 1887 的 `c_ip` 存这个 IP；访客身份（1889 的 `c_credit_code`）用 `访客_<IP>`
- **拿不到 IP 不致命**：退回 `访客_<浏览器随机 id>`，只是归属不稳定（见 `src/utils/client-ip.ts`）

## 三、已经没有人调用的（死代码，只标注未删）

| 位置 | 原本支撑的功能 | 处置 |
|---|---|---|
| `src/network/api/card/index.js`（`getMediaList` / `giveFeedback` / `appendHistory`） | 卡片媒体信息、点赞点踩的**旧接口版落库**、追加服务端历史 | ✅ **2026-09-18 整文件删除**（连同 `useBusinessAssistantChat.ts` 里那个未使用的 `import cardAPI`） |
| `src/network/api/assistant-statistics.ts` | 使用统计埋点 | ✅ **2026-09-18 整文件删除**（访客 id 那部分已搬进 DMS 模块，见第二节） |
| `PolicyListUpdatedMatch.vue` | 旧协议 `<policy-list-updated>` 卡片列表 | ⚠️ **保留**：仍被 `BusinessRecord` 挂载，**老会话的历史内容里可能还有这种块**，删了那些卡片列表就渲染不出来 |

> 删除的代码都在 git 历史里（`git log --diff-filter=D --name-only` 可查）。
> 上面「保留」那条不是遗漏 —— 它虽对新协议无效，但**对旧历史仍然有效**。

## 四、复核方法（可重跑）

```bash
# 1. 列出所有网络调用点
grep -rn "fetch(\|new WebSocket\|new EventSource\|axios" src/ index.html \
  --include=*.ts --include=*.vue --include=*.js --include=*.html

# 2. 对每个点反查调用方（以 card/index.js 为例）
grep -rn "getMediaList\|giveFeedback\|appendHistory\|network/api/card" src/ \
  --include=*.ts --include=*.vue --include=*.js | grep -v "^src/network/api/card/index.js"
```

**判据**：出现在第 1 步 ≠ 还在用。必须做第 2 步——**没有调用方的就是死代码**。
第二节每条的「触发条件」也是这么查的（例如第 5 条要看 `fetchPolicyList` 前面两档 return
才能判断它几乎走不到）。