# Host 数据请求清单 v2(发给宿主开发,存量历史数据导入)

> 这份是宿主接入的**存量数据通道**。增量通道(Pull / Push)另见 [`host-integration-v2.md`](host-integration-v2.md) §4-§5。**存量 + 增量两者都做才算正式接入**。

> **一句话**:把下面几类业务数据按宿主方的表**原样 `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  | 转介绍记录           | 渠道归因空白             |

### 🟡 可选(有就给)

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

---

## 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 只能猜。

📄 **详尽示例参考**:[`host-data-dictionary-example.yaml`](host-data-dictionary-example.yaml) — 覆盖 10 张主要表的完整模板,可对照填。

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

---

## 4. 数据规模

**5 个试点诊所全量数据**:

- 杭州大厦
- 杭州高德
- 无锡学前街
- 上海世纪公园
- 北京朝阳公园

---

## 5. 脱敏

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

---

## 6. 常见疑问

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

---

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