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

> **状态**：🔄 **部分已实现**（2026-09-17 更新）—— 见下方「落地进度」
> **日期**：2026-09-17
> **依据文档**：[`DMS_API.md`](../../reference/DMS_API.md)、[`DMS_COLUMNS.md`](../../reference/DMS_COLUMNS.md)、
> [`DMS_MAPPING.md`](../../reference/DMS_MAPPING.md)（三份都来自 `DMS_Data_Migration` 项目）
> **现状清单**：本文第四节逐条列出前端当前调用的全部接口
>
> ## 落地进度（2026-09-17）
>
> | 本文第一节列的项 | 状态 |
> |---|---|
> | 1.2 会话列表（1887） | ✅ 已切 —— [`../completed/dms-chat-storage.md`](../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` 里的条目逐项做 —— 现在只是方案，没有动代码。