zhaoshang_client_ui/harness/docs/exec-plans/active/dms-api-replacement.md

用 DMS 接口替换前端接口 — 方案

状态：🔄 部分已实现（2026-09-17 更新）—— 见下方「落地进度」 日期：2026-09-17 依据文档：DMS_API.md、DMS_COLUMNS.md、 DMS_MAPPING.md（三份都来自 DMS_Data_Migration 项目） 现状清单：本文第四节逐条列出前端当前调用的全部接口

落地进度（2026-09-17）

本文第一节列的项	状态
1.2 会话列表（1887）	✅ 已切 —— ../completed/dms-chat-storage.md
1.3 会话历史/问答记录（1889）	✅ 已切 —— 同上
2.1 会话改名 / 2.2 删除 / 2.3 反馈（1889）	✅ 已切 —— 同上
1.1 企业信息（1888）	❌ 未做 —— 仍走 {VITE_API}/fta_ent_policy/enterprise_info

用户当时选择「先切换助手会话和助手问答记录」，故本轮只做了 1887/1889 相关。 企业信息那条要单独决定：它服务的是「企业登录后拉一次工商信息」， 与对话链路无关，且前端只用到 name / credit_code 两个字段（见本文 1.1）。

另：本文原先问的四个问题里，「前端直连还是后端转发」实际选了 vite 代理注入 token （浏览器不持有 DMS token），生产需 nginx 等价转发。

---

结论先说

DMS 是数据管理服务（建栏目、管模型、存内容），不是业务 API 网关。 能替换的是「按 credit_code / session_id 读业务数据」这一类，共 3 条只读 + 3 条写； 对话、政策、上传、语音、登录这些都换不了（各有原因，见第三节）。

而且现在一条都不能换：DMS 五个栏目目前全是空的 （selectContentList 一律返回 code=202 数据不存在）。数据迁移（F4-*）没做完之前切过去， 前端会从「有数据」直接变成「全空」。

---

一、能替换的：3 条只读

三条都是「精确查 + 分页」，语义与 DMS 的 selectContentList 天然吻合。

1.1 企业信息 ← 最干净的一条

前端现在调	GET {VITE_API}/fta_ent_policy/enterprise_info?credit_code=
位置	src/network/api/enterprise.ts
改走 DMS	栏目 1888 企业基础信息，search=[{"field":"c_credit_code","searchType":1,"content":{"value":"…"}}]
调用方	src/components/useEnterpriseAuth.ts（登录后拉一次）

✅ 前端其实只用两个字段：name、credit_code （useEnterpriseAuth.ts:58-59；其余 19 个字段在 src/ 里零引用）。 DMS 的 c_name / c_credit_code 正好覆盖 —— 所以这条不需要字段映射层。

1.2 会话列表

前端现在调	GET {VITE_API}/chat/sessions?credit_code=&page_index=&page_size=
位置	src/network/api/chat-sessions.ts
改走 DMS	栏目 1887 助手会话：c_credit_code 精确 + orderBy=[{"field":"c_updated_at","orderByType":2}] + 分页
调用方	BusinessAssistantPC.vue:1041、BusinessAssistantMobile.vue:937

字段对得上：session_id / title / updated_at / credit_code ← c_session_id / c_title / c_updated_at / c_credit_code。

⚠️ 时间字段格式不同：前端 RemoteSession.updated_at 是 epoch 毫秒（number）， DMS 里是 timestamp。取值后要换算，否则时间显示会错（这一条容易漏）。

1.3 会话历史（问答记录）

前端现在调	GET {VITE_API}/chat/session_record?session_id=
位置	src/network/api/chat-sessions.ts
改走 DMS	栏目 1889 助手问答记录：c_session_id 精确
调用方	useBusinessAssistantChat.ts:1513

字段对得上：question / answer / created_at ← c_question / c_answer / c_created_at。

⚠️ 返回是列表，前端现在依赖服务端给的顺序；换 DMS 必须显式 orderBy c_created_at， 否则顺序不保证 —— 会表现为「历史消息乱序」。

---

二、能替换但要小心：3 条写操作

#	前端现在调	改走 DMS	风险
2.1	PUT /chat/session_info（改标题/绑企业）	1887 updateContent	⚠️ 定位方式不同：前端用 session_id，DMS 的 content 里要的是记录 uuid → 得先查一次拿 uuid
2.2	POST /chat/del_session_info（删会话）	1887 delContentById	⚠️ 该端点参数未文档化（OpenAPI 里存在但没写参数，Apifox 也未收录）。必须先在测试栏目验证
2.3	POST /chat/feedback（赞/踩）	1889 的 c_feedback_status / c_feedback_option / c_feedback_remark / c_feedback_at	⚠️ 同样需要 uuid；且要确认状态码语义与前端 FeedbackType 的对应

写操作还有一个共同问题：DMS 的写入会改变「行数核对」的基准。 若迁移工具按 id 幂等键做增量同步，前端在 DMS 里新建/修改的记录会不会被下一次同步覆盖？ 这条要在动手前跟迁移那边对齐。

---

三、替换不了的，以及为什么

前端接口	为什么换不了
POST /api/chat（对话 SSE）	DMS 是数据管理服务，没有对话能力，无对应端点
{VITE_MODEL_SERVER}/v1/policies（政策列表查询）	DMS 没有政策栏目（五个栏目里没有政策）；且这条已有本地 json 兜底路径
POST /enterprise/login（企业登录换 token）	这是 OAuth 登录。DMS 反过来依赖它（AuthInterceptor 回调 OAuth 校验，serviceId=2）—— 被依赖方无法被依赖者替代
OSS 上传（/common/qp_signed_url + 直传）	用途不同：那是对话附件。DMS 的 /file/uploadFile 是给栏目内容挂附件的（columnId+contentId）
ASR（/api/human_asr/v2/asr/gen_auth + wss）	语音识别，与 DMS 无关
GET /dialog/file_info（卡片媒体信息）	DMS 无对应
POST /dialog/append_history、/knowledge/append_history	该调用已在前端禁用（useBusinessAssistantChat.ts:310 注释保留），无需处理
POST assistant_statistics/page_view（埋点写入）	栏目 1885 只覆盖它的 4 个字段，技术上能写；但不建议：埋点是高频写入，DMS 是管理服务，不是埋点接收端。除非明确要「数据统一收口到 DMS」
POST assistant_statistics/feedback（统计反馈）	五个栏目里没有对应的反馈栏目，无处可写

---

四、动手前必须解决的 5 件事

1. 数据迁移要先完成（当前 5 栏目全空，code=202）。这是硬前置。
2. 鉴权与暴露面 —— 最需要你拍板的一条。 DMS 要 header token: {access_token}，权限按栏目 tag（yszs_*）注册在 OAuth 上。 让浏览器直连 DMS，等于把「数据管理」的 token 发给每一个访客——它能读的就不止这五个栏目。 建议后端加一层转发（照 /chat-api 的做法），前端不直连 DMS。
3. HTTPS 混合内容：页面是 HTTPS，DMS 是 http://121.43.55.7:10081 → 浏览器会拦。 dev 用 vite 代理、生产用 nginx，与聊天接口同样的处理。 （若走后端转发，这条自动解决。）
4. states 与发布态：selectContentList 的 states 过滤会影响 count。 迁移写入的内容若是草稿态，前端按发布态（3）查会一条都查不到。 需要确认迁移后数据的发布状态。
5. 读接口全部标着 📄「未实测」：selectContentList / selectContentById 等 只在 SKILL.md / Apifox 里有，本项目没调用过。第一次用必须先在测试栏目验证 search / orderBy / states 的确切写法。

---

五、如果要做，建议的顺序

步	内容	验收
0	小样本验证：拿 1887 助手会话（7 字段，最少）跑通 selectContentList	鉴权、代理、search/orderBy/states 写法、时间格式全部确认
1	只读替换：企业信息（1888）→ 会话（1887）→ 问答记录（1889）	页面显示与现在逐字段一致；条数对得上
2	写操作：会话改名/删除、反馈	改动后 DMS 里确实变了；不被下次同步覆盖
3	埋点写入（建议不做）	—

每一步都加开关、可回退 —— 照 VITE_POLICY_LOCAL_FIRST 的先例（新老数据源可切， 验证通过再删旧的）。不要一次性全切。

---

六、需要你决定

1. DMS 是给前端「在线查询」用的，还是只做「数据底座」？ 若是底座（给后台/BI/迁移用），以上替换一条都不该做 —— 前端继续走业务 API， DMS 只服务管理与分析。这一条决定了整个方案做不做。
2. 若要做：前端直连 DMS，还是后端转发？（我建议后端转发，理由见第四节第 2 条）
3. 数据迁移（F4-*）什么时候完成？
4. 反馈与埋点要不要一起收口到 DMS？

你确认方向后，我再把它拆成 feature_list.json 里的条目逐项做 —— 现在只是方案，没有动代码。