# 技术债

> 记在这里的债都是**有意欠的**，不是忘了。每条写清：是什么、为什么先欠着、
> 什么条件下该还。

## 未还

### 1. 公司候选提交的是文本而非序号（协议标注的做法）

- **是什么**：接口文档写的是"选择第 1 家公司提交 `question="1"`，**API 由序号映射到原候选**"，
  而当前前端提交的是**选项全部内容拼接的文本**（公司名 + 信用代码 + 状态 + 负责人）。
- **为什么先欠着**：这是产品明确要求的形态。文本在语义上无法表达"我选这一个"，
  后端可能把它当成"换关键词"走 refine 路径重新检索。
- **欠着会怎样**：**可能出现"选一次又弹回同一批候选"的死循环。**
- **该还的条件**：上游公司数据服务恢复后**必须补测** —— 走一遍有候选（`status: found`）的流程，
  选中一家，确认返回的是选定公司后的结果而不是又弹候选列表。
  若循环，两条路：①改回提交序号（序号取自当前显示顺序）；②后端扩语义识别全字段文本。
- **当前状态**：上游持续 `provider_failure`，**`status: found` 一次都没出现过**，因此从未验证。

### 2. `answer.text` 与 `summary.text` 首句重复

- **是什么**：后端把同一段话既放进 `answer.text`（渲染在消息正文）又放进 `summary.text` 的开头，
  实测两者首句**逐字相同**，用户会看到同一段话出现两次。
- **为什么先欠着**：已确认是**后端内容重复**，不是前端渲染问题（前端对两个字段各渲染一次）。
- **欠着会怎样**：回答开头重复一段，观感差。
- **该还的条件**：后端修（推荐，最干净），或前端加去重（权宜：比对首句并剥离，
  但属启发式判断，可能误删）。**需用户拍板走哪条。**

### 3. 文件上传功能待定

- **是什么**：旧协议的文件/图片上传（按钮、拖拽、粘贴三条入口）当前**入口已隐藏**，
  发送逻辑被注释保留。
- **为什么先欠着**：接口请求体只接受 `{thread_id, question}` 两个字段，多一个返回 422，
  旧协议的 `transmission.files / file_pos` **发不出去**。
- **该还的条件**：先定后端方案 —— ①后端扩展请求体接受 files/file_pos；
  ②前端把 OSS 地址拼进 question 文本；③后端提供文件登记接口返回 file_id。
- **参考**：原实现的完整参数见 `harness/docs/reference/legacy/API.md`（旧协议快照，仅供理解原实现）

### 4. 部门筛选在新数据下筛不出结果

- **是什么**：政策「更多」面板的部门下拉是**固定的最初 15 个部门**，
  按字面相等匹配；而接口返回的部门是全称（如"青浦区科学技术委员会"），字面不相等。
- **为什么先欠着**：**用户明确要求**保持最初的实现，暂时不做匹配。
- **⚠️ 不要当 bug 修**：曾试过①按接口数据动态生成选项、②保留固定选项但加关键词归一化匹配，
  两个方案都被否掉。
- **该还的条件**：用户明确要求时再动。

### 5. `Question.message` 字段未被渲染

- **是什么**：`QuestionCard` 的 `Question` 接口里定义了 `message` 字段，
  但模板**从未渲染它** —— 适配层写的提示文案一直不可见。
- **为什么先欠着**：只影响观感，不影响功能；改模板会扩大改动面。
- **该还的条件**：需要展示这类提示时。

### 6. 语音识别仍跑在厂商（metamaker）的服务上

- **是什么**：语音输入走 `wss://qingpu-data-api.metamaker.cn/common/asr_hub`
  （引擎 `aliyun_dashscope`），且**鉴权 token 与 appKey 都硬编码在源码里**
  （`src/three-libs/asr/index.ts` 的 token：`iss: human-large-screen`，**exp 2034-12-29**，入库可见）。
- **为什么先欠着**：**用户 2026-09-18 明确「先不动，先用原来的语音识别功能」**——
  现在能用、无成本、前端零维护；独立的成本主要在「要有人长期维护一个 ASR 网关 + 引擎账号」。
- **欠着会怎样**：⚠️ **厂商若失效那条 token、或停掉那个网关，语音功能会突然不可用，且没有任何预警**；
  另外用户语音音频流经厂商服务器（政务场景下涉及数据合规评估）。
- **该还的条件**：出现以下任一情况就该动 —— ①厂商停服/改价/要求换凭据；②合规要求音频不出自己的服务器；
  ③要换引擎。**退路已经准备好**：协议契约已存档在
  [`../reference/current-api-call-sites.md`](../reference/current-api-call-sites.md) 的「ASR 协议契约」，
  实现方照着就能写自建网关，**前端一行都不用改**（只把 `VITE_ASR` 指向新地址）。
- **一个低成本的前置动作（尚未做）**：把 `index.html` 里写死的 `globalThis.isXF = false`
  **改成环境变量开关** —— 这样万一厂商出问题，改配置就能切到讯飞分支，不必改代码重新发版。

## 已还

（还清后从上面移到此处，保留一行说明怎么还的，便于追溯）