---
title: 数据字典示例
description: 一份覆盖 10 张主要表的 host 数据字典 YAML 示例模板,供宿主方对照填写。
icon: FileSpreadsheet
---

下面是一份**示例 host 数据字典**,作为格式参考(不是要照搬)。它覆盖患者主档、预约、接诊、电子病历、影像、收费单、收款、充值、投诉、转介绍等 10 张主要表,每张表都给出字段类型、中文含义、枚举值映射、软删除标识和表关联。宿主方可按自己的实际表结构、字段命名、枚举值对照填写。中文 / Markdown / Excel 都接受,这份 YAML 只为示意。配套填写要点见 [数据请求清单](/docs/integration/data-request-checklist) §3。

```yaml
# Host 数据字典 — 详尽示例
#
# 用途:这是一份"格式参考",不是要照搬。按宿主方实际表结构、字段命名、枚举值填即可。
# pull 和 push 两条路都用这份字典,所以请尽量详尽。
#
# 格式说明:中文 / Markdown / Excel 都接受,本 yaml 只为示意。
# 关键:① 字段含义写清楚  ② 枚举值列全  ③ 表关联说清楚  ④ 软删除标识告知

# ─────────────────────────────────────────────
# 全局上下文(必填两项)
# ─────────────────────────────────────────────
contexts:
  amount_unit: yuan              # yuan(元小数) / fen(分整数),金额数值的单位
  timezone:    Asia/Shanghai     # IANA 时区,解释无时区的 datetime

# ─────────────────────────────────────────────
# 1. 患者主档
# ─────────────────────────────────────────────
tb_patient:
  含义: 患者主档(身份)
  字段:
    id              { type: bigint,        含义: 主键 }
    pat_no          { type: varchar(32),   含义: 患者档案号(诊所内可见编号) }
    brand           { type: varchar(32),   含义: 品牌 / 命名空间标识 —— 多品牌集团必给(PAC 据此派生 source_unit 给患者号在集团内消歧;同号不同品牌=不同人);单一品牌可省 }
    name            { type: varchar(64),   含义: 姓名 }
    gender          { type: char(1),       含义: 性别,
                      枚举: { M: 男, F: 女, U: 未知 } }
    birth_date      { type: date,          含义: 出生日期 }
    phone           { type: varchar(20),   含义: 手机号(主要联系电话) }
    vip_level       { type: tinyint,       含义: VIP 等级,
                      枚举: { 0: 普通, 1: 银卡, 2: 金卡, 3: 钻卡 } }
    tags            { type: varchar(255),  含义: 自定义标签(逗号分隔,如 "难沟通,周末忙") }
    remark          { type: text,          含义: 客户备注(自由文本) }
    contact_relation{ type: varchar(8),    含义: 主要联系人关系,
                      枚举: { SELF: 本人, SPOUSE: 配偶, PARENT: 父母, CHILD: 子女, OTHER: 其他 } }
    do_not_contact  { type: tinyint,       含义: 不打扰标记,
                      枚举: { 0: 可联系, 1: 不打扰(投诉/已转出/已故等) } }
    created_at      { type: datetime,      含义: 建档时间(无时区,按 timezone 解释) }
    updated_at      { type: datetime,      含义: 最后更新时间 }
    is_deleted      { type: tinyint,       含义: 软删除,
                      枚举: { 0: 有效, 1: 已删除(查询应自动过滤) } }
  关联:
    - 无外键,其他表通过 patient_id 关联

# ─────────────────────────────────────────────
# 2. 预约
# ─────────────────────────────────────────────
tb_appointment:
  含义: 预约记录 + 状态变更
  字段:
    id              { type: bigint,        含义: 主键 }
    apt_no          { type: varchar(32),   含义: 预约编号 }
    patient_id      { type: bigint,        含义: 关联 tb_patient.id }
    clinic_id       { type: bigint }
    doctor_id       { type: bigint }
    apt_start_time  { type: datetime,      含义: 预约开始时间(无时区) }
    apt_duration    { type: int,           含义: 预约时长(分钟) }
    apt_type        { type: varchar(8),    含义: 预约类型,
                      枚举: { FIRST: 首诊, REVISIT: 复诊, REVIEW: 复查, ORTHO: 正畸调矫, OTHER: 其他 } }
    apt_status      { type: varchar(8),    含义: 预约状态,
                      枚举: { NEW: 新建, CFRM: 已确认, CHKIN: 已到诊, FIN: 完成, CXL: 取消, NS: 爽约 } }
    cancel_reason   { type: varchar(64),   含义: 取消原因(apt_status=CXL 时填) }
    source          { type: varchar(16),   含义: 来源,
                      枚举: { ONLINE: 线上, PHONE: 电话, WALKIN: 到店, REFERRAL: 转介绍, RECALL: 回访邀约 } }
    created_at      { type: datetime }
    updated_at      { type: datetime }
    is_deleted      { type: tinyint }
  关联:
    - patient_id → tb_patient.id
    - doctor_id  → tb_doctor.id(若有医生表;否则字典里列 id↔name 映射)

# ─────────────────────────────────────────────
# 3. 接诊主表
# ─────────────────────────────────────────────
tb_encounter:
  含义: 医生接诊主表(一次看诊 = 一行)
  字段:
    id              { type: bigint,        含义: 主键 }
    enc_no          { type: varchar(32),   含义: 接诊编号 }
    patient_id      { type: bigint,        含义: 关联患者 }
    apt_id          { type: bigint,        含义: 关联预约(可空,walk-in 没预约) }
    clinic_id       { type: bigint }
    doctor_id       { type: bigint,        含义: 主治医生 }
    enc_start_time  { type: datetime,      含义: 接诊开始时间 }
    enc_end_time    { type: datetime,      含义: 接诊结束时间(可空,未结束时 NULL) }
    enc_status      { type: varchar(8),    含义: 接诊状态,
                      枚举: { OPEN: 进行中, CLOSED: 完成, VOID: 作废 } }
    chief_complaint { type: text,          含义: 主诉 }
    notes           { type: text,          含义: 接诊备注 }
    created_at      { type: datetime }
    updated_at      { type: datetime }
    is_deleted      { type: tinyint }
  关联:
    - patient_id → tb_patient.id
    - apt_id     → tb_appointment.id(一对一,可空)

# ─────────────────────────────────────────────
# 4. 电子病历(诊断/治疗内容主要载体)⭐
# ─────────────────────────────────────────────
tb_emr:
  含义: 电子病历(诊断 / 治疗计划 / 医嘱 主要载体)
  字段:
    id                { type: bigint,       含义: 主键 }
    encounter_id      { type: bigint,       含义: 关联接诊(一对一) }
    patient_id        { type: bigint,       含义: 关联患者(冗余,便于查询) }
    diagnosis_text    { type: text,         含义: 诊断描述(自由文本,医生写) }
    diagnosis_codes   { type: varchar(255), 含义: 诊断编码(ICD-10 或诊所自定义,逗号分隔,可空) }
    treatment_plan    { type: text,         含义: 治疗计划(自由文本 + 项目编号) }
    treatment_codes   { type: varchar(255), 含义: 治疗项目编码(逗号分隔,关联 tb_order_item.item_code) }
    doctor_advice     { type: text,         含义: 医嘱(自由文本,含 "3 个月后复查" 等下次安排) }
    next_review_at    { type: date,         含义: 建议下次复查日期(结构化字段,可空 — 有则优先于 doctor_advice 解析) }
    image_ids         { type: varchar(255), 含义: 关联影像 id(逗号分隔) }
    submitted_at      { type: datetime,     含义: 病历提交时间 }
    quality_status    { type: varchar(8),   含义: 质控状态,
                        枚举: { DRAFT: 草稿, SUBMITTED: 已提交, REJECTED: 打回, APPROVED: 通过 } }
    reject_reason     { type: varchar(255), 含义: 打回原因(quality_status=REJECTED 时填) }
    created_at        { type: datetime }
    updated_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - encounter_id → tb_encounter.id (一对一)
    - patient_id   → tb_patient.id

# ─────────────────────────────────────────────
# 5. 影像 metadata(不含文件本体)⭐
# ─────────────────────────────────────────────
tb_image:
  含义: 影像 metadata(PAC 不消费文件本体,只看 metadata + 医生所见)
  字段:
    id                { type: bigint,       含义: 主键 }
    patient_id        { type: bigint }
    encounter_id      { type: bigint,       含义: 关联接诊(可空,术前独立拍片可没绑接诊) }
    image_type        { type: varchar(16),  含义: 影像类型,
                        枚举: { PA: 根尖片, BW: 咬合翼, PANO: 全景片, CBCT: CBCT, SCAN: 口扫, PHOTO: 口内照, FACE: 面相 } }
    tooth_positions   { type: varchar(64),  含义: 涉及牙位(FDI 编号,逗号分隔,如 "16,17") }
    finding           { type: text,         含义: 影像所见(医生描述,自由文本) }
    captured_at       { type: datetime,     含义: 拍摄时间 }
    doctor_id         { type: bigint,       含义: 操作医生 }
    file_url          { type: varchar(512), 含义: 文件 URL(PAC 不取,记录用,可置空) }
    created_at        { type: datetime }
    updated_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - patient_id   → tb_patient.id
    - encounter_id → tb_encounter.id(可空)

# ─────────────────────────────────────────────
# 6. 收费单主表 + 明细
# ─────────────────────────────────────────────
tb_charge_order:
  含义: 收费单主表(医嘱/治疗/耗材/药品的开单)
  字段:
    id                { type: bigint,       含义: 主键 }
    order_no          { type: varchar(32),  含义: 收费单号 }
    patient_id        { type: bigint }
    encounter_id      { type: bigint,       含义: 关联接诊(可空) }
    clinic_id         { type: bigint }
    doctor_id         { type: bigint,       含义: 开单医生 }
    order_status      { type: varchar(8),   含义: 收费单状态,
                        枚举: { DRAFT: 草稿, SUBMITTED: 已提交待付, PARTIAL: 部分收款, PAID: 已付清, VOID: 作废, REFUND: 已退 } }
    total_amount      { type: decimal(10,2), 含义: 应收总额(单位见 amount_unit) }
    paid_amount       { type: decimal(10,2), 含义: 已收金额 }
    submitted_at      { type: datetime,     含义: 开单提交时间 }
    created_at        { type: datetime }
    updated_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - patient_id   → tb_patient.id
    - encounter_id → tb_encounter.id(可空)

tb_order_item:
  含义: 收费单明细(一个收费单 1:N 条明细;按类型区分治疗/耗材/药品)
  字段:
    id                  { type: bigint }
    order_id            { type: bigint,       含义: 关联 tb_charge_order.id }
    item_type           { type: varchar(8),   含义: 明细类型,
                          枚举: { TX: 治疗, MAT: 耗材, DRUG: 药品 } }
    item_code           { type: varchar(32),  含义: 项目编码(诊所内部) }
    item_name           { type: varchar(128), 含义: 项目名称(如 "33 号种植体") }
    treatment_category  { type: varchar(8),   含义: 治疗大类(item_type=TX 时填),
                          枚举: { ENDO: 根管, CROWN: 烤瓷冠, ORTHO: 正畸主治, IMP: 单颗种植, PERIO: 牙周, CLEAN: 洁牙, EXT: 拔牙, FILL: 补牙, OTHER: 其他 } }
    tooth_position      { type: varchar(16),  含义: 牙位(FDI,可空) }
    quantity            { type: int }
    unit_price          { type: decimal(10,2) }
    amount              { type: decimal(10,2), 含义: 小计 }
    created_at          { type: datetime }
  关联:
    - order_id → tb_charge_order.id(一对多)

# ─────────────────────────────────────────────
# 7. 收款流水
# ─────────────────────────────────────────────
tb_payment:
  含义: 收款流水
  字段:
    id                { type: bigint }
    pay_no            { type: varchar(32),   含义: 收款单号 }
    order_id          { type: bigint,        含义: 关联收费单(可空,杂收时可空) }
    patient_id        { type: bigint }
    clinic_id         { type: bigint }
    amount            { type: decimal(10,2), 含义: 实收金额(正数=收款 / 负数=退款) }
    pay_method        { type: varchar(16),   含义: 支付方式,
                        枚举: { CASH: 现金, WX: 微信, ALI: 支付宝, CARD: 银行卡, RECHARGE: 储值卡扣款, INSURE: 医保, OTHER: 其他 } }
    paid_at           { type: datetime,      含义: 实际支付时间 }
    operator_id       { type: bigint,        含义: 经办人 }
    created_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - order_id   → tb_charge_order.id(可空)
    - patient_id → tb_patient.id

# ─────────────────────────────────────────────
# 8. 充值 / 储值 / 福利卡(🟠 强烈推荐)
# ─────────────────────────────────────────────
tb_recharge:
  含义: 充值入账 / 储值卡 / 福利卡办理记录
  字段:
    id                { type: bigint }
    patient_id        { type: bigint }
    clinic_id         { type: bigint }
    recharge_type     { type: varchar(8),    含义: 类型,
                        枚举: { CASH: 现金充值, GIFT: 福利赠送, MEMBER: 会员卡, REFUND_BACK: 退款转存 } }
    amount            { type: decimal(10,2), 含义: 充值金额 }
    bonus_amount      { type: decimal(10,2), 含义: 赠送金额(充 1000 送 200 的 200) }
    balance_after     { type: decimal(10,2), 含义: 充值后余额 }
    recharged_at      { type: datetime }
    operator_id       { type: bigint }
    created_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - patient_id → tb_patient.id

# ─────────────────────────────────────────────
# 9. 投诉记录(🟠 强烈推荐 — 合规硬约束)
# ─────────────────────────────────────────────
tb_complaint:
  含义: 患者投诉
  字段:
    id                { type: bigint }
    patient_id        { type: bigint }
    related_enc_id    { type: bigint,        含义: 关联接诊(可空) }
    complaint_type    { type: varchar(16),   含义: 投诉类型,
                        枚举: { SERVICE: 服务态度, QUALITY: 治疗质量, PRICE: 价格争议, ENV: 环境, OTHER: 其他 } }
    content           { type: text,          含义: 投诉内容 }
    severity          { type: varchar(8),    含义: 严重程度,
                        枚举: { LOW: 一般, MED: 较重, HIGH: 严重(可能涉法律) } }
    status            { type: varchar(8),    含义: 处理状态,
                        枚举: { OPEN: 待处理, IN_PROGRESS: 处理中, CLOSED: 已结案 } }
    resolution        { type: text,          含义: 处理结果 }
    filed_at          { type: datetime,      含义: 投诉提交时间 }
    resolved_at       { type: datetime,      含义: 结案时间(可空) }
    created_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - patient_id     → tb_patient.id
    - related_enc_id → tb_encounter.id(可空)

# ─────────────────────────────────────────────
# 10. 转介绍记录(🟠 强烈推荐)
# ─────────────────────────────────────────────
tb_referral:
  含义: 老带新 / 转介绍归因
  字段:
    id                { type: bigint }
    referrer_id       { type: bigint,        含义: 介绍人 patient_id }
    referee_id        { type: bigint,        含义: 被介绍人 patient_id }
    referral_channel  { type: varchar(16),   含义: 介绍渠道,
                        枚举: { WORD: 口碑, WX: 微信分享, ACTIVITY: 活动邀约, STAFF: 内部员工, OTHER: 其他 } }
    reward_type       { type: varchar(8),    含义: 奖励类型,
                        枚举: { NONE: 无, CASH: 现金, COUPON: 优惠券, RECHARGE: 储值, SERVICE: 服务券 } }
    reward_amount     { type: decimal(10,2), 含义: 奖励金额 }
    referred_at       { type: datetime,      含义: 介绍发生时间 }
    converted_at      { type: datetime,      含义: 被介绍人转化(首诊)时间(可空) }
    created_at        { type: datetime }
    is_deleted        { type: tinyint }
  关联:
    - referrer_id → tb_patient.id
    - referee_id  → tb_patient.id

# ─────────────────────────────────────────────
# 11-14. 可选(有就给)— 退费 / 咨询 / 挂号 / 接待登记
# ─────────────────────────────────────────────
# 同上格式,按宿主方实际表结构填即可。
# tb_refund / tb_consultation / tb_visit_registration / tb_visit_reception
```
