# 招商助手前端 API 接口文档

> ## ⚠️ 这是交接时的代码快照，不是接口规格
>
> - **来源**：接手项目时根据当时的源码整理生成
> - **没有版本可追溯性**：接口和功能后续一直在改，本文档不会跟着更新；
>   从生成那一刻之后新增或修改的接口，它一律不知道
> - **用途**：只能用来翻"某个前端模块**当初**调了什么接口、传了什么参数"
>
> **不要**照着它实现新功能（现行契约见 `../api-chat.md`）；
> **也不要**拿它当"原来行为是什么"的判据——它是二手整理，可能遗漏或失真，
> 精确判断请直接 diff 改动前的源码备份。

> 基于 `zhaoshang-llm` 项目源码整理，涵盖全部前端调用的后端接口。
>
> 环境变量说明:
> - `VITE_API` — 主业务 API 网关基础地址（如 `//qingpu-data-api.metamaker.cn`）
> - `VITE_MODEL_SERVER` — LLM 模型服务地址（如 `https://qingpu-data-api.metamaker.cn/llms/qingpu`）
> - `VITE_ASR` — 语音识别服务地址
> - `VITE_ASSISTANT_STATISTICS_BASE_URL` — 统计服务基础地址（回退到 `VITE_API`）
> - `VITE_STREAM_SERVER` — 流媒体/数字人视频流服务地址

---

## 目录

1. [对话服务](#1-对话服务)
   - 1.1 [AI 对话生成（SSE 流式）](#11-ai-对话生成sse-流式)
   - 1.2 [表单对话生成（SSE 流式）](#12-表单对话生成sse-流式)
   - 1.3 [表单提交对话（SSE 流式）](#13-表单提交对话sse-流式)
2. [企业认证服务](#2-企业认证服务)
   - 2.1 [企业登录](#21-企业登录)
   - 2.2 [获取企业信息](#22-获取企业信息)
3. [会话管理服务](#3-会话管理服务)
   - 3.1 [获取远程会话列表](#31-获取远程会话列表)
   - 3.2 [获取会话聊天记录](#32-获取会话聊天记录)
   - 3.3 [更新会话信息（重命名）](#33-更新会话信息重命名)
   - 3.4 [删除会话](#34-删除会话)
4. [反馈服务](#4-反馈服务)
   - 4.1 [对话反馈（点赞/点踩）](#41-对话反馈点赞点踩)
   - 4.2 [统计反馈上报](#42-统计反馈上报)
5. [统计服务](#5-统计服务)
   - 5.1 [页面访问统计](#51-页面访问统计)
6. [文件上传服务](#6-文件上传服务)
   - 6.1 [获取 OSS 上传签名凭证](#61-获取-oss-上传签名凭证)
   - 6.2 [上传文件到 OSS](#62-上传文件到-oss)
7. [媒体资源服务](#7-媒体资源服务)
   - 7.1 [获取媒体文件信息](#71-获取媒体文件信息)
8. [政策服务](#8-政策服务)
   - 8.1 [政策列表搜索](#81-政策列表搜索)
   - 8.2 [政策列表更新数据获取](#82-政策列表更新数据获取)
9. [历史记录服务（已停用）](#9-历史记录服务已停用)
   - 9.1 [追加历史记录](#91-追加历史记录)
10. [TTS 语音合成服务（已停用）](#10-tts-语音合成服务已停用)
    - 10.1 [文本转语音](#101-文本转语音)
11. [ASR 语音识别服务](#11-asr-语音识别服务)
    - 11.1 [ASR WebSocket 语音识别](#111-asr-websocket-语音识别)
12. [环境配置与代理映射](#12-环境配置与代理映射)
13. [后端服务架构总览](#13-后端服务架构总览)

---

## 1. 对话服务

### 1.1 AI 对话生成（SSE 流式）

**用户向 AI 发送问题，服务端以 Server-Sent Events 流式返回回答内容。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/knowledge/chat` 或 `{VITE_API}/dialog/chat` |
| **选择逻辑** | 由 `isKnowledgeApi()` 返回 `true` 时用 `/knowledge/chat`，否则用 `/dialog/chat` |
| **请求方法** | `POST` |
| **通讯协议** | SSE（Server-Sent Events），使用 `@microsoft/fetch-event-source` 库 |
| **源码位置** | `src/components/stream-message-coordinator.ts` L270-551 |
| **调用入口** | `useBusinessAssistantChat.ts` → `sendMessage()` → `smc.generateAnswer(text)` |

#### 请求 Headers

| Header | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Content-Type` | `string` | ✅ | 固定为 `application/json` |
| `Authorization` | `string` | ⚠️ 可选 | 用户认证 token（`globalThis.authToken` 或 `globalThis.token`） |
| `Uber-Trace-Id` | `string` | ⚠️ 可选 | 阿里云 ARMS 链路追踪 ID（当 `window.__bl` 存在时自动注入） |

#### 请求体 (JSON)

```json
{
  "card_id": 0,
  "department_id": "",
  "text": "用户输入的问题文本",
  "session_id": "uuid-session-id",
  "format": "object",
  "model": "当前 LLM 模型名（globalThis.llmModel）",
  "transmission": {
    "session_id": "uuid-session-id",
    "model": "当前 LLM 模型名",
    "credit_code": "企业统一社会信用代码",
    "files": ["https://oss-url/uploaded-file1.pdf"],
    "file_pos": [0],
    "enable_thinking": true
  },
  "source": "zhaoshang",
  "credit_code": "企业统一社会信用代码",
  "knowledge_ids": ["知识库 ID 列表"],
  "enable_history": true
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `card_id` | `number` | ✅ | 卡片 ID，固定传入 |
| `department_id` | `string` | ⚠️ | 部门 ID |
| `text` | `string` | ✅ | 用户问题文本 |
| `session_id` | `string` | ✅ | 当前会话 UUID |
| `format` | `string` | ✅ | 固定值 `"object"` |
| `model` | `string` | ✅ | LLM 模型标识，如 `"gpt-4"` |
| `transmission` | `object` | ✅ | 传输参数，包含会话、模型、企业、文件等上下文 |
| `transmission.credit_code` | `string` | ⚠️ | 企业信用代码（登录用户才有） |
| `transmission.files` | `string[]` | ⚠️ | 用户上传的文件 URL 列表 |
| `transmission.file_pos` | `number[]` | ⚠️ | 文件位置标记（与 files 长度一致） |
| `transmission.enable_thinking` | `boolean` | ⚠️ | 是否开启深度思考模式 |
| `source` | `string` | ⚠️ | 来源标识，如 `"zhaoshang"` |
| `credit_code` | `string` | ⚠️ | 企业信用代码 |
| `knowledge_ids` | `string[]` | ⚠️ | 知识库 ID 列表（从上一轮返回中获取） |
| `enable_history` | `boolean` | ✅ | 固定值 `true`，启用历史上下文 |
| `task_id` | `string` | ⚠️ | 仅在 `formChatting=true` 时传入 |

#### SSE 事件处理

**`onopen` 回调**：

连接建立后触发，可能返回服务端预处理信息（如限流提示），通过 `handleServerPreprocessInfo(response)` 解析。

**`onmessage` 回调**：

每条 SSE 消息的 `data` 为 JSON 字符串：

```json
{
  "message": "流式输出的文本片段",
  "record_id": "对话记录 ID（首条消息携带）",
  "status": "done | interrupt",
  "reasoning_content": "思考过程文本（深度思考模式）",
  "knowledge_ids": ["知识库 ID"],
  "disease_id": "诊断 ID（医疗场景）",
  "from": "风险等级标识"
}
```

| 事件/字段 | 说明 |
|---|---|
| `msg.event === "fail"` | 服务端返回失败，`data.message` 为错误信息 |
| `data.record_id` | 首次出现时，触发 `recordId` 事件供反馈使用 |
| `data.reasoning_content` | 深度思考内容，触发 `reasoning_content` 事件 |
| `data.message` 包含 `<think>` / `</think>` | 切换思考模式标志 |
| `data.message` 包含媒体资源 | 解析后触发 `relate` / `reference` 事件 |
| `data.message` 包含 `<!-- POLICY_TABLE` | 政策表格标记，整块 enqueue |
| `data.message` 包含 `<scope>` | 进入范围标签缓冲区 |
| `data.message` 包含 `<followup>` | 由 `StreamXMLFilter` 解析并触发 `followupSuggestions` 事件 |
| `data.message` 包含 `<policy-list-updated>` | 触发政策列表更新、刷新 `globalThis.policiesPublic` |
| `data.status === "done"` 或 `"interrupt"` | 对话结束或被中断 |

**`onerror` 回调**：触发 `error` 事件并自动 `stopGenerate()`。

**`onclose` 回调**：流式连接关闭，`generating = false`，触发 `close` 事件，存储完整回复。

---

### 1.2 表单对话生成（SSE 流式）

**与 1.1 相同连接，当 `formChatting = true` 时自动切换到表单对话 URL。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/knowledge/form_chat` |
| **请求方法** | `POST` |
| **通讯协议** | SSE |
| **源码位置** | `src/components/stream-message-coordinator.ts` L343 |
| **触发条件** | `smc.formChatting === true` 且调用 `generateAnswer()` |

请求参数与 1.1 一致，额外携带 `task_id` 字段。

---

### 1.3 表单提交对话（SSE 流式）

**独立的 LLM 模型服务接口，用于表单提交结果的对话生成。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_MODEL_SERVER}/v1/chat/completions` |
| **请求方法** | `POST` |
| **通讯协议** | SSE |
| **源码位置** | `src/components/stream-message-coordinator.ts` L553-770 |
| **调用入口** | `smc.generateFormSubmit(text)` |

#### 请求体 (JSON)

```json
{
  "card_id": 0,
  "department_id": "",
  "text": "用户输入",
  "session_id": "uuid-session-id",
  "format": "object",
  "model": "form_submit",
  "transmission": {
    "session_id": "uuid-session-id",
    "model": "form_submit"
  }
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `model` | `string` | 固定为 `"form_submit"` |

SSE 响应处理与 1.1 完全一致。

---

## 2. 企业认证服务

### 2.1 企业登录

**通过政务系统的 `access_token` 换取企业信用代码和内部认证 token。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/enterprise/login` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/enterprise.ts` L49-79 |
| **调用入口** | `useEnterpriseAuth.ts` → `initAuth()` → `fetchEnterpriseLogin(accessToken)` |
| **触发时机** | URL 中携带 `access_token` 参数时，应用初始化阶段自动调用 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |

#### 请求参数

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `access_token` | `string` | ✅ | 政务系统签发的访问令牌（URL 编码） |

**Request Body (JSON):**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### 响应

**成功 (200):**

```json
{
  "err_code": 0,
  "err_msg": "",
  "ret": {
    "credit_code": "91310118MA1JLRL16G",
    "access_token": "内部签发的 JWT token"
  }
}
```

**失败:**

```json
{
  "err_code": 1001,
  "err_msg": "token 无效或已过期"
}
```

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `err_code` | `number` | 0 = 成功，非 0 = 失败 |
| `err_msg` | `string` | 错误信息 |
| `ret.credit_code` | `string` | 企业统一社会信用代码 |
| `ret.access_token` | `string` | 后续请求使用的内部 auth token |

#### 前端处理

- 成功后将 `authToken` 存入 `globalThis.authToken`、`globalThis.token` 和 `localStorage(ba_auth_token)`。
- 随后自动调用 `fetchEnterpriseInfo` 获取企业详细信息。

---

### 2.2 获取企业信息

**根据企业信用代码查询企业详细注册信息。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/fta_ent_policy/enterprise_info` |
| **请求方法** | `GET` |
| **源码位置** | `src/network/api/enterprise.ts` L81-109 |
| **调用入口** | `useEnterpriseAuth.ts` → `initAuthWithCreditCode()` → `fetchEnterpriseInfo(creditCode)` |
| **触发时机** | 企业登录成功后 或 URL 直接携带 `credit_code` 参数时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{authToken}` |

#### 请求参数 (Query)

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `credit_code` | `string` | ✅ | 企业统一社会信用代码 |
| `source` | `string` | ⚠️ | 来源标识，如 `"zhaoshang"` |

#### 响应

**成功 (200):**

```json
{
  "err_code": 0,
  "err_msg": "",
  "ret": {
    "credit_code": "91310118MA1JLRL16G",
    "name": "上海某某科技有限公司",
    "regno": "310118003XXXXXX",
    "peid": "企业 PE ID",
    "op_from": "2015-01-01",
    "op_to": "2045-01-01",
    "es_date": "2015-01-01",
    "appr_date": "2015-01-01",
    "reg_cap": 1000000,
    "op_scope": "计算机软件开发、信息技术咨询...",
    "dom": "上海市青浦区XX路XX号",
    "ent_type_name": "有限责任公司",
    "industry_phy_name": "软件和信息技术服务业",
    "industry_co_name": "软件开发",
    "reg_org_name": "上海市青浦区市场监督管理局",
    "reg_org_province": "上海",
    "reg_org_city": "上海市",
    "reg_org_county": "青浦区",
    "reg_cap_cur_name": "人民币",
    "ent_status_name": "在营",
    "fr_name": "法人姓名"
  }
}
```

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `ret.credit_code` | `string` | 统一社会信用代码 |
| `ret.name` | `string` | 企业名称 |
| `ret.reg_cap` | `number` | 注册资本（单位：元） |
| `ret.op_scope` | `string` | 经营范围 |
| `ret.dom` | `string` | 注册地址 |
| `ret.ent_type_name` | `string` | 企业类型 |
| `ret.industry_phy_name` | `string` | 所属行业大类 |
| `ret.industry_co_name` | `string` | 所属行业小类 |
| `ret.reg_org_name` | `string` | 登记机关 |
| `ret.ent_status_name` | `string` | 企业状态 |
| `ret.fr_name` | `string` | 法定代表人 |
| `ret.op_from` / `ret.op_to` | `string` | 营业期限起止 |
| `ret.es_date` / `ret.appr_date` | `string` | 成立日期 / 核准日期 |

#### 前端处理

- 信息存入 `enterpriseInfo` 响应式变量和 `localStorage(ba_enterprise_info)`。
- `credit_code` 写入 `globalThis.credit_code` 和 `globalThis.transmission.credit_code` 供后续对话接口使用。

---

## 3. 会话管理服务

### 3.1 获取远程会话列表

**查询已登录用户的所有远程会话列表。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/chat/sessions` |
| **请求方法** | `GET` |
| **源码位置** | `src/network/api/chat-sessions.ts` L47-86 |
| **调用入口** | `BusinessAssistantPC.vue` / `BusinessAssistantMobile.vue` → `onMounted` → `fetchAndMergeRemoteSessions()` → `fetchRemoteSessions(creditCode)` |
| **触发时机** | 组件挂载且企业已登录时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{authToken}` |

#### 请求参数 (Query)

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `credit_code` | `string` | ✅ | — | 企业统一社会信用代码 |
| `page_index` | `number` | ✅ | `1` | 页码 |
| `page_size` | `number` | ✅ | `100` | 每页数量 |
| `source` | `string` | ⚠️ | `"zhaoshang"` | 来源标识 |

#### 响应

```json
{
  "err_code": 0,
  "err_msg": "",
  "ret": {
    "data": [
      {
        "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "关于高新技术企业优惠政策",
        "updated_at": 1700000000,
        "credit_code": "91310118MA1JLRL16G"
      }
    ],
    "total": 10,
    "page_index": 1,
    "page_size": 100
  }
}
```

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `ret.data` | `RemoteSession[]` | 会话数组 |
| `ret.data[].session_id` | `string` | 会话 UUID |
| `ret.data[].title` | `string` | 会话标题 |
| `ret.data[].updated_at` | `number` | 最后更新时间（Unix 时间戳，秒） |
| `ret.total` | `number` | 总会话数 |

---

### 3.2 获取会话聊天记录

**获取指定会话的完整消息历史。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/chat/session_record` |
| **请求方法** | `GET` |
| **源码位置** | `src/network/api/chat-sessions.ts` L88-117 |
| **调用入口** | `useBusinessAssistantChat.ts` → `loadRemoteSessionRecords(sessionId)` → `fetchRemoteSessionRecords(sessionId)` |
| **触发时机** | 切换到已有会话，且本地无缓存消息时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{authToken}` |

#### 请求参数 (Query)

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `session_id` | `string` | ✅ | 会话 UUID |
| `source` | `string` | ⚠️ | 来源标识 |

#### 响应

```json
{
  "err_code": 0,
  "ret": {
    "total": 5,
    "page_size": 100,
    "page_index": 1,
    "data": [
      {
        "session_id": "a1b2c3d4-...",
        "question": "高新技术企业有哪些优惠政策？",
        "answer": "根据青浦区政策...",
        "created_at": 1700000000
      }
    ]
  }
}
```

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `ret.data` | `RemoteSessionRecord[]` | 消息记录数组 |
| `ret.data[].question` | `string` | 用户提问内容 |
| `ret.data[].answer` | `string` | AI 回答内容（Markdown 格式） |
| `ret.data[].created_at` | `number` | 创建时间（Unix 时间戳） |

---

### 3.3 更新会话信息（重命名）

**更新会话标题。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/chat/session_info` |
| **请求方法** | `PUT` |
| **源码位置** | `src/network/api/chat-sessions.ts` L119-150 |
| **调用入口** | `useBusinessAssistantChat.ts` → `syncSessionTitleToServer(sessionId, title)` → `updateSessionInfo(sessionId, creditCode, title)` |
| **触发时机** | 1) 新会话首次发送消息后自动生成标题同步；2) 用户手动重命名会话 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{authToken}` |

#### 请求体 (JSON)

```json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "credit_code": "91310118MA1JLRL16G",
  "title": "新的会话标题",
  "source": "zhaoshang"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `session_id` | `string` | ✅ | 会话 UUID |
| `credit_code` | `string` | ✅ | 企业信用代码 |
| `title` | `string` | ✅ | 新标题文本 |
| `source` | `string` | ✅ | 来源标识 |

#### 响应

```json
{
  "err_code": 0,
  "err_msg": ""
}
```

| 字段 | 说明 |
|---|---|
| `err_code` | 0 = 成功 |

---

### 3.4 删除会话

**删除指定会话及其聊天记录。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/chat/del_session_info` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/chat-sessions.ts` L152-181 |
| **调用入口** | `useBusinessAssistantChat.ts` → `syncSessionDeleteToServer(sessionId)` → `deleteSessionInfo(sessionId, creditCode)` |
| **触发时机** | 用户在侧边栏删除会话时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{authToken}` |

#### 请求体 (JSON)

```json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "credit_code": "91310118MA1JLRL16G",
  "source": "zhaoshang"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `session_id` | `string` | ✅ | 会话 UUID |
| `credit_code` | `string` | ✅ | 企业信用代码 |
| `source` | `string` | ✅ | 来源标识 |

#### 响应

```json
{
  "err_code": 0,
  "err_msg": ""
}
```

---

## 4. 反馈服务

### 4.1 对话反馈（点赞/点踩）

**用户对 AI 回复进行满意度评价。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/chat/feedback` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/card/index.js` L22-43 |
| **调用入口** | `BusinessRecord.vue` → `FeedbackWidget.vue` / `DislikeDialog.vue` → `cardAPI.giveFeedback(payload)` |
| **触发时机** | 用户点击消息下方的 👍 / 👎 按钮 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{token}` |

#### 请求体 (JSON)

```json
{
  "id": "record_id_from_sse",
  "status": 1,
  "option": "回答不准确",
  "remark": "实际政策已经更新了"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `string` | ✅ | 对话记录 ID（从 SSE 流中的 `record_id` 获取） |
| `status` | `number` | ✅ | 反馈状态。`1` = 点赞，`2` = 点踩 |
| `option` | `string` | ⚠️ | 不满意的原因分类（点踩时可选） |
| `remark` | `string` | ⚠️ | 补充说明文本（点踩时可选） |

#### 响应

```json
{
  "err_code": 0,
  "err_msg": ""
}
```

---

### 4.2 统计反馈上报

**将用户反馈同步到独立的统计系统。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_ASSISTANT_STATISTICS_BASE_URL}/assistant_statistics/feedback` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/assistant-statistics.ts` L122-164 |
| **调用入口** | `reportAssistantFeedback(payload, options)` |
| **触发时机** | 与 4.1 同步触发 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{token}` |

#### 请求体 (JSON)

```json
{
  "record_id": "对话记录 ID",
  "status": 1,
  "visitor_id": "uuid-visitor-id",
  "business_code": "business_assistant",
  "env": "release"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `record_id` | `string` | ✅ | 对话记录 ID |
| `status` | `number` | ✅ | 反馈状态 |
| `visitor_id` | `string` | ✅ | 访客 UUID（`localStorage` 持久化，自动生成） |
| `business_code` | `string` | ✅ | 业务编码，固定 `"business_assistant"` |
| `env` | `string` | ✅ | 环境标识：`"release"` (qingpu) / `"test"` (production) |

#### 响应

HTTP 状态码 200 即为成功，无特定响应体结构要求。

---

## 5. 统计服务

### 5.1 页面访问统计

**记录用户访问招商助手页面的行为。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_ASSISTANT_STATISTICS_BASE_URL}/assistant_statistics/page_view` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/assistant-statistics.ts` L76-115 |
| **调用入口** | `BusinessAssistant.vue` → `onMounted` → `recordCurrentAssistantPageView({ apiBaseUrl })` |
| **触发时机** | 页面首次加载完成时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{token}` |

#### 请求体 (JSON)

```json
{
  "visitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "business_code": "business_assistant",
  "env": "release",
  "source": "zhaoshang"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `visitor_id` | `string` | ✅ | 访客 UUID，存储于 `localStorage(assistant_statistics_visitor_id)`，首次访问自动生成 |
| `business_code` | `string` | ✅ | 固定 `"business_assistant"`（由 `policyMode` → `resolveAssistantBusinessCode()` 映射） |
| `env` | `string` | ✅ | `"release"` (qingpu 部署) / `"test"` (production 部署) |
| `source` | `string` | ⚠️ | 来源标识 |

#### 响应

HTTP 状态码 200 即为成功。

---

## 6. 文件上传服务

### 6.1 获取 OSS 上传签名凭证

**在上传文件前，先获取阿里云 OSS 的临时签名凭证。**

| 属性 | 值 |
|---|---|
| **接口地址** | `//qingpu-data-api.metamaker.cn/common/qp_signed_url` |
| **请求方法** | `POST` |
| **源码位置** | `src/components/business-assistant/useBusinessAssistantUpload.ts` L115-141 |
| **调用入口** | `uploadFile()` → `requestOssSignature(extension, signal)` |
| **触发时机** | 用户选择图片/附件后自动触发 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |

#### 请求体 (JSON)

```json
{
  "ext": "png"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ext` | `string` | ✅ | 文件扩展名，如 `"png"`, `"pdf"`, `"docx"` |

#### 响应

```json
{
  "ret": {
    "file_url": "https://oss-bucket.oss-cn-shanghai.aliyuncs.com/path/to/file.png",
    "host": "https://oss-bucket.oss-cn-shanghai.aliyuncs.com",
    "key": "uploads/2024/01/01/uuid.png",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNC0...",
    "x-oss-signature": "签名字符串",
    "x-oss-signature-version": "OSS4-HMAC-SHA256",
    "x-oss-credential": "凭证字符串",
    "x-oss-date": "20240101T000000Z",
    "security_token": "STS临时安全令牌"
  }
}
```

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `ret.file_url` | `string` | ✅ 上传成功后的可访问 URL |
| `ret.host` | `string` | ✅ OSS 上传目标地址 |
| `ret.key` | `string` | ✅ 对象存储 key |
| `ret.policy` | `string` | ✅ OSS 签名策略 |
| `ret.x-oss-signature` | `string` | ✅ OSS 签名（也可能返回 `x_oss_signature` 格式） |
| `ret.x-oss-signature-version` | `string` | 签名版本 |
| `ret.x-oss-credential` | `string` | 凭证 |
| `ret.x-oss-date` | `string` | 签名日期 |
| `ret.security_token` | `string` | ⚠️ STS 临时令牌（使用临时凭证时） |

> ⚠️ 字段命名兼容两种格式：`x-oss-*`（kebab-case）和 `x_oss_*`（snake_case），前端通过 `getOssField()` 工具函数统一处理。

---

### 6.2 上传文件到 OSS

**将实际文件以 FormData 方式直接上传到阿里云 OSS。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{signature.host}`（动态，来自 6.1 响应的 `host` 字段） |
| **请求方法** | `POST` |
| **Content-Type** | `multipart/form-data`（浏览器自动设置） |
| **源码位置** | `src/components/business-assistant/useBusinessAssistantUpload.ts` L144-170 |
| **调用入口** | `uploadFile()` → `uploadToOss(file, signature, signal)` |

#### FormData 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `success_action_status` | `string` | ✅ | 固定值 `"200"` |
| `policy` | `string` | ✅ | 来自签名凭证 |
| `x-oss-signature` | `string` | ✅ | 来自签名凭证 |
| `x-oss-signature-version` | `string` | ✅ | 默认 `"OSS4-HMAC-SHA256"` |
| `x-oss-credential` | `string` | ✅ | 来自签名凭证 |
| `x-oss-date` | `string` | ✅ | 来自签名凭证 |
| `key` | `string` | ✅ | 来自签名凭证 |
| `x-oss-security-token` | `string` | ⚠️ | STS 临时令牌（存在时） |
| `file` | `File` | ✅ | 实际文件数据 |

#### 文件限制

| 限制项 | 图片 | 附件 |
|---|---|---|
| 最大大小 | 20MB (`MAX_IMAGE_SIZE`) | 50MB (`MAX_FILE_SIZE`) |
| 支持格式 | `SUPPORTED_IMAGE_EXTENSIONS` | `SUPPORTED_ATTACHMENT_EXTENSIONS` |

#### 响应

HTTP 200 表示上传成功，无需额外解析响应体。上传成功后使用签名凭证中的 `file_url` 作为文件的最终访问地址。

#### 上传状态流

```
选择文件 → 创建上传项(status='uploading')
         → 请求 OSS 签名(6.1)
         → 上传到 OSS(6.2)
         → 成功: status='success', fileUrl=signature.file_url
         → 失败: status='error', errorMsg=错误信息
         → 取消: AbortController.abort()
```

---

## 7. 媒体资源服务

### 7.1 获取媒体文件信息

**根据文件 ID 列表批量获取媒体文件的元信息（URL、尺寸等）。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/dialog/file_info` |
| **请求方法** | `GET` |
| **源码位置** | `src/network/api/card/index.js` L7-19 |
| **调用入口** | `cardAPI.getMediaList(ids)` |
| **触发时机** | AI 回复中包含媒体引用时 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/x-www-form-urlencoded` |
| `Authorization` | `{token}` |

#### 请求参数 (Query)

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | `string` | ✅ | 逗号分隔的文件 ID 列表，如 `"id1,id2,id3"` |

#### 响应

返回媒体文件的详细信息数组（包含 URL、类型、尺寸等）。

---

## 8. 政策服务

### 8.1 政策列表搜索

**在政策面板中按关键词、部门、分类搜索和分页浏览政策列表。**

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_MODEL_SERVER}/v1/policies` |
| **请求方法** | `GET` |
| **源码位置** | `src/components/Chat/PolicyMatch.vue` L791-840 + `src/components/Chat/policy-match-utils.ts` L24-62 |
| **调用入口** | `PolicyMatch.vue` → `fetchPolicyList()` |
| **触发时机** | 用户在政策面板中搜索、翻页、切换筛选条件时 |

#### 请求参数 (Query)

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | `number` | ✅ | 页码，从 1 开始 |
| `page_size` | `number` | ✅ | 每页数量 |
| `keyword` | `string` | ⚠️ | 搜索关键词（空则不传） |
| `department` | `string` | ⚠️ | 部门筛选（`"全部部门"` 时不传） |
| `auto_granted` | `string` | ⚠️ | 免申即享筛选：`"true"` / `"false"`（`"所有分类"` 时不传） |
| `session_id` | `string` | ⚠️ | 当前会话 ID |

#### 响应

```json
{
  "data": [
    {
      "title": "政策名称",
      "department": "发布部门",
      "desc": "政策描述",
      "declaration_item": "申报事项",
      "auto_granted": true
    }
  ],
  "total": 100
}
```

> 响应结构由 `extractPolicyListResponse()` 自适应解析，支持多种嵌套格式（`data.items`, `data.list`, `data.records`, `data.results` 等）。

---

### 8.2 政策列表更新数据获取

**当 AI 回复中包含 `<policy-list-updated>` 标签时，从指定 URL 拉取最新政策数据。**

| 属性 | 值 |
|---|---|
| **接口地址** | 动态 URL（由流式消息中 `<policy-list-updated>` 的 `link` 字段指定） |
| **请求方法** | `GET` |
| **源码位置** | `src/components/Chat/PolicyListUpdatedMatch.vue` L55-89 + `src/components/stream-message-coordinator.ts` L176-210 |
| **触发位置** | 1) `StreamMessageCoordinator` 的 `followupFilter` 处理器内（L176）；2) `PolicyListUpdatedMatch.vue` 组件内（L73） |
| **触发时机** | AI 在流式回复中返回政策更新标签 |

#### URL 构建

```
原始 link（从 JSON 中提取）+ payload 中的其他参数作为 query string
```

#### 响应

```json
{
  "data": [
    {
      "title": "政策名称",
      "department": "部门"
    }
  ]
}
```

#### 前端处理

- `data.data` 数组存入 `globalThis.policiesPublic`，供本地政策列表搜索和展示使用。

---

## 9. 历史记录服务（已停用）

### 9.1 追加历史记录

> ⛔ **状态：已停用**。代码保留但调用处已注释，改由后端通过 `enable_history=true` 自动管理。

| 属性 | 值 |
|---|---|
| **接口地址** | `{VITE_API}/knowledge/append_history` 或 `{VITE_API}/dialog/append_history` |
| **请求方法** | `POST` |
| **源码位置** | `src/network/api/card/index.js` L45-75 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/json` |
| `Authorization` | `{token}` |

#### 请求体 (JSON)

```json
{
  "card_id": 0,
  "id": "record_id"
}
```

---

## 10. TTS 语音合成服务（已停用）

### 10.1 文本转语音

> ⚠️ **状态：代码保留，调用链已注释**。`checkAvailableTexts()` 中的 TTS 调用被注释 (L1110)。

| 属性 | 值 |
|---|---|
| **接口地址** | `//llm-api.test.metamaker.cn/knowledge/tts`（默认值，可通过 `args.TTSURL` 覆盖） |
| **请求方法** | `POST` |
| **Content-Type** | `application/x-www-form-urlencoded` |
| **源码位置** | `src/components/stream-message-coordinator.ts` L990-1026 |

#### 请求 Headers

| Header | 值 |
|---|---|
| `Content-Type` | `application/x-www-form-urlencoded` |
| `Authorization` | `{token}` |
| `X-Heijing-Verf` | 签名值（`this.sign()` 存在时） |

#### 请求体 (x-www-form-urlencoded)

| 字段 | 类型 | 说明 |
|---|---|---|
| `text` | `string` | 待合成文本（已去除 Markdown 标签） |
| `tts_args` | `string` | JSON 序列化的 TTS 参数，含 `anim_agent`, `silence_type` 等 |
| `audio_type` | `string` | 固定 `"wav"` |
| `storage_type` | `string` | 固定 `"cloud"` |
| `card_id` | `number` | 卡片 ID |
| `is_strict` | `boolean` | 是否严格模式 |
| `disable_censor` | `boolean` | 是否禁用敏感词过滤 |

#### 响应

```json
{
  "err_code": 0,
  "ret": {
    "audio": "https://oss-url/audio.wav",
    "expression_anim": "https://oss-url/expression.json",
    "teeth_anim": "https://oss-url/teeth.json"
  }
}
```

---

## 11. ASR 语音识别服务

### 11.1 ASR WebSocket 语音识别

**实时语音识别，将麦克风输入转为文本。**

| 属性 | 值 |
|---|---|
| **接口地址** | `VITE_ASR` 配置值（如 `wss://qingpu-data-api.metamaker.cn`） |
| **通讯协议** | WebSocket |
| **源码位置** | `src/three-libs/asr/index.ts`（ASR SDK） |
| **调用入口** | PC: `BusinessAssistantPC.vue` → `toggleVoiceInput()`；Mobile: `BusinessAssistantMobile.vue` → `toggleVoiceInput()` |
| **触发时机** | 用户点击麦克风按钮 |

---

## 12. 环境配置与代理映射

### 环境变量总览

| 变量 | Development | Production | Qingpu | Test |
|---|---|---|---|---|
| `VITE_API` | `//qingpu-data-api.metamaker.cn` | `//qingpu-data-api.metamaker.cn` | `//qingpu-data-api.metamaker.cn` | `//human-card-mini.metamaker.cn` |
| `VITE_MODEL_SERVER` | `https://qingpu-data-api.metamaker.cn/llms/qingpu` | `https://qingpu-data-api.metamaker.cn/llms/qingpu` | `https://qingpu-data-api.metamaker.cn/llms/qingpu` | — |
| `VITE_ASR` | `https://qingpu-data-api.metamaker.cn` | `wss://qingpu-data-api.metamaker.cn` | `wss://qingpu-data-api.metamaker.cn` | `https://qingpu-data-api.metamaker.cn` |
| `VITE_STREAM_SERVER` | `//flv-enc.metamaker.cn` | `//flv-enc.metamaker.cn` | `/stream` | `//flv-enc.test.metamaker.cn` |
| `VITE_USE_KNOWLEDGE_API` | `true` | `true` | `true` | `false` |
| `VITE_ASSISTANT_STATISTICS_BASE_URL` | — | — | `https://qingpu-data-api.metamaker.cn/` | — |
| `VITE_DOWNLOAD_URL` | `https://qingpu-data-api.metamaker.cn/llm/download/` | `https://qingpu-data-api.metamaker.cn/llm/download/` | `/api/download/` | — |

### 开发环境代理

| 前端路径 | 目标服务 | 备注 |
|---|---|---|
| `/api/*` | `http://aixq.shqp.gov.cn` | 政务 API 网关 |
| `/asr/*` | `https://human-screen-v3.metamaker.cn` | ASR 语音识别（WebSocket） |
| `/stream/*` | `https://flv-enc.metamaker.cn` | 流媒体/数字人视频流（WebSocket） |

---

## 13. 后端服务架构总览

### 按物理服务地址分类

```
┌──────────────────────────────────────────────────────────┐
│                    前端应用 (Vue 3)                        │
└───────┬──────────┬──────────┬──────────┬────────┬────────┘
        │          │          │          │        │
        ▼          ▼          ▼          ▼        ▼
   ① 主网关      ② ASR      ③ 流媒体   ④ TTS    ⑤ OSS
   qingpu-data   qingpu-    flv-enc.   llm-api   阿里云
   -api.meta     data-api   metamaker  .test.    OSS
   maker.cn      (WSS)      .cn        meta      (动态)
                                       maker.cn
                                       (已停用)
```

### ① 主网关内部路由模块

| 路径前缀 | 逻辑模块 | 接口数量 |
|---|---|---|
| `/dialog/*` | 对话服务（旧版） | 2 |
| `/knowledge/*` | 知识库对话服务（新版） | 3 |
| `/chat/*` | 会话管理 + 反馈 | 5 |
| `/enterprise/*` | 企业认证 | 1 |
| `/fta_ent_policy/*` | 企业政策 | 1 |
| `/common/*` | 公共工具 | 1 |
| `/assistant_statistics/*` | 统计 | 2 |
| `/llms/qingpu/v1/*` | LLM 模型服务 | 2 |

### 认证机制

- **全局 Token**：`globalThis.authToken` / `globalThis.token`，通过 `Authorization` Header 传递。
- **401 拦截**：`useEnterpriseAuth.ts` 中通过 Fetch 拦截器监听，收到 401 时自动清除登录态。
- **来源标识**：`globalThis.source`（如 `"zhaoshang"`），跟随 `policyMode` 配置。

### 通用响应格式

```json
{
  "err_code": 0,
  "err_msg": "成功/错误描述",
  "ret": {}
}
```

- `err_code === 0` 表示成功
- `err_code !== 0` 表示业务错误
- HTTP 401 表示认证失效

### 接口总览表

| # | 接口路径 | 方法 | 文件 | 功能 | 状态 |
|---|---|---|---|---|---|
| 1 | `/dialog/chat` 或 `/knowledge/chat` | SSE POST | `stream-message-coordinator.ts` | AI 对话（主流程） | ✅ 在用 |
| 2 | `/knowledge/form_chat` | SSE POST | `stream-message-coordinator.ts` | 表单对话 | ✅ 在用 |
| 3 | `{MODEL_SERVER}/v1/chat/completions` | SSE POST | `stream-message-coordinator.ts` | 表单提交对话 | ✅ 在用 |
| 4 | `/enterprise/login` | POST | `enterprise.ts` | 企业登录 | ✅ 在用 |
| 5 | `/fta_ent_policy/enterprise_info` | GET | `enterprise.ts` | 企业信息查询 | ✅ 在用 |
| 6 | `/chat/sessions` | GET | `chat-sessions.ts` | 远程会话列表 | ✅ 在用 |
| 7 | `/chat/session_record` | GET | `chat-sessions.ts` | 会话消息记录 | ✅ 在用 |
| 8 | `/chat/session_info` | PUT | `chat-sessions.ts` | 会话重命名 | ✅ 在用 |
| 9 | `/chat/del_session_info` | POST | `chat-sessions.ts` | 删除会话 | ✅ 在用 |
| 10 | `/chat/feedback` | POST | `card/index.js` | 对话反馈 | ✅ 在用 |
| 11 | `/assistant_statistics/feedback` | POST | `assistant-statistics.ts` | 统计反馈 | ✅ 在用 |
| 12 | `/assistant_statistics/page_view` | POST | `assistant-statistics.ts` | 页面访问统计 | ✅ 在用 |
| 13 | `/common/qp_signed_url` | POST | `useBusinessAssistantUpload.ts` | OSS 签名获取 | ✅ 在用 |
| 14 | `{signature.host}` (OSS) | POST | `useBusinessAssistantUpload.ts` | 文件上传 | ✅ 在用 |
| 15 | `/dialog/append_history` 或 `/knowledge/append_history` | POST | `card/index.js` | 追加历史 | ⛔ 已禁用 |
| 16 | `/dialog/file_info` | GET | `card/index.js` | 媒体信息查询 | ✅ 在用 |
| 17 | `/knowledge/tts` | POST | `stream-message-coordinator.ts` | TTS 语音合成 | ⚠️ 代码保留，调用已注释 |
| 18 | `{MODEL_SERVER}/v1/policies` | GET | `PolicyMatch.vue` | 政策列表搜索 | ✅ 在用 |
| 19 | 动态 URL (policy-list-updated) | GET | `PolicyListUpdatedMatch.vue` | 政策数据更新 | ✅ 在用 |
| 20 | ASR WebSocket | WS | `three-libs/asr/` | 语音识别 | ✅ 在用 |