---
title: 接入总览
description: 从宿主开发视角概述 PAC 对接的整体清单、鉴权、数据通道与 iframe 嵌入方式。
icon: Plug
---

> **一句话**:PAC 接收宿主方的患者业务数据,产出召回任务,**客服界面由 PAC 以 iframe / 独立链接形式提供**,宿主方自由放进自己系统的合适位置。
> **宿主方工作**:① 把数据提供给 PAC(选一种 Pull 源,可选再加 Push) ② 嵌入 PAC iframe(由 PAC 提供链接)。
> **不需要**:写召回客服界面 / 调 PAC 业务 API / 学 PAC 内部概念 / 改字段命名 / 进 PAC 控制台。

---

## 1. 接入清单

| 项 | 必/选 | 时机 | 说明 |
|---|---|---|---|
| 数据通道:Pull(任一源)或 Push(§2,至少一种)| ✅ 必 | 对接期 | 给文件 / 开直连 / 实现 endpoint / 推事件 |
| 接入鉴权 — 换票(§3)| ✅ 必 | 对接期 | host backend 调 `/auth/token` 拿 JWT |
| 凭证管理 + 运维 | ✅ 必 | 持续 | apiKey / pushSecret 安全存储 + 轮换 |
| 存量历史导入(首次必做,§2)| ✅ 必 | 上线时 | 一次性历史数据 dump |
| 嵌入 PAC iframe(§5)| ✅ 必 | 上线时 | PAC 给链接,宿主方用 `iframe` 嵌入生产 UI |
| 提供 actionUrls 模板(§4)| ⚠️ 推荐 | 上线时 | 客服在 PAC iframe 内点"看患者档案"跳回宿主方 UI |

---

## 全局约定

### 响应信封与错误码

所有 API(PAC 出口 + 宿主 endpoint + push 入口)共用统一响应信封 —— **HTTP 恒 `200`**,业务结果看信封里的 `code`(非 0 = 错误)。信封结构、编码规则与全量码表见 [响应信封与错误码](/docs/error-codes)。

### 时间 / 金额归一化

宿主侧**接入时一次性提供两个配置**:

```yaml
timezone:    Asia/Shanghai     # IANA 时区,解释无时区的 datetime
amount_unit: yuan              # yuan(元小数) / fen(分整数)
```

**所有入站路径**的时间和金额字段都**按这套配置由 PAC 归一化**,宿主侧**永远不用关心格式化** — 怎么存的怎么给就行。

PAC 出站 API 统一 ISO 8601 带时区 + 整数分。

---

## 2. 数据接入

摄入只有 **两种传输方向** —— **Pull**(PAC 主动取)/ **Push**(宿主主动推),叠加正交的 **存量(首次全量)/ 增量(持续)**。宿主按自己的数据形态选一种 Pull 源,可选再加 Push;三种 Pull 源的**数据形态完全一致**,共用同一份数据字典,切换零返工。

### 2.1 Pull —— PAC 主动取(主通道,3 种数据源任选其一)

| 数据源 | 宿主提供 | 存量 | 增量 | 详见 |
|---|---|---|---|---|
| **文件(CSV / JSON)** | 导出裸表文件 + 数据字典 | ✅ | 重新导出 | [数据请求清单](/docs/integration/data-request-checklist) |
| **数据库直连(ClickHouse)** | 开只读权限,PAC 直接 SQL 读数仓 | ✅ | ✅ 游标 | [CH 视图](/docs/integration/channel-clickhouse) |
| **REST API** | 实现资源 endpoint(REST GET + 游标) | ✅ | ✅ 游标 | [REST API 通道](/docs/integration/channel-rest) |

存量(首次无游标的全量,即业内 cold-import)与增量(游标)走**同一条 pull 路径**,只是有无游标之别。

> 现状:文件 / 直连已就绪;REST API 适配器 PAC 侧开发中(契约见 [REST API 通道](/docs/integration/channel-rest))。

### 2.2 Push —— 宿主主动推(可选增强)

宿主把 transaction 事件主动推给 PAC(HMAC 验签),天然秒级增量。**有事件总线 + 想秒级再做**,否则 Pull 已够。完整契约(两种形态、HMAC 验签、幂等、补推)见 [Push 通道](/docs/integration/channel-push)。

> **存量首次必做**:无论哪种源,接入时先把历史背景一次性灌进 PAC —— 种植 / 正畸 / 牙周等长周期场景,没有 24-36 个月历史无法工作。数据字典参考 [数据字典示例](/docs/integration/data-dictionary)。

---

## 3. 鉴权

换票流程、请求 / 响应字段、`role` 与 `orgScope`(数据权限)填法见 [登录授权](/docs/integration/auth-login)。要点:host backend 调 `POST /pac/v1/auth/token`(`appId` + `appSecret` + `user`)拿一次性 `code` → 前端用 code 打开 iframe(`code` 60s 有效;不要把 accessToken 放进 URL)。

### 3.1 凭证

| 凭证 | 用途 | 安全要点 |
|---|---|---|
| `appId` + `appSecret` | host backend 换 JWT | plaintext 一次性发给宿主方,PAC 永不回读 |
| `pushSecret`(可选)| Push 路径 HMAC | 同上;支持多 key 平滑轮换 |
| `apiKey`(宿主方颁发给 PAC)| PAC 调宿主方资源 API | 宿主方颁发,推荐 Bearer 形式 |

### 3.2 错误码

鉴权错误码(`101xx`)及全量码表见 [响应信封与错误码](/docs/error-codes)。

---

## 4. actionUrls(可选,deep-link 模板)

提供一组跳转 URL 模板,PAC 前端在召回卡片点"看患者档案"等按钮时跳回宿主方的 UI。

```jsonc
{
  "VIEW_PATIENT":       "https://host.example.com/patient/{patientId}",
  "VIEW_EMR":           "https://host.example.com/emr?patientId={patientId}",
  "CREATE_APPOINTMENT": "https://host.example.com/appointment/new?patientId={patientId}",
  "VIEW_XRAY":          null,                  // null = 不支持,按钮不渲染
  "CALL_PATIENT":       null
}
```

**只提供宿主方能支持的**,不写或填 `null` 都行。占位符 `{patientId}` / `{appointmentId}` / `{emrId}` / `{clinicId}` / `{userId}` 按字面替换。

**打开方式**:PAC 前端 `window.open(url)`(新标签)或 `_top`(整页跳宿主页)。患者上下文经 URL 参数带过去,宿主页预填。

**动作没有独立页(是弹窗 / 组件)**:宿主给一个能触发弹窗的**深链参数**即可,仍是链接 —— 无需 postMessage:

```
https://host.example.com/console?action=new-appointment&patientId={patientId}
```

宿主页加载识别 `action` 就弹自己的组件。

**回跳召回**:动作页「返回召回」跳**宿主自己承载召回 iframe 的那个页**(或 `history.back()`);**PAC 不提供 returnUrl**,宿主链自己的页面即可。

**单向、无回调**:动作结果由数据摄入(如新预约 → 预约事实回流)+ 客服在 PAC 记 outcome 反映,**不做 UI 回调 / postMessage**。

**跨域登录态**:推荐宿主方用 cookie 跨域共享(跳过去自动登录),或在跳转 URL 加短时 token。

---

## 5. iframe 嵌入(客服界面接入方式)

**现阶段唯一接入方式**:PAC 提供客服工作台 URL,宿主方用 `iframe` 嵌入自己系统合适位置(如客服后台某个 tab / 主管 dashboard 一块区域)。
召回列表、患者画像、话术、摘要、执行回写表单等所有客服操作 UI **由 PAC 提供**,宿主方不写也不调 PAC 业务 API。

### 5.1 嵌入步骤

1. host backend 跑换票流程(§3.1),拿到 `code`(一次性,60s)
2. iframe 的 `src` = PAC 工作台**路由** + `?code=`:

   ```html
   <iframe
     src="https://pac.example.com/plans?code=XXX"
     sandbox="allow-scripts allow-same-origin allow-popups allow-top-navigation"
     style="width:100%; height:100%; border:0;">
   </iframe>
   ```

3. PAC 前端读 `?code=` 换 access token、存本地、并把 code 从 URL 抹掉,之后自启动。再次进入时本地 token 仍有效可不带 code。

### 5.2 PAC 工作台路由(嵌哪个页面 = 用哪条路径)

`?code=` 在任意工作台路由上都能换票自启动;**嵌哪个页面就用哪条路径**:

| 路径 | 用途 |
|---|---|
| `/plans` | 客服召回任务列表 + 详情(默认)|
| `/plans/{planId}` | 直接打开某个召回任务 |
| `/assistant` | PAC 助手(AI 对话查患者,需 `AGENT_INVOKE` 权限)|

### 5.3 嵌入约束

- 浏览器 CSP:宿主方配置 `frame-ancestors <宿主方 UI 域名>`(PAC 接入时约定)
- iframe `sandbox` 最小权限(上面示例已含):`allow-popups` 供动作新标签打开、`allow-top-navigation` 供动作 `_top` 跳转,按 §4 用到再加
- **不依赖 postMessage** 跟 PAC 通信 — 状态全走 PAC 后端,iframe 是纯渲染容器
- **嵌入态自动隐藏** PAC 品牌 / 用户信息 / 登出(宿主已提供),只留召回功能区
- 客服界面响应式适配,移动端 / 桌面端均可

**会话失效**:嵌入态 `code` / token 失效后,PAC 显示「登录已过期 + 重试」引导回宿主重新进入(§3.1 重新换票即恢复),**不弹内置登录**。

### 5.4 (可选)PAC 开放 REST API

完整 API 仅作 **未来扩展 / 运维 / 第三方对接** 预留,现阶段宿主方不需要调。各 endpoint 见侧栏 **API 参考**(OpenAPI 自动生成、按模块分组:auth / plan / push / sync …),或线上 Swagger 同源:`https://<pac-host>/api/docs`。

---

## 6. 接入流程 + Checklist

### 6.1 4 阶段

| Phase | 宿主方做 | 验证 |
|---|---|---|
| **1. 注册** | 提供联系人 / 试点 clinic 清单 / 接入模式选择 | PAC 团队跑 CLI 创 host,回发 appId + appSecret |
| **2. 联调** | 走 cold-import 先跑通 → 再开 pull / push | `failed=0, facts>0` |
| **3. 灰度** | 1 家试点 clinic 开放生产数据 + iframe 嵌入到客服界面 + 客服培训 | 24h 数据流入,前 100 召回业务方点评 |
| **4. 全量** | 其他试点 clinic 接入 + 凭证轮换演练 | 全量数据无严重异常 |

> PAC 团队侧的对应操作步骤见 [接入 Runbook](/docs/integration/runbook)。

### 6.2 验证 Checklist(交付前自查)

通道中立的上线前自查;各通道的具体验收项(必带列 / endpoint / 游标语义等)见对应通道文档。

#### 必填
- [ ] 鉴权:PAC 发的 `appId` + `appSecret` 已安全存储,换票跑通(§3)
- [ ] 数据通道任选其一并跑通存量 cold-import(`failed=0, facts>0`)
- [ ] 时区 + 金额单位配置已确认(§全局约定)
- [ ] 试点 clinic 字典 + 源组织命名空间(品牌)已提交
- [ ] iframe 已嵌入,`frame-ancestors` 配置生效(§5.3)
- [ ] 联系人 + oncall 渠道开通

#### 可选
- [ ] REST API 通道:增量游标自查见 [REST API 通道](/docs/integration/channel-rest)
- [ ] Push:HMAC 验签跑通(契约见 [Push 通道](/docs/integration/channel-push))
- [ ] actionUrls 模板提交(§4)
- [ ] 跨域单点登录方案确认

---

## 7. SLA + 运维

| 项 | 宿主方责任 | PAC 责任 |
|---|---|---|
| 凭证 | 安全存储 appSecret / pushSecret;按期轮换 | 提供轮换 CLI |
| 数据完整性 | 增量游标单调、关键资源逻辑删除(走直连 / REST 时)| 对账兜底 |
| API 可用性 | 资源 API ≥ 99.5% / month(如实现 REST 通道)| PAC 服务 ≥ 99.5% / month |
| 字段 / schema 变更 | **提前 2 周通知** PAC | 同步调整接入映射 |
| 故障 | 7×24 oncall 联系方式 | 同上 |

---

**联系**:对接细节 / 字段含义 / 故障排查,直接找 PAC 接入对接人。
