医学健康图谱 · Neo4j 完整包

版本：medical-health-graph-2.0.0；资料核查：2026-10-03。

本包提供真实 Neo4j Community 数据库导入与专业图谱管理所需的数据、脚本、查询和预载数据库。当前收录 868 条医学检测与健康评估定义、503 条条件化数值参考案例、5,161 个节点、11,784 条关系。保留原有 350 条指标编号，新增 518 条。467 条来源记录对应 455 个不同来源 URL。

这是面向全医学领域的可持续扩展目录。不是“已经包含全部医学检测及全球统一正常值”的承诺。血液、生化、免疫、感染、内分泌、生殖孕产、新生儿与遗传代谢、药物、毒理、影像、功能、康复、眼耳口腔皮肤、心理认知、患者报告与血气已收录；罕见病完整基因目录、所有病原/药物、所有儿科年龄和孕周、医院自定义方法仍需继续接入。

1. 先使用现有平台

访问个人健康管理平台，进入“医学健康图谱”：

图谱探索：按医学领域、参考类型、名称搜索，使用 Cytoscape.js 缩放、平移、力导向/层次/环形布局、1–2 层邻居和 PNG/JSON 局部导出。
医学指标目录：逐项查看标本、单位、完整参考文字和参考案例，支持分页和筛选导出。
图谱管理：新增个人检测或参考值草稿、追加修订版本、归档和导出。草稿需要专业审核，不自动进入个人结果判读。
Neo4j 工作台：查看真实连接状态、复制 Cypher、查询数据库领域覆盖。未配置服务时，明确显示发布版目录模式。

平台原有报告上传、原文核对、个人画像、历史趋势、风险线索、复查计划与设备数据功能继续保留。单报告 350 条是导入操作上限，不是指标目录总量上限。

2. 启动 Neo4j（Docker 方式）

需要 Docker Compose 和 Python 3.10+。使用固定镜像 neo4j:5.26.31-community。

将 .env.example 复制为 .env，填写你自己的 NEO4J_PASSWORD。密码不能留空，不要将 .env 放入版本控制。
在本包目录启动：

docker compose up -d

浏览器打开 http://localhost:7474/browser/。用户名为 neo4j，密码为刚设置的值。
导入完整图谱。脚本会安全提示输入密码：

python import_graph.py

导入完成应输出 nodes: 5161、indicators: 868、edges: 11784。脚本使用唯一约束和 MERGE，重复执行不会重复创建相同节点或关系。它不会清空已有数据库，不自动删除你另外添加的知识；同一 ID 的发布版字段会更新。建议先在专用知识数据库中使用本包，生产升级前保留快照。

Compose 的数据和日志使用命名卷，默认仅将端口绑定本机回环地址。云端个人健康平台不能连接你电脑的 localhost。 若要接到云端平台，需要一个持续运行、能经 HTTPS 到达的 Neo4j 实例（自行部署或适用的 Neo4j Aura 实例）。服务器资源及访问方式由实际部署决定。

本次使用同版本的官方 Linux tar 包完成了实际数据库验证；当前环境没有 Docker，因此没有声称执行过上述 Docker Compose。

3. 使用预载数据库文件

data/neo4j.dump 是本次真实 Neo4j 5.26.31 Community 导出的 neo4j 知识数据库，只含本包知识、索引与约束，不含个人报告、system 数据库或数据库登录凭据。

可在兼容的 Neo4j Desktop 中以数据库 dump 创建一个新的本地数据库。也可在一个新的、已停止的 Neo4j 5.26.31 实例中使用官方加载命令：

bin/neo4j-admin database load neo4j --from-path=/absolute/path/to/this-package/data

请对新的空数据库执行加载。不要为了加载本包覆盖正在使用的个人或业务数据库。导入 JSON 与加载 dump 是两种使用方式，选择一种即可。

4. 连接健康平台

在平台服务器的运行环境设置中配置：

NEO4J_HTTP_URL=https://your-neo4j-instance.example
NEO4J_DATABASE=neo4j
NEO4J_USERNAME=your-user
NEO4J_PASSWORD=your-secret

NEO4J_HTTP_URL 填实例源地址，不附 /db/... 路径。平台通过 POST /db/{database}/query/v2 发出固定、带参数的只读查询，检查响应中的 errors 数组。HTTP 202 本身不代表查询成功。凭据只存在服务端，浏览器不接收数据库密码。

连接后，在“图谱探索”的数据来源中选“Neo4j 实时查询”。一次查询最多返回约 100 个邻居关系；可选中节点后继续展开。发布版目录仍对应本包的数据快照，不会把实时数据库的未知新增条目假装成已经通过整理的参考库。

当前交付已完成本地数据库和平台适配器的真实验证；没有收到你的云端 Neo4j 地址或凭据，因此当前已发布平台的云端数据库连接尚未配置。不会把临时验证进程当成持久服务。

5. 图模型与专业管理

每个节点都有稳定的业务 id，并附 MedicalEntity 与具体类型标签。不要用 Neo4j 内部 elementId() 作为跨版本的医学指标标识。

节点	主要内容
IndicatorDefinition	中文/英文名、别名、医学域、结果类型、标本、方法、单位、完整参考、来源
ReferenceStatement	原适用条件下的完整参考文字，含定性、分级或无通用范围说明
ReferenceCase	参考性质、上下界、边界包含性、性别、年龄、生理阶段、方法、条件、来源
Specimen / Method / Unit / Population	独立的标本、方法、单位与适用人群上下文
EvidenceSource	具体原始页面、机构、核查日期与核查状态
HealthDomain / CheckupItem	学科与检查层级
ExternalTerm	经明确核验的术语映射或后续接入的 LOINC 术语
UserGraphRevision	个人未审核修订；不加入供知识 API 读取的 MedicalEntity 标签

核心关系：HAS_INDICATOR、HAS_REFERENCE、HAS_REFERENCE_CASE、SUPPORTED_BY、MEASURED_IN、USES_METHOD、REPORTED_IN_UNIT、HAS_POPULATION_CONTEXT、MAPPED_TO。

图边保留 evidence_status：structural 是数据结构关系；editorial_classification 是编目归类；source_supported 是有直接来源支持的既有医学关联或核验映射。关联存在不能推导个人诊断或疾病概率。

打开 queries.cypher，把各段查询粘贴到 Neo4j Browser，可查看多条件参考、证据路径、未结构化项目和术语映射。browser.grass 提供节点颜色和标签样式。可以在 Browser 原生运行经过审核的 Cypher 来维护专业知识；平台网页只开放固定查询，避免误执行任意语句。

Neo4j Browser 与商业的 Bloom/Explore 产品是不同组件。本包使用 Community + Browser + Cytoscape.js，不宣称已购买或启用 Bloom 企业功能。

6. 参考范围如何建模

868 条定义都有参考说明，不代表 868 条都有通用数字区间。当前 503 个数值案例覆盖 363 条定义；其余 505 条可能有全文条件、定性解释、分级、设备常模，或明确要求使用本实验室范围。

类型	本版主分类数量	解释
参考区间	300	特定方法、标本与参考人群的范围
临床决策界值	121	阴阳性、临床分层或特定判定切点
治疗 / 监测目标	25	与药物、给药方案、采样时点相关
定性结果	149	阴性、未检出或特定正常表现
解释规则 / 分级	162	影像分级、病理、量表或综合算法
无统一范围	80	不存在可跨场景通用的正常区间
本实验室范围	31	依机构、设备或适用常模确认

类型是索引用的主分类，详细判读始终查看完整 reference_text 和每个 ReferenceCase.kind；一些项目同时涉及区间和决策条件。

不得将年龄空值理解为全年龄适用，不得将不存在的上界理解为任何极端值都合理。凝血因子等相对校准活性的百分数可超过100；不使用“所有%必须0–100”的通用校验。药物峰值、谷值和随机值不可混用。PSG 与消费级睡眠估计、ECG-HRV 与 PPG-PRV、血液 SaO2 与光学 SpO2 保留方法区别。

7. 向完整标准目录扩展

LOINC 定义实验室和临床观察项目的编码及多个语义轴，不提供一套可直接套用的全医学正常值。官方 2.74 发行说明记录 UnitsAndRange 字段清空/删除，原因包括范围随实验室和人群不同。

本包没有附带未经授权取得的全量 LOINC/SNOMED CT 数据。已核验的 3 条 LOINC 映射只对应 Mayo 原始单位的血清游离轻链结果。其他指标明确处于未映射状态。

获得你有权使用的官方 Loinc.csv 后，可使用：

python import_loinc.py --csv /absolute/path/Loinc.csv --release YOUR_EXACT_RELEASE

脚本保留 Component、Property、Time、System、Scale、Method 六轴及状态，创建 ExternalTerm；新增术语不自动映射到本地指标，也不产生“正常范围”。保留官方发行包中的许可、归属与第三方内容条款。SNOMED CT 需要按实际所在地区、发行版与授权接入；本版仅预留外部术语模型，没有实现完整 RF2 导入器。

人工映射至少记录 indicator_id, external_system, external_code, source_url, source_version, reviewed_by, reviewed_at, status。核对分析物、标本、性质、时间、尺度、方法及术语状态后才能标记 verified。EGFR/eGFR、MCV、RET、LTA、FV:C/FVC 等缩写碰撞不得按字符串自动合并。

建议扩展顺序：本地 LIS 项目字典和执行实验室参考值 → LOINC 六轴映射 → 医院影像/功能方法和常模 → 儿科与孕周 → 药物与遗传专科。用覆盖统计展示未完成的条件，而不是给缺失范围填一个常见数字。

8. 个人修订导入

平台“图谱管理”导出 JSON 后，可导入到个人实例：

python import_revisions.py --file /path/医学图谱个人修订.json --workspace my-private-workspace

该操作保存 UserGraphRevision 历史与草稿状态，不将其转换成已经临床审核的 ReferenceCase。它不执行来源 URL 的抓取，不运行草稿内的文字，不修改个人报告判读。经专业人员审核后，可以按照发布版模型增补新的指标与范围节点，并另行保存版本快照。

9. 已完成验证及范围

真实 Neo4j 5.26.31 Community：首次导入与第二次导入均为 5,161 节点、868 指标、11,784 关系。
真实 Query API v2：ACTH 参考区间7.2–63 pg/mL、参考条件到来源的路径、目录领域覆盖、邻居查询均通过。
真实平台 HTTP 适配器：连接状态、参数绑定、错误处理、未配置状态通过；非法参数没有执行成 Cypher。
平台 37 项校核：保留原31项功能，并验证跨学科缩写、图邻域范围、参考条件、个人修订历史和两用户隔离。D1/身份测试使用测试替身；Neo4j测试使用真实本地数据库。
JSON 数据完整性：868个稳定ID、来源引用、关系端点、503个数值边界全部通过。
临床诊断准确性、真实可穿戴硬件、真实用户浏览器端到端尚不属于本次已验证事项。来源核查不等于临床有效性验证。

详情见 validation/catalogue-validation.json 与 validation/neo4j-validation.json。源码目录还保存了平台测试和可复现生成脚本。当前包不包含原网页全文缓存。

10. 文件与来源

data/graph.json：完整图，所有属性和关系。
data/catalogue.json：868定义、503案例及467来源记录。
data/coverage.json：实际覆盖与未完成范围。
data/neo4j.dump：实际导出的 Neo4j 知识数据库。
import_graph.py / client.py：无第三方 Python 依赖的图导入与 Query API。
import_loinc.py：有权使用的 LOINC 发布版导入。
import_revisions.py：个人草稿历史导入。
queries.cypher / browser.grass：原生查询与可视化样式。
docker-compose.yml / .env.example：本地持久部署配置。
validation/：本次实际测试结果。
SHA256SUMS：交付文件校验和。

官方技术来源

Neo4j Query API：https://neo4j.com/docs/query-api/current/
Query API 请求与响应：https://neo4j.com/docs/query-api/current/query/
Neo4j Java版本要求：https://neo4j.com/docs/operations-manual/current/installation/requirements/
Neo4j 部署中心：https://neo4j.com/deployment-center/
Neo4j 离线导出：https://neo4j.com/docs/operations-manual/current/backup-restore/offline-backup/
Cytoscape.js：https://js.cytoscape.org/
LOINC 许可：https://loinc.org/kb/license
LOINC 2.74范围字段说明：https://loinc.org/kb/release-notes-archive/2.74
UCUM：https://ucum.org/ucum
SNOMED CT获取：https://www.snomed.org/get-snomed

医学事实来源示例

ACTH及上午采血参考：https://mml.testcatalog.org/show/ACTH
网织红细胞：https://www.mayocliniclabs.com/test-catalog/overview/616856
2026自由轻链与方法特异区间：https://www.mayocliniclabs.com/test-catalog/overview/608250
MPO/PR3 当前方法切点：https://www.mayocliniclabs.com/test-catalog/Overview/83012
心腔定量：https://www.asecho.org/wp-content/uploads/2016/02/2015_ChamberQuantificationREV.pdf
动脉血气：https://www.healthcare.uiowa.edu/path_handbook/handbook/test303.html

其余来源逐项写入 data/catalogue.json 的 sources 和 source_ids。知识编目与脚本不能取代执行实验室、相应指南和专业人员对具体人的解释。