Skip to content

P
pac
Commit f3d7ae77 by luoqi
Options

merge: feat/friday-ingestion → main(FRIDAY 摄入契约收敛 + 推送自助反馈) 

- 摄入契约收敛为 9 张自洽表(宿主 inline 自己的引用,全路径一致)
- 结算 WHERE 迁移单一真理源 + 冷导入网页通道 + 数据对账
- push 预检(dryRun)+ 推送记录查询(HMAC 免登录)
- 修 traceRawSourceTable union 回溯(refund_full 在 push/reparse 静默跳过)

阶段性完成,业务确认可合。
parents a91f8a37 ec026cb2
Showing with 1962 additions and 258 deletions
apps/pac-docs/content/docs/data-reconciliation.mdx 0 → 100644
---
title: 数据对账(设计)
description: 独立核对 PAC 侧数据与各宿主源是否一致 —— 同闸口径、去重患者数、多宿主 provider、复用企微日报。
icon: Scale
---
<Callout type="warn">
**本文是设计文档,尚未实现**。记录对账机制的口径与方案,供评审 / 落地参照。
</Callout>
## 为什么要独立对账
现有的几层防线都是**单向补漏 / 水位监控**,抓不到"该有的数据到底在不在":
| 现有机制 | 作用 | 抓不到 |
|---|---|---|
| 48h 回看窗 | 容忍 DW 落库迟到 | 超 48h / 时间戳不跳的漏拉 |
| 主档反向强拉 | 补 cohort 的主档 | 非主档信号的积压 |
| ReconcileOrchestrator | 时间窗重拉补漏(手动) | 不告诉你"差了多少" |
| DwLagMonitor | cursor 距今 >24/48h 告警 | 只看水位新旧,不看行在不在 |
尤其前述三个已知漏点 —— [无 cursor 表积压](/docs/ingestion#21-增量-cohort-与无-cursor-表)、`updatedAt` 不跳漏拉、事务/fact 不一致 —— **都是补漏和水位监控抓不到的**。缺的是一个**双向数量核对**:定期比"源侧应有 vs PAC 实有",差超阈值告警。
## 三个难点与解法
对账看似简单(两边 count 一比),实则有三个坑,逐个解:
### 难点 1:多宿主 —— 源计数从哪来因宿主而异
PAC 是多宿主,不能绑死 DW —— 但对账**只覆盖 PAC 能直连源库的宿主**:
| 宿主类型 | 例 | 能直连源? | 对账 |
|---|---|---|---|
| **pull**(直连) | jvs-dw(ClickHouse) | ✅ | ✅ PAC 主动查源计数 |
| **push**(无直连) | friday(SaaS) | ❌ PAC 够不到其库 | **不对账** |
**push 宿主不对账**(定):PAC 够不到源库,唯一办法是宿主自报,但那要它维护一套"按 PAC 口径过滤后的计数",负担与可信度都不划算 —— 直接排除。push 宿主的数据质量靠既有的 push 路径告警(疑似改表 / 失败率超阈)兜。
抽象成:**PAC 只负责「拿到 `(scope, sourceCount)` → 对比 `pacCount` → 报 diff」;`sourceCount` 由每个可直连宿主的 provider 供给**(查询源库)。将来任何可直连的新宿主接入只需实现 provider,对账主逻辑不动。
### 难点 2:摄入是筛选子集 —— 不能数原表全量
PAC 摄入的**不是原表全量**,有大量故意筛选(结算 `status IN (1,3)`、瑞泰不摄、cohort 限有就诊、诊所范围…)。拿原表 count 比,diff 里全是"故意的差",没法用。
**解法:源计数复用摄入查询本身,只换投影。** manifest 的 `sql_source` 查询**就是"PAC 应该有什么"的定义**,把 `SELECT *` 换成 `count(distinct patient)`:
```sql
sourceCount = count(distinct patient) FROM ( «摄入用的那条 sql_source 查询,原样» )
```
两边都过了同一道筛选闸,diff 只剩**真漂移**。且筛选口径**零重复维护** —— 改了 `sql_source` 的 WHERE,对账自动跟着变(用的同一条查询),不会两份逻辑慢慢跑偏。
(push 宿主不对账,见难点 1,不涉及此。)
### 难点 3:fan-out 噪声 —— 不能比行数
一条源行可能拆成 N 条 fact(诊断+治疗+建议),加上版本流,行数根本不可比。
**解法:只比「去重患者数」,不比行数。** 干净、可比、且直接对应业务关切("多少患者的 X 信号 PAC 没跟上")。
## 对账口径:同闸 + 去重患者数 + 两层
只看总患者数**不够** —— 无 cursor 表积压时患者还在 PAC 里(只是他的回访/咨询行旧了),总量层 diff=0 会漏检。故分两层:
| 层 | sourceCount | pacCount | 抓什么 |
|---|---|---|---|
| **总量** | cohort 查询的 `count(distinct patient)` | PAC 该 host 的 `count(distinct patient)` | 整体漏人 |
| **信号** | 各资源 sql_source(含各自过滤)的 `count(distinct patient)` | PAC 里有对应 `fact_type` 的 `count(distinct patient)` | 某类信号积压(定位到无 cursor 表) |
**信号层示例**:`DW 有影像分析的患者 5.0 万 vs PAC 有 image_record 的患者 4.8 万,diff 2000` → 既可比又定位到"影像信号积压"。
**覆盖范围:全 fact 类型**(定)。不挑重点,每类都对(诊断 / 治疗 / 影像 / 回访 / 咨询 / 结算 / 转介…),一眼看全哪条信号在漂;性能由下节"每日一次 + 秒级 count"兜住,全覆盖不构成负担。
## 性能
对账要跑一堆 `count(distinct patient)`,得算清楚成本再上:
- **频率:每日一次**(不是每轮增量)。跟健康日报同一时刻(09:00 沪、DW 刷新后)跑一次即可 —— 漂移是慢变量,日粒度足够。
- **DW 侧**:每类信号一条 `count(distinct patient)`,全覆盖约 10 条。ClickHouse 的 `count(distinct)` 对 13M 行通常秒级;精度不敏感处可用 `uniq`(HyperLogLog,~0.5% 误差)换更低开销,要精确用 `uniqExact`。**上线前实测这 10 条的总耗时**,确认 < 分钟级。
- **PAC 侧**:`patient_facts` 按 `fact_type` 分组 `count(distinct patient_id)`,一条走索引的聚合查询,廉价。
- **不常驻**:对账是日报里的一个步骤,跑完即释放,无常驻连接 / 内存。
每日一次 + 秒级查询 → 全覆盖的性能开销可忽略,不影响在线摄入 / 重算。
## 基线:压掉"已知的正常差"
有些差**本来就该存在**,不压会天天误报 → 告警疲劳:
- 瑞泰品牌不摄(恒差)
- 无 cursor 表短期积压(会自愈)
- 源侧脏数据 / 时间窗边界
**基线放 manifest 配置**(每宿主声明"哪些 scope 差多少以内算正常"),只有**偏离基线**才告警,不是有差就报。
```yaml
# data/<host>/manifest.yaml(拟)
reconcile:
baseline:
total_patient: { tolerance_pct: 2 } # 总量差 2% 内正常
fact.image_record: { tolerance_pct: 5 } # 影像积压容忍高些
fact.payment_record: { tolerance_abs: 200 }
```
## 汇报:复用企微,折进每日健康日报
**不新起消息流** —— 复用 `AlertService`(企微群机器人),把「数据对账」折进已有的 [每日健康日报](/docs/monitoring)(每天 09:00 沪、DW 刷新后跑)。对账项超基线时,把日报整体级别顶成 🟡/🔴(现有逻辑:取最差项)。
```
每日 09:00 健康日报(已有)增加一段「数据对账」:
for each host:
for each scope in [总量患者, 各 fact 类型患者]:
sourceCount = provider(host, scope) # pull 查询 / push 自报
pacCount = PAC 同口径 count(distinct patient)
diff, diffPct
超 manifest.reconcile.baseline → 标 🟡/🔴
推企微(复用 AlertService,超基线才顶级别)
```
## 分期落地
**先只观察企微,不建表**(定)。
| 版本 | 做什么 | 不做 |
|---|---|---|
| **v1(先做)** | 同闸口径算 diff(全 fact 类型)+ 基线压噪 + 折进健康日报推企微 | **不建表**;趋势靠每日日报肉眼比 |
| v2(以后) | 若肉眼比不够,再建 `reconcile_checks` 表存快照 → 自动趋势 + 审计历史 | — |
先跑 v1 观察企微:口径准不准、会不会噪声、diff 稳不稳。够用就不上表。
## 已定 / 待决
**已定**:push 宿主(无直连)不对账 · 全 fact 类型覆盖 · 每日一次跑 · 先不建表只观察企微。
**待决**:基线初值怎么定 —— 建议**先不设容忍、原样把 diff 报进日报观察一两周**,摸清各 scope 的"正常差"后再回填 `manifest.reconcile.baseline`,避免拍脑袋定阈值。
apps/pac-docs/content/docs/ingestion.mdx
......@@ -93,6 +93,46 @@ pnpm sync -- --dir=./data/<host> --dry-run # 不写库,预览游标注入
pnpm sync -- --dir=./data/<host> --full # 忽略游标强制全量(灾后)
```
### 2.1 增量 cohort 与「无 cursor 表」
增量分两步,理解成本要分开看:
1. **选 cohort**:`manifest.incremental.per_query` 声明的表,各按自己 `cursor_column`
取 `WHERE cursor > 水位` 的患者,**并集**成本轮 cohort(UNION —— 任一表有变更就纳入,
避免"预约变了但人没来"被漏)。
2. **拉资源**:对 cohort 患者,**所有**源表按 `(patient_id, brand) IN (cohort)` 拉行。
没进 `per_query` 的表(无 cursor)也在此步被拉 —— **按患者收窄,不全表扫**。
**关键推论**:无 cursor 表**不能独立把患者拉进增量**。若某患者只有无 cursor 表变了
(且 cursor 表都没动)→ 不进 cohort → 该变更**积压到该患者下次因 cursor 表再进 cohort 才补上**。
所以无 cursor 表适合**弱信号 / 展示类**(容忍延迟),不适合驱动召回的核心信号。
以 **jvs-dw(瑞尔)** 为例(2026-07 DW 实测行数):
| 源表 | 行数 | cursor | CH 排序键 | 说明 |
|---|---:|---|---|---|
| fact_client_out | 5.7M | `last_visit_time` | patient_id | 患者主档 |
| fact_emr_treatment_out | 5.1M | `updated_date` | patient_id… | 治疗/病历(召回核心) |
| fact_appointment_out | 9.1M | `updated_date` | id | 预约 |
| fact_settlement_out | 9.1M | `updated_date` | id | 结算 |
| fact_settlement_mode_out | 4.4M | `updated_date` | — | 支付通道 |
| **fact_returnvisit_out** | **13.4M** | **无** | 无 | 回访任务(展示) |
| **fact_consult_out** | **10.8M** | **无** | org… | 咨询(意向,弱信号) |
| fact_emr_image_analysis_out | 553K | 无 | emr_id | 影像 AI |
| fact_customer_referee_out | 499K | 无 | 无 | 转介 |
<Callout type="info">
**提频(如 2h 一轮)的成本**——由**空轮短路**决定,不是 cohort 大小:
- **cohort 选择每轮都跑**(含空轮):cursor 列(`updated_date` 等)通常**不是 CH 排序键
→ 无索引 → 每轮全列扫**。但只扫单列,9M 行亚秒级,几张合计几秒/轮,绝对量可忽略。
- **资源拉取只在 cohort 非空时跑**:上游多为日更 → 日内多数轮 cohort 为空 →
在选 cohort 后即**短路**(跳过资源拉取 + persona/plan 重算),不触碰上面两张最大的无 cursor 表。
- 所以提频主要增加的是**廉价的空轮探查**,重活(资源全表扫 + 重算)仍是刷新后 1–2 轮,不被放大。
真要压这点空轮扫描,治本是给 cursor 表的 `updated_date` 加 CH 数据跳过索引;收益很小,通常不值当。
</Callout>
---
## 三、数据完整性
......@@ -102,7 +142,15 @@ pnpm sync -- --dir=./data/<host> --full # 忽略游标强制全量(灾
- `patient_transactions`:partial UNIQUE `(host_id, tenant_id, source_event_id) WHERE source_event_id NOT NULL`
- `patient_facts`:UNIQUE `(host_id, tenant_id, subject_id, version)` + active 行 partial UNIQUE
`source_event_id` 内含 `updatedAt`,因此源数据行级 in-place 更新会自然产生新 tx 与新 fact 版本(旧版 supersede);同行同 `updatedAt` 则幂等跳过。
`source_event_id` 内含 `updatedAt`(缺失时确定性回退 `createdAt`),因此源数据行级 in-place 更新会自然产生新 tx 与新 fact 版本(旧版 supersede);同行同 `updatedAt` 则幂等跳过。fact 层的变更判定是**内容驱动**的(比对 content hash + 状态 + 时间锚,不看 `updatedAt`),所以即使事务被幂等跳过,只要行被重新处理,内容真变了 fact 仍会升版本——变更不会因时间戳丢失而漏掉。
<Callout type="warn">
**`updatedAt` 维护缺失的两个后果**(如某些源表主档 `updated_gmt_at` 大量为 null)。当前设计有意保留 `updatedAt` 在幂等键中,**不改**;接入时按下面两点评估:
1. **pull/增量取数够不到**：增量按 `WHERE updated_date > cursor` 拉数,**内容变了但 `updatedAt` 没随之更新的行根本不会被选出来**——这道过滤在幂等之前,fact 层内容比对再准也无行可比。file 全量装载 / push(宿主自选推送)不受此限(不按 cursor 过滤)。治本靠源表维护 `updatedAt`;主档另有定期全量反拉兜底(见上「主档补全」)。
2. **事务与 fact 可能不一致 → reparse 会打回**:若内容变了但 `updatedAt` 没变,事务因 `source_event_id` 未变被幂等跳过(`rawPayload` 停在旧内容),但 fact 层仍按新内容升版本 —— 二者内容不再一致。此后 [reparse](#52-reparse--字典改了补存量无需全量重摄) 从 `transaction.rawPayload`(旧值)离线重放,会把 fact 打回旧内容。**规避**:对 `updatedAt` 不可靠的源表,不要依赖 reparse 修其存量,改走 DW 重摄 / 重推。
</Callout>
**主档补全(两条保障,确保 patient_id 不丢)**:
......@@ -148,6 +196,7 @@ pnpm sync -- --dir=./data/<host> --full # 忽略游标强制全量(灾
- **不连数据源**:rawPayload 在本地,比全量重摄快一个量级;
- **可圈定**:按 host / subject-type / 患者集 / dry-run / 是否重算;
- **覆盖范围**:field/enum/keyword_mapping、transforms 算子、parser 改动;**不覆盖**改了 `sql_source` 的 SELECT 本身(需从数据源多拉列/表,那才需真重摄)。非 transform 产出的资源(如 SQL 视图类)会自动跳过。
- **前提:rawPayload 是最新的**。reparse 只能和源行的最后一次落库一样新。若某源表 `updatedAt` 维护缺失,曾出现「内容变了但事务被幂等跳过」(见 §三 Callout),其 `rawPayload` 已滞后 —— 对这类表 reparse 会把 fact 打回旧内容,应改走重摄 / 重推而非 reparse。
```bash
# dry-run:报 scope(患者数 / txn 数),不写库
......
apps/pac-docs/content/docs/integration/friday-push-payload.mdx
---
title: FRIDAY 推送数据契约
description: FRIDAY SaaS 按形态 A 推送的 15 个 source 及字段定义;与已验证的存量导出形状一致,push 无缝衔接。
description: FRIDAY SaaS 按形态 A 推送的 9 个 source 及字段定义;宿主推自洽的业务表(自己的引用 inline 进相关行),PAC 做跨宿主临床归一。
icon: FileJson
---
> 本文是 [Push 通道](/docs/integration/channel-push)**形态 A** 在 FRIDAY SaaS 宿主的具体化:每个 `source` 的 JSON 字段清单。
> 字段形状与 PAC 已完成的存量摄入**完全一致**——宿主按此推送,与存量自动衔接:
> 同行同 `updated_gmt_at` 幂等去重,行更新(`updated_gmt_at` 变)自动版本演进。**重叠无害,宁多勿漏**。
> 同行按幂等键去重,行更新(`updated_gmt_at` 变)自动版本演进。**重叠无害,宁多勿漏**。
> 时间字段的可空语义与 `created_gmt_at` 兜底见 §1 通用约定。
---
......@@ -24,20 +25,33 @@ icon: FileJson
|---|---|
| **id 类字段一律字符串** | `patient_id` / `id` / `appointment_id` 等统一 String(数值型会被 PAC 校验拒收——存量摄入实测踩过的坑) |
| **时间格式** | 统一传 naive 北京墙钟 `"YYYY-MM-DD HH:mm:ss"`(PAC 按 `Asia/Shanghai` 解释)。实证(2026-07-20):MySQL `datetime` 存的就是北京墙钟(`_gmt_` 命名系惯例误导),直出即可;**Mongo `Date` 是北京墙钟伪装成 UTC 存储**(小时分布双证)——从 Mongo 读出后**须直读 UTC 字段还原墙钟**,切勿 `toISOString()` 带 `Z` 推送(会被按真 UTC 多加 8 小时) |
| **`updated_gmt_at` 必须随行更新 bump** | 它是幂等键的一半:不 bump,该行的更新会被永久去重丢弃 |
| **`updated_gmt_at`** | **可空,缺失不影响变更捕获**。PAC 的变更识别是**内容驱动**的:按 `(subjectId + 内容 hash + 状态 + 时间锚)` 判定,不看 `updated_gmt_at`——同一 `subjectId` 内容变了就升版本,没变就幂等去重。所以只要 `subjectId` 稳定、内容如实推,时间字段缺不缺都不丢更新。`updated_gmt_at` 仅用于**乱序防护**(补推的旧快照晚到时不覆盖新版本);为 null 时该保护退回"按到达顺序",对正常单向推送无影响。**无需宿主侧 COALESCE 兜底,重推安全。** |
| **空值** | 传 `null` 或省略字段;不要传 `"NULL"` 字符串 |
| **金额单位** | **元**(decimal 原值,实证:洁治单价均值 ¥310/已结算客单均值 ¥1,730);PAC 侧转分 |
| **投递语义** | at-least-once:未收到 2xx 确认就重推;重复由 PAC 幂等键吸收 |
> **职责边界(重要)**:宿主**在推送前解析好自己的引用**,把结果 inline 进相关业务行 ——
> ① 私有字典码(诊断 `linkCode→std_code`、影像 `class_code→类型名`)② 1:N 派生标量(默认联系号 + 归属)
> ③ 头-行属性(计划头的诊所/方案名下放到计划行)。这些**都是宿主自己的 within-host join**,数据在它手里、成本极低。
> PAC 只做**跨宿主的临床归一**(共享 K 码/modality/治疗类别字典、金额单位、时区、结算 status 切分、变更检测/版本)。
> 好处:每张 source 自洽,增量推变更行天然成立,无跨表依赖。
>
> **两条配套纪律**:① **整表照推,宿主不做任何行过滤**——status/金额范围等切分全部由 PAC 完成
> (单一真理源,与 file / cold-import 同口径),故本文各表**不再规定「推送范围」**;
> ② **列名一律沿用宿主原表列名**——包括 inline 进来的列(`contacts_tel`/`relationship`/`std_code`/
> `class_name`/`organization_id`/`plan_name`),PAC 不发明新名,宿主无需为 PAC 做字段改名。
---
## 2. 患者与关系(3 个 source)
## 2. 患者(2 个 source)
### `customer_basic_info` — 患者主档
> ✅ 患者主档已支持 push(2026-07-20):**部分更新语义** —— 只更新本次提供的字段,
> 未提供的字段不覆盖存量(如只推 `customer_basic_info` 时 phone 不在场 → 保留库内号码);
> push 无"清空字段"语义,需要清空走全量通道。`customer_referee_circle`(关系边)同样可 push。
> **部分更新语义**:只更新本次提供的字段,未提供的不覆盖存量;push 无"清空字段"语义,需清空走全量通道。
>
> **联系电话已 inline(不再单独推 customer_contacts)**:宿主按 `is_default↓ → contacts_type↑(1=本人优先) → id↑`
> **挑出默认号**,把号码与归属 inline 进本表的 `contacts_tel` / `relationship` 两列(沿用 customer_contacts 原列名)。PAC 现只消费这一个有效号 + 归属
> (存 `patient.phone` 与 `contactPhone.isSelf`),不需要完整通讯录 → 联系方式 1:N 表无需摄入。改号 = 重推本表。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
......@@ -48,20 +62,10 @@ icon: FileJson
| `file_number` | string | | 病历号/档案号(客服沟通用) |
| `tenant_id` | string | ✅ | 品牌 GUID(宿主原生列) |
| `organization_id` | string | | 建档诊所 |
| `contacts_tel` | string | | **默认联系号(宿主 inline)**——按上述规则挑出的有效号码(= customer_contacts 原列名) |
| `relationship` | string/number | | **该号归属(宿主 inline,= customer_contacts 原列名)**——`PhoneRelationshipEnum`:`1`本人 `2`爸爸 `3`妈妈 `4`爷爷 `5`奶奶 `6`朋友 `7`配偶 `8`子女 `9`其他(PAC 存 `isSelf`=码=='1') |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | ✅ | 建档/更新时间 |
### `customer_contacts` — 联系方式(1:N)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | ✅ | 行主键 |
| `customer_id` | string | ✅ | → 患者 id |
| `contacts_tel` | string | ✅ | 电话号码 |
| `is_default` | string/number | | 默认号标记(PAC 挑默认号:is_default↓ → contacts_type↑ → id↑) |
| `contacts_type` | string/number | | 联系类型(`1` 本人号候选优先) |
| `tel_type` | string/number | | 号码类型 |
| `relationship` | string/number | | 持号人与患者的关系(官方枚举 `PhoneRelationshipEnum`:`1`本人 `2`爸爸 `3`妈妈 `4`爷爷 `5`奶奶 `6`朋友 `7`配偶 `8`子女 `9`其他) |
### `customer_referee_circle` — 转介绍圈(患者-患者关系)
| 字段 | 类型 | 必填 | 说明 |
......@@ -97,12 +101,10 @@ icon: FileJson
---
## 4. 病历链(3 个 source)
## 4. 病历链(2 个 source)
### `med_emr_info` — 病历正文(Mongo 平铺;一张表喂诊断/治疗/建议/复查/病历全链)
**推送范围:`status ∈ {3, 4}`(已完成/归档);`status=2` 未完成草稿不推。**
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `emr_sub_id` | string | ✅ | 小病历号 uuid(病历主键;临床事实同诊聚合锚) |
......@@ -115,8 +117,8 @@ icon: FileJson
| `user_id` / `user_name` | string | | 接诊医生 id / 姓名 |
| `clinic_time` | string(datetime) | ✅ | 就诊时刻 |
| `visit_indicator` | number | | `1`初诊 `2`复诊 |
| `status` | number | ✅ | `3`已完成 `4`归档(推送范围) |
| `diag` | array | | 诊断数组,元素 `{ "toothPosition": "41;42", "value": "慢性牙髓炎", "linkCode": "<std_diag.diag_code 或空>" }` |
| `status` | number | ✅ | `3`已完成 `4`归档 `2`未完成草稿(整表照推,PAC 侧只取 3/4) |
| `diag` | array | | 诊断数组,元素 `{ "toothPosition": "41;42", "value": "慢性牙髓炎", "std_code": "<宿主已解析的标准码或空>" }`。**`std_code` 由宿主 inline**——原 `linkCode` 经自家 `std_diag` 解析所得,沿用 std_diag 原列名;K 开头 PAC 截 K 大类,非 K/空按自由文本 |
| `treat` | array | | 本次治疗数组,元素同上结构(`value`=治疗名) |
| `dispose` | array | | 处置叙述数组,元素 `{ "toothPosition", "value" }` |
| `examine` | array | | 检查所见数组,元素同上 |
......@@ -129,13 +131,8 @@ icon: FileJson
> 牙位格式:FDI 牙位号,多牙分号分隔,可带牙面字母(`"42 L;43 D"` / `"11;12;13"`)。
### `std_diag` — 诊断字典(低频;变更时全量重推)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `diag_code` | string | ✅ | 字典主键(= `diag[].linkCode` 指向) |
| `diag_name` | string | ✅ | 诊断名 |
| `std_code` | string | | 标准码(`K02.901` 等;K 开头 PAC 截 K 大类,非 K 按自由文本处理) |
> **`std_diag` 不再单独推**——它是纯翻译字典(`linkCode→std_code`),离开诊断行无独立意义。
> 宿主在导出/推 `med_emr_info` 时,把 `diag[].linkCode` 用自家 `std_diag` 解析成 `std_code` **inline 进 diag 元素**即可。
### `med_check` — 影像档案(metadata,不含文件本体)
......@@ -147,28 +144,33 @@ icon: FileJson
| `organization_name` | string | | 诊所名称(同上,诊所名字典来源之一) |
| `patient_id` | string | ✅ | → 患者 id |
| `emr_id` | string | | → 病历号(`med_emr_info.emr_id`) |
| `class_code` | string | | 影像类型 → `std_check_class` |
| `class_name` | string | | **影像类型名(宿主 inline)**——原 `class_code` 经自家 `std_check_class` 解析成类型名(口内像照片/小牙片/全景片/CT影像截图/口腔扫描…);PAC 再映射成 modality |
| `file_name` / `file_type` | string | | 文件名 / 类型 |
| `file_url` | string | | OSS 相对路径 |
| `files_size` | number | | 字节数 |
| `shooting_time` | string(datetime) | ✅ | 拍摄时间 |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | ✅ | |
配套字典 **`std_check_class`**(低频):`class_code`(主键) / `class_name`(口内像照片、小牙片、全景片…) / `tenant_id`。
> **`std_check_class` 不再单独推**——同 `std_diag`,纯翻译字典。宿主把 `med_check.class_code`
> 用自家字典解析成 `class_name` **inline 进 med_check 行**即可。
---
## 5. 结算链(4 个 source)
## 5. 结算链(2 个 source)
> **拆分规则(宿主侧按 status/金额分流成两个 source 推)**。`status` 官方语义
> (`PatientSettlementEntity` 实体注释,比枚举类更全):`0`未结算 `1`已结算 `2`只生成uuid
> `3`退款 `4`插入的退款数据 `5`重新结算数据(废弃历史行) `6`医生未提交 `7`流程结束
> `8`欠款补缴插入数据。**0/2/5/6/7/8 均不推**——其中 `8` 是原单克隆(receivable_this
> 原样复制,`payment_arrears`=本次补缴额,ref 挂原欠费单),入消费会双计应收;`7` 零金额流程关单。
> **结算原表照抄推送,宿主不做任何 status/金额过滤或分流**——消费 / 整单退费 / 行级退费明细的
> 切分全部由 PAC transforms 完成(单一真理源,与 file / cold-import 同口径)。宿主推 2 张原表:
> `patient_settlement`(结算头,全 status)、`patient_settlement_spec`(结算明细,全量)。
> **支付金额取结算头 `net_receipts_this`(实收);支付通道明细(`settlement_modes`)暂不摄入**
> (总值在结算头,PAC 当前无需通道拆分;若后续要"支付方式分析"再加)。
>
> `status` 全值照推,PAC 侧识别(`PatientSettlementEntity` 实体注释):`0`未结算 `1`已结算
> `2`只生成uuid `3`含退费行 `4`整单反向冲减 `5`重新结算(废弃历史) `6`医生未提交 `7`流程结束
> `8`欠款补缴克隆单。PAC 取:**消费**=`status∈{1,3}` 且 `receivable_this≥0`;**整单退费**=`status=4`
> 或(`status=3` 且 `receivable_this<0`);**退费明细**=`patient_settlement_spec.is_refund=1`。
> 其余(`0/2/5/6/7/8`)PAC 丢弃(`8` 原单克隆入消费会双计应收、`7` 零金额流程关单)。
### `patient_settlement` — 消费单
**推送范围:`status ∈ {1, 3}` 且 `receivable_this >= 0`。**
### `patient_settlement` — 结算头原表(全 status 照推,含消费与整单退费)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
......@@ -177,74 +179,47 @@ icon: FileJson
| `organization_id` | string | ✅ | 诊所 |
| `patient_id` | string | ✅ | → 患者 id |
| `doctor_id` | string | | 开单医生 |
| `status` | string/number | ✅ | 见上 |
| `receivable_this` | number(元) | ✅ | 应收(PAC 计患者价值/LTV 用) |
| `net_receipts_this` | number(元) | | 实收 |
| `status` | string/number | ✅ | 全值照推(见 §5 引言;PAC 侧切分) |
| `receivable_this` | number(元) | ✅ | 应收(PAC 计患者价值/LTV 用);**可为负 = 退费表达**(status=4 或部分品牌 status=3 负额) |
| `net_receipts_this` | number(元) | | 实收(退费行为负,PAC 取绝对值) |
| `billing_date` | string(datetime) | | 开单时间 |
| `registration_id` | string | | 关联接诊号 |
| `ref_settlement_id` | string | | (消费单一般为空) |
| `ref_settlement_id` | string | | **退费行(status=4)= 被退的原结算单 uuid**(PAC 据此把退费挂回原消费);消费行一般空 |
| `settlement_serial_num` | string | | 结算流水号 |
| `reason` | string | | 备注/原因 |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | ✅ | |
### `patient_settlement_refund` — 整单退费
**推送范围:`status = 4` 或(`status = 3` 且 `receivable_this < 0`)。** 字段同 `patient_settlement`;其中:
- `net_receipts_this` 负值 = 冲减金额(PAC 取绝对值)
- `ref_settlement_id` = **被退的原结算单 uuid**(status=4 必带;PAC 据此把退费挂回原消费)
### `patient_settlement_spec_refund` — 行级部分退费
**推送范围:结算明细行中 `is_refund = 1` 的行。**
### `patient_settlement_spec` — 结算明细原表(全量照推,含行级退费)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | ✅ | 明细行主键 |
| `tenant_id` / `organization_id` / `patient_id` | string | ✅ | 同上 |
| `tenant_id` / `organization_id` | string | ✅ | 品牌 / 诊所 |
| `settlement_id` | string | ✅ | 所属结算单 uuid(退费挂回原消费) |
| `cure_name` / `service_project_name` | string | | 被退项目名 |
| `receivable_this` / `net_receipts_this` | number(元) | ✅ | 被退金额(正值) |
| `is_refund` | string/number | ✅ | 恒为 `1` |
| `patient_id` | string | ✅ | **宿主已反填真 patient_id(inline)**——原生 spec.patient_id 部分品牌是诊所本地 id、不可信(实测元和王永全列与结算头不符),导出时按 `settlement_id` 从结算头取真值反填;PAC 直接用 |
| `cure_name` / `service_project_name` | string | | 项目名(退费行=被退项目) |
| `receivable_this` / `net_receipts_this` | number(元) | | 金额(`is_refund=1` 时为被退金额,正值) |
| `is_refund` | string/number | ✅ | `1`=退费行(PAC 只取此值切退费明细) `0`=正常明细 `2`=其他 |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | ✅ | |
### `settlement_modes` — 支付通道明细(每单×通道一行)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | ✅ | 行主键 |
| `tenant_id` | string | ✅ | 品牌 GUID |
| `settlement_id` | string | ✅ | → 结算单 uuid |
| `modes_name` | string | ✅ | 通道名(现金支付/微信支付/刷卡支付/医保支付…原样即可) |
| `money` | number(元) | ✅ | 该通道金额(PAC 取金额最大者为主导通道) |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | | |
---
## 6. 治疗计划与咨询(3 个 source)
## 6. 治疗计划与咨询(2 个 source)
### `customer_treat_plan` — 治疗计划(头)
### `customer_treat_plan_item` — 治疗计划(行;头属性已 inline)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | ✅ | 计划主键 |
| `tenant_id` | string | ✅ | 品牌 GUID |
| `organization_id` | string | ✅ | 诊所(**行项靠头表拿诊所,缺失该行会被丢弃**) |
| `customer_id` | string | ✅ | → 患者 id |
| `plan_group_id` / `plan_group_num` | string | | 方案分组(多方案对比) |
| `plan_name` | string | | 方案名 |
| `desired_effect` / `emergency_urgency` | string/number | | 期望效果 / 紧迫度 |
| `expect_cost` | string | | 期望费用 |
| `created_gmt_at` / `updated_gmt_at` | string(datetime) | ✅ | |
### `customer_treat_plan_item` — 治疗计划(行)
> **计划头 `customer_treat_plan` 不再单独推**——PAC 只从头取"诊所 + 方案名"两个属性给计划行,
> 头不是 PAC 实体。宿主把头的 `organization_id` / `plan_name` **inline 进每条计划行**即可;
> 头的 `expect_cost`/`desired_effect` PAC 暂不消费(将来做计划价值/LTV 再约定加)。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | ✅ | 行主键 |
| `tenant_id` | string | ✅ | 品牌 GUID |
| `customer_id` | string | ✅ | → 患者 id |
| `treat_plan_id` | string | ✅ | → 计划头 id |
| `organization_id` | string | ✅ | **诊所(宿主 inline,取自计划头)**——缺失该行会被 PAC 丢弃(计划事实必须归属诊所) |
| `plan_name` | string | | **方案名(宿主 inline,取自计划头)** |
| `treat_plan_id` | string | | → 计划头 id(留作溯源,PAC 不再靠它 lookup) |
| `tooth_position` | string | | 牙位 |
| `mode_name` | string | ✅ | 术式名(PAC 翻 11 类治疗类别) |
| `charge_min` / `charge_max` | number(元) | | 价格区间 |
......@@ -270,7 +245,67 @@ icon: FileJson
---
## 7. 语义澄清记录(2026-07,源码 + 数据双证)
## 7. 对接自测(预检 + 推送记录)
对接期不必盲推 —— PAC 提供两个自助工具,**测试环境** `https://pac.jarvismedical.asia`:
### 7.1 预检:`?dryRun=1`(强烈建议先跑)
```
POST /pac/v1/push/rows?dryRun=1
```
跑**完整管线**(transforms + 装配 + 归一 + 租户解析)但**不落任何库、不触发重算**,响应告诉你"若正式推会发生什么",并带**样本 canonical** —— 直接核对 PAC 把你的原生行翻译成了什么:
```jsonc
{"code":0,"data":{
"dryRun": true,
"accepted": 6, // 收到 6 行
"transactionsWritten": 5, // 其中 5 行会落库(差值 = 被 PAC 规则过滤,如噪音 status)
"failed": 0,
"mappingMisses": 0, // ⚠️ >0:有原值没映射上(落 _default)
"suspectFields": 0, // ⚠️ >0:疑似列改名/缺列
"samples": [ { "resource": "payment", "canonical": { "externalId": "…", "amount": 40000, … } } ]
}}
```
**自测通过标准**:`failed=0` 且 `mappingMisses=0` 且 `suspectFields=0`,再看 `samples` 里的字段值对不对 —— 都 OK 才去掉 `?dryRun=1` 正式推。
### 7.2 推送记录:事后可查(两种查法)
**① 免登录 —— 用已有 push 凭据验签(联调推荐)**
```
GET /pac/v1/push/logs?limit=50
Headers: X-PAC-Host-Id / X-PAC-Timestamp / X-PAC-Signature
```
鉴权方式与推送完全一致,**不必为联调另开账号**。GET 无 body,签名对**空串**计算:
`hex(HMAC-SHA256("<timestamp>.", secret))`(注意 timestamp 后那个点)。
这**不是公开接口** —— 没有正确签名拿不到任何数据。
**② 登录态 —— 宿主自助页同源接口**
```
GET /pac/v1/admin/host/self/push-logs?limit=50
```
两者返回**同一份数据**:按时间倒序最近 N 批(默认 50、上限 200),每批含
`source / status / dryRun / fetched / transactionsWritten / duplicates / failed / errorMessage`。
当时的同步响应没留存也能事后查:**哪批错了、错在哪**。预检批次由 `dryRun:true` 标识,不与正式推送混淆。
### 7.3 其他可用面
| 用途 | 地址 |
|---|---|
| 交互式 API 文档(可试调) | `/api/docs` |
| 本契约文档 | `/docs/integration/friday-push-payload` |
| 宿主自助页(患者数 / 24h 交易 / 上次 push / 失败率) | `/admin/host` |
| 队列面板(看 push 触发的画像重算) | `/admin/queues` |
> **常见错误码**:`10106` 缺 header / 签名不匹配(或时间戳偏差 >5min)· `10001` source 拼错
> (响应会列出可选源表名)· `10002` body 校验失败 · `10003` 并发超限(退避重发即可,幂等安全)
> · `30802` 整批失败,疑似关键字段缺名/改名。
---
## 8. 语义澄清记录(2026-07,源码 + 数据双证)
以下曾是开放问题,现已定案 —— 推送方无需再确认,列此备查:
......@@ -278,7 +313,7 @@ icon: FileJson
|---|---|---|
| 时间口径 | MySQL `datetime` = 北京墙钟(`_gmt_` 命名系惯例误导);**Mongo `Date` 是北京墙钟伪装成 UTC** | `clinicTime`/`createdGmtAt` 小时分布呈营业双峰;按真 UTC 解释则半数病历落深夜 |
| 金额单位 | 元(`decimal(9,2)`) | 洁治单价均值 ¥310、已结算客单均值 ¥1,730 |
| `contacts.relationship` | `PhoneRelationshipEnum` 1-9(见 §2) | customer 服务枚举类 |
| `relationship`(默认号归属) | `PhoneRelationshipEnum` 1-9(见 §2;宿主挑默认号后 inline) | customer 服务枚举类 |
| `referee_relationship` | `RecommendRelationshipEnum` 17 码,**语义 = 本行 customer 是 referee 的 X**(PAC 侧按逆关系映射) | 枚举类 `reverseValue()` + 双方年龄差数据 |
| `med_emr_info.treat` vs `dispose` | `treat` = 本次治疗(→ 结构化治疗事实);`dispose` = 处置叙述(→ 病历自由文本) | EMR 接口 DTO 字段注释 |
| `patient_settlement.status` 全 9 值 | `0`未结算 `1`已结算 `2`只生成uuid `3`含退费行 `4`整单反向冲减 `5`重新结算(废弃历史) `6`医生未提交 `7`流程结束 `8`欠款补缴克隆单 | 实体注释 + `savePatientSettlementQk()` 实现 |
......@@ -290,5 +325,6 @@ icon: FileJson
|---|---|
| `organization_name` 覆盖 | 目前仅病历/影像表带诊所名,**只覆盖有病历记录的诊所**;其余诊所前端回退显示 GUID。若贵方有组织树接口(如 `regional_nodes_structure`),提供 `诊所 id → 名称` 全量表可补齐 |
| 品牌名 | PAC 当前**不需要**品牌中文名(无展示位,内部按品牌 id 标识)。将来若有展示需求,再约定推品牌主档(`tenant_apply.tenant_info` 的 `tenant_id`/`name`)——贵方 `tenant_name` 未冗余进业务表,只能走主档 |
| 字典表推送频率 | `std_diag` / `std_check_class` 变更不频繁,按"变更时全量重推"即可,无需增量 |
| 私有字典不单独推 | `std_diag`(生产多品牌合计 1.5万~3万+行)/ `std_check_class`:纯翻译字典,**由宿主解析好 inline** 进 `diag[].std_code` / `med_check.class_name`。既省掉大表全量重推,也省掉 PAC 侧持久化字典存储——PAC 只留跨宿主的 `_shared` 临床字典 |
| 支付通道 | `settlement_modes`(约 24% 结算单多通道拆付)暂不摄入:总值已在结算头 `net_receipts_this`,PAC 当前无支付方式分析需求。将来要"医保占比/分次支付"再摄入通道明细 |
| 测试环境数据特征 | 部分租户为开发沙盒(诊所名如"XX专用诊所勿动"),字典类映射(治疗类别关键词等)待**生产数据**回流后再校准一轮 |
apps/pac-docs/content/docs/meta.json
......@@ -14,6 +14,7 @@
"deployment",
"deploy-runbook",
"ingestion",
"data-reconciliation",
"monitoring",
"troubleshooting",
"---参考---",
......
apps/pac-docs/openapi/pac.json
This source diff could not be displayed because it is too large. You can view the blob instead.
apps/pac-service/data/friday/assemblers/diagnosis.yaml
# diagnosis — FRIDAY 诊断 fact(med_emr_info.diag[] 拆行)
# 消费 transforms 输出表 diagnosis_rows(split + std_diag lookup + normalize/substring/coalesce)
# 消费 transforms 输出表 diagnosis_rows(split + normalize/substring/coalesce;std_code 由宿主 inline 进 diag 元素)
#
# code 解析规则(用户定,2026-07-18):
# linkCode 非空 → std_diag.std_code K 开头 → 截 K 大类(std_code_k 直通下方共享字典 passthrough);
......
apps/pac-service/data/friday/assemblers/emr.yaml
......@@ -10,7 +10,7 @@ emits:
occurredAtField: submittedAt
primary:
table: med_emr_info
table: _emr_official # transforms 产出:med_emr_info status∈{3,4}(排草稿;迁自导出侧过滤)
key: emr_sub_id # 小病历号 uuid(两侧连接键 + 临床事实锚点)
dedup_by: emr_sub_id
......
apps/pac-service/data/friday/assemblers/image.yaml
# image — FRIDAY 影像 metadata(MySQL emr.med_check;PAC 不持文件本体)
# 影像不在 Mongo 病历文档内(全字段枚举证实),挂 emr_id(10 位病历号)回病历。
# 消费 transforms 输出表 image_rows(med_check lookup std_check_class 附 class_name)
# 直接消费 med_check(class_name 由宿主 inline:class_code→std_check_class 已解析);modality 经共享字典翻
canonical: image
emits:
......@@ -9,7 +9,7 @@ emits:
occurredAtField: uploadedAt
primary:
table: image_rows
table: med_check
key: id
dedup_by: id
......@@ -21,7 +21,7 @@ field_mapping:
clinicId: organization_id
uploadedAt: shooting_time # 拍摄时间
encounterExternalId: emr_id # 病历号级挂载(= med_emr_info.emr_id,非 emr_sub_id)
modality: class_name # lookup 自 std_check_class 字典
modality: class_name # 宿主 inline(class_code→std_check_class 已解析)→ 共享字典翻
fileUrl: file_url # OSS 相对路径(passthrough)
fileName: file_name
......
apps/pac-service/data/friday/assemblers/patient.yaml
# patient — 主档 upsert(不进 transaction,无 emits)
# 源:customer.customer_basic_info(原始表);phone 由 manifest.transforms.lookup
# 从 customer_contacts 挑默认号附加进来,故这里直接映射标量 phone。
# 源:customer.customer_basic_info;contacts_tel / relationship 由宿主导出时挑默认号 inline 进主档
# (不再 PAC 侧 lookup customer_contacts),故这里直接映射标量。
canonical: patient
primary:
......@@ -10,12 +10,12 @@ primary:
field_mapping:
externalId: id # customer_basic_info 主键 = host 内部患者唯一 id(→ String 化)
name: name
phone: phone # 由 transforms.lookup 从 customer_contacts 挑默认号附加
phone: contacts_tel # 宿主 inline 的默认号(沿用 customer_contacts 原列名)
# 该号关系码(lookup 同源带出)→ preferences.contactPhone{relationshipCode, relationship, isSelf}。
# 官方枚举(源码实锤 friday-saas/customer …/enums/PhoneRelationshipEnum.java,2026-07-20):
# 1本人 2爸爸 3妈妈 4爷爷 5奶奶 6朋友 7配偶 8子女 9其他(语义=持号人是患者的X)
phoneRelationshipCode: phone_relationship
phoneRelationship: phone_relationship # 同源列解码成 PAC 关系词(下方 enum_mapping)
phoneRelationshipCode: relationship
phoneRelationship: relationship # 同源列解码成 PAC 关系词(下方 enum_mapping)
gender: sex # tinyint 1/2 → enum_mapping 归一;0/空 → 空
birthDate: birthday # date;空值入库为 null
medicalRecordNumber: file_number # 档案号(病历号,客服沟通用)
......
apps/pac-service/data/friday/assemblers/payment.yaml
......@@ -26,7 +26,8 @@ field_mapping:
# 应收降级 receivableAmount(折扣率分母/权益客识别)。
amount: net_receipts_this
receivableAmount: receivable_this
method: method # lookup 主导支付通道(现金/微信/刷卡/医保…原样入 fact)
# method 暂不接:支付通道明细(settlement_modes)不摄入,金额取结算头 net_receipts_this。
# 将来要"支付方式分析"(医保占比/分次支付)再摄入 settlement_modes、恢复 method。
doctorId: doctor_id
encounterExternalId: registration_id # 关联接诊
settlementSerialNum: settlement_serial_num # 结算流水号(passthrough,对账用)
apps/pac-service/data/friday/assemblers/refund_full.yaml
......@@ -13,7 +13,7 @@ emits:
kind: actual
primary:
table: patient_settlement_refund
table: refund_full_rows # transforms 产出:status=4 ∪ (status=3 且 receivable<0)
key: uuid
dedup_by: uuid
......
apps/pac-service/data/friday/assemblers/refund_item.yaml
......@@ -11,7 +11,7 @@ emits:
kind: actual
primary:
table: patient_settlement_spec_refund
table: refund_item_rows # transforms 产出:patient_settlement_spec 里 is_refund=1
key: id
dedup_by: id
......@@ -19,6 +19,7 @@ field_mapping:
externalId: id
updatedAt: updated_gmt_at
createdAt: created_gmt_at
# spec.patient_id 部分品牌原是诊所本地 id → 宿主导出时已从结算头反填真 patient_id(inline);PAC 直接用
patientExternalId: patient_id
clinicId: organization_id
refundedAt: created_gmt_at
......
apps/pac-service/data/friday/assemblers/treatment_planned.yaml
# treatment_planned — FRIDAY 治疗计划(customer_treat_plan + _item 独立表;用户确认此表为治疗计划)
# 消费 transforms 输出表 treatment_planned_rows(行表 lookup 头表拿 organization_id/plan_name)
# treatment_planned — FRIDAY 治疗计划(消费 customer_treat_plan_item;头属性 organization_id/plan_name 由宿主 inline)
# 消费 transforms 输出表 treatment_planned_rows(item 过滤无诊所行 + normalize 术式名)
# 行粒度 = 计划行项(牙位 + 术式 mode_name + 价格区间);externalId = 行表主键(host 稳定)
canonical: treatment
......@@ -19,7 +19,7 @@ field_mapping:
updatedAt: updated_gmt_at
createdAt: created_gmt_at
patientExternalId: customer_id
clinicId: organization_id # lookup 自头表(行表无诊所)
clinicId: organization_id # 宿主 inline 自计划头(行表原生无诊所)
occurredAt: created_gmt_at # 计划制定时点
category: mode_norm # 归一术式名 → 共享字典翻 11 类闭集
subtype: mode_name # 原始术式名
......
apps/pac-service/data/friday/export.sh
#!/usr/bin/env bash
# FRIDAY SaaS 测试环境 → PAC cold-import 导出(等价"host 侧单表 dump")
# FRIDAY SaaS 测试环境 → PAC cold-import 导出(host 侧「自洽业务表」参考实现)
#
# 纪律(同 jvs-dw SQL 朴素化):每条导出 = 列选 + WHERE,零 join/零变换;
# (2026-07 对齐:一列都不改名 —— 宿主原生字段直出;与 PAC 租户概念的区分由 PAC 适配层消化。)
# 形态改造(拆 JSON 数组/字典 join/K 码截取)全部在 PAC transforms 层做。
# 纪律(2026-07 对齐,契约见 docs/integration/friday-push-payload):
# - 业务 WHERE / status 切分 / K 码截取 / 数组拆行 → 全在 PAC transforms 层(不在导出侧)。
# - 但**宿主自己的引用**在导出时 within-host join 后 inline 进相关行(PAC 无从做,数据在宿主手里):
# 私有字典码(diag linkCode→std_code、影像 class_code→类型名)、1:N 派生(默认联系号+归属)、
# 头-行属性(计划头 诊所/方案名 下放到计划行)。故不再导出纯字典表/联系方式/计划头/支付通道。
# - **列名一律沿用宿主原表列名**(含 inline 进来的:contacts_tel/relationship/std_code/class_name/
# organization_id/plan_name)—— PAC 不发明新名,宿主无需为 PAC 做字段改名。
#
# 用法(cohort 过滤,语义与 jvs-dw cold-import --clinics/--since 完全一致):
# ./export.sh # 全量(默认行为不变)
......@@ -123,31 +127,25 @@ mysql_csv() {
}
echo "── MySQL 导出 ──"
# 患者主档(全量;既有 450 行样本 → 扩全量,EMR 覆盖 ~1.65 万患者的前置)
mysql_csv "SELECT id,name,sex,birthday,file_number,tenant_id,organization_id,created_gmt_at,updated_gmt_at FROM customer.customer_basic_info $(pf id)" customer_basic_info.csv
# 联系方式 1:N(lookup 挑默认号 → patient.phone)
mysql_csv "SELECT id,customer_id,contacts_tel,is_default,contacts_type,tel_type,relationship FROM customer.customer_contacts $(pf customer_id)" customer_contacts.csv
# ⭐ 自洽形态:宿主 within-host join 把私有字典码 / 1:N 默认号 / 计划头属性 inline 进相关表
# (契约见 docs/integration/friday-push-payload)。纯字典表 / 联系方式 1:N / 计划头 / 支付通道
# 不再单独导出成文件——PAC 只摄入自洽业务行(所有摄入路径同形态)。
# 患者主档 + inline 默认联系号(挑:非空号 → is_default↓ → contacts_type↑ → id↑;phone 与归属同源同一条)
mysql_csv "SELECT cbi.id,cbi.name,cbi.sex,cbi.birthday,cbi.file_number,cbi.tenant_id,cbi.organization_id,cbi.created_gmt_at,cbi.updated_gmt_at,
(SELECT c.contacts_tel FROM customer.customer_contacts c WHERE c.customer_id=cbi.id AND c.contacts_tel<>'' ORDER BY c.is_default DESC,c.contacts_type ASC,c.id ASC LIMIT 1) AS contacts_tel,
(SELECT c.relationship FROM customer.customer_contacts c WHERE c.customer_id=cbi.id AND c.contacts_tel<>'' ORDER BY c.is_default DESC,c.contacts_type ASC,c.id ASC LIMIT 1) AS relationship
FROM customer.customer_basic_info cbi $(pf cbi.id)" customer_basic_info.csv
# 预约(全状态;transforms 丢草稿 10)
mysql_csv "SELECT id,patient_appointment_id,organization_id,tenant_id,appointment_date,appointment_start,appointment_status,doctor_user_id,appointment_time_length,in_time,created_gmt_at,updated_gmt_at FROM \`arrail-appointment-server\`.appointment_base $(pf patient_appointment_id)" appointment_base.csv
# 影像档案(挂 emr_id 病历号;modality 经 std_check_class 字典翻)
mysql_csv "SELECT id,tenant_id,organization_id,organization_name,patient_id,emr_id,class_code,file_name,file_type,file_url,files_size,shooting_time,created_gmt_at,updated_gmt_at FROM emr.med_check $(pf patient_id)" med_check.csv
# 影像类型字典(class_code UUID 全局唯一,lookup 不需 tenant 限定)
mysql_csv "SELECT class_code,class_name,tenant_id FROM emr.std_check_class" std_check_class.csv
# 诊断字典(linkCode → std_code;K 码用,非 K 落自由文本)
mysql_csv "SELECT diag_code,diag_name,std_code FROM emr.std_diag" std_diag.csv
# 治疗计划(头:方案名/期望;行:牙位/术式/价格区间)→ treatment_planned
mysql_csv "SELECT id,tenant_id,organization_id,customer_id,plan_group_id,plan_name,desired_effect,emergency_urgency,expect_cost,created_gmt_at,updated_gmt_at FROM customer.customer_treat_plan $(pf customer_id)" customer_treat_plan.csv
mysql_csv "SELECT id,tenant_id,customer_id,treat_plan_id,tooth_position,mode_name,charge_min,charge_max,created_gmt_at,updated_gmt_at FROM customer.customer_treat_plan_item $(pf customer_id)" customer_treat_plan_item.csv
# 结算(消费/退费)。status 语义(2026-07-18 实测):1=已结算 3=含退费行的单 4=整单反向冲减(负额+ref 挂原单)。
# ⚠️ 2ac96f6d 品牌不用 status=4:整单冲减直接记 status=3 负金额(实测 200 行)→ 按金额正负切分:
# 消费 = status∈{1,3} 且金额≥0;整单退费 = status=4 或 status=3 负金额(退费第三表达)。
# 其余 status(0 草稿/2/5/6/7/8)语义未明,先不收 → WHERE 收窄(host 等价 dump 允许的过滤)
mysql_csv "SELECT uuid,tenant_id,organization_id,patient_id,doctor_id,status,receivable_this,net_receipts_this,billing_date,registration_id,ref_settlement_id,settlement_serial_num,reason,created_gmt_at,updated_gmt_at FROM \`arrail-settlement-server\`.patient_settlement WHERE status IN (1,3) AND receivable_this >= 0 $(pfa patient_id)" patient_settlement.csv
mysql_csv "SELECT uuid,tenant_id,organization_id,patient_id,doctor_id,status,receivable_this,net_receipts_this,billing_date,registration_id,ref_settlement_id,settlement_serial_num,reason,created_gmt_at,updated_gmt_at FROM \`arrail-settlement-server\`.patient_settlement WHERE (status=4 OR (status=3 AND receivable_this < 0)) $(pfa patient_id)" patient_settlement_refund.csv
# 退费行级明细(部分退费轨道:is_refund=1 全部归属 status=3 头单)
mysql_csv "SELECT id,tenant_id,organization_id,patient_id,settlement_id,cure_name,service_project_name,receivable_this,net_receipts_this,is_refund,created_gmt_at,updated_gmt_at FROM \`arrail-settlement-server\`.patient_settlement_spec WHERE is_refund=1 $(pfa patient_id)" patient_settlement_spec_refund.csv
# 支付通道长表(每单×通道一行;lookup 挑金额最大者为主导通道)
mysql_csv "SELECT id,tenant_id,settlement_id,modes_name,money,created_gmt_at,updated_gmt_at FROM \`arrail-settlement-server\`.settlement_modes $(pfs)" settlement_modes.csv
# 影像档案 + inline class_name(class_code→std_check_class,宿主解析;PAC 再翻 modality)
mysql_csv "SELECT mc.id,mc.tenant_id,mc.organization_id,mc.organization_name,mc.patient_id,mc.emr_id,mc.class_code,sc.class_name,mc.file_name,mc.file_type,mc.file_url,mc.files_size,mc.shooting_time,mc.created_gmt_at,mc.updated_gmt_at FROM emr.med_check mc LEFT JOIN emr.std_check_class sc ON sc.class_code=mc.class_code $(pf mc.patient_id)" med_check.csv
# 治疗计划行 + inline 头属性(organization_id/plan_name 取自计划头;头不单独导出)
mysql_csv "SELECT it.id,it.tenant_id,it.customer_id,it.treat_plan_id,it.tooth_position,it.mode_name,it.charge_min,it.charge_max,it.created_gmt_at,it.updated_gmt_at,h.organization_id,h.plan_name FROM customer.customer_treat_plan_item it LEFT JOIN customer.customer_treat_plan h ON h.id=it.treat_plan_id $(pf it.customer_id)" customer_treat_plan_item.csv
# 结算头单原表(全 status,导出侧不做业务 WHERE;消费/退费切分全在 PAC)
mysql_csv "SELECT uuid,tenant_id,organization_id,patient_id,doctor_id,status,receivable_this,net_receipts_this,billing_date,registration_id,ref_settlement_id,settlement_serial_num,reason,created_gmt_at,updated_gmt_at FROM \`arrail-settlement-server\`.patient_settlement $(pf patient_id)" patient_settlement.csv
# 结算明细原表(全量含 is_refund,PAC 侧切退费明细)。JOIN 结算头:① 挂靠限定 cohort
# ② 反填真 patient_id(spec.patient_id 部分品牌是诊所本地 id,不可信 → 取结算头 ps.patient_id inline)
mysql_csv "SELECT sp.id,sp.tenant_id,sp.organization_id,ps.patient_id,sp.settlement_id,sp.cure_name,sp.service_project_name,sp.receivable_this,sp.net_receipts_this,sp.is_refund,sp.created_gmt_at,sp.updated_gmt_at FROM \`arrail-settlement-server\`.patient_settlement_spec sp JOIN \`arrail-settlement-server\`.patient_settlement ps ON ps.uuid=sp.settlement_id $(pf ps.patient_id)" patient_settlement_spec.csv
# 转介绍圈(患者-患者关系边,双向成对存;referee_relationship 为宿主字典 id,PAC 侧统计推断解码)
mysql_csv "SELECT id,tenant_id,organization_id,customer_id,referee_patient_id,referee_relationship,type,created_gmt_at,updated_gmt_at FROM customer.customer_referee_circle $(pf customer_id)" customer_referee_circle.csv
# 咨询(意向 potential_treatment/未成交原因;测试库仅 45 行,结构真实)
......@@ -163,9 +161,22 @@ echo "── Mongo 导出(med_emr_info,status∈{3,4} 正式病历)──"
# 按真 UTC 解释则一半病历落深夜——荒谬)。故导出**不能** toISOString 带 Z(会被 PAC 当真
# UTC 再 +8,EMR 链时间全偏 8 小时,已踩):把 UTC 字段值直读为墙钟,输出 naive
# "YYYY-MM-DD HH:mm:ss",交给 manifest timezone=Asia/Shanghai 解释 → 瞬间正确。
# 诊断字典 map(diag_code→std_code)—— diag[] inline std_code 的 within-host join;linkCode 在 Mongo、
# 字典在 MySQL,故预取成 map 挂进 mongo 容器,eval 里逐元素解析(不再 PAC 侧 lookup std_diag)。
printf 'SELECT diag_code,std_code FROM emr.std_diag\n' | docker run -i --rm mysql:8 mysql \
-h"$FRIDAY_MYSQL_HOST" -P"$FRIDAY_MYSQL_PORT" -u"$FRIDAY_MYSQL_USER" -p"$FRIDAY_MYSQL_PASSWORD" \
--default-character-set=utf8mb4 --batch --raw=FALSE --connect-timeout=20 \
| node -e '
const lines = require("fs").readFileSync(0, "utf-8").split("\n"); const m = {};
for (let i = 1; i < lines.length; i++) { const l = lines[i]; if (!l) continue; const t = l.split("\t");
if (t[0] && t[0] !== "NULL") m[t[0]] = (t[1] && t[1] !== "NULL") ? t[1] : ""; }
process.stdout.write(JSON.stringify(m));
' > std_diag_map.json
echo " std_diag_map.json: $(node -e 'process.stdout.write(String(Object.keys(JSON.parse(require("fs").readFileSync("std_diag_map.json","utf-8"))).length))') 码"
# cohort 模式:挂载 id 文件供 $in 过滤(bash 3.2 + set -u 下空数组要用 ${arr[@]+...} 展开)
MONGO_ARGS=()
if [ -n "$COHORT_IN" ]; then MONGO_ARGS=(-v "$PWD/cohort_ids.json:/cohort_ids.json:ro" -e "COHORT=1"); fi
MONGO_ARGS=(-v "$PWD/std_diag_map.json:/std_diag_map.json:ro")
if [ -n "$COHORT_IN" ]; then MONGO_ARGS+=(-v "$PWD/cohort_ids.json:/cohort_ids.json:ro" -e "COHORT=1"); fi
docker run --rm ${MONGO_ARGS[@]+"${MONGO_ARGS[@]}"} mongo:7 mongosh "$FRIDAY_MONGO_URI" --quiet --eval '
const flat = (v) => v instanceof Date ? v.toISOString().slice(0, 19).replace("T", " ")
: (v && v.constructor && v.constructor.name === "Long") ? String(v)
......@@ -173,13 +184,15 @@ docker run --rm ${MONGO_ARGS[@]+"${MONGO_ARGS[@]}"} mongo:7 mongosh "$FRIDAY_MON
// id 类字段字符串化:Mongo 存的是 number/Long 混型,canonical 契约要 string
// (CSV 源天然全字符串;JSON 导出须显式对齐,否则 patientExternalId 等校验失败)
const sid = (v) => (v === undefined || v === null || v === "") ? null : String(flat(v));
// 诊断字典 map(within-host join):diag[].linkCode → std_code inline 进元素(沿用宿主列名 std_code)
let DIAG = {}; try { DIAG = JSON.parse(require("fs").readFileSync("/std_diag_map.json", "utf-8")); } catch (e) {}
const q = { status: { $in: [3, 4] } };
if (process.env.COHORT === "1") {
try {
// cohort 激活但文件读不到 → 硬失败(宁可让 .tmp 校验拒绝,不能静默退化成全量导出)
const ids = JSON.parse(require("fs").readFileSync("/cohort_ids.json", "utf-8"));
const both = (s) => { const n = Number(s); return Number.isFinite(n) && String(n) === s ? [s, n] : [s]; };
q.patientId = { $in: ids.flatMap(both) };
}
} catch (e) {}
let first = true;
print("[");
db.med_emr_info.find(q).forEach((d) => {
......@@ -190,7 +203,10 @@ docker run --rm ${MONGO_ARGS[@]+"${MONGO_ARGS[@]}"} mongo:7 mongosh "$FRIDAY_MON
organization_name: flat(d.organizationName), // 诊所名(clinic_directory 派生 host.clinicNames)
patient_id: sid(d.patientId), user_id: sid(d.userId), user_name: flat(d.userName),
clinic_time: flat(d.clinicTime), visit_indicator: flat(d.visitIndicator), status: flat(d.status),
diag: d.diag ?? [], treat: d.treat ?? [], dispose: d.dispose ?? [], examine: d.examine ?? [],
// diag[] inline std_code(宿主 within-host join);treat/dispose/examine 原生数组原样
diag: (d.diag ?? []).map((el) => Object.assign({}, el,
{ std_code: (el && el.linkCode != null && el.linkCode !== "") ? (DIAG[String(el.linkCode)] ?? "") : "" })),
treat: d.treat ?? [], dispose: d.dispose ?? [], examine: d.examine ?? [],
// emr_record 自由文本位要字符串(fact 层 zod nullableString);数组原样给 split_json_array 拆行
dispose_text: (d.dispose ?? []).length ? JSON.stringify(d.dispose) : null,
examine_text: (d.examine ?? []).length ? JSON.stringify(d.examine) : null,
......
apps/pac-service/data/friday/manifest.yaml
# FRIDAY SaaS Cold Import Manifest(首版 — 仅 patient 试跑)
#
# 数据源:FRIDAY SaaS MySQL(customer 库)。cold-import 不支持 MySQL 直连,
# 走 CSV 文件模式:host 端**纯导原始表**(SELECT * FROM tb),不做任何 join。
# 电话在 1:N 的 customer_contacts 里 → 由 transforms.lookup 按 customer_id join、
# 挑默认号(is_default→本人→最早)填成 patient.phone 标量。宿主零特殊处理。
# 走 CSV 文件模式。宿主推「自洽业务表」:自己的引用(私有字典码 / 1:N 默认号 / 头-行属性)
# 在导出时 within-host join 后 inline 进相关行,**列名沿用宿主原表列名**(见 tables 上方说明);
# 业务 WHERE / status 切分等全部留在 PAC transforms(单一真理源)。
#
# ── 方案 B:合成"市场"集团 tenant;品牌降为 source_unit 命名空间 ──
# FRIDAY 是多品牌 SaaS(30+ 独立品牌 tenant_id,各含 1-8 诊所 organization_id)。
......@@ -39,7 +39,7 @@ clinic_directory:
# ── 增量水位声明(2026-07 与 jvs-dw 统一;file 源放 manifest 顶层)──
# file 装载不消费水位(每轮全量装载,幂等去重兜底);每轮跑完与 jvs-dw 走同一段 finally
# 记账 cursor_after = run_start(sync_logs)。用途:delta 导出 WHERE 模板 / push 回放起点。
# 只列有 updated_gmt_at 的事件表;字典表(std_*)与 customer_contacts(无更新列)恒全量。
# 只列有 updated_gmt_at 的事件表(字典/联系方式/计划头等已 inline,不再单独摄入)。
incremental:
per_query:
customer_basic_info: { cursor_column: updated_gmt_at }
......@@ -47,53 +47,32 @@ incremental:
med_emr_info: { cursor_column: updated_gmt_at }
med_check: { cursor_column: updated_gmt_at }
patient_settlement: { cursor_column: updated_gmt_at }
patient_settlement_refund: { cursor_column: updated_gmt_at }
patient_settlement_spec_refund: { cursor_column: updated_gmt_at }
settlement_modes: { cursor_column: updated_gmt_at }
customer_treat_plan: { cursor_column: updated_gmt_at }
patient_settlement_spec: { cursor_column: updated_gmt_at }
customer_treat_plan_item: { cursor_column: updated_gmt_at }
customer_referee_circle: { cursor_column: updated_gmt_at }
customer_consult: { cursor_column: updated_gmt_at }
# ⭐ 宿主推「自洽的业务表」:私有字典码 / 1:N 派生 / 头-行属性 都由宿主 within-host join 后 inline 进相关行
# (契约见 docs/integration/friday-push-payload)。故不再摄入纯字典表(std_diag/std_check_class)、
# 联系方式 1:N(customer_contacts→inline 默认号进主档)、计划头(customer_treat_plan→inline 进行)、
# 支付通道(settlement_modes,金额已在结算头 net_receipts_this)。所有摄入路径(push/file/pull/reparse)同此形态。
tables:
- { table: customer_basic_info, file: customer_basic_info.csv } # 患者主档(原始)
- { table: customer_contacts, file: customer_contacts.csv } # 联系方式 1:N(原始)
- { table: customer_basic_info, file: customer_basic_info.csv } # 患者主档(含 inline contacts_tel/relationship)
- { table: appointment_base, file: appointment_base.csv } # 预约(原始,全状态)
# ── EMR 病历链(W FRIDAY-EMR:Mongo med_emr_info status∈{3,4} 正式病历;export.sh 平铺导出)──
# 数组字段(diag/treat/dispose/examine)导出保留原生数组(split_json_array 原生支持);
# dispose_text/examine_text 是同数据的 JSON 字符串形态(emr_record 自由文本位要 string)。
# diag[] 元素含 inline std_code(宿主解析 linkCode→std_diag.std_code);treat/dispose/examine 原生数组。
- { table: med_emr_info, file: med_emr_info.json } # 病历正文(Mongo,含 diag/treat 数组)
- { table: med_check, file: med_check.csv } # 影像档案(挂 emr_id 病历号)
- { table: std_check_class, file: std_check_class.csv } # 影像类型字典(class_code→class_name)
- { table: std_diag, file: std_diag.csv } # 诊断字典(linkCode→std_code;K 码用)
- { table: customer_treat_plan, file: customer_treat_plan.csv } # 治疗计划头(方案名/期望)
- { table: customer_treat_plan_item, file: customer_treat_plan_item.csv } # 治疗计划行(牙位/术式/价格)
- { table: patient_settlement, file: patient_settlement.csv } # 消费头单(status 1/3 且金额≥0)
- { table: patient_settlement_refund, file: patient_settlement_refund.csv } # 整单退费(status=4 或 3 负额)
- { table: patient_settlement_spec_refund, file: patient_settlement_spec_refund.csv } # 行级退费明细(is_refund=1)
- { table: settlement_modes, file: settlement_modes.csv } # 支付通道长表
- { table: med_check, file: med_check.csv } # 影像档案(含 inline class_name;挂 emr_id)
- { table: customer_treat_plan_item, file: customer_treat_plan_item.csv } # 治疗计划行(含 inline organization_id/plan_name)
# 结算原表(全 status,导出侧不做业务 WHERE)—— 消费/退费/明细全部由 PAC transforms 切分(单一真理源)
- { table: patient_settlement, file: patient_settlement.csv } # 结算头单原表(全 status)
- { table: patient_settlement_spec, file: patient_settlement_spec.csv } # 结算明细原表(全量,含 is_refund)
- { table: customer_referee_circle, file: customer_referee_circle.csv } # 转介绍圈(患者-患者边)
- { table: customer_consult, file: customer_consult.csv } # 咨询(意向/未成交原因)
transforms:
# ── 患者:把 1:N 联系方式归约成 patient.phone 标量(无需源侧 join)──
- kind: lookup
input: customer_basic_info
output: customer_basic_info # in-place 附加 phone 列
from: customer_contacts
left_key: id # 患者主键
right_key: customer_id # 联系方式指向患者的外键
where:
contacts_tel: { not_empty: true } # 空号候选剔除
order_by: # 挑一条:默认号 → 本人(type=1) → 最早 id
- { field: is_default, dir: desc }
- { field: contacts_type, dir: asc }
- { field: id, dir: asc }
select:
phone: contacts_tel # patient.phone ← 选中候选的 contacts_tel
# 该号与患者的关系码(host sys_dict 编码;实测 1=本人 78.7%(成人),儿童过半非本人号)。
# 先落原码(preferences.contactPhone,isSelf=码=='1');完整标签字典待 sys_dict 可读后补。
phone_relationship: relationship
# ── 患者 phone:宿主已按「默认号→本人→最早」挑好、inline 进 customer_basic_info 的
# contacts_tel / relationship 两列(沿用宿主源列名;不再 lookup customer_contacts)。patient.yaml 直接读。──
# ── 预约:丢草稿 → 全部预约(拼 scheduledAt)+ 已到诊拆成接诊事件(→ encounter)──
# 与 jvs-dw 同款设计:一个预约源喂两张 canonical(appointment / encounter)。
......@@ -126,9 +105,16 @@ transforms:
# ── E.1 病历自由文本行(emr.yaml 直接消费 med_emr_info,无需 project:
# assembler field_mapping 天然只取所需列,数组列不映射即不入 canonical)──
# ── E.0 病历排草稿:status∈{3,4} 正式病历(迁自 mongo 导出侧过滤;PAC 侧统一)──
- kind: filter
input: med_emr_info
output: _emr_official
where:
status: { in: ['3', '4'] }
# ── E.2 diag[] 拆行 → 诊断候选 ──
- kind: split_json_array
input: med_emr_info
input: _emr_official
output: _diag_raw
array_field: diag
parent_keys:
......@@ -145,19 +131,9 @@ transforms:
element_fields:
value: value
tooth_position: toothPosition
link_code: linkCode
std_code: std_code # 宿主已解析 linkCode→std_diag.std_code、inline 进元素(沿用宿主列名;不再 PAC 侧 lookup)
where:
value: { not_empty: true } # 只要求有诊断名;linkCode 可空(仅 0.3% 有)
# E.2.1 linkCode → std_diag 字典(diag_code UUID 全局唯一,LEFT JOIN 未命中 → std_code=null)
- kind: lookup
input: _diag_raw
output: _diag_raw # in-place 附加 std_code
from: std_diag
left_key: link_code
right_key: diag_code
select:
std_code: std_code
value: { not_empty: true } # 只要求有诊断名;std_code 可空(非 K/未解析 → 走自由文本)
# E.2.2 归一 + K 码截取 + coalesce
# 规则(用户定):std_code K 开头 → 截 K 大类;非 K(DA0E.50 等 ICD-11)/join 不上/linkCode 空
......@@ -190,7 +166,7 @@ transforms:
# 注:treat 填充仅 25%(dispose 98% 是处置叙述,整段进 emr_record.disposal 不丢);
# 若后续漏召,可加 dispose keyword 路由补 actual(Phase 2 评估)。
- kind: split_json_array
input: med_emr_info
input: _emr_official
output: _treat_raw
array_field: treat
parent_keys:
......@@ -296,30 +272,13 @@ transforms:
op: concat
parts: ['${emr_sub_id}', '|rec|', '${value}', '|', '${tooth_position}']
# ── E.4 影像:med_check + 类型字典 → class_name(modality 经共享字典翻)──
- kind: lookup
input: med_check
output: image_rows
from: std_check_class
left_key: class_code
right_key: class_code
select:
class_name: class_name
# ── E.4 影像:med_check 已含 inline class_name(宿主解析 class_code→std_check_class);
# image.yaml 直接以 med_check 为 primary、读 class_name 翻 modality(不再 PAC 侧 lookup)。──
# ── E.5 治疗计划:行表 join 头表拿 诊所/方案名 → planned 候选 ──
- kind: lookup
input: customer_treat_plan_item
output: _plan_item_joined
from: customer_treat_plan
left_key: treat_plan_id
right_key: id
select:
organization_id: organization_id
plan_name: plan_name
# 头表 lookup 未命中 / 头表无诊所 → 计划行无法归属诊所,显式丢弃(canonical clinicId 必填;
# 留着只会变 failed 噪音。测试库实测 75/187 行如此)
# ── E.5 治疗计划:计划行已含 inline organization_id/plan_name(宿主取自计划头);
# 仅丢弃无诊所归属的行(canonical clinicId 必填;头无诊所 → 该行产 failed 噪音,提前剔除)。──
- kind: filter
input: _plan_item_joined
input: customer_treat_plan_item
output: _plan_item_with_org
where:
organization_id: { not_empty: true }
......@@ -336,25 +295,43 @@ transforms:
# 消费 = status∈{1,3};退费双轨 = ①status=4 整单(ref_settlement_id 挂原单)②spec is_refund=1 行级。
# LTV = Σpayment − Σrefund 自然对账;不从 settlement 反推治疗(财务≠临床,jvs-dw 已验证的教训)。
# ── S.1 消费:status 1/3 → 主导支付通道 lookup(金额最大者)──
# ── S.1 消费:status∈{1,3} 且应收≥0 → payment(金额取结算头 net_receipts_this)。
# 支付通道(settlement_modes)暂不摄入 → payment 无 method(总值在结算头,无需通道拆分)。──
- kind: filter
input: patient_settlement
output: _pay_hdr
output: payment_rows
where:
status: { in: ['1', '3'] }
- kind: lookup
input: _pay_hdr
output: payment_rows
from: settlement_modes
left_key: uuid
right_key: settlement_id
order_by:
- { field: money, dir: desc }
select:
method: modes_name # 主导支付通道(现金/微信/刷卡/医保…干净中文名,原样入 fact)
receivable_this: { gte: 0 } # 应收≥0(迁自导出侧 WHERE;数值算子)
# ── S.2 退费①:整单冲减(status=4 或 status=3 负金额;导出侧 WHERE 已切分,assembler 直读
# patient_settlement_refund 表;金额负值由 refund parser Math.abs 归一)──
# ── S.2 退费①:整单冲减 —— PAC 侧切分(不再靠导出 WHERE)。两种表达 union:
# ① status=4 整单反向;② status=3 且 receivable_this<0(2ac96f6d 品牌用负额表达退费)。
# 金额负值由 refund parser Math.abs 归一为正 cents。
- kind: filter
input: patient_settlement
output: _refund_status4
where:
status: { equals: '4' }
- kind: filter
input: patient_settlement
output: _refund_neg3
where:
status: { equals: '3' }
receivable_this: { lt: 0 } # 数值算子:负额退费表达
- kind: union
inputs: ['_refund_status4', '_refund_neg3']
output: refund_full_rows
# ── S.3 退费明细②:行级退费(patient_settlement_spec is_refund=1)——PAC 侧 filter ──
# ⚠️ spec.patient_id 部分品牌是「诊所本地 id」而非全局 customer id(元和王永 691828a5 实测
# 全 26421 行不符,spec=2/头=666716)。退费明细是结算头子行 → 宿主导出时已按 settlement_id
# 从结算头把真 patient_id **反填进 spec.patient_id**(within-host join,inline),PAC 直接信;
# 故此处仅 filter,不再跨表 lookup 结算头(单表 push 自洽)。
- kind: filter
input: patient_settlement_spec
output: refund_item_rows
where:
is_refund: { equals: '1' }
# ═══════════ 患者关系链(customer_referee_circle → patient_relations 独立表)═══════════
# 宿主 referee_relationship 是字典 id(DB 无字典表,疑似代码硬编码)。解码 = 统计推断
......
apps/pac-service/package.json
......@@ -90,6 +90,7 @@
"socket.io": "^4.8.3",
"winston": "^3.19.0",
"ws": "^8.21.0",
"yauzl": "^3.3.0",
"zod": "^4.4.3"
},
"devDependencies": {
......
apps/pac-service/src/modules/admin/admin.module.ts
......@@ -7,6 +7,7 @@ import { MappingMissAdminController } from './mapping-miss.controller';
import { HostsService } from './hosts.service';
import { AiInvocationsService } from './ai-invocations.service';
import { MappingMissService } from './mapping-miss.service';
import { ImportUploadService } from './import-upload.service';
@Module({
controllers: [
......@@ -14,7 +15,7 @@ import { MappingMissService } from './mapping-miss.service';
AiInvocationsAdminController,
MappingMissAdminController,
],
providers: [HostsService, AiInvocationsService, MappingMissService],
providers: [HostsService, AiInvocationsService, MappingMissService, ImportUploadService],
exports: [HostsService, AiInvocationsService],
})
export class AdminModule {}
apps/pac-service/src/modules/admin/dto/admin.dto.ts
import { createZodDto } from 'nestjs-zod';
import { z } from 'zod';
import {
ListHostsResponseSchema,
HostSummarySchema,
......@@ -32,3 +33,35 @@ export class AiInvocationListQueryDto extends createZodDto(AiInvocationListQuery
export class AiInvocationDetailDto extends createZodDto(AiInvocationDetailSchema) {}
export class AiInvocationStatsDto extends createZodDto(AiInvocationStatsSchema) {}
export class ListAiInvocationsResponseDto extends createZodDto(ListAiInvocationsResponseSchema) {}
// Cold-import 网页上传(host-self)
const ColdImportUploadResponseSchema = z.object({ jobId: z.string() });
export class ColdImportUploadResponseDto extends createZodDto(ColdImportUploadResponseSchema) {}
// 进度:BullMQ job 状态 + 完成时的 ImportRunResult(含 totals);job 已清理/不存在 → state='not_found'
const ColdImportStatusSchema = z.object({
state: z.string(),
result: z.any().nullable(),
failedReason: z.string().nullable(),
// 运行中的真实进度(cohortDone/cohortTotal 批次);非运行态或 dryRun 为 null
progress: z.object({ done: z.number(), total: z.number() }).nullable(),
});
export class ColdImportStatusDto extends createZodDto(ColdImportStatusSchema) {}
/// 宿主推送记录(sync_logs direction=push 的对宿主视图)—— 对接期自助排查:
/// 哪一批、什么时候、收了几行、落了几条、去重几条、失败几条、错在哪。
const PushLogSchema = z.object({
id: z.string(),
source: z.string().describe('推送的源表名'),
status: z.string().describe('success / partial / failed'),
dryRun: z.boolean().describe('true = 预检批次(未落库)'),
fetched: z.number().int().describe('收到的行数'),
transactionsWritten: z.number().int().describe('实际落库事件数(与 fetched 的差 = 被 PAC 规则过滤)'),
duplicates: z.number().int().describe('幂等命中数(重推安全的证据)'),
failed: z.number().int(),
errorMessage: z.string().nullable(),
startedAt: z.string(),
endedAt: z.string().nullable(),
});
const PushLogsSchema = z.object({ items: z.array(PushLogSchema) });
export class PushLogsDto extends createZodDto(PushLogsSchema) {}
apps/pac-service/src/modules/admin/host-self.controller.ts
......@@ -6,19 +6,28 @@ import {
Param,
Patch,
Post,
Query,
UploadedFile,
UseInterceptors,
} from '@nestjs/common';
import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
import { FileInterceptor } from '@nestjs/platform-express';
import { ApiBearerAuth, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger';
import { ZodResponse } from 'nestjs-zod';
import { Permission } from '@pac/types';
import { ApiCode, Permission } from '@pac/types';
import { RequirePermission } from '../../common/decorators/permissions.decorator';
import { CurrentUser, AuthenticatedUser } from '../../common/decorators/current-user.decorator';
import { BizError } from '../../common/errors/biz-error';
import {
TenantScope,
TenantScopeContext,
} from '../../common/decorators/tenant-scope.decorator';
import {
ColdImportStatusDto,
ColdImportUploadResponseDto,
HostDetailDto,
HostStatsDto,
HostSummaryDto,
PushLogsDto,
RemovePushSecretResponseDto,
RotateCallbackSecretResponseDto,
RotatePushSecretResponseDto,
......@@ -26,6 +35,16 @@ import {
UpdateHostRequestDto,
} from './dto/admin.dto';
import { HostsService } from './hosts.service';
import { ImportUploadService } from './import-upload.service';
/// multer 内存模式的最小文件形状(不引 @types/multer,同 assistant.controller)
interface UploadedZip {
buffer: Buffer;
originalname: string;
mimetype: string;
}
/// 上传大小上限:存量分批包压缩后通常几十 MB;留 500MB 余量
const MAX_IMPORT_ZIP_BYTES = 500 * 1024 * 1024;
/**
* Host Self Admin — 宿主自己的 admin 用户管理"自己这个 host"的配置页。
......@@ -42,7 +61,10 @@ import { HostsService } from './hosts.service';
@Controller('admin/host/self')
@RequirePermission(Permission.PLATFORM_MANAGE)
export class HostSelfAdminController {
constructor(private readonly hosts: HostsService) {}
constructor(
private readonly hosts: HostsService,
private readonly importUpload: ImportUploadService,
) {}
@Get()
@ZodResponse({ status: 200, type: HostDetailDto })
......@@ -58,6 +80,20 @@ export class HostSelfAdminController {
return this.hosts.getStats(scope.hostId);
}
@Get('push-logs')
@ZodResponse({ status: 200, type: PushLogsDto })
@ApiOperation({
summary: '当前宿主的推送记录(对接自助排查)',
description:
'按时间倒序列最近 N 批 push(默认 50,上限 200)。每批含 source / 收行数 / 落库数 / ' +
'去重数 / 失败数 / 报错原因;dryRun=true 的是 ?dryRun=1 预检批次。' +
'用途:当时的同步响应没留存也能事后查——对接期定位"哪批错了、错在哪"。',
})
getPushLogs(@TenantScope() scope: TenantScopeContext, @Query('limit') limit?: string) {
const n = Number.parseInt(limit ?? '', 10);
return this.hosts.getPushLogs(scope.hostId, Number.isFinite(n) && n > 0 ? n : 50);
}
@Patch()
@ZodResponse({ status: 200, type: HostSummaryDto })
@ApiOperation({
......@@ -125,4 +161,38 @@ export class HostSelfAdminController {
) {
return this.hosts.removeCallbackSecretBySuffix(scope.hostId, suffix);
}
// ─── 数据导入(上传压缩包 → 后台 cold-import,方向:宿主 → PAC)───
@Post('cold-import')
@ApiConsumes('multipart/form-data')
@UseInterceptors(
FileInterceptor('file', { limits: { fileSize: MAX_IMPORT_ZIP_BYTES } }),
)
@ZodResponse({ status: 202, type: ColdImportUploadResponseDto })
@ApiOperation({
summary: '上传数据压缩包触发整包 cold-import',
description:
'zip 内含 manifest.tables 声明的数据文件(CSV/JSON);manifest+assemblers 取自 PAC 代码库不接受上传。' +
'校验通过后落后台队列,返回 jobId 供轮询进度。',
})
async coldImport(
@TenantScope() scope: TenantScopeContext,
@CurrentUser() user: AuthenticatedUser,
@UploadedFile() file: UploadedZip | undefined,
@Body('dryRun') dryRun?: string,
) {
if (!file?.buffer?.length) {
throw new BizError(ApiCode.CLIENT_BAD_REQUEST, '未收到上传文件(字段名应为 file)');
}
// multipart 文本字段是字符串;'true' → dry-run 预检(不落库)
return this.importUpload.prepareAndEnqueue(scope, file.buffer, user.sub, dryRun === 'true');
}
@Get('cold-import/:jobId')
@ZodResponse({ status: 200, type: ColdImportStatusDto })
@ApiOperation({ summary: '查询一次 cold-import 进度(前端轮询,含运行中百分比)' })
async coldImportStatus(@Param('jobId') jobId: string) {
return this.importUpload.getProgress(jobId);
}
}
apps/pac-service/src/modules/admin/hosts.service.ts
......@@ -17,6 +17,7 @@ import type {
PullConfig,
ActionUrlsConfig,
} from '@pac/types';
import { SyncDirection } from '@pac/types';
import { PrismaService } from '../../prisma/prisma.service';
/**
......@@ -300,6 +301,37 @@ export class HostsService {
};
}
/**
* 宿主推送记录(自助排查)—— 列最近 N 批 push 的结果。
*
* 对接期宿主开发最需要的"事后可查":当时的同步响应若没打进日志,这里仍能看到
* 每批 source / 收行数 / 落库数 / 去重 / 失败 / 报错原因。`?dryRun=1` 的预检批次
* 由 triggeredBy 前缀 `push-dryrun:` 标识,单独打标,不与正式推送混淆。
*/
async getPushLogs(hostId: string, limit = 50) {
const take = Math.min(Math.max(limit, 1), 200);
const rows = await this.prisma.syncLog.findMany({
where: { hostId, direction: SyncDirection.PUSH },
orderBy: { startedAt: 'desc' },
take,
});
return {
items: rows.map((r) => ({
id: r.id,
source: r.resource,
status: r.status,
dryRun: (r.triggeredBy ?? '').startsWith('push-dryrun:'),
fetched: r.fetched ?? 0,
transactionsWritten: r.transactionsWritten ?? 0,
duplicates: r.duplicates ?? 0,
failed: r.failed ?? 0,
errorMessage: r.errorMessage,
startedAt: r.startedAt.toISOString(),
endedAt: r.endedAt?.toISOString() ?? null,
})),
};
}
// ─────────────────────────────────────────────────────────
// Remove push secret(按 suffix 定位,精确移除某个 grace key)
// ─────────────────────────────────────────────────────────
......
apps/pac-service/src/modules/admin/import-upload.service.ts 0 → 100644
import { Injectable, Logger } from '@nestjs/common';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { randomUUID } from 'node:crypto';
import * as yaml from 'js-yaml';
import * as yauzl from 'yauzl';
import { ApiCode } from '@pac/types';
import { BizError } from '../../common/errors/biz-error';
import { PrismaService } from '../../prisma/prisma.service';
import { QueueProducer } from '../../queues/queue-producer.service';
/**
* ImportUploadService — 网页上传压缩包 → 触发 cold-import 的编排层。
*
* 安全核心:manifest.yaml + assemblers/ **永远取自 PAC 代码库** `data/<host>/`,不接受上传。
* importDirectory 从 manifest 的 host_name 决定写哪个 host,若让上传者带 manifest 即可篡改
* 写入目标。故:
* - 按 scope.hostId 反查 host.name → 只认代码库 data/<name>/ 那份 manifest+assemblers
* - 从 zip 里**仅白名单提取** manifest.tables[].file 声明的文件名(basename 匹配,
* 落 join(tmpDir, basename) → 天然挡 zip-slip 路径穿越)
* - manifest.host_name 天然 == 反查的 name → 不可能写到别的 host
*
* 长任务不在 HTTP 里同步跑:落盘就绪后 enqueue cold-import 队列,返回 jobId 供前端轮询。
*/
@Injectable()
export class ImportUploadService {
private readonly logger = new Logger(ImportUploadService.name);
constructor(
private readonly prisma: PrismaService,
private readonly queue: QueueProducer,
) {}
/** 代码库 host 数据根(与 ColdImportService.resolveHostDir 同约定)。 */
private dataRoot(): string {
return process.env.PAC_INCREMENTAL_DATA_DIR ?? path.resolve(process.cwd(), 'data');
}
/** 临时解压工作根;跑完由 processor 清理。 */
private workRoot(): string {
return process.env.PAC_IMPORT_WORK_DIR ?? path.join(this.dataRoot(), '.imports');
}
/**
* 校验 + 落盘 + 入队。返回前端轮询用的 jobId。
* @param scope 调用者(宿主)scope,来自 token
* @param zipBuffer 上传的 zip 内容(multer memoryStorage buffer)
* @param userId 触发人(进 triggeredBy)
*/
async prepareAndEnqueue(
scope: { hostId: string; tenantId: string },
zipBuffer: Buffer,
userId: string,
dryRun = false,
): Promise<{ jobId: string }> {
// 上传内容先落盘成临时 zip(yauzl 从文件流式解压);finally 删除
await fs.promises.mkdir(this.workRoot(), { recursive: true });
const zipPath = path.join(this.workRoot(), `upload-${randomUUID()}.zip`);
await fs.promises.writeFile(zipPath, zipBuffer);
try {
const host = await this.prisma.host.findUnique({ where: { id: scope.hostId } });
if (!host) {
throw new BizError(ApiCode.CLIENT_BAD_REQUEST, `host 不存在: ${scope.hostId}`);
}
// 1. 代码库 data/<name>/ 必须已配置 manifest(否则该 host 不支持文件导入)
const srcDir = path.join(this.dataRoot(), host.name);
const manifestPath = path.join(srcDir, 'manifest.yaml');
if (!fs.existsSync(manifestPath)) {
throw new BizError(
ApiCode.CLIENT_BAD_REQUEST,
`该宿主未配置文件导入(缺 data/${host.name}/manifest.yaml)`,
);
}
// 2. 白名单 = manifest.tables[].file(都是根级 basename,如 customer_basic_info.csv)
const manifest = yaml.load(fs.readFileSync(manifestPath, 'utf-8')) as {
tables?: Array<{ file?: string; group?: string }>;
};
const whitelist = new Set(
(manifest.tables ?? [])
.map((t) => t.file)
.filter((f): f is string => !!f)
.map((f) => path.basename(f)),
);
if (whitelist.size === 0) {
throw new BizError(
ApiCode.CLIENT_BAD_REQUEST,
`manifest.tables 为空,无可导入文件声明`,
);
}
// 3. 临时目录做成"迷你 data 根"(与 data/ 同构):
// tmpRoot/<host>/ ← manifest + assemblers + 解压的数据文件
// tmpRoot/_shared/ ← 共享字典层副本
// assembler 的 dict_includes 用 ../../_shared/dict/ 相对引用(相对 assemblers/ 上两级),
// 必须保住这个相对位置,否则共享字典找不到(CLI dry-run 实测抓到)。
const tmpRoot = path.join(this.workRoot(), `import-${randomUUID()}`);
const runDir = path.join(tmpRoot, host.name);
await fs.promises.mkdir(runDir, { recursive: true });
await fs.promises.copyFile(manifestPath, path.join(runDir, 'manifest.yaml'));
const assemblersSrc = path.join(srcDir, 'assemblers');
if (fs.existsSync(assemblersSrc)) {
await fs.promises.cp(assemblersSrc, path.join(runDir, 'assemblers'), { recursive: true });
}
const sharedSrc = path.join(this.dataRoot(), '_shared');
if (fs.existsSync(sharedSrc)) {
await fs.promises.cp(sharedSrc, path.join(tmpRoot, '_shared'), { recursive: true });
}
// 4. 流式解压 —— 仅提取白名单 basename(挡 zip-slip)。
// yauzl 对损坏包 / 路径穿越条目会 fail-closed(整包拒绝)→ 转友好 400,不冒泡成 500。
let extracted: Set<string>;
try {
extracted = await extractWhitelisted(zipPath, runDir, whitelist);
} catch (err) {
await fs.promises.rm(tmpRoot, { recursive: true, force: true });
throw new BizError(
ApiCode.CLIENT_BAD_REQUEST,
`压缩包解析失败(可能损坏或含非法路径条目): ${err instanceof Error ? err.message : err}`,
);
}
// 5. 宽容 + 成组完整性校验(不再要求全表齐 —— PAC 各主体独立,装载层已宽容跳过):
// ① 非空:压缩包至少含一个可识别数据文件
// ② 成组:manifest 声明 group 的表,组内要么全在、要么整组不在;部分在 → 报错
// (半组产不出主体,如 treatment_plan 头+行缺一 → planned 产 0 行)
// ③ 独立表(无 group)缺失:放行,只少那部分 facts
if (extracted.size === 0) {
await fs.promises.rm(tmpRoot, { recursive: true, force: true });
throw new BizError(
ApiCode.CLIENT_BAD_REQUEST,
`压缩包不含任何可识别的数据文件(需匹配 manifest.tables 声明的文件名)`,
);
}
const incompleteGroups = findIncompleteGroups(manifest.tables ?? [], extracted);
if (incompleteGroups.length > 0) {
await fs.promises.rm(tmpRoot, { recursive: true, force: true });
throw new BizError(
ApiCode.CLIENT_VALIDATION_FAILED,
`成组主体不完整:${incompleteGroups
.map((g) => `"${g.group}" 缺 ${g.missing.join(',')}`)
.join(';')}(该组表须一起上传,或整组都不传)`,
{ incompleteGroups },
);
}
this.logger.log(
`import 就绪 host=${host.name} runDir=${runDir} 文件=${extracted.size}/${whitelist.size}` +
(extracted.size < whitelist.size
? `(缺 ${whitelist.size - extracted.size} 张独立表,宽容跳过)`
: ''),
);
// 6. 入队,返回 jobId。dir=runDir(跑),cleanupDir=tmpRoot(processor 跑完清整个迷你根)
const { jobId } = await this.queue.enqueueColdImport({
hostId: host.id,
tenantId: scope.tenantId,
hostName: host.name,
dir: runDir,
cleanupDir: tmpRoot,
dryRun,
triggeredBy: `upload:${userId}`,
});
return { jobId };
} finally {
// 上传的原始 zip 用完即删(已解压到 runDir);迷你根由 processor 跑完清理
await fs.promises.rm(zipPath, { force: true }).catch(() => undefined);
}
}
/**
* 查一次进度(前端轮询)。job active 时补查运行中的 sync_log.metadata.cohortDone/cohortTotal
* → 前端算真实百分比(importDirectory 每批实时写)。dryRun 不建 sync_log,只有 state。
*/
async getProgress(jobId: string): Promise<{
state: string;
result: unknown;
failedReason: string | null;
progress: { done: number; total: number } | null;
}> {
const job = await this.queue.getColdImportJob(jobId);
if (!job) return { state: 'not_found', result: null, failedReason: null, progress: null };
let progress: { done: number; total: number } | null = null;
if (job.state === 'active' && job.hostId) {
const log = await this.prisma.syncLog.findFirst({
where: { hostId: job.hostId, status: 'running' },
orderBy: { startedAt: 'desc' },
select: { metadata: true },
});
const m = log?.metadata as { cohortDone?: number; cohortTotal?: number } | null;
if (m?.cohortTotal) progress = { done: m.cohortDone ?? 0, total: m.cohortTotal };
}
return {
state: job.state,
result: job.returnValue,
failedReason: job.failedReason,
progress,
};
}
}
/**
* yauzl 流式解压,只提取 basename 命中白名单的条目。
* 只用 basename + join(destDir, ...) → 无法逃逸目标目录(zip-slip 防护)。
* 返回实际提取到的 basename 集合(供缺文件校验)。
* export 供单测(tests/cold-import-extract.spec.ts)。
*/
export function extractWhitelisted(
zipPath: string,
destDir: string,
whitelist: Set<string>,
): Promise<Set<string>> {
return new Promise((resolve, reject) => {
const extracted = new Set<string>();
yauzl.open(zipPath, { lazyEntries: true }, (err, zipfile) => {
if (err || !zipfile) return reject(err ?? new Error('无法打开压缩包'));
zipfile.on('error', reject);
zipfile.on('end', () => resolve(extracted));
zipfile.on('entry', (entry: YauzlEntry) => {
const base = path.basename(entry.fileName);
// 目录项 / 白名单外 → 跳过。
// (路径穿越 `../` 由 yauzl 自身 fail-closed 直接 emit error;此处 basename+join 是纵深防御)
if (entry.fileName.endsWith('/') || base.includes('..') || !whitelist.has(base)) {
return zipfile.readEntry();
}
zipfile.openReadStream(entry, (e, readStream) => {
if (e || !readStream) return reject(e ?? new Error('读取压缩条目失败'));
const ws = fs.createWriteStream(path.join(destDir, base));
readStream.on('error', reject);
ws.on('error', reject);
ws.on('close', () => {
extracted.add(base);
zipfile.readEntry();
});
readStream.pipe(ws);
});
});
zipfile.readEntry();
});
});
}
/**
* 成组完整性校验(通用,读宿主 manifest 的 group 声明):
* 返回"部分在但不全"的组(半组产不出主体 → 上传应拒)。组内全在或整组都不在 → 不返回(放行)。
* export 供单测(tests/cold-import-groups.spec.ts)。
*/
export function findIncompleteGroups(
tables: Array<{ file?: string; group?: string }>,
extracted: Set<string>,
): Array<{ group: string; present: string[]; missing: string[] }> {
const groups = new Map<string, string[]>(); // group → [basename...]
for (const t of tables) {
if (t.group && t.file) {
const arr = groups.get(t.group) ?? [];
arr.push(path.basename(t.file));
groups.set(t.group, arr);
}
}
return [...groups.entries()]
.map(([group, members]) => ({
group,
present: members.filter((f) => extracted.has(f)),
missing: members.filter((f) => !extracted.has(f)),
}))
.filter((g) => g.present.length > 0 && g.missing.length > 0);
}
// ── yauzl 最小类型(遵循仓库"不引 @types"的先例,如 assistant.controller UploadedAudio)──
interface YauzlEntry {
fileName: string;
}
apps/pac-service/src/modules/sync/cold-import/clickhouse-source.service.ts
......@@ -134,6 +134,35 @@ export class ClickHouseSourceService {
/// 用途:增量 fetched=0 时分辨「DW 真没新数据(静默)」vs「查询条件失效在空转(告警)」
/// —— 2026-06-10 游标 ISO 格式 bug 让增量空转三天才被人工发现,此探针让它当天就暴露。
/// 探针绝不能影响同步主流程:任何异常吞掉返回 {}。
/**
* 对账用:把资源查询原样包一层,统计**去重患者数**(patient_id + brand 元组 —— 集团内
* 同 patient_id 跨品牌是两个人,必须带 brand)。复用摄入查询本身 → 筛选口径零重复维护。
* 失败返回 null(对账降级,不阻断日报)。查询超时放宽到 120s(大表 count distinct)。
*/
async countDistinctPatients(source: ClickHouseSource, innerSql: string): Promise<number | null> {
let client: ReturnType<typeof createClient> | null = null;
try {
const conn = this.resolveConnection(source);
client = createClient({
url: conn.url,
database: conn.database,
username: conn.username,
password: conn.password,
request_timeout: 120_000,
compression: { response: true, request: false },
});
const q = `SELECT uniqExact(patient_id, brand) AS c FROM (\n${innerSql}\n)`;
const rs = await client.query({ query: q, format: 'JSONEachRow' });
const rows = (await rs.json()) as Array<{ c: string | number }>;
return Number(rows[0]?.c ?? 0);
} catch (e) {
this.logger.warn(`[reconcile] countDistinctPatients 失败: ${e instanceof Error ? e.message : String(e)}`);
return null;
} finally {
if (client) await client.close();
}
}
async probeNewRowCounts(
source: ClickHouseSource,
perQuery: IncrementalConfig['perQuery'],
......
apps/pac-service/src/modules/sync/cold-import/cold-import.service.ts
......@@ -286,6 +286,9 @@ export class ColdImportService {
source: string; // 原生源表名(= manifest tables[].table / transform 终端表)
rows: Record<string, unknown>[];
triggeredBy?: string;
/// 预检:跑完整管线(transforms + 装配 + 归一 + tenant 解析)但**不落任何库**,
/// 用于宿主对接自测——看 accepted/失败数与样本 canonical,确认 PAC 理解对了再正式推。
dryRun?: boolean;
}): Promise<{
syncLogId: string;
perResource: PerResourceStats[];
......@@ -333,7 +336,9 @@ export class ColdImportService {
tenantId: 't_pending', // push 多 tenant 由行决定;finalize 时回填首个 seen tenant
direction: SyncDirection.PUSH,
resource: opts.source,
triggeredBy: opts.triggeredBy ?? `push:${opts.hostName}:${opts.source}`,
triggeredBy:
opts.triggeredBy ??
`${opts.dryRun ? 'push-dryrun' : 'push'}:${opts.hostName}:${opts.source}`,
status: SyncStatus.RUNNING,
},
});
......@@ -362,19 +367,19 @@ export class ColdImportService {
if (cfg.canonical === 'patient') {
perResource.push(
await this.processPatients(
transformed, cfg, host.id, tenantResolver, seenTenants, normalize, false, true,
transformed, cfg, host.id, tenantResolver, seenTenants, normalize, !!opts.dryRun, true,
),
);
} else if (cfg.canonical === 'patient_relation') {
perResource.push(
await this.processPatientRelations(
transformed, cfg, host.id, tenantResolver, normalize, false,
transformed, cfg, host.id, tenantResolver, normalize, !!opts.dryRun,
),
);
} else if (cfg.canonical === 'patient_return_visit') {
perResource.push(
await this.processPatientReturnVisits(
transformed, cfg, host.id, tenantResolver, normalize, false,
transformed, cfg, host.id, tenantResolver, normalize, !!opts.dryRun,
),
);
}
......@@ -388,7 +393,7 @@ export class ColdImportService {
seenTenants,
normalize,
syncLog.id,
false,
!!opts.dryRun,
);
perResource.push(stats);
}
......@@ -570,6 +575,37 @@ export class ColdImportService {
}
/**
* 数据对账 —— DW 源侧「去重患者数」(设计见 /docs/data-reconciliation)。
*
* 复用摄入用的 sql_source 查询本身(同一道筛选闸)→ diff 只剩真漂移,零重复维护。
* 只算 DW 侧;PAC 侧计数 + diff + 渲染由调用方(日报)做(它持 prisma + 按 fact_type)。
*
* @param queryKeys 要对账的 sql_source.queries key(如 fact_emr_treatment_out / image_finding_rows)
* @returns { queryKey: 去重患者数 | null(查失败) };无 sql_source(file/push 宿主)→ 空 {}
*/
async reconcileDwPatientCounts(
hostName: string,
queryKeys: string[],
): Promise<Record<string, number | null>> {
const out: Record<string, number | null> = {};
let manifest: ColdImportManifest;
try {
manifest = this.readManifest(this.resolveHostDir(hostName));
} catch (e) {
this.logger.warn(`[reconcile] 读 manifest 失败 host=${hostName}: ${e instanceof Error ? e.message : String(e)}`);
return out;
}
const source = manifest.sql_source;
if (!source) return out; // file/push 宿主无直连源,不对账
for (const key of queryKeys) {
const sql = source.queries[key];
if (!sql) { out[key] = null; continue; }
out[key] = await this.chSource.countDistinctPatients(source, sql);
}
return out;
}
/**
* raw 层列漂移检测(form A):本次推送行的列集 vs 历史同源 rawPayload 的列集。
* - 历史有、本次没有 → column_removed(疑似宿主删列/改名)
* - 本次有、历史没有 → column_added(疑似宿主加列/改名)
......@@ -596,10 +632,25 @@ export class ColdImportService {
orderBy: { createdAt: 'desc' },
});
if (sample.length < MIN_BASELINE) return [];
const baseline = new Set<string>();
for (const s of sample) {
// 同 subjectType 可能混多源(如 refund = 结算头 patient_settlement ∪ 结算明细
// patient_settlement_spec,列集不同)。按「与本批列签名的 Jaccard 相似度」自选**同源**样本,
// 否则另一源的专属列会被误报成"本源删列"(suspectFields 虚警)。跨源如 settlement/spec 交并比
// 仅 ~0.35,≥0.5 阈值可干净分离;同源 ≈1.0。
const pushed = args.pushedCols;
const sameSource = sample.filter((s) => {
const rp = s.rawPayload as Record<string, unknown> | null;
if (rp) for (const k of Object.keys(rp)) if (!k.startsWith('_')) baseline.add(k);
if (!rp) return false;
const cols = Object.keys(rp).filter((k) => !k.startsWith('_'));
if (cols.length === 0) return false;
const inter = cols.filter((c) => pushed.has(c)).length;
const union = new Set([...cols, ...pushed]).size;
return union > 0 && inter / union >= 0.5;
});
if (sameSource.length < MIN_BASELINE) return []; // 同源基线不足 → 不可靠,宁可不报
const baseline = new Set<string>();
for (const s of sameSource) {
const rp = s.rawPayload as Record<string, unknown>;
for (const k of Object.keys(rp)) if (!k.startsWith('_')) baseline.add(k);
}
const out: SuspectField[] = [];
......@@ -2150,16 +2201,28 @@ export class ColdImportService {
'manifest 缺数据源:既无 sql_source 也无 tables[](schema refine 本该拦住,兜底报错)',
);
}
// 宽容装载:声明表文件缺失 → warn + 跳过(不 throw)。
// PAC 各主体 assembler 独立:缺某表只少那部分 facts。下游已宽容——
// transform lookup/from 缺表当空表、project input 缺表跳过、assembler primary.table
// 缺表产 0 行。成组主体的完整性由上传层(ImportUploadService)按 manifest group 声明前置守卫,
// 不在此处判(此处也服务 CLI 全量导入,不宜硬拦)。
const tables: Record<string, unknown[]> = {};
const skipped: string[] = [];
for (const t of manifest.tables) {
const filePath = path.join(dir, t.file);
if (!fs.existsSync(filePath)) {
throw new Error(`Raw table file not found: ${filePath}`);
skipped.push(t.table);
continue;
}
const format = t.format ?? inferFileFormat(t.file);
tables[t.table] = this.readRows(filePath, format);
this.logger.log(` loaded raw table "${t.table}" (${tables[t.table]!.length} rows)`);
}
if (skipped.length > 0) {
this.logger.warn(
` ${skipped.length} 张声明表文件缺失,已跳过(依赖它们的 assembler/transform 将当空表处理): ${skipped.join(', ')}`,
);
}
return tables;
}
......@@ -2262,24 +2325,46 @@ interface TotalsBlock {
/// 沿 transforms 的 output→input 链回溯,找到非任何 transform 产出的"原始源表"名。
/// 例:diagnosis_rows ← _diagnosis_norm ← _diagnosis_raw ← fact_emr_treatment_out(终点=源表)。
/// 用于 reparse:transaction.rawPayload 存的就是这张源表的行。
function traceRawSourceTable(primaryTable: string, transforms: ReadonlyArray<unknown>): string {
const byOutput = new Map<string, string>(); // output 表名 → input 表名
/// 用于 reparse(rawPayload 存的就是这张源表的行)+ push(source→匹配 assembler)。
///
/// union 多输入:各输入独立回溯,**全部收敛到同一根表**才返回该根(如 refund_full_rows
/// ← union[_refund_status4, _refund_neg3] 两路都回到 patient_settlement → 返回它);
/// 若发散到多个根(语义歧义)→ 停在 union 输出本身(维持旧行为,不误判)。
/// 修复前 union 不被追 → refund_full 在 push/reparse 里回溯不到源表被静默跳过(丢财务数据)。
export function traceRawSourceTable(primaryTable: string, transforms: ReadonlyArray<unknown>): string {
const byOutput = new Map<string, string>(); // output → input(单输入算子)
const unionInputs = new Map<string, string[]>(); // union output → inputs[]
for (const tf of transforms) {
const t = tf as { input?: string; output?: string; outputs?: Array<{ output?: string }> };
const t = tf as {
kind?: string;
input?: string;
output?: string;
inputs?: string[];
outputs?: Array<{ output?: string }>;
};
if (t.kind === 'union' && t.output && Array.isArray(t.inputs)) {
unionInputs.set(t.output, t.inputs);
continue;
}
if (t.output && t.input) byOutput.set(t.output, t.input);
// route_by_pattern 多 output:每个 output 都回到同一 input
if (Array.isArray(t.outputs) && t.input) {
for (const o of t.outputs) if (o?.output) byOutput.set(o.output, t.input);
}
}
let cur = primaryTable;
const seen = new Set<string>();
while (byOutput.has(cur) && !seen.has(cur)) {
seen.add(cur);
cur = byOutput.get(cur)!;
}
return cur;
const resolve = (tbl: string, seen: Set<string>): string => {
if (seen.has(tbl)) return tbl; // 环保护
seen.add(tbl);
if (byOutput.has(tbl)) return resolve(byOutput.get(tbl)!, seen);
const ins = unionInputs.get(tbl);
if (ins && ins.length > 0) {
// 各输入独立回溯(各带 seen 副本,兄弟分支互不干扰);全一致才收敛,否则停在 union 输出
const roots = new Set(ins.map((i) => resolve(i, new Set(seen))));
return roots.size === 1 ? [...roots][0]! : tbl;
}
return tbl; // 已是根
};
return resolve(primaryTable, new Set<string>());
}
export interface PerResourceStats extends TotalsBlock {
......
apps/pac-service/src/modules/sync/cold-import/manifest.schema.ts
......@@ -26,6 +26,12 @@ export const RawTableSchema = z.object({
file: z.string().min(1).describe('e.g. tb_encounter.csv / tb_patient.json'),
/// 文件格式(默认按扩展名推断)
format: z.enum(['csv', 'json']).optional(),
/// 成组主体标签(宿主特有,可选)。同 group 的表在**网页上传**时要么全在、要么整组跳过
/// —— 由 ImportUploadService 通用地读此声明做完整性校验。用于"半组产不出主体"的强依赖
/// (如 treatment_planned = customer_treat_plan[头] + _item[行],缺任一整个资源产 0 行)。
/// 不标 = 独立表:缺失仅少那部分 facts(装载层已宽容跳过)。
/// 注:CLI 全量导入不受此约束(只 warn 跳过);仅上传路径按 group 前置守卫。
group: z.string().min(1).optional(),
});
export type RawTable = z.infer<typeof RawTableSchema>;
......
apps/pac-service/src/modules/sync/push/push-receiver.service.ts
......@@ -49,14 +49,18 @@ export class PushReceiverService {
hostName: string;
source: string;
rows: Record<string, unknown>[];
/// 预检(?dryRun=1):跑完整管线但不落库,也不触发重算。宿主对接自测用。
dryRun?: boolean;
}): Promise<PushRowsResponse> {
const { hostId, hostName, source, rows } = input;
const dryRun = !!input.dryRun;
const r = await this.coldImport.ingestRawTables({
hostName,
source,
rows,
triggeredBy: `push:${hostName}:${source}`,
dryRun,
triggeredBy: `${dryRun ? 'push-dryrun' : 'push'}:${hostName}:${source}`,
});
const agg = r.perResource.reduce(
......@@ -81,8 +85,9 @@ export class PushReceiverService {
// 事件驱动:touched 患者入队 persona-recompute(去抖:存量批次重放时窗内合并,见 QueueProducer)
// ⚠️ plan 不在此触发(persona 完成后链式 enqueue),与单患者刷新路径有意区分。
// 预检不产生任何副作用 → 不入队(touched 本就为空,此处显式短路,语义更清楚)。
let personaEnqueued = 0;
for (const { patientId, tenantId } of r.touched) {
for (const { patientId, tenantId } of dryRun ? [] : r.touched) {
try {
await this.queue.enqueuePersonaRecompute(
{ hostId, tenantId, patientId, triggeredBy: `push:${hostName}` },
......@@ -101,6 +106,13 @@ export class PushReceiverService {
`txn=${agg.txn} dup=${agg.dup} failed=${agg.failed} personaEnqueued=${personaEnqueued}`,
);
// 预检:回样本 canonical(各资源首行),供宿主核对 PAC 把原生行翻译成了什么
const samples = dryRun
? r.perResource
.filter((s) => (s.sampleCanonical?.length ?? 0) > 0)
.map((s) => ({ resource: s.resource, canonical: s.sampleCanonical[0] }))
: [];
return {
syncLogId: r.syncLogId,
source,
......@@ -111,6 +123,8 @@ export class PushReceiverService {
personaEnqueued,
mappingMisses: r.mappingMisses.length,
suspectFields: r.suspectFields.length,
dryRun,
samples,
};
}
......
apps/pac-service/src/modules/sync/push/push.controller.ts
import {
Body,
Controller,
Get,
Headers,
HttpCode,
Post,
Query,
Req,
} from '@nestjs/common';
import type { Request } from 'express';
import { ApiOperation, ApiTags } from '@nestjs/swagger';
import { ApiOperation, ApiQuery, ApiTags } from '@nestjs/swagger';
import { ApiCode } from '@pac/types';
import { BizError } from '../../../common/errors/biz-error';
import { Public } from '../../../common/decorators/public.decorator';
import { HmacVerifier } from './hmac-verifier.service';
import { PushReceiverService } from './push-receiver.service';
import { HostsService } from '../../admin/hosts.service';
import {
PushEventsRequestSchema,
type PushEventsRequest,
......@@ -44,6 +47,7 @@ export class PushController {
constructor(
private readonly verifier: HmacVerifier,
private readonly receiver: PushReceiverService,
private readonly hosts: HostsService,
) {}
/**
......@@ -137,14 +141,23 @@ export class PushController {
@Public()
@HttpCode(200)
@ApiOperation({
summary: '宿主推送原生表行 webhook(形态 A,HMAC 验签)',
description: 'Headers 必填 X-PAC-Host-Id / X-PAC-Timestamp / X-PAC-Signature。Body: { tenantId?, source, rows[] }。',
summary: '宿主推送原生表行 webhook(形态 A,HMAC 验签;?dryRun=1 预检不落库)',
description:
'Headers 必填 X-PAC-Host-Id / X-PAC-Timestamp / X-PAC-Signature。Body: { source, rows[] }。' +
' 加 ?dryRun=1 走**预检**:跑完整管线(transforms+装配+归一)但不落库、不触发重算,' +
'响应带各资源样本 canonical —— 对接自测先预检到 failed=0 且 mappingMisses/suspectFields 为 0,再正式推。',
})
@ApiQuery({
name: 'dryRun',
required: false,
description: "预检开关:'1' / 'true' / 'yes' = 跑完整管线但不落库、不触发重算,响应带样本 canonical",
})
async receiveRows(
@Req() req: Request & { rawBody?: Buffer },
@Headers('x-pac-host-id') hostIdHeader: string | undefined,
@Headers('x-pac-timestamp') timestampHeader: string | undefined,
@Headers('x-pac-signature') signatureHeader: string | undefined,
@Query('dryRun') dryRunQuery: string | undefined,
@Body() body: PushRowsRequest,
) {
const rawBody = req.rawBody ? req.rawBody.toString('utf8') : JSON.stringify(body);
......@@ -158,13 +171,53 @@ export class PushController {
const parsed = this.parseOrReject(() => PushRowsRequestSchema.parse(body));
// ?dryRun=1 / true / yes 均视为预检(宿主客户端拼 query 习惯不一)
const dryRun = ['1', 'true', 'yes'].includes((dryRunQuery ?? '').trim().toLowerCase());
return this.withHostLock(hostId, hostName, () =>
this.receiver.receiveRows({
hostId,
hostName,
source: parsed.source,
rows: parsed.rows,
dryRun,
}),
);
}
/**
* 推送记录查询 —— **用已有 push 凭据验签,无需另外登录**(对接自测友好)。
*
* 与登录态的 `GET /admin/host/self/push-logs` 返回同一份数据(同一实现),区别只在鉴权方式:
* 这里复用宿主推送时已经在用的 HMAC 三件套,故不必为联调再开账号;
* 也**不是公开接口** —— 没有正确签名拿不到任何数据,不会泄露宿主推送情况。
*
* GET 无 body,签名对**空串**计算:`hex(HMAC-SHA256(`${timestamp}.`, secret))`。
*/
@Get('logs')
@Public()
@HttpCode(200)
@ApiOperation({
summary: '查询本宿主推送记录(HMAC 验签,免登录)',
description:
'Headers 同 push:X-PAC-Host-Id / X-PAC-Timestamp / X-PAC-Signature。' +
'GET 无 body,签名对空串算:hex(HMAC-SHA256(`<timestamp>.`, secret))。' +
'返回最近 N 批(默认 50、上限 200):source / status / dryRun / 收行数 / 落库数 / 去重 / 失败 / 报错。',
})
@ApiQuery({ name: 'limit', required: false, description: '返回条数,默认 50、上限 200' })
async logs(
@Headers('x-pac-host-id') hostIdHeader: string | undefined,
@Headers('x-pac-timestamp') timestampHeader: string | undefined,
@Headers('x-pac-signature') signatureHeader: string | undefined,
@Query('limit') limit?: string,
) {
const { hostId } = await this.verifier.verify({
hostIdHeader,
timestampHeader,
signatureHeader,
rawBody: '', // GET 无 body
});
const n = Number.parseInt(limit ?? '', 10);
return this.hosts.getPushLogs(hostId, Number.isFinite(n) && n > 0 ? n : 50);
}
}
apps/pac-service/src/modules/sync/push/push.schema.ts
......@@ -87,9 +87,15 @@ export const PushRowsResponseSchema = z.object({
duplicates: z.number().int(),
failed: z.number().int(),
personaEnqueued: z.number().int().describe('入队画像重算的患者数(plan 不在此触发,由定时任务保)'),
/// 宿主自检信号(代替 cold-import 的 dry-run):样本批推完看这两个数,>0 先停下联系 PAC。
/// 宿主自检信号:样本批推完看这两个数,>0 先停下联系 PAC。
mappingMisses: z.number().int().describe('映射覆盖缺口种类数(有原值落 _default)'),
suspectFields: z.number().int().describe('疑似宿主改表项数(列缺席/新增,vs 历史基线)'),
/// 预检模式(?dryRun=1):跑完整管线(transforms+装配+归一+tenant 解析)但**不落任何库**,
/// 数字表示"若正式推会发生什么"。对接自测用:先预检到 failed=0 且两个自检信号为 0,再正式推。
dryRun: z.boolean().describe('true = 本次为预检,未落库'),
samples: z
.array(z.object({ resource: z.string(), canonical: z.unknown() }))
.describe('预检样本:各 canonical 资源首行的翻译结果(仅 dryRun 返回,供宿主核对 PAC 是否理解正确)'),
});
export type PushRowsResponse = z.infer<typeof PushRowsResponseSchema>;
apps/pac-service/src/modules/sync/sync.module.ts
......@@ -32,8 +32,11 @@ import { HmacVerifier } from './push/hmac-verifier.service';
* - AssemblerModule(raw → canonical;真实 HTTP adapter 才需要;mock/push 跳过)
* - PipelineModule(synthesizer + parser pipeline)
*/
import { AdminModule } from '../admin/admin.module';
@Module({
imports: [
AdminModule, // push/logs 复用 HostsService.getPushLogs(与登录态自助页同一实现)
FactsModule,
AssemblerModule,
TransformsModule,
......
apps/pac-service/src/modules/sync/transforms/operators/filter.op.ts
......@@ -10,6 +10,7 @@ import { isEmptyText, type Row } from '../row';
* - not_empty: true — 字段非 null/undefined/空字符串
* - in: [...] — 字段值在列表中
* - equals: x — 字段值等于 x
* - lt/lte/gt/gte: n — 数值比较(字段解析为数字;非数值/空 → 不通过)
*/
export function runFilter(op: FilterOp, rows: Row[]): { rows: Row[]; dropped: number } {
const out: Row[] = [];
......@@ -127,7 +128,26 @@ function passAll(row: Row, where: Record<string, WhereRule>): boolean {
if (!set.has(String(v))) return false;
} else if ('equals' in rule) {
if (String(v) !== String(rule.equals)) return false;
} else if ('lt' in rule) {
const n = toNumber(v);
if (n === null || n >= rule.lt) return false;
} else if ('lte' in rule) {
const n = toNumber(v);
if (n === null || n > rule.lte) return false;
} else if ('gt' in rule) {
const n = toNumber(v);
if (n === null || n <= rule.gt) return false;
} else if ('gte' in rule) {
const n = toNumber(v);
if (n === null || n < rule.gte) return false;
}
}
return true;
}
/// 数值解析:空/非数字 → null(数值比较一律不通过)。CSV 字段是字符串,金额如 "-30.00"。
function toNumber(v: unknown): number | null {
if (v === null || v === undefined || (typeof v === 'string' && v.trim() === '')) return null;
const n = Number(v);
return Number.isFinite(n) ? n : null;
}
apps/pac-service/src/modules/sync/transforms/transforms.schema.ts
......@@ -69,6 +69,8 @@ export type ProjectOp = z.infer<typeof ProjectOpSchema>;
* - `not_empty: true` — 字符串非空 / null 过滤
* - `in: [...]` — 值在列表中
* - `equals: x` — 值等于 x
* - `lt/lte/gt/gte: n` — 数值比较(字段解析为数字;非数值/空 → 不通过)。
* 让退费正负切分等"业务口径 WHERE"能在 PAC 侧做(宿主导原表,PAC transforms 过滤)。
*/
export const WhereRuleSchema = z.union([
z.object({ not_empty: z.literal(true) }),
......@@ -82,6 +84,11 @@ export const WhereRuleSchema = z.union([
z.object({ real_no_tooth: z.array(z.union([z.string(), z.number()])).min(1) }),
z.object({ in: z.array(z.union([z.string(), z.number()])).min(1) }),
z.object({ equals: z.union([z.string(), z.number()]) }),
// 数值比较:字段解析为数字后比较;非数值/空值一律不通过(退费 receivable_this < 0 等)。
z.object({ lt: z.number() }),
z.object({ lte: z.number() }),
z.object({ gt: z.number() }),
z.object({ gte: z.number() }),
]);
export type WhereRule = z.infer<typeof WhereRuleSchema>;
......
apps/pac-service/src/queues/daily-health-report.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { Cron } from '@nestjs/schedule';
import { Prisma } from '@prisma/client';
import { PrismaService } from '../prisma/prisma.service';
import { AlertService, type AlertLevel } from '../common/alerting/alert.service';
import { ColdImportService } from '../modules/sync/cold-import/cold-import.service';
/**
* 数据对账 scope —— DW 源(sql_source.queries key)↔ PAC 侧计数口径。
* 复用摄入查询做源计数(同闸),PAC 侧按对应 fact_type / 表数去重患者。设计见 /docs/data-reconciliation。
*/
type PacCountKind =
| { kind: 'patient' }
| { kind: 'fact'; types: string[] }
| { kind: 'return_visit' }
| { kind: 'image_ai' };
const RECONCILE_SCOPES: Array<{ label: string; dwKey: string; pac: PacCountKind }> = [
{ label: '总量', dwKey: 'fact_client_out', pac: { kind: 'patient' } },
{ label: '治疗病历', dwKey: 'fact_emr_treatment_out', pac: { kind: 'fact', types: ['encounter_record', 'emr_record', 'diagnosis_record', 'treatment_record', 'recommendation_record'] } },
{ label: '预约', dwKey: 'fact_appointment_out', pac: { kind: 'fact', types: ['appointment_record'] } },
{ label: '结算', dwKey: 'fact_settlement_out', pac: { kind: 'fact', types: ['payment_record'] } },
{ label: '影像', dwKey: 'image_finding_rows', pac: { kind: 'image_ai' } },
{ label: '咨询', dwKey: 'fact_consult_out', pac: { kind: 'fact', types: ['consultation_record'] } },
{ label: '回访', dwKey: 'fact_returnvisit_out', pac: { kind: 'return_visit' } },
{ label: '转介', dwKey: 'fact_customer_referee_out', pac: { kind: 'fact', types: ['referral_record'] } },
];
/**
* DailyHealthReportService — 每日 09:00(沪)给企微推一份**简洁的线上健康日报**。
......@@ -21,6 +43,7 @@ export class DailyHealthReportService {
constructor(
private readonly prisma: PrismaService,
private readonly alerter: AlertService,
private readonly coldImport: ColdImportService,
) {}
@Cron(process.env.PAC_HEALTH_REPORT_CRON || '0 9 * * *', {
......@@ -68,6 +91,31 @@ export class DailyHealthReportService {
const lagHours = lastSync?.cursorAfter ? cursorLagHours(lastSync.cursorAfter, now) : null;
const lagTag = lagHours == null ? '⚪' : lagHours > errorH ? '🔴' : lagHours > warnH ? '🟡' : '🟢';
// ── 每轮增量明细(近 24h)──
// DW 现为 2h 刷新 → 每轮理应有数据;**空轮(fetched=0)大概率是异常**(DW 没刷 / 游标失效),
// 计入 warning。失败轮同样计入。逐轮列出让"每次 pull 的情况"一眼可见。
const rounds = await this.prisma.syncLog.findMany({
where: { resource: 'incremental_bundle', startedAt: { gte: since24h } },
orderBy: { startedAt: 'desc' },
select: {
startedAt: true, endedAt: true, status: true,
fetched: true, transactionsWritten: true, factsEmitted: true, duplicates: true, failed: true,
},
take: 20,
});
const roundEmpty = rounds.filter((r) => r.status === 'success' && r.fetched === 0).length;
const roundFailed = rounds.filter((r) => r.status !== 'success' && r.status !== 'running').length;
const roundLines = rounds.map((r) => {
const t = fmtClock(r.startedAt);
const mins = r.endedAt ? Math.round((+new Date(r.endedAt) - +new Date(r.startedAt)) / 60000) : null;
const dur = mins == null ? '' : mins >= 60 ? ` ${(mins / 60).toFixed(1)}h` : ` ${mins}m`;
if (r.status === 'running') return ` ${t} ⏳ 进行中`;
if (r.status !== 'success') return ` ${t} ❌ 失败${dur}`;
if (r.fetched === 0) return ` ${t} ⚠️ 空轮(0行)${dur}`;
return ` ${t} ✅ 拉${fmtNum(r.fetched)} tx${fmtNum(r.transactionsWritten)}/dup${fmtNum(r.duplicates)}/失${r.failed} f+${fmtNum(r.factsEmitted)}${dur}`;
});
const roundTag = roundFailed > 0 ? '🔴' : roundEmpty > 0 ? '🟡' : '🟢';
// ── 重算:画像 / 召回 最近一次 ──
const [lastPersona, lastPlanGen] = await Promise.all([
this.prisma.personaRecomputeLog.findFirst({ orderBy: { startedAt: 'desc' }, select: { startedAt: true, status: true } }),
......@@ -143,13 +191,23 @@ export class DailyHealthReportService {
if (fail7d > 0 && lastSync == null) level = 'critical';
if (lagHours != null && lagHours > warnH) level = 'warning';
if (lastPersona?.status === 'failed' || (lastPlanGen == null)) level = 'warning';
// DW 2h 刷新下,空轮/失败轮是异常信号
if (roundEmpty > 0) level = 'warning';
if (lagHours != null && lagHours > errorH) level = 'critical';
if (roundFailed > 0) level = 'critical';
// ── 数据对账(DW 源 vs PAC,去重患者数;设计见 /docs/data-reconciliation)──
// v1 观察模式:原样报 diff,不设基线、不驱动报告级别(diff 含已知差如瑞泰未全摄,
// 先看一两周摸清"正常差"再回填基线)。DW 不可达 → 该行降级 "—",不阻断日报。
const reconcileLines = await this.buildReconcile();
const dateStr = new Date(now).toLocaleDateString('zh-CN', { timeZone: 'Asia/Shanghai' }).replace(/\//g, '-');
const title = `每日健康报告 · ${dateStr}`;
const body = [
`📥 摄入 ${lagTag} 上次 ${fmtTime(lastSync?.startedAt)} · DW延迟 ${lagHours == null ? '—' : lagHours.toFixed(1) + 'h'} · 近7日失败 ${fail7d}`,
`📥 增量每轮(近24h · ${roundTag} ${rounds.length}轮${roundEmpty ? ` · 空${roundEmpty}` : ''}${roundFailed ? ` · 失败${roundFailed}` : ''})` +
(roundLines.length ? '\n' + roundLines.join('\n') : ' 无'),
`🔄 重算 画像 ${fmtTime(lastPersona?.startedAt)}${lastPersona?.status && lastPersona.status !== 'success' ? `(${lastPersona.status})` : ''} · 召回 ${fmtTime(lastPlanGen?.startedAt)}`,
`📈 数据(近24h↑) 患者 ${fmtNum(patientsTotal)}(+${patients24h}) · 事实 ${fmtWan(factsTotal)}(+${fmtNum(facts24h)})`,
`🖼 画像(24h) 重算 ${fmtNum(personaRuns24h)} 次(${personaRunsZh}) · 覆盖 ${fmtNum(personaPatients)}/${fmtNum(patientsTotal)}(${coveragePct}%)`,
......@@ -157,10 +215,66 @@ export class DailyHealthReportService {
`📋 召回池 待办 ${fmtNum(plansActive)} · 进行中 ${fmtNum(plansAssigned)}`,
`📞 客服执行(24h) ${execTotal} 次${execBreakdown ? ` · ${execBreakdown}` : ''}`,
`🤖 AI(24h) ${inv24h} 次 · ¥${cost24h.toFixed(2)}`,
`⚖️ 对账(去重患者·DW源vsPAC)${reconcileLines.length ? '\n' + reconcileLines.join('\n') : ' —'}`,
].join('\n');
return { level, title, body };
}
/**
* 数据对账 —— 逐 scope 比 DW 源 vs PAC 的去重患者数。
* DW 侧复用摄入 sql_source 查询(同闸口径);PAC 侧按对应 fact_type / 表数去重患者。
* v1 只渲染原始 diff(不设基线、不驱动级别),供观察。失败降级 "—",绝不阻断日报。
*/
private async buildReconcile(): Promise<string[]> {
try {
const host = await this.prisma.host.findFirst({ where: { name: 'jvs-dw' }, select: { id: true } });
if (!host) return [];
const dwCounts = await this.coldImport.reconcileDwPatientCounts('jvs-dw', RECONCILE_SCOPES.map((s) => s.dwKey));
if (Object.keys(dwCounts).length === 0) return []; // 无 sql_source(file/push 宿主)
const lines: string[] = [];
for (const s of RECONCILE_SCOPES) {
const dw = dwCounts[s.dwKey] ?? null;
const pac = await this.pacPatientCount(host.id, s.pac);
lines.push(fmtReconcileLine(s.label, dw, pac));
}
return lines;
} catch (err) {
this.logger.warn(`对账段生成失败(降级,不阻断日报): ${err instanceof Error ? err.message : String(err)}`);
return [];
}
}
/** PAC 侧去重患者数(当前版本:superseded_at IS NULL)。 */
private async pacPatientCount(hostId: string, pac: PacCountKind): Promise<number | null> {
try {
if (pac.kind === 'patient') {
return this.prisma.patient.count({ where: { hostId } });
}
if (pac.kind === 'return_visit') {
const r = await this.prisma.$queryRaw<Array<{ c: bigint }>>`
SELECT count(distinct patient_id) AS c FROM patient_return_visit WHERE host_id = ${hostId}::uuid`;
return Number(r[0]?.c ?? 0);
}
if (pac.kind === 'image_ai') {
// 影像 AI → diagnosis_record 且 content.code_source='image_ai'(image_finding 装配打的标)
const r = await this.prisma.$queryRaw<Array<{ c: bigint }>>`
SELECT count(distinct patient_id) AS c FROM patient_facts
WHERE host_id = ${hostId}::uuid AND superseded_at IS NULL
AND type = 'diagnosis_record' AND content->>'code_source' = 'image_ai'`;
return Number(r[0]?.c ?? 0);
}
// fact 类型:跨多类型取去重患者并集(不是各类型之和)
const r = await this.prisma.$queryRaw<Array<{ c: bigint }>>`
SELECT count(distinct patient_id) AS c FROM patient_facts
WHERE host_id = ${hostId}::uuid AND superseded_at IS NULL
AND type IN (${Prisma.join(pac.types)})`;
return Number(r[0]?.c ?? 0);
} catch (err) {
this.logger.warn(`PAC 计数失败(${JSON.stringify(pac)}): ${err instanceof Error ? err.message : String(err)}`);
return null;
}
}
}
/** cursor_after JSON({resource: "2026-06-21 19:30:00", ...})→ 距今小时数(取最大游标)。 */
......@@ -198,3 +312,18 @@ function fmtTime(d: Date | null | undefined): string {
if (!d) return '—';
return new Date(d).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hour12: false });
}
/** 只要 HH:mm(每轮明细用,同日多轮不必重复日期)。 */
function fmtClock(d: Date | null | undefined): string {
if (!d) return '—';
return new Date(d).toLocaleTimeString('zh-CN', { timeZone: 'Asia/Shanghai', hour: '2-digit', minute: '2-digit', hour12: false });
}
/** 对账单行:DW / PAC / 差(+ = PAC 缺,源比 PAC 多)。v1 只报数不判级,大差多为已知基线(如瑞泰未全摄)。 */
function fmtReconcileLine(label: string, dw: number | null, pac: number | null): string {
if (dw == null || pac == null) return ` ${label} DW ${dw == null ? '—' : fmtNum(dw)} / PAC ${pac == null ? '—' : fmtNum(pac)}`;
const diff = dw - pac;
const pct = dw > 0 ? (diff / dw) * 100 : 0;
const sign = diff > 0 ? '+' : '';
return ` ${label} DW${fmtNum(dw)}/PAC${fmtNum(pac)} 差${sign}${fmtNum(diff)}(${pct.toFixed(0)}%)`;
}
apps/pac-service/src/queues/job-payloads.ts
......@@ -40,3 +40,18 @@ export interface ExecutionCallbackJob {
executionId: string;
triggeredBy: string;
}
export interface ColdImportJob {
hostId: string;
tenantId: string;
/** manifest.host_name;仅日志用(importDirectory 从 dir 内 manifest 自定位 host) */
hostName: string;
/** cold-import 的 --dir:迷你 data 根下的 <host>/ 子目录(含 manifest+assemblers+数据文件) */
dir: string;
/** 清理根:迷你 data 根(dir 的父,含 <host>/ 和 _shared/);worker 跑完整个删掉 */
cleanupDir: string;
/** true = dry-run 预检:跑完整校验+翻译但不落库,返回 totals(failed/mappingMiss)供确认 */
dryRun?: boolean;
/** `upload:<userId>` */
triggeredBy: string;
}
apps/pac-service/src/queues/processors/cold-import.processor.ts 0 → 100644
import { Logger } from '@nestjs/common';
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Job } from 'bullmq';
import * as fs from 'node:fs';
import { QueueName } from '../queue-names';
import type { ColdImportJob } from '../job-payloads';
import { ColdImportService } from '../../modules/sync/cold-import/cold-import.service';
/**
* cold-import worker — 网页上传压缩包触发的整包导入。
*
* 流程:
* 1. 调 ColdImportService.importDirectory(job.dir) — 与 CLI `pnpm cold-import` 同一入口;
* 内部自建 syncLog(审计/最近事件)、cohort 分批、幂等落库。返回 ImportRunResult。
* 2. finally 清理临时解压目录(含 PII 的上传数据文件不残留);失败时保留供排查。
*
* concurrency=1:整包导入是重任务,且 importDirectory 有 partial UNIQUE(host_id)
* WHERE status='running' 并发锁 —— 串行天然避免撞锁。attempts=1 不自动重试。
*
* 返回值即 job.returnvalue,前端按 jobId 轮询时读其中 totals 展示结果。
*/
@Processor(QueueName.COLD_IMPORT, { concurrency: 1 })
export class ColdImportProcessor extends WorkerHost {
private readonly logger = new Logger(ColdImportProcessor.name);
constructor(private readonly coldImport: ColdImportService) {
super();
}
async process(job: Job<ColdImportJob>) {
const { hostName, dir, cleanupDir, dryRun, triggeredBy } = job.data;
this.logger.log(
`cold-import START job=${job.id} host=${hostName} dir=${dir} dryRun=${!!dryRun} triggeredBy=${triggeredBy}`,
);
try {
const result = await this.coldImport.importDirectory(dir, { dryRun: !!dryRun });
this.logger.log(
`cold-import DONE job=${job.id} host=${hostName} status=${result.status} ` +
`patients=${result.totals.patientsUpserted} txn=${result.totals.transactionsWritten} ` +
`dup=${result.totals.duplicates} failed=${result.totals.failed} ` +
`factsCreated=${result.totals.factsCreated} factsSuperseded=${result.totals.factsSuperseded}`,
);
return result;
} finally {
// 成功/失败都清理整个迷你 data 根(cleanupDir,含 <host>/ 数据 + _shared/ 副本)。
// 始终清理(PII 优先),失败原因已在 syncLog.errorMessage + job.failedReason 里。
const target = cleanupDir ?? dir; // 兼容旧 job(无 cleanupDir)
try {
await fs.promises.rm(target, { recursive: true, force: true });
this.logger.debug(`cold-import 清理临时目录 job=${job.id} dir=${target}`);
} catch (err) {
this.logger.warn(
`cold-import 清理临时目录失败 job=${job.id} dir=${target}: ${err instanceof Error ? err.message : err}`,
);
}
}
}
}
apps/pac-service/src/queues/queue-names.ts
......@@ -15,6 +15,8 @@ export const QueueName = {
PLAN_ASSET_GENERATE: 'plan-asset-generate',
/// 执行结果回执投递(PAC → 宿主 callbackUrl,HMAC 签名 + 退避重试;jobName = executionId)
EXECUTION_CALLBACK: 'execution-callback',
/// 网页上传压缩包触发的整包 cold-import(长任务,jobName = jobId;concurrency=1 串行)
COLD_IMPORT: 'cold-import',
} as const;
export type QueueName = (typeof QueueName)[keyof typeof QueueName];
......@@ -53,4 +55,14 @@ export const QueueDefaults = {
removeOnComplete: { count: 500 },
removeOnFail: { count: 5_000 },
},
[QueueName.COLD_IMPORT]: {
/**
* 整包导入是几十分钟的重任务,且 importDirectory 有 partial UNIQUE(host_id) WHERE status='running'
* 并发锁(重试会撞锁)→ **不自动重试**(attempts:1),失败就留 failed 供人工排查。
* 完成的 job 保留久一点(前端靠 jobId 轮询进度,别在读到前被清)。
*/
attempts: 1,
removeOnComplete: { age: 24 * 3_600, count: 100 },
removeOnFail: { count: 1_000 },
},
} as const;
apps/pac-service/src/queues/queue-producer.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { InjectQueue } from '@nestjs/bullmq';
import { randomUUID } from 'node:crypto';
import type { Queue } from 'bullmq';
import { QueueName, QueueDefaults } from './queue-names';
import type {
......@@ -7,6 +8,7 @@ import type {
PlanRecomputeJob,
PlanAssetGenerateJob,
ExecutionCallbackJob,
ColdImportJob,
} from './job-payloads';
/**
......@@ -29,6 +31,7 @@ export class QueueProducer {
@InjectQueue(QueueName.PLAN_RECOMPUTE) private readonly planQ: Queue,
@InjectQueue(QueueName.PLAN_ASSET_GENERATE) private readonly assetQ: Queue,
@InjectQueue(QueueName.EXECUTION_CALLBACK) private readonly callbackQ: Queue,
@InjectQueue(QueueName.COLD_IMPORT) private readonly coldImportQ: Queue,
) {}
async enqueuePersonaRecompute(
......@@ -90,6 +93,41 @@ export class QueueProducer {
);
}
/**
* 整包 cold-import 入队。返回 jobId 作前端轮询句柄(不落 syncLog —— importDirectory 自己会写
* 自己的 syncLog 供审计/最近事件;前端进度直接查 BullMQ job 的 state + returnvalue)。
* concurrency=1 串行 + importDirectory 自带 running 锁 → 同 host 不会并发跑。
*/
async enqueueColdImport(job: ColdImportJob): Promise<{ jobId: string }> {
const jobId = randomUUID();
await this.coldImportQ.add(job.hostName, job, {
jobId,
...QueueDefaults[QueueName.COLD_IMPORT],
});
this.logger.log(
`enqueue cold-import job=${jobId} host=${job.hostName} triggeredBy=${job.triggeredBy}`,
);
return { jobId };
}
/** 查一次 cold-import job 进度(前端轮询用)。job 不存在返回 null(可能已被清理)。 */
async getColdImportJob(jobId: string): Promise<{
state: string;
hostId: string | null;
returnValue: unknown;
failedReason: string | null;
} | null> {
const job = await this.coldImportQ.getJob(jobId);
if (!job) return null;
const state = await job.getState();
return {
state,
hostId: (job.data as { hostId?: string } | undefined)?.hostId ?? null,
returnValue: job.returnvalue ?? null,
failedReason: job.failedReason ?? null,
};
}
async enqueueExecutionCallback(job: ExecutionCallbackJob): Promise<void> {
// jobId = executionId(append-only 唯一)→ 同一 execution 不会重复入队
await this.callbackQ.add(job.executionId, job, {
......
apps/pac-service/src/queues/queues.module.ts
......@@ -17,6 +17,7 @@ import { PersonaRecomputeProcessor } from './processors/persona-recompute.proces
import { PlanRecomputeProcessor } from './processors/plan-recompute.processor';
import { PlanAssetGenerateProcessor } from './processors/plan-asset-generate.processor';
import { ExecutionCallbackProcessor } from './processors/execution-callback.processor';
import { ColdImportProcessor } from './processors/cold-import.processor';
/**
* Queues — BullMQ 三个队列的统一注册入口。
......@@ -56,6 +57,7 @@ import { ExecutionCallbackProcessor } from './processors/execution-callback.proc
{ name: QueueName.PLAN_RECOMPUTE },
{ name: QueueName.PLAN_ASSET_GENERATE },
{ name: QueueName.EXECUTION_CALLBACK },
{ name: QueueName.COLD_IMPORT },
),
PersonaModule,
PlanModule,
......@@ -73,6 +75,7 @@ import { ExecutionCallbackProcessor } from './processors/execution-callback.proc
PlanRecomputeProcessor,
PlanAssetGenerateProcessor,
ExecutionCallbackProcessor,
ColdImportProcessor,
],
exports: [BullModule, QueueProducer, StaleScanService, SyncIncrementalSchedulerService],
})
......
apps/pac-service/src/types/yauzl.d.ts 0 → 100644
// yauzl 无官方 @types —— 遵循仓库"不引额外类型包"的先例(见 assistant.controller、mcp-sdk.d.ts),
// 只声明本项目实际用到的最小 API 面。
declare module 'yauzl' {
import type { EventEmitter } from 'node:events';
import type { Readable } from 'node:stream';
export interface Entry {
fileName: string;
}
export interface ZipFile extends EventEmitter {
readEntry(): void;
openReadStream(
entry: Entry,
callback: (err: Error | null, stream?: Readable) => void,
): void;
}
export interface OpenOptions {
lazyEntries?: boolean;
}
export function open(
path: string,
options: OpenOptions,
callback: (err: Error | null, zipfile?: ZipFile) => void,
): void;
}
apps/pac-service/tests/cold-import-extract.spec.ts 0 → 100644
/**
* cold-import 上传解压 — extractWhitelisted 白名单 + zip-slip 防护
*
* 覆盖:
* - 白名单过滤:zip 里白名单外的文件(c.csv)不提取
* - 子目录条目按 basename 落平(sub/nested.csv → nested.csv,若在白名单)
* - 缺文件:zip 缺白名单声明的文件 → extracted 集合据此可算出缺哪些
* - zip-slip:含 `../evil.csv` 路径穿越条目的包被 yauzl fail-closed **整包拒绝**(reject)
*
* fixtures 由 tests/fixtures/cold-import/*.zip 提供(python3 zipfile 预造,含合法 arcname `../`)。
*
* 跑:pnpm --filter @pac/service test -- cold-import-extract
*/
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { extractWhitelisted } from '../src/modules/admin/import-upload.service';
const FIX = path.join(__dirname, 'fixtures', 'cold-import');
function tmpDir(): string {
return fs.mkdtempSync(path.join(os.tmpdir(), 'cold-import-test-'));
}
describe('extractWhitelisted', () => {
it('只提取白名单命中的文件,忽略白名单外条目', async () => {
const dest = tmpDir();
try {
const got = await extractWhitelisted(
path.join(FIX, 'good.zip'),
dest,
new Set(['a.csv', 'b.csv']),
);
expect([...got].sort()).toEqual(['a.csv', 'b.csv']);
expect(fs.existsSync(path.join(dest, 'a.csv'))).toBe(true);
expect(fs.existsSync(path.join(dest, 'b.csv'))).toBe(true);
} finally {
fs.rmSync(dest, { recursive: true, force: true });
}
});
it('缺文件:zip 缺声明文件 → extracted 不含它(供缺文件校验)', async () => {
const dest = tmpDir();
try {
const whitelist = new Set(['a.csv', 'b.csv']);
const got = await extractWhitelisted(path.join(FIX, 'partial.zip'), dest, whitelist);
const missing = [...whitelist].filter((f) => !got.has(f));
expect(missing).toEqual(['b.csv']);
} finally {
fs.rmSync(dest, { recursive: true, force: true });
}
});
it('zip-slip:含 `../` 路径穿越条目的包被整包拒绝,且父目录零写入', async () => {
const parent = tmpDir();
const dest = path.join(parent, 'inner');
fs.mkdirSync(dest);
try {
await expect(
extractWhitelisted(path.join(FIX, 'evil.zip'), dest, new Set(['a.csv', 'evil.csv'])),
).rejects.toThrow(/relative path|invalid/i);
// 关键:父目录绝无 evil.csv 写入(未逃逸)
expect(fs.existsSync(path.join(parent, 'evil.csv'))).toBe(false);
} finally {
fs.rmSync(parent, { recursive: true, force: true });
}
});
it('白名单外文件(c.csv)不落盘,子目录条目按 basename 落平', async () => {
const dest = tmpDir();
try {
const got = await extractWhitelisted(
path.join(FIX, 'extra.zip'),
dest,
new Set(['a.csv', 'nested.csv']),
);
expect([...got].sort()).toEqual(['a.csv', 'nested.csv']);
expect(fs.existsSync(path.join(dest, 'a.csv'))).toBe(true);
expect(fs.existsSync(path.join(dest, 'nested.csv'))).toBe(true); // sub/nested.csv → nested.csv
expect(fs.existsSync(path.join(dest, 'c.csv'))).toBe(false); // 白名单外
} finally {
fs.rmSync(dest, { recursive: true, force: true });
}
});
});
apps/pac-service/tests/cold-import-groups.spec.ts 0 → 100644
/**
* cold-import 成组完整性 — findIncompleteGroups
*
* 规则(用户定):同 manifest group 的表在网页上传时要么全在、要么整组不在;部分在 → 拒(半组无意义)。
* 独立表(无 group)缺失不影响(装载层宽容跳过)。
*
* 跑:pnpm --filter @pac/service test -- cold-import-groups
*/
import { findIncompleteGroups } from '../src/modules/admin/import-upload.service';
// 模拟 FRIDAY manifest.tables 的关键子集:treatment_plan 组(头+行)+ 若干独立表
const TABLES = [
{ file: 'customer_basic_info.csv' }, // 独立
{ file: 'appointment_base.csv' }, // 独立
{ file: 'customer_treat_plan.csv', group: 'treatment_plan' },
{ file: 'customer_treat_plan_item.csv', group: 'treatment_plan' },
];
describe('findIncompleteGroups', () => {
it('组内全在 → 不报(通过)', () => {
const got = findIncompleteGroups(
TABLES,
new Set(['customer_basic_info.csv', 'customer_treat_plan.csv', 'customer_treat_plan_item.csv']),
);
expect(got).toEqual([]);
});
it('整组都不在 → 不报(宽容:该主体不导)', () => {
const got = findIncompleteGroups(TABLES, new Set(['customer_basic_info.csv']));
expect(got).toEqual([]);
});
it('组内部分在(缺行表)→ 报不完整', () => {
const got = findIncompleteGroups(
TABLES,
new Set(['customer_basic_info.csv', 'customer_treat_plan.csv']), // 缺 _item
);
expect(got).toHaveLength(1);
expect(got[0]!.group).toBe('treatment_plan');
expect(got[0]!.missing).toEqual(['customer_treat_plan_item.csv']);
expect(got[0]!.present).toEqual(['customer_treat_plan.csv']);
});
it('独立表缺失不影响(无 group 不参与成组)', () => {
const got = findIncompleteGroups(
TABLES,
new Set(['customer_treat_plan.csv', 'customer_treat_plan_item.csv']), // 缺两张独立表,但组齐
);
expect(got).toEqual([]);
});
});
apps/pac-service/tests/filter-numeric.spec.ts 0 → 100644
/**
* filter 数值比较算子 — lt/lte/gt/gte
*
* 动机:让"业务口径 WHERE"(如退费正负切分 receivable_this < 0)能在 PAC transforms 做,
* 宿主只需导原表。非数值/空值一律不通过(空金额不算负数)。
*
* 跑:pnpm --filter @pac/service test -- filter-numeric
*/
import { runFilter } from '../src/modules/sync/transforms/operators/filter.op';
import type { FilterOp } from '../src/modules/sync/transforms/transforms.schema';
const rows = [
{ m: '-30.00' },
{ m: '0' },
{ m: '5' },
{ m: '' }, // 空
{ m: 'abc' }, // 非数值
{ m: null as unknown as string },
];
function filt(where: FilterOp['where']) {
const op = { kind: 'filter', input: 'x', output: 'y', where } as FilterOp;
return runFilter(op, rows).rows.map((r) => r.m);
}
describe('filter 数值算子', () => {
it('lt:< 0 只保留负数,空/非数值不通过', () => {
expect(filt({ m: { lt: 0 } })).toEqual(['-30.00']);
});
it('gte:>= 0 保留 0 和正数', () => {
expect(filt({ m: { gte: 0 } })).toEqual(['0', '5']);
});
it('gt:> 0 只保留正数', () => {
expect(filt({ m: { gt: 0 } })).toEqual(['5']);
});
it('lte:<= 0 保留 0 和负数', () => {
expect(filt({ m: { lte: 0 } })).toEqual(['-30.00', '0']);
});
it('空值 / 非数值 / null 一律不通过数值比较', () => {
// 用一个恒真下界也不会把空/非数值放进来
expect(filt({ m: { gte: -1e9 } })).toEqual(['-30.00', '0', '5']);
});
});
apps/pac-service/tests/friday-settlement-where.spec.ts 0 → 100644
/**
* FRIDAY 结算/病历 WHERE 迁移到 PAC transforms —— 验证"导原表 → PAC 侧 filter 切分"正确。
*
* 背景:业务 WHERE 从 export.sh 全部搬进 manifest transforms(单一真理源)。
* 本测用合成的**原表**数据(全 status + 正负金额)喂 TransformEngine,断言四处切分:
* ① 消费 status∈{1,3} 且 receivable≥0(负额被 gte 挡)
* ② 退费① status=4 ∪ (status=3 且 receivable<0) ← filter×2 + union
* ③ 退费明细 is_refund=1
* ④ 病历 status∈{3,4} 排草稿
*
* 跑:pnpm --filter @pac/service test -- friday-settlement-where
*/
import { TransformEngine } from '../src/modules/sync/transforms/transform-engine';
import type { TransformsConfig } from '../src/modules/sync/transforms/transforms.schema';
const engine = new TransformEngine();
// 合成原表(CSV 源天然全字符串;med_emr_info 是 JSON,status 用数字测 in 的 String 归一)
const patient_settlement = [
{ uuid: 's1', status: '1', receivable_this: '100', patient_id: '666716' }, // 消费
{ uuid: 's3', status: '3', receivable_this: '50', patient_id: '666716' }, // 消费(status3 正额)
{ uuid: 's1neg', status: '1', receivable_this: '-5', patient_id: '666716' }, // 消费但金额<0 → 被 gte 挡
{ uuid: 's4', status: '4', receivable_this: '-30', patient_id: '666716' }, // 退费(status4 整单反向)
{ uuid: 's3neg', status: '3', receivable_this: '-20', patient_id: '666716' }, // 退费(status3 负额表达)
{ uuid: 's2', status: '2', receivable_this: '10', patient_id: '666716' }, // 草稿/其他 → 都不收
];
// spec.patient_id 部分品牌原是「诊所本地垃圾 id」→ 宿主导出时已从结算头反填真 patient_id(inline);PAC 直用
const patient_settlement_spec = [
{ id: 'sp1', is_refund: '1', settlement_id: 's3', patient_id: '666716' }, // 退费明细(宿主已反填真 patient_id)
{ id: 'sp2', is_refund: '0', settlement_id: 's1', patient_id: '666716' }, // 非退费
];
const med_emr_info = [
{ emr_sub_id: 'e3', status: 3 }, // 正式
{ emr_sub_id: 'e4', status: 4 }, // 正式
{ emr_sub_id: 'e2', status: 2 }, // 草稿 → 排除
];
const transforms = [
{ kind: 'filter', input: 'patient_settlement', output: '_pay_hdr', where: { status: { in: ['1', '3'] }, receivable_this: { gte: 0 } } },
{ kind: 'filter', input: 'patient_settlement', output: '_refund_status4', where: { status: { equals: '4' } } },
{ kind: 'filter', input: 'patient_settlement', output: '_refund_neg3', where: { status: { equals: '3' }, receivable_this: { lt: 0 } } },
{ kind: 'union', inputs: ['_refund_status4', '_refund_neg3'], output: 'refund_full_rows' },
{ kind: 'filter', input: 'patient_settlement_spec', output: 'refund_item_rows', where: { is_refund: { equals: '1' } } },
{ kind: 'filter', input: 'med_emr_info', output: '_emr_official', where: { status: { in: ['3', '4'] } } },
] as unknown as TransformsConfig;
describe('FRIDAY 结算/病历 WHERE 迁移(导原表 + PAC 切分)', () => {
const out = engine.run({
tables: { patient_settlement, patient_settlement_spec, med_emr_info },
transforms,
});
const pick = (rows: unknown[], key: string) =>
(rows as Array<Record<string, unknown>>).map((r) => r[key]).sort();
it('① 消费:status∈{1,3} 且 receivable≥0(负额 s1neg 被挡,s2/s4 不在)', () => {
expect(pick(out['_pay_hdr'] ?? [], 'uuid')).toEqual(['s1', 's3']);
});
it('② 退费①:status=4 ∪ (status=3 且金额<0)', () => {
expect(pick(out['refund_full_rows'] ?? [], 'uuid')).toEqual(['s3neg', 's4']);
});
it('③ 退费明细:is_refund=1', () => {
expect(pick(out['refund_item_rows'] ?? [], 'id')).toEqual(['sp1']);
});
it('③.1 退费明细患者 = 宿主反填的真 patient_id(spec.patient_id 直用,不再跨表 lookup)', () => {
const rows = (out['refund_item_rows'] ?? []) as Array<Record<string, unknown>>;
expect(rows.map((r) => r['patient_id'])).toEqual(['666716']);
});
it('④ 病历:status∈{3,4} 排草稿 e2', () => {
expect(pick(out['_emr_official'] ?? [], 'emr_sub_id')).toEqual(['e3', 'e4']);
});
});
apps/pac-service/tests/trace-raw-source.spec.ts 0 → 100644
/**
* traceRawSourceTable —— 回溯 assembler primary 表到「原始源表」,用于 push(source→匹配 assembler)
* 与 reparse(rawPayload 属哪张源表)。重点回归:**union 多输入必须能收敛到同一根**,
* 否则 union-primary 资源(refund_full)在 push/reparse 里被静默跳过(丢财务数据)。
*
* 跑:pnpm --filter @pac/service test -- trace-raw-source
*/
import { traceRawSourceTable } from '../src/modules/sync/cold-import/cold-import.service';
// 结算链最小 transforms:消费(filter 链)+ 退费整单(filter×2 + union)+ 退费明细(filter+lookup)
const transforms = [
{ kind: 'filter', input: 'patient_settlement', output: '_pay_hdr', where: {} },
{ kind: 'lookup', input: '_pay_hdr', output: 'payment_rows', from: 'settlement_modes', select: {} },
{ kind: 'filter', input: 'patient_settlement', output: '_refund_status4', where: {} },
{ kind: 'filter', input: 'patient_settlement', output: '_refund_neg3', where: {} },
{ kind: 'union', inputs: ['_refund_status4', '_refund_neg3'], output: 'refund_full_rows' },
{ kind: 'filter', input: 'patient_settlement_spec', output: '_refund_item_raw', where: {} },
{ kind: 'lookup', input: '_refund_item_raw', output: 'refund_item_rows', from: 'patient_settlement', select: {} },
// route_by_pattern 多输出回同一 input
{ kind: 'route_by_pattern', input: '_treat_raw', outputs: [{ output: '_actual_raw' }, { output: '_rec_raw' }] },
];
describe('traceRawSourceTable', () => {
it('单输入链:payment_rows → patient_settlement', () => {
expect(traceRawSourceTable('payment_rows', transforms)).toBe('patient_settlement');
});
it('union 收敛:refund_full_rows 两路都回到 patient_settlement(修复点)', () => {
expect(traceRawSourceTable('refund_full_rows', transforms)).toBe('patient_settlement');
});
it('lookup 链取 input(不取 from):refund_item_rows → patient_settlement_spec', () => {
expect(traceRawSourceTable('refund_item_rows', transforms)).toBe('patient_settlement_spec');
});
it('route 多输出回同一 input:_actual_raw → _treat_raw', () => {
expect(traceRawSourceTable('_actual_raw', transforms)).toBe('_treat_raw');
});
it('已是根表:原样返回', () => {
expect(traceRawSourceTable('patient_settlement', transforms)).toBe('patient_settlement');
});
it('union 输入发散到多根 → 停在 union 输出(不误判)', () => {
const diverge = [
{ kind: 'filter', input: 'table_a', output: '_a', where: {} },
{ kind: 'filter', input: 'table_b', output: '_b', where: {} },
{ kind: 'union', inputs: ['_a', '_b'], output: 'merged' },
];
expect(traceRawSourceTable('merged', diverge)).toBe('merged');
});
});
apps/pac-web/src/components/host-admin/cold-import-card.tsx 0 → 100644
'use client';
import { useEffect, useRef, useState } from 'react';
import { Upload, Loader2 } from 'lucide-react';
import { toast } from 'sonner';
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { hostApi, type ColdImportStatus } from './host-api';
/** BullMQ 终态:轮询到这些状态就停。 */
const TERMINAL = new Set(['completed', 'failed', 'not_found']);
const POLL_MS = 3000;
const STATE_LABEL: Record<string, string> = {
waiting: '排队中',
delayed: '排队中',
active: '导入中',
completed: '完成',
failed: '失败',
not_found: '已结束',
};
function fmtElapsed(sec: number): string {
const m = Math.floor(sec / 60);
const s = sec % 60;
return m > 0 ? `${m}分${s}秒` : `${s}秒`;
}
/**
* ColdImportCard — 宿主自助上传数据压缩包触发 cold-import。
*
* 流程:选 zip → 上传拿 jobId → 每 3s 轮询进度 → 终态停 + 展示 totals + 刷新最近事件。
* manifest/assemblers 取自 PAC 代码库,上传包只含数据文件(见后端 ImportUploadService)。
*/
export function ColdImportCard({ onDone }: { onDone: () => void }) {
const inputRef = useRef<HTMLInputElement>(null);
const [file, setFile] = useState<File | null>(null);
const [dryRun, setDryRun] = useState(true); // 默认先预检,更安全
const [uploading, setUploading] = useState(false);
const [jobId, setJobId] = useState<string | null>(null);
const [status, setStatus] = useState<ColdImportStatus | null>(null);
const [startedAt, setStartedAt] = useState<number | null>(null);
const [elapsed, setElapsed] = useState(0);
// onDone 存 ref,避免父组件重渲染导致轮询 effect 被重置
const onDoneRef = useRef(onDone);
useEffect(() => {
onDoneRef.current = onDone;
}, [onDone]);
// 轮询:仅依赖 jobId
useEffect(() => {
if (!jobId) return;
let timer: ReturnType<typeof setInterval> | null = null;
let stopped = false;
const poll = async () => {
try {
const s = await hostApi.getImportStatus(jobId);
if (stopped) return;
setStatus(s);
if (TERMINAL.has(s.state)) {
if (timer) clearInterval(timer);
timer = null;
if (s.state === 'completed') {
if (s.result?.dryRun) {
// 预检:未落库,不刷新最近事件
toast.success('预检完成(未落库),检查下方 failed / 数量再正式导入');
} else {
toast.success('导入完成');
onDoneRef.current();
}
} else if (s.state === 'failed') {
toast.error(`导入失败:${s.failedReason ?? '未知原因'}`);
} else {
toast.message('任务已不在队列(可能已完成并被清理)');
}
}
} catch {
// 单次轮询失败不打断,等下一轮
}
};
void poll();
timer = setInterval(() => void poll(), POLL_MS);
return () => {
stopped = true;
if (timer) clearInterval(timer);
};
}, [jobId]);
const running = jobId != null && (!status || !TERMINAL.has(status.state));
// 已用时长:running 时每秒 tick
useEffect(() => {
if (!running || startedAt == null) return;
const t = setInterval(() => setElapsed(Math.floor((Date.now() - startedAt) / 1000)), 1000);
return () => clearInterval(t);
}, [running, startedAt]);
const onUpload = async () => {
if (!file) return;
setUploading(true);
setStatus(null);
setJobId(null);
try {
const form = new FormData();
form.append('file', file);
form.append('dryRun', String(dryRun));
const { jobId: id } = await hostApi.importArchive(form);
setJobId(id);
setStartedAt(Date.now());
setElapsed(0);
toast.success(dryRun ? '已上传,开始预检(不落库)' : '已上传,开始后台导入');
} catch (e) {
toast.error(e instanceof Error ? e.message : '上传失败');
} finally {
setUploading(false);
}
};
const t = status?.result?.totals;
return (
<Card>
<CardHeader>
<CardTitle>数据导入</CardTitle>
<CardDescription>
上传数据压缩包(zip,含 manifest 声明的 CSV/JSON)触发整包 cold-import。manifest / assemblers
取自 PAC 侧无需上传。重复上传同一批数据是安全的(幂等空转:去重高、fact 新建≈0)。
</CardDescription>
</CardHeader>
<CardContent className="space-y-3">
<input
ref={inputRef}
type="file"
accept=".zip"
className="hidden"
onChange={(e) => setFile(e.target.files?.[0] ?? null)}
/>
<div className="flex flex-wrap items-center gap-3">
<Button
variant="outline"
onClick={() => inputRef.current?.click()}
disabled={uploading || running}
>
选择 zip
</Button>
<span className="min-w-0 flex-1 truncate text-sm text-muted-foreground">
{file ? file.name : '未选择文件'}
</span>
<label className="flex items-center gap-1.5 text-sm text-muted-foreground">
<input
type="checkbox"
checked={dryRun}
onChange={(e) => setDryRun(e.target.checked)}
disabled={uploading || running}
/>
仅预检(不落库)
</label>
<Button onClick={onUpload} disabled={!file || uploading || running}>
{uploading ? (
<Loader2 className="mr-2 h-4 w-4 animate-spin" />
) : (
<Upload className="mr-2 h-4 w-4" />
)}
{dryRun ? '预检' : '上传并导入'}
</Button>
</div>
{jobId && (
<div className="rounded-md border p-3 text-sm">
<div className="flex items-center gap-2">
{running && <Loader2 className="h-4 w-4 animate-spin" />}
<span>
状态:{STATE_LABEL[status?.state ?? ''] ?? status?.state ?? '排队中'}
{status?.result?.dryRun ? '(预检)' : ''}
</span>
{(running || elapsed > 0) && (
<span className="text-xs text-muted-foreground">· 用时 {fmtElapsed(elapsed)}</span>
)}
</div>
{/* 运行中真实进度条(cohortDone/cohortTotal 批次) */}
{status?.progress && status.progress.total > 0 && (
<div className="mt-2">
<div className="h-1.5 w-full overflow-hidden rounded bg-muted">
<div
className="h-full bg-primary transition-all"
style={{
width: `${Math.round((status.progress.done / status.progress.total) * 100)}%`,
}}
/>
</div>
<div className="mt-1 text-xs text-muted-foreground">
已处理 {status.progress.done}/{status.progress.total} 批
</div>
</div>
)}
{/* 长任务提示:后台跑,可离开 */}
{running && (
<p className="mt-1.5 text-xs text-muted-foreground">
导入在后台进行,可离开此页,稍后回来查看结果。
</p>
)}
{status?.state === 'failed' && status.failedReason && (
<p className="mt-1 text-destructive">失败原因:{status.failedReason}</p>
)}
{t && (
<div className="mt-2 grid grid-cols-2 gap-x-4 gap-y-1 text-muted-foreground">
<span>患者 upsert:{t.patientsUpserted}</span>
<span>事务写入:{t.transactionsWritten}</span>
<span>幂等去重:{t.duplicates}</span>
<span>失败:{t.failed}</span>
<span>fact 新建:{t.factsCreated}</span>
<span>fact 更新:{t.factsSuperseded}</span>
<span>fact 未变:{t.factsUnchanged}</span>
<span>证据追加:{t.factsEvidenceAppended}</span>
</div>
)}
</div>
)}
</CardContent>
</Card>
);
}
apps/pac-web/src/components/host-admin/host-admin-app.tsx
......@@ -24,6 +24,7 @@ import { isPostMessageSentinel } from '@/lib/host-message';
import { hostApi } from './host-api';
import { useConfirm } from './use-confirm';
import { SecretRevealDialog } from './secret-reveal-dialog';
import { ColdImportCard } from './cold-import-card';
/**
* HostAdminApp — 宿主自己的 admin 配置页主视图。
......@@ -248,6 +249,9 @@ export function HostAdminApp({ data, onRefresh }: { data: HostDetail; onRefresh:
<StatsCard data={data} />
{/* 数据导入(上传压缩包触发 cold-import) */}
<ColdImportCard onDone={onRefresh} />
{/* 凭据 */}
<Card>
<CardHeader>
......
apps/pac-web/src/components/host-admin/host-api.ts
......@@ -13,6 +13,28 @@ import { api } from '@/lib/api-client';
const BASE = '/pac/v1/admin/host/self';
export interface ColdImportTotals {
patientsUpserted: number;
transactionsWritten: number;
duplicates: number;
failed: number;
factsCreated: number;
factsSuperseded: number;
factsUnchanged: number;
factsEvidenceAppended: number;
factsFailed: number;
}
export interface ColdImportStatus {
/** BullMQ job 状态:waiting/active/completed/failed/...;'not_found' = 已清理或不存在 */
state: string;
/** 完成时的 ImportRunResult(含 totals + dryRun 标志);进行中为 null */
result: { status?: string; dryRun?: boolean; totals?: ColdImportTotals } | null;
failedReason: string | null;
/** 运行中的真实进度(cohortDone/cohortTotal 批次);非运行态或 dryRun 为 null */
progress: { done: number; total: number } | null;
}
export const hostApi = {
getSelf: () => api.get<HostDetail>(BASE),
getStats: () => api.get<HostStats>(`${BASE}/stats`),
......@@ -28,4 +50,9 @@ export const hostApi = {
api.delete<{ totalKeysRemaining: number }>(
`${BASE}/callback-secrets/${encodeURIComponent(suffix)}`,
),
// 数据导入:上传压缩包(FormData 字段名 file)→ 返回 jobId;按 jobId 轮询进度
importArchive: (form: FormData) => api.post<{ jobId: string }>(`${BASE}/cold-import`, form),
getImportStatus: (jobId: string) =>
api.get<ColdImportStatus>(`${BASE}/cold-import/${encodeURIComponent(jobId)}`),
};
pnpm-lock.yaml
......@@ -235,6 +235,9 @@ importers:
ws:
specifier: ^8.21.0
version: 8.21.0
yauzl:
specifier: ^3.3.0
version: 3.3.0
zod:
specifier: ^4.4.3
version: 4.4.3
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment