# 技术债

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

## 未还

### 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` 字段，
  但模板**从未渲染它** —— 适配层写的提示文案一直不可见。
- **为什么先欠着**：只影响观感，不影响功能；改模板会扩大改动面。
- **该还的条件**：需要展示这类提示时。

## 已还

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