本项目是专为医院信息科主数据管理员设计的患者主索引Master Patient Index, MPI匹配策略验证工具。它不介入真实生产环境也不执行任何数据库写操作而是以测试数据为输入在本地完成多维相似度计算、阈值敏感性扫描、规则驱动动作决策与冲突归因分析核心形态是一个命令行驱动CLI的离线模拟系统。我们用编辑距离拼音相似度行政区划出生日期构建复合评分模型用参数化阈值扫描生成「阈值-匹配数」曲线辅助决策用可读性强的 JSON 规则 DSL 定义 merge/review/new 三类动作触发逻辑最终输出结构化 CSV 结果与自然语言 TXT 冲突报告供人工复核确认最优参数组合。技术栈基于 Python 3.10依赖 rapidfuzz 做高效字符串比对pydantic 保障输入数据合规click 提供稳定 CLI 接口。定位与能力边界这不是一个上线即用的 MPI 合并引擎也不是替代现有主数据平台的中间件。它的存在意义非常明确在收到跨院区患者合并申请后、正式执行前为信息科提供一次零风险的参数沙盘推演。所有操作均在本地完成不连接任何 HRP、EMR 或区域健康平台数据库所有输入必须是脱敏后的模拟数据如data/mock_patients.csv不接受真实身份证号或手机号直接入参所有输出仅用于人工研判不自动触发下游流程。我们刻意划清三条线- 不处理实时流数据只接受静态 CSV 文件输入- 不修改任何源系统记录所有“合并建议”仅存在于输出文件中- 不封装 Web 界面或 API 服务全部能力通过终端命令显式调用。这种克制不是功能缺失而是责任前置主数据治理的关键环节必须由人审慎把关系统只负责把“不同阈值会带来多少匹配、哪些记录会冲突、按当前规则该怎么做”这件事算得清楚、列得明白、报得及时。核心功能详解本项目围绕“参数可信度验证”这一主线提供四个环环相扣的能力模块功能模块输入方式输出内容关键价值多维相似度匹配单条患者记录对name/id_card/phone/regionsimilarity_score0.0–1.0、suggested_actionmerge/review/new、conflict_flagTrue/False融合拼音、编辑距离、行政区划编码、出生日期差值避免单一维度误判如仅靠姓名拼音可能将“张三丰”与“张三峰”高分误配阈值参数化扫描指定单个阈值如 0.85output/scan_*.csv含每对记录的评分与建议动作快速验证某组参数在当前数据集上的表现用于小范围快速试错阈值-匹配数曲线生成全量测试数据output/threshold_curve.csv含 threshold、match_count、review_count、new_count及对应图表脚本直观呈现阈值微调带来的匹配数量跃变点识别敏感区间例如从 0.82→0.83 匹配数激增 40%提示此处需重点审查冲突报告生成已有的扫描结果 CSVoutput/report_*.txt按冲突类型分组列出典型记录对、相似度、差异字段与规则依据将机器判定转化为人类可读归因例如“record_a.id_card 末四位为 1234record_b 为 1235但 name 拼音完全一致且 region 同属浦东新区建议 review”所有功能均服务于同一目标让信息科同事在点击“正式执行合并”按钮前能确切知道这个 0.85 是怎么来的它会让多少人被合进错误档案哪些关键字段不一致却仍被建议 merge有没有漏掉本该合并的双胞胎患者使用与配置流程整个使用过程分为三步准备数据 → 扫描验证 → 报告研判。无安装依赖外的额外步骤。首先确保你有一份符合要求的模拟患者数据 CSV字段必须包含name,id_card,phone,region四者缺一不可。region字段应为国家统计局标准的六位行政区划代码如310115代表上海市浦东新区非文字描述。示例数据已内置在data/mock_patients.csv中。接着根据验证目标选择命令python -m src.cli scan --input data/mock_patients.csv --threshold 0.85该命令运行后会在output/下生成类似scan_20240615_0.85.csv的文件其中每行是一对可能匹配的患者记录并附带评分与动作建议。若需全面评估参数影响运行python -m src.cli threshold-curve --input data/mock_patients.csv默认在 0.60–0.95 区间以 0.01 步长扫描输出threshold_curve_20240615.csv可用 Excel 或 Python pandas 快速绘图观察拐点。最后将任一扫描结果传给 report 命令生成可读报告python -m src.cli report --input-scan-result-csv output/scan_20240615_0.85.csv报告文本会按conflict_flagTrue和suggested_actionreview分类汇总并标注每组记录的关键差异字段便于信息科集中核查。全部规则逻辑定义在rules/sample_match_rules.json中采用简洁 JSON 格式支持对similarity_score、id_card_match、phone_match、region_match、birth_date_diff_days等变量做布尔组合判断。修改后无需重启或重编译下次扫描即生效。数据字段与语义说明输入字段虽仅四列但每一列都承担明确语义角色不可随意替换或省略字段名是否必填说明示例值name是患者中文姓名用于拼音转换与编辑距离计算张三丰id_card是18 位身份证号用于精确比对与末位校验310115199003071234phone是11 位手机号用于格式标准化后比对13800138000region是六位行政区划代码用于地理层级归并控制310115输出字段共五项全部在 CSV 中明确定义record_a,record_b原始 CSV 中的行索引从 0 开始标识哪两条记录参与比对similarity_score0.0–1.0 浮点数综合得分越高表示越可能为同一人suggested_action字符串取值为merge自动合并、review需人工确认、new确认为新患者conflict_flag布尔值True表示存在关键字段矛盾如 id_card 完全不同但 name 拼音高度相似需优先关注。注意similarity_score不是概率值也不代表置信度百分比而是归一化后的相对可比分数。其绝对数值无业务意义真正有价值的是同一数据集下不同阈值间的排序关系与分布形态。工程结构与可扩展性项目采用清晰分层结构便于理解与二次开发目录/文件职责说明src/cli.py统一入口定义 scan / threshold-curve / report 三条命令及其参数解析src/matcher.py核心匹配引擎封装 rapidfuzz 调用、拼音转换、行政区划校验、日期差计算等逻辑src/rule_engine.py规则 DSL 解析器将 JSON 规则编译为可执行条件函数rules/sample_match_rules.json默认规则模板开箱即用支持按院区、科室、年龄段定制分支逻辑data/mock_patients.csv内置测试数据含常见歧义场景同音不同字、身份证升位、手机号运营商变更等output/所有输出文件默认落目录含 CSV 与 TXT命名含时间戳防覆盖如需扩展新的相似度维度如住址街道级模糊匹配只需在src/matcher.py中新增计算函数并在评分聚合处加入权重系数如需对接其他主数据标准如 HL7 FHIR Patient Resource可在输入适配层增加 parser 模块不侵入核心匹配逻辑。环境与运行要求本项目对运行环境要求极简仅需标准 Python 运行时与基础依赖依赖项版本要求用途说明Python3.10 或更高运行时基础利用类型提示与结构化异常处理提升健壮性rapidfuzz≥ 3.0.0提供高性能编辑距离与拼音相似度计算内置 pypinyinpydantic≥ 2.0.0对输入 CSV 行做字段校验与类型强制转换防止空值/非法格式中断流程click≥ 8.0.0构建可发现、可嵌套、带自动 help 的命令行接口安装只需一行命令无编译环节Windows/macOS/Linux 全平台一致pip install -r requirements.txt首次运行建议先用内置数据走通全流程python -m src.cli threshold-curve --input data/mock_patients.csv若遇到ModuleNotFoundError请确认是否在项目根目录执行即src/与data/目录同级若提示pypinyin缺失请检查 rapidfuzz 安装是否完整部分镜像源需手动指定--no-deps后单独装。项目地址https://github.com/nexorin9/mpi-matching-simulator