---
title: 数据请求清单
description: 发给宿主开发的存量历史数据导出工作单,包含数据类别、上下文配置与数据字典要求。
icon: ListChecks
---

> 这份是宿主接入的**存量数据通道**。增量通道(Pull / Push)另见 [接入总览](/docs/integration/overview) §2。**存量 + 增量两者都做才算正式接入**。

> **一句话**:把下面几类业务数据按宿主方的表**原样 `SELECT *` 导出 CSV/JSON**,配一份数据字典(每个字段什么意思),不用 JOIN、不用改字段名、不用建 JSON,PAC 这边写代码做翻译聚合。

---

## 1. 需要的数据类别

> 一类可能对应宿主方多张表(主表 + 明细表),按宿主方实际结构原样导出。**诊断 / 治疗一般没有单独表,都在电子病历 / 影像里 — 这两个反而是重点。**

### 🔴 必填(召回算法核心)

| #   | 类别             | 业务含义                                      | 可能对应的表(供宿主方核对)                      |
| --- | -------------- | ----------------------------------------- | ----------------------------------- |
| 1   | **患者主档**       | 患者身份信息                                    | `tb_patient` / `tb_customer`        |
| 2   | **预约**         | 预约记录 + 状态变更                               | `tb_appointment` / `tb_booking`     |
| 3   | **接诊**         | 医生看诊主表                                    | `tb_encounter` / `tb_visit`         |
| 4   | **电子病历 EMR** ⭐ | 诊断 / 治疗内容主要载体(自由文本 / 结构化字段 都行)            | `tb_emr` / `tb_medical_record`      |
| 5   | **影像** ⭐       | X 光 / CBCT / 口扫 **metadata + 描述**(不要文件本体) | `tb_image` / `tb_xray`              |
| 6   | **收费单(医嘱)**    | 收费单 + 明细                                  | `tb_charge_order` + `tb_order_item` |
| 7   | **收款**         | 收款流水                                      | `tb_payment` / `tb_settle`          |

### 🟠 强烈推荐

| #   | 类别              | 缺则影响               |
| --- | --------------- | ------------------ |
| 8   | 充值 / 储值 / 福利卡   | LTV 严重失真,无法识别 VIP  |
| 9   | 投诉记录            | 合规硬约束 — 不能给投诉过的人推销 |
| 10  | 转介绍记录           | 渠道归因空白             |

### 🟡 可选(有就给)

退费 / 咨询 / 挂号 / 接待登记

### 每张表必带的列(所有 Pull 源通用)

不管走文件 / ClickHouse / REST,每张表 / 每行都要能给出这几列(**名字随你,字典里指明即可**):

| 列 | 作用 | 缺失后果 |
|---|---|---|
| 业务主键(如 `*_id`)| 幂等去重的锚 | 重复入库 |
| 患者外键(如 `patient_id`)| 挂到患者 | 召回挂不上人 |
| 诊所列(如 `clinic_id`)| 数据隔离 + 定位发生地 | 隔离失守 |
| 命名空间列(如 `brand`)| **多品牌集团必给** —— PAC 据此派生 `source_unit` 给患者号消歧(同号不同品牌 = 不同人);单一品牌可省 | 跨品牌撞号 |
| 更新时间列(如 `updated_at`)| 增量游标基准:首次全量、之后只取它变大的行 | 没有只能每次全量 |

---

## 2. 必答的两个上下文

```yaml
amount_unit:  <yuan / fen>       # 金额数值单位
timezone:     <Asia/Shanghai>    # IANA 时区,解释无时区的 datetime
```

---

## 3. 数据字典(请配一份)

每张表给一段说明,**中文 / Excel / Markdown 都行**,包含:

| 项 | 说明 |
|---|---|
| 表名 + 中文含义 | `tb_encounter` = 接诊主表 |
| 字段 + 类型 + 中文含义 | `enc_status varchar(2)`:接诊状态 |
| 表关联(FK / 业务约定)| `tb_emr.encounter_id → tb_encounter.id` |
| **枚举字段的可能值含义** ⚠️ | `enc_status:00=新建 / 01=进行中 / 02=完成 / 03=作废` |
| 软删除字段(如有)| `is_deleted=1 表示已删除` |

⚠️ **枚举值是关键** — 编码值(`01` / `02` / `A01` ...)必须列出含义,否则 PAC 只能猜。

📄 **详尽示例参考**:[数据字典示例](/docs/integration/data-dictionary) — 覆盖 10 张主要表的完整模板,可对照填。

> **pull / push 都吃这一份字典**:pull 路径下 PAC 按字典写 AssemblerEngine yaml 翻译字段;push 路径下 `rawPayload` 是宿主方原生形态,parser 仍需字典理解字段含义。**写一份,两路通用**。

---

## 4. 数据规模

**接入时约定的试点诊所全量数据**(通常 3-5 家;具体诊所清单对接时给)。

---

## 5. 脱敏

按宿主方合规要求处理(姓名 / 手机号 / 身份证等)。**业务字段(诊断 / 治疗 / 状态 / 金额 / 业务 id)请保留原值**,否则召回算法无法工作。

---

## 6. 常见疑问

| 问                             | 答                                                        |
| ----------------------------- | -------------------------------------------------------- |
| 字段命名不规范 / 字段名是中文              | 行,字典写清意思即可                                               |
| 一类数据分散在多张表(如患者主档 + 联系方式 + 标签) | **每张原样导**,字典写清 `patient_id` 等关联键 — PAC 合并,不要宿主方 JOIN      |
| 表之间没 FK,只有业务约定关联              | 字典里说"用 X 字段关联"即可                                         |
| 示例 yaml 里的字段宿主方没有 / 不一样       | 示例只是格式参考,**不是 PAC 定死字段** — 按宿主方实际表字段导出即可,字典写清意思就行        |
| 这次给一份就够,还是要持续更新               | **存量数据这次给一份全量**(过去 24-36 个月);后续**增量**走 Pull / Push API,届时再约 |
| 字典格式有要求吗                      | 无 — Markdown / Excel / YAML / 文档表格都行,讲清楚就好               |

---

## 7. 接入必问(避免返工)

> 这几条是历次接入踩出来的坑,**对接时先问清能省大量返工**。原则:宿主只「提供数据 + 解释含义 + 给更新时间列」,**不改 schema / 命名 / 码**。

| # | 必问 | 为什么 |
|---|---|---|
| 1 | **业务 ID 唯一边界**:`patient_id` 等在 host / brand / clinic 哪个粒度内唯一? | 跨某维度才唯一(如多品牌共用一套 id)→ 得靠那个维度区分,否则两个人会被当成同一个 |
| 2 | **每张表有「更新时间」列吗?** ETL 写入时刷新? | 增量同步靠它(游标);没有只能全量 |
| 3 | **view 还是物理实表?** ETL 频率(实时 / 小时 / T+1)? | 决定实时性 + 重摄策略 |
| 4 | **分类字段有稳定语义码吗?**(诊断 / 治疗 / 结算)还是只给中文 name? | 只给中文 name → 写法五花八门、识别准确率低、长尾要持续补;有稳定码(ICD / 项目字典)从源头解决 |
| 5 | **写入是 upsert 当前态,还是 append 事件流?** 状态变更留痕吗? | upsert 只剩终态(中间态丢失);行为分析 / 动作流需 append |
| 6 | **时间字段粒度**:日期与时分是否分列?「约定时刻」与「实际发生」分得清吗? | 只取日期会让同日多次操作「看着重复」 |
| 7 | **「已做治疗」的凭据**:哪张表算真做了(结算 / 收费)?带牙位吗? | 结算无牙位 → 召回排除只能患者级(粗化);推动补 `tooth_position` |
| 8 | **子表**:嵌套 Array 还是 JOIN 炸行? | 炸行 PAC 能兜底去重,但更希望 ETL 侧修(嵌套成数组 / 给明确主键)|
| 9 | **字段含义靠数据推,不靠命名**:字段名 / 注释常误导 | 举例:字面像「日期」的列可能是结算操作日(会延后),真正的接诊 / 治疗时间藏在另一列 —— 需按数据分布确认,不能照名字猜 |

---

## 8. 不在数据通道范围内的事(所有 Pull 源通用)

数据通道(文件 / ClickHouse / REST / Push)**只覆盖"把业务数据给 PAC"那一段**,下面三件是独立链路,跟选哪种通道无关:

| 项 | 渠道 |
|---|---|
| 鉴权换票(宿主 → PAC iframe 登录态)| [登录授权](/docs/integration/auth-login) |
| iframe 嵌入(客服界面) | [接入总览 §5](/docs/integration/overview) |
| actionUrls deep-link(跳回宿主 UI) | [接入总览 §4](/docs/integration/overview) |

---

**联系**:字段含义 / 数据完整性疑问,直接找 PAC 接入对接人。
