---
title: 主体标准化字段
description: PAC 各业务主体(subjectType)的标准化 canonical 字段全量参考。
icon: Table2
---

> PAC 对每类业务主体定义一套**标准化字段**。用途:
> - **Push 形态 C**:事件 `payload` 按对应主体填这些字段。
> - **Push 形态 A / 文件 / 直连**:你给原生列 + 数据字典,PAC 映射到这些字段。
>
> 字段命名 = PAC canonical(camelCase)。**未列出的字段照样可透传**(留底,不报错),只是 PAC 算法不识别。`action` / `subjectType` 取值见 [事件枚举](/docs/event-enums)。
>
> 真理源 = 各主体 parser 实际读取的字段(`apps/pac-service/.../pipeline/parsers/*.parser.ts`);摄入校验 schema(`canonical.ts`)只强校验身份三件套 + 少数关键字段,其余字段透传,以 parser 为准。

---

## 公共字段(所有主体)

| 字段 | 必填 | 说明 |
|---|---|---|
| `externalId` | ✅ | 本记录在你系统的 id(= 事件里的 `subjectId`)|
| `patientExternalId` | ✅ | 所属患者 id（`patient` 主档自身可省）|
| `clinicId` | ✅ | 诊所 id（`referral` / `patient` 主档可空）|
| 〈发生时间〉 | ✅ | 每个主体一个主时间字段,名字见下表(如 `scheduledAt` / `startedAt` / `paidAt`)|

> 另需 §1 的组织 id（`tenantId` / `sourceUnit`)。金额字段按接入配置的 `amountUnit` 原样发,PAC 归一;时间本地值即可。

下面**只列各主体专有字段**(公共字段不再重复)。除身份/时间外几乎都可选 —— 映射不上的留空,PAC 自然 null。

---

## 患者主档域

### `patient` 患者主档

| 字段 | 说明 |
|---|---|
| `name` / `phone` / `gender` / `birthDate` | 姓名 / 电话 / 性别 / 生日(`YYYY-MM-DD`)|
| `medicalRecordNumber` | 病历号(客服沟通用)|
| `status` | `active` / `archived`(默认 active)|
| `doNotContact` / `doNotContactReason` / `deceased` | 免打扰 / 离世标记(合规)|
| `hostFollowUpActive` | 宿主侧正在跟进该患者(true → 召回排除闸)。宿主推自己的「跟进中」凭据,PAC 不猜 |
| `tags` / `notes` | 标签数组 / 备注 |
| `acquisitionChannel` / `acquisitionSub` | 获客渠道 / 二级渠道 |
| `referralCount` / `referralAmount` | 转介绍人数 / 带来金额 |
| 主时间 | `createdAt` / `updatedAt` |

### `patient_relation` 患者关系

| 字段 | 必填 | 说明 |
|---|---|---|
| `relatedExternalId` | ✅ | 关系人(也是一个患者)|
| `relationship` | ✅ | `mother`/`father`/`spouse`/`child`/`sibling`/`friend`/`other` 等 |

---

## 主流程

### `consultation` 咨询 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `intentRaw` | 意向原文 —— PAC 解析出潜在治疗意向 / 类别 |
| `firstVisit` | 是否初诊(`1`/`0` 或布尔)|
| `doctorId` | 接诊 / 咨询医生 |
| `appointmentExternalId` | 关联预约 |
| `taskDirector` | 任务负责人 |

### `appointment` 预约 — 主时间 `scheduledAt`

| 字段 | 说明 |
|---|---|
| `status` | `scheduled`/`rescheduled`/`cancelled`/`arrived`/`in_treatment`/`completed`/`no_show`/`walk_in` |
| `appointmentType` | 预约类型 |
| `doctorId` | 医生 |
| `arrivedAt` | 到诊时刻(实际到诊填)|
| `durationMinutes` | 时长 |
| `complaintCategory` / `complaintText` | 主诉类别 / 主诉原文 |
| `cancellationReason` | 取消原因 |
| `staffNotes` | 客服 / 前台备注 |

### `visit_registration` 挂号 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `appointmentExternalId` | 关联预约 |

### `visit_reception` 接待登记 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `receptionistId` | 接待人 |

### `encounter` 医生接诊 — 主时间 `startedAt`

| 字段 | 说明 |
|---|---|
| `doctorId` / `doctorName` | 医生 / 医生名 |
| `encounterType` | 接诊类型 |
| `chiefComplaint` | 主诉 |
| `notes` | 接诊备注 |

> 诊断 / 治疗建议**单独发** `diagnosis` / `treatment` / `recommendation` 主体(老格式可在 encounter 里嵌 `diagnoses[]` / `treatments[]`,兼容)。

---

## 临床

### `diagnosis` 诊断 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `code` / `name` | 诊断码 / 原始诊断名(PAC 映射标准码)|
| `stdCodeRaw` | 你已标准化的码(有则优先,免 PAC 猜)|
| `codeSource` | 码来源声明(如 `image_ai`)|
| `toothPosition` | 牙位(如 `17;37`)|
| `severity` / `onsetDate` | 程度 / 起病日期 |
| `doctorId` / `doctorName` | 医生 / 医生名 |
| `sourceEncounterExternalId` | 反查源接诊 |

### `treatment` 治疗 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `category` / `subtype` | 治疗大类(种植 / 正畸 / 牙周…)/ 子类 |
| `toothPosition` | 牙位 |
| `status` | 实际治疗状态 |
| `startedAt` / `completedAt` | 开始 / 完成 |
| `quantity` / `unitName` | 数量 / 单位名 |
| `treatStages` | 治疗阶段数组 |
| `reviewWindowDays` | 复查窗口天数 |
| `doctorId` / `doctorName` | 医生 / 医生名 |
| `relatedDiagnosisExternalId` / `sourceEncounterExternalId` | 关联诊断 / 源接诊 |

> 计划 vs 实际由 `action` 区分(`treatment_planned` / `treatment_started` / `treatment_completed`)。

### `recommendation` 医生建议 — 主时间 `occurredAt`

| 字段 | 说明 |
|---|---|
| `code` / `name` | 建议码(如 `IMPLANT_RECOMMENDED`)/ 名称 |
| `toothPosition` | 牙位 |
| `windowDays` | 建议窗口天数 |
| `extractedBy` / `confidence` | 抽取来源(`rule`/`llm`/`doctor_input`)/ 置信度 |
| `doctorId` / `doctorName` | 医生 / 医生名 |
| `sourceEncounterExternalId` / `sourceFactSubjectId` | 源接诊 / 源记录 |

---

## 病历 / 影像

### `emr` 病历文档 — 主时间 `submittedAt`

| 字段 | 说明 |
|---|---|
| `doctorId` / `doctorName` | 医生 / 医生名 |
| 病历自由文本段(映射不上的留空) | `illnessDesc`(主诉/现病史)· `examFindings`(检查所见)· `disposal`(处置)· `doctorAdvice`(医嘱)· `diagnosisText` · `treatmentPlan` · `generalCondition`(一般情况)· `pastHistory`(既往史)· `preIllness` |
| `encounterExternalId` | 关联接诊 |
| `qualityStatus` / `rejectReason` | 质检状态 / 打回原因 |

### `image` 影像 — 主时间 `uploadedAt`

| 字段 | 说明 |
|---|---|
| `modality` | 影像类型(CBCT / 全景 / 根尖片…)|
| `finding` | 医生影像所见 |
| `toothPositions` | 牙位 |
| `doctorId` / `doctorName` | 医生 / 医生名 |
| `encounterExternalId` | 关联接诊 |

---

## 单据

### `order` 医嘱 / 收费单 — 主时间 `createdAt`

| 字段 | 必填 | 说明 |
|---|---|---|
| `items[]` | ✅ | 至少 1 项;每项 `{ name(必), amount(必,金额), type, treatmentCategory, currency }`,`type` = `treatment`/`consumable`/`medication` |
| `totalAmount` | ✅ | 总金额 |
| `status` | ✅ | `submitted`/`paid`/`partial_paid`/`cancelled` |
| `currency` | ⭕ | 币种(默认 CNY)|

### `payment` 收款 — 主时间 `paidAt`

| 字段 | 说明 |
|---|---|
| `amount` | 金额(必)|
| `method` | 支付方式 |
| `orderExternalId` / `encounterExternalId` | 关联医嘱 / 接诊 |
| `doctorId` | 医生 |
| `cardName` / `cardTypeName` | 储值/福利卡名 / 卡类型 |
| `discountCard` / `discountCompany` / `discountDept` | 卡 / 公司 / 科室三类折扣额(PAC 合计)|
| `insuranceName` | 医保 / 保险名 |
| `settlementProject` | 结算项目 |
| `currency` | 币种 |

### `refund` 退费 — 主时间 `refundedAt`

| 字段 | 说明 |
|---|---|
| `amount` | 金额(必)|
| `paymentExternalId` | 关联收款 |
| `reason` | 退费原因 |

---

## 产品收集

### `recharge` 充值 / 储值 — 主时间 `rechargedAt`

| 字段 | 说明 |
|---|---|
| `amount` | 金额(必)|
| `rechargeType` | 福利卡 / 储值卡 / 项目预存 |
| `currency` | 币种 |
| `benefits` | 福利内容(JSON,如赠送项目 / 抵扣比例)|

### `complaint` 投诉 — 主时间 `filedAt`

| 字段 | 说明 |
|---|---|
| `content` | 投诉内容自由文本 |
| `category` | 类别(service / clinical / billing…)|
| `status` | `open` / `resolved` / `pending`(默认 open)|
| `resolvedAt` | 结案时间 |
| `relatedTreatmentSubjectId` | 关联治疗 |

### `referral` 转介绍 — 主时间 `recordedAt`

> fact 挂在**被推荐人**(`patientExternalId` = referee);推荐人信息进字段快照。

| 字段 | 说明 |
|---|---|
| `referrerExternalId` / `referrerName` / `referrerChartNumber` | 推荐人 id / 姓名 / 病历号 |
| `referrerType` | `patient`(老带新)/ `staff` / `partner` / `other` |
| `channel` | `wechat` / `face_to_face` / `event` …(自定义)|
