# Host 数据请求清单(发给宿主开发)？数仓、冷数据

> 给宿主开发的"一键导出"工作单。**不要求宿主理解 PAC 概念,不要求改字段名,不要求建 JSON**——直接 `SELECT * FROM 你们的表` 导出即可。PAC 这边写代码做所有翻译 / 聚合 / 枚举映射。

---

## 0. 一句话需求

```
请把下面 5 大类业务数据(各对应你们的若干张表)按表原样导出 CSV/JSON,
配一份数据字典(每个字段什么意思)给我们,我们这边写代码消化,
不需要你们重塑数据结构。
```

---

## 1. 需要的数据类别(必填 5 类 + 强烈推荐 3 类 + 可选 6 类)

> 一类可能对应你们多张表(主表 + 明细表),按你们实际的表结构原样导出即可,不用 JOIN 不用合并。

### 🔴 必填(召回算法核心 — 不给完全跑不通)

| #   | 类别       | 业务含义                       | 对应可能的表(供你们核对)                                                                   |
| --- | -------- | -------------------------- | ------------------------------------------------------------------------------- |
| 1   | **患者主档** | 患者身份信息                     | `tb_patient` / `tb_customer` 等                                                  |
| 2   | **预约**   | 预约记录 + 状态变更                | `tb_appointment` / `tb_booking` 等                                               |
| 3   | **接诊**   | 医生看诊过程 + 诊断 + 治疗，电子病历、影像？？ | `tb_encounter`(接诊主表)+ `tb_diagnosis`(诊断明细)+ `tb_treatment`(治疗明细),通常是 1:N 关系的多张表 |
| 4   | **收费单**  | 收费单 + 明细                   | `tb_charge_order`(主表)+ `tb_order_item`(明细)                                      |
| 5   | **收款**   | 收款流水                       | `tb_payment` / `tb_settle` 等                                                    |
|     |          |                            |                                                                                 |

### 🟠 强烈推荐(产品收集 — 业务方明确指出关键)

来源:回访中心信息字段.docx — 业务方亲口列的高价值字段。**不给的话 PAC 画像精度大幅下降 / 特定召回场景失效**。

| #   | 类别              | 业务含义                | 缺则影响                                    |
| --- | --------------- | ------------------- | --------------------------------------- |
| 6   | **充值/储值/福利卡** ⭐ | 充值入账 / 办储值卡 / 福利卡使用 | LTV 严重失真(中国民营牙科核心商业模式),无法识别 VIP / 高价值客户 |
| 7   | **投诉记录** ⭐      | 投诉内容 + 关联治疗(如有)     | **合规硬约束** — 不能给投诉过的人推销;PAC 不知道的话会踩雷     |
| 8   | **转介绍记录** ⭐     | 老带新 / 推荐人 / 渠道归因    | 转介绍激励逻辑失效,渠道分析空白                        |

### 🟡 可选(增强画像精度,有就给)

| #   | 类别   | 业务含义                                  |
| --- | ---- | ------------------------------------- |
| 9   | 退费   | 退款流水(配合 LTV 算净值)                      |
| 10  | 咨询   | 400 / 接待中心咨询记录(电话 / 在线)               |
| 11  | 到诊 | 患者到店挂号记录                              |
| 12  | 接待登记 | 前台接诊确认                                |
| 13  | 病历   | EMR 文档 / 提交记录                         |
| 14  | 影像   | X 光 / CBCT / 口扫的 metadata(**不要文件本体**) |

### 患者主档的额外字段(产品收集,非独立资源)

如果 `tb_patient` 里有以下字段,顺手一起导(不要为 PAC 新建字段):
- **多源标签 / 备注**(诊所对客户描述,如"VIP 卡客户" / "难沟通" / 备注信息)→ PAC 用作 Persona 输入
- **联系人关系**(主要联系人是患者本人 / 配偶 / 父母 / 子女)→ PAC 触达流程必备(儿童/老年患者打监护人不打本人)

---

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

每张表给一段说明就行,**中文 / Excel / Markdown 都接受**,格式无要求。包含:

| 项 | 说明 |
|---|---|
| 表名 + 中文含义 | `tb_encounter` = 接诊主表 |
| 每列字段名 + 类型 + 中文含义 | `enc_status varchar(2)`:接诊状态 |
| 表关联(FK)| `tb_diagnosis.encounter_id → tb_encounter.id` |
| 枚举字段的可能值含义 | `enc_status:00=新建 / 01=进行中 / 02=完成 / 03=作废` |
| 软删除字段(如有)| `is_deleted=1 表示已删除,我们这边查询应自动过滤` |

例子(凑合的格式都行):

```yaml
tb_encounter:
  含义: 接诊主表(医生看诊一次 = 一行)
  字段:
    id: 主键
    patient_id: 关联患者(→ tb_patient.id)
    clinic_id: 诊所
    doctor_id: 医生
    enc_start_time: 接诊开始时间(本地时间,无时区)
    enc_status: 状态 00=新建 / 01=进行中 / 02=完成 / 03=作废
    notes: 医生备注
  关联:
    tb_diagnosis.encounter_id → tb_encounter.id (一对多)
    tb_treatment.encounter_id → tb_encounter.id (一对多)

tb_treatment:
  含义: 治疗明细(一次接诊可多条治疗)
  字段:
    id: 主键
    encounter_id: 关联接诊
    tooth: 牙位
    category: 治疗大类 — 你们的内部枚举:
      A01 = 根管
      A02 = 烤瓷冠
      B01 = 正畸主治
      C01 = 单颗种植
      ... (列出实际值)
    status: 0=进行中 / 1=完成
    next_step: 医嘱下一步,自由文本(可空)
    next_step_days: 建议天数(可空)
```

⚠️ **枚举值是关键**——你们用 `01`/`02` / `A01` 等编码值的字段,**必须列出值的含义**,否则我们做映射时只能猜。

---

## 3. 必答的两个上下文(避免踩坑)

```yaml
amount_unit: <yuan / fen>          # 金额字段数值的单位
                                   # yuan(元小数,3200 = ¥3200)
                                   # fen(分整数,3200 = ¥32)

timezone:    <Asia/Shanghai>       # IANA 时区,用于解释无时区的 datetime 字符串
```

---

## 4. 数据规模 + 时间范围

| 项          | 建议                                      |
| ---------- | --------------------------------------- |
| 时间范围       | **过去 36 个月**(覆盖种植年度复查 540 天窗口 + buffer) |
| 患者规模(初装试装) | 5个试点诊所全量数据,或者 200-500 patient 抽样？？      |
| 患者规模(正式接入) | 试点诊所全量,后续逐步扩                            |

---

## 5. 脱敏要求(必须做的)？？

| 字段 | 处理 |
|---|---|
| `姓名` | 保留姓 + "先生/女士"(`张先生`)或用 hash 前 3 位 |
| `手机号` | `138****1234`(前 3 + 后 4,中间星号)|
| `身份证` / `居住地址` / `紧急联系人` | **完全去掉,不要导**(PAC 不需要这些)|
| `生日` | 保留 `YYYY-MM-01`(日改为 01)|
| `医生备注` | 删除可识别信息(同事姓名 / 全名 / 转介绍人姓名)|
| 其他业务 id(patient_id / encounter_id 等)| 保留原值(不算 PII)|
| 金额数值 | 保留真实(用于 LTV 验证)|
| 诊断 / 治疗类型 / 状态字段 | 保留真实(召回算法核心)|

---

## 6. 交付方式

| 方式               | 适用                  |
| ---------------- | ------------------- |
| 加密 zip 邮件        | < 100 MB            |
| 内网 sftp / S3 私有桶 | < 5 GB              |
| 1Password 共享(临时) | 凭证类(后续 appSecret 等) |

文件命名:`<host_slug>-<YYYYMMDD>.zip`(如 `friday-20260513.zip`)

---

## 7. 交付物清单(host 给我们的)

```
friday-20260513/
├── README.md                  ← 数据字典 + 上下文(amount_unit / timezone / 表关联)
│
├── tb_patient.csv             ← 必填 1 主档
├── tb_appointment.csv         ← 必填 2 预约
├── tb_encounter.csv           ← 必填 3 接诊主表
├── tb_diagnosis.csv           ← 必填 3 诊断明细(跟 encounter 1:N)
├── tb_treatment.csv           ← 必填 3 治疗明细(跟 encounter 1:N)
├── tb_charge_order.csv        ← 必填 4 收费单主表
├── tb_order_item.csv          ← 必填 4 收费明细(跟 order 1:N)
├── tb_payment.csv             ← 必填 5 收款
│
├── tb_recharge.csv            ← 🟠 强烈推荐(充值/储值)
├── tb_complaint.csv           ← 🟠 强烈推荐(投诉)
├── tb_referral.csv            ← 🟠 强烈推荐(转介绍)
├── tb_refund.csv              ← 可选
├── tb_consultation.csv        ← 可选
└── ... (其他可选类别)
```

**说明**:
- 表名跟你们实际的一致就行,不用改;数据字典里说清"这张文件对应你们 DB 哪张表"即可
- 文件格式 CSV 或 NDJSON 都行(每行一条记录)
- 不需要做 JSON 嵌套 / 不需要 JOIN / 不需要改字段名 — **原样 `SELECT *` 导出**

---

## 8. 我们这边收到后做什么

1. PAC 团队根据你们的数据字典写一个 **Assembler**(每个 host 一个,~200 行 TS)
2. Assembler 做的事:
   - 把多张表 JOIN / 聚合成 PAC 内部的资源结构
   - 把你们的枚举值翻译成 PAC 枚举(`A01` → `endodontic`,`02` → `submitted` 等)
   - 处理单位(yuan→cents)+ 时区
3. 跑 `pnpm cold-import`,数据落 PAC 三层模型
4. 跑 4 个高价值召回场景验证命中

**整个过程不需要你们再动手**。如有数据本身的问题(字段含义不明 / 枚举值缺失),我们会聚拢一次性反馈给你们澄清,**不会零零碎碎来回打扰**。

---

## 9. 常见疑问

| 问 | 答 |
|---|---|
| 我们字段命名不规范行不行 | 行,字典写清楚意思就够 |
| 几张表之间没 FK,只有业务约定关联 | 在字典里说"我们用 patient_phone 关联",PAC Assembler 适配即可 |
| 我们的字段是中文(如 `姓名`/`手机号`)| 行,字典里列出来 |
| 我们没有 `expectedNextStep` / 治疗链下一步 | 可以不给,PAC 用启发式兜底(精度略低)。若医生备注里有规律("建议 X 个月后复查"),也告诉我们我们 NLP 解析 |
| 病历可以不给吗 | 可以,病历是可选;但**接诊 + 治疗 + 收费**是必填 |
| 我们要导多少数据 | 试装:1 个诊所 36 个月 / 或抽样 200-500 patient |
| 接口对接什么时候启动 | 先冷启数据走通,稳定后再做实时 pull/push(W5+) |

---

**联系**:有任何字段含义 / 数据完整性 / 脱敏程度上的疑问,直接找 PAC 接入对接人。
