Главная Обзор Помощь
Вход
skyversation
/
zhaoshang_client_ui
9
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 264ad1c7ad
Ветки Метки
zhaoshang_clien...
/
harness
/
docs
/
reference
/
README.md

README.md 9.4 KB
История Исходник

接口契约与参考资料

这个目录放外部接口的契约文档，供人和 agent 共同查阅。 原则：参考材料显式收进仓库，避免依赖聊天上下文或人的记忆。

先看哪份

文档 状态 什么时候读
api-chat.md ✅ 现行契约 改任何聊天相关代码之前
api-chat-fields-zh.md ✅ 现行契约 需要字段中英对照、状态取值释义时
company-classification.md ⚠️ 现行契约（后端有实测问题） 做企业信息分类同步（company_info → 1888/1886）时
legacy/API.md 📦 交接快照（非规格、不更新） 只在需要翻"当初调了什么接口"时读
DMS_API.md 📄 外部服务契约（含实测结论） 要调 DMS（数据管理服务）时
DMS_COLUMNS.md 📄 栏目现状 查 DMS 五个栏目的 columnId / 字段时
DMS_MAPPING.md 📄 表→栏目映射 做数据迁移、核对字段映射时
current-api-call-sites.md 📋 现状清单 想知道「还有哪些功能在用老接口 / 哪些是死代码」时

DMS 三份文档的来路：它们出自另一个项目 F:\yysk\AI_zhaoshang\DMS_Data_Migration\（那边有 harness/artifacts/dms_openapi.json、 harness/tools/create_dms_columns.py、harness/docs/RUNBOOK.md）。 复制进来时没带上这些同伴，本文档里指向它们的链接已改为绝对路径。 那边的项目才是 DMS 工作的主场；这里保留它们，是为了让本仓库的问题排查能查到 DMS 契约。

栏目现状（2026-09-18 更新，原「五个栏目全空」的说法已过期）：

  • 1887 助手会话 / 1889 助手问答记录：前端已接入（会话、整段对话、反馈都写这里）， 属于在用的在线数据源。见 ../exec-plans/active/dms-chat-storage.md （注：1887 的写入已于 2026-09-18 按用户指示停用，只保留读取与删除清理）
  • 1886 企业荣誉信息 / 1888 企业基础信息：前端已开始写入（企业信息分类同步， 见 company-classification.md 与 ../exec-plans/active/company-classify-dms-sync.md）—— 两栏目的模型已分别扩到 12 / 47 个字段（新增的 c_tag_* 就是分类标签）。 F4 数据迁移仍未开始，所以这两栏目里目前只有前端同步写进去的行， 源库（qcc_enterprise 8.1 万行 / qcc_honor 7 千行）的行还没迁过来
  • 1885 页面浏览：仍是空的（统计埋点已于 2026-09-18 删除，前端不再写）

现行契约：POST /api/chat

curl --request POST \
  --url http://192.168.2.23:8000/api/chat \
  --header 'Content-Type: application/json' \
  --data '{
  "thread_id": "1111",
  "question": "高新技术企业的奖励是多少钱"
}'

最容易踩的坑：请求体只接受 thread_id 与 question 两个字段，多一个就返回 422。 旧的 transmission.files / file_pos 等字段在新接口上发不出去（这正是"文件上传"功能阻塞的原因）。

  • 返回的是 SSE 命名事件流：accepted / progress / heartbeat / answer / source / item / summary / interrupt / result / done / error
  • 每个事件的 data 统一封装为 {thread_id, request_id, data}
  • answer.text 与 result.response 相同，只能展示一次（result 是快照，不要重复追加）
  • 未收到 done/error 就断开 → 按连接中断处理，不自动重试

前端侧的适配层在 src/components/api-chat-coordinator.ts：它把新协议翻译成既有渲染组件 能识别的内容标记（<scope> / <!-- POLICY_TABLE --> / <ref_links> / <question-cards>）， 因此渲染层（BusinessRecord / PolicyMatch / QuestionCard / ScopeContent）不需要感知新协议。

接口地址由 VITE_CHAT_API 配置，两种写法都支持（服务前缀会自动追加 /api/chat， 已是完整地址则原样使用），见 src/utils/runtime-config.ts 的 getChatApiBaseUrl()。 开发环境走同源代理 /chat-api → http://192.168.2.23:8000（见 vite.config.ts）。

⚠️ 已知的有意偏离：公司候选提交的是公司名，不是序号

api-chat.md 的 interrupt 一节写的是：

用户操作 下一次 question
选择显示的第1家公司 "1"，从1开始；不要重排候选后仍按原序号提交
换关键词 新名称或代码

不能直接把 actions 或 KeyNo 对象放入 question；当前 question 必须是字符串， API 由序号映射到原候选。

当前前端不这么做。 公司候选提交的是选项全部内容拼接成的文本 （公司名 + 信用代码 + 状态 + 负责人，见 src/components/api-chat-coordinator.ts 的 toChatQuestionAnswer）。这是产品明确要求。

🚨 已实际发生的事故：死循环。 提交公司名后再次调用接口，落进了协议里 "换关键词"那条路径 → 后端重新检索 → 返回同一批候选 → 用户再选 → 再循环。 这与上表的语义冲突是预期内的：协议把"文本"这种输入形式保留给了 refine， 文本在语义上无法表达"我选这一个"。

若死循环再次出现，只有两条路：

  1. 改回提交序号（协议的做法）——序号取自当前显示顺序（1 起）， 不要重排候选后仍按原序号提交
  2. 后端扩语义——让后端能识别这种"全字段文本"等价于选中该候选

验证方式：在真实后端走一遍公司候选流程，选中一家后确认返回的是选定公司后的 结果，而不是再次弹出候选列表。

📌 判据以跑着的后端为准。 本文档（含 api-chat.md）描述的是某一时刻的约定， 接口会持续演进。文档与后端行为不一致时，以后端实际行为为准， 并回头更新本文档——不要拿文档去否定实际观测到的行为。

固定动作选项不受影响，仍映射为协议控制串：查看更多 → /next、重新查询 → /retry、 取消公司查询 → /cancel、不需要公司信息 → 不需要。 自由输入（用户手打名称/代码）原样发送，那本就是协议的"换关键词"路径。

interrupt 的全部状态（后端确认）

补问用 kind + status 两个字段描述，四种情况都可能出现：

kind status 含义 前端形态
company_selection found 有候选待选择 候选列表 + 查看更多 / 取消公司查询
company_need not_found 未找到候选，需要补充信息 上方常驻输入框 + 跳过公司查询
company_need failed 查询服务失败 上方常驻输入框 + 跳过公司查询（文案须说明是失败）
company_need 无 status 初次询问是否需要公司信息 上方常驻输入框 + 不需要公司信息

两条容易踩的规则：

  1. failed 不能说成"未查询到"。接口文档明确要求"空候选与查询失败需分别展示"、 "有此错误时，不把空候选说成查无公司"。失败时要给出原因（result.error 经 describeCompanyError 翻译），或至少说"公司查询服务暂时失败"。
  2. 不要用 input_help 的文案做判断。曾经用 /跳过|skip/ 正则去猜按钮文案， 后端改一个字就会失效 —— status 才是为这件事准备的字段。

实现见 src/components/api-chat-coordinator.ts 的 buildQuestionCardsContent。 status 缺失时退回"有没有候选"判断，以兼容旧版本。

legacy/API.md 是什么

它是交接时根据项目源码生成的快照，不是规格。

  • 来源：接手这个项目时，由当时的项目源码整理生成，涵盖那一刻前端调用的全部后端接口
  • 版本可追溯性：没有。接口和功能后续一直在改，这份文档不会跟着更新， 从那之后新增/修改的接口它一律不知道
  • 性质：它是"当时的代码长这样"的记录，不是"接口应该长这样"的约定

保留它的理由只有一条：需要翻"某个前端模块（上传、会话管理、反馈等）当初调了什么接口、 传了什么参数"时，它是个方便的索引。

⚠️ 两件事都不要做：

  1. 不要照着它实现新功能。 新增或修改接口调用一律以 api-chat.md 为准。
  2. 不要拿它当"原来行为是什么"的判据。 它是二手整理，可能遗漏或失真； 要精确判断原行为，直接 diff 备份目录里的源码（见下）。

相关位置

  • ../architecture.md —— 架构与关键约束
  • ../exec-plans/tech-debt-tracker.md —— 已知技术债（含接口相关的未决项）
  • ../../README.md —— harness/ 的结构导航
  • F:\yysk\AI_zhaoshang\备份\zhaoshang-llm —— 改动之前的原始代码备份（仓库外）。 判断"原来怎么写的/怎么做的"以源码为准，直接 diff 那里，不要凭记忆、也不要只信 legacy/API.md（它是生成物，会失真）。
  • F:\yysk\AI_zhaoshang\接口文档\ —— 上述文档在仓库外的原件，未随仓库维护。 注意其中 API.md 同样是交接时的快照，不是持续维护的规格。