技术债
记在这里的债都是有意欠的,不是忘了。每条写清:是什么、为什么先欠着、
什么条件下该还。
未还
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 字段,
但模板从未渲染它 —— 适配层写的提示文案一直不可见。
- 为什么先欠着:只影响观感,不影响功能;改模板会扩大改动面。
- 该还的条件:需要展示这类提示时。
已还
(还清后从上面移到此处,保留一行说明怎么还的,便于追溯)