[开源] 科室二次分配公平感模拟器：用博弈论算出护士长敢拍板的奖金方案，让夜班、年资、技术难度全进模型
本项目是一个面向临床科室管理者的决策支持工具，专为解决护理单元、急诊科、外科等一线科室在绩效二次分配中“凭经验难服众、按平均没激励、看年资欠公平”的典型困境而设计。我们把 Shapley 值（合作博弈中的边际贡献量化）、基尼系数（收入分配离散度）、纳什均衡（稳定不背叛的分配状态）三套数学逻辑封装进一个可本地运行的 Python 工具里，输入一张含姓名、岗位、年资、夜班占比、技术难度和贡献分的 CSV 表，就能输出带洛伦兹曲线、抱怨风险热力图、多方案公平感评分对比的 HTML 报告。它不是 Web SaaS，不上传数据；不是 Excel 插件，不依赖人工拖拽；而是命令行驱动的 CLI 工具（也支持交互式向导），核心模块全部开源可审，技术栈聚焦 nashpy、scipy、matplotlib 和 Jinja2，所有计算在本地完成，输出即用。
定位与能力范围
我们不做全院级薪酬系统，也不碰一次分配规则，那是人事科和财务科的权限。我们专注在「科室主任或护士长拿到一笔已核定的绩效总额后，如何在组内 5–15 人之间拆得既合规又服众」这一窄而深的环节。这个环节没有标准答案，但有可量化的公平边界：有人觉得按年资分最稳，有人主张技术难度该加权，还有人强调夜班多的人必须多拿。传统做法靠开会、投票、折中，结果常是“表面同意、背后嘀咕”。本项目把这层模糊共识翻译成数学语言：用 Shapley 值算每个人对科室整体产出的实际边际贡献，用基尼系数衡量每种分配方案下的结果离散程度，再用 nashpy 求解纳什均衡点，即没人单方面改变策略（比如要求重分）能让自己更满意的状态。三者叠加，不是给出唯一答案，而是标出哪些方案落在“数学上稳定+统计上公平”的交集区，并明确提示谁可能成为高风险抱怨对象。
这不是理论玩具。3 组示例数据已覆盖典型场景：内科五区（5人小团队，适合快速验证逻辑）、外科十区（10人标准配置，含护师/护士/技术员多岗）、急诊科（15人高强度轮值，夜班比重大、技术难度梯度宽）。每组数据都包含bonus_total（总金额）、night_shift_ratio（夜班占比）、technical_difficulty（技术难度系数）等真实字段，直接运行即可看到完整报告。
核心功能
我们把“公平感”拆解为可计算、可对比、可归因的四个动作：
- 公平感指数生成
：对每种分配策略（平均、年资加权、技术难度加权、夜班权重加权），同步输出三项指标：Shapley 值（反映个体不可替代性）、基尼系数（越接近 0 越平均，0.4 是常见警戒线）、纳什稳定性得分（1.0 表示完全均衡，低于 0.7 视为易引发博弈反弹）
- 方案自动比对
：不只列数字，而是生成横向表格，直观显示同一组人用不同策略分到的金额、对应公平感三项指标、以及相对均值的偏离幅度（如“张三在夜班权重方案中比平均分配多得 12.3%，但其夜班占比达 38%”）
- 抱怨风险定位
：基于成员对自身贡献的认知偏差（contribution_score 与实际分配额的残差）、与其他人的横向比较落差（如年资 8 年却分得低于年资 5 年者），预测高概率表达不满的成员名单，并按风险等级标注（高/中/低）
- HTML 可视化交付
：一键生成含交互元素的静态报告，包括洛伦兹曲线（直观展示分配偏移）、公平感雷达图（四策略并排对比）、抱怨风险热力图（横轴为成员，纵轴为风险维度，色块深浅表强度）
这些能力不是堆砌，而是环环相扣：Shapley 值决定“谁该多拿”，基尼系数约束“多拿不能太离谱”，纳什均衡确保“分完没人想掀桌子”，风险预测则提前划出沟通重点，让护士长在宣布方案前，就知道该单独找谁聊哪一条。
使用与配置
你不需要懂博弈论也能用。整个流程就三步：准备数据、选择模式、查看报告。
数据准备（只需一个 CSV）
字段必须严格匹配，但无需手动录入。项目自带src/data_generator.py，运行一次就在data/下生成三组真实结构的示例文件。你也可以基于以下字段新建 CSV（UTF-8 编码，逗号分隔）：
字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
department_name | 是 | 科室全称，用于报告标题 | 急诊科 |
bonus_total | 是 | 本次可分配总金额（元） | 24797.76 |
name | 是 | 成员真实姓名 | 王五 |
position | 否 | 岗位类型，影响默认权重 | 护士长/护师/护士/技术员/行政 |
seniority | 否 | 年资（年），用于年资加权策略 | 12 |
contribution_score | 是 | 主管评定的相对贡献分（0–1 区间） | 1.0 |
night_shift_ratio | 否 | 近期夜班占总班次比例（0–1） | 0.3 |
technical_difficulty | 否 | 所承担操作/病种的技术难度系数（≥1.0） | 1.2 |
运行方式（两种入口）
推荐新手从交互式向导开始，它会逐项提示输入路径、选择策略、确认参数：
python main.py --interactive熟悉后可直接命令行调用，例如分析外科十区数据并生成报告：
python main.py --data data/sample_department_10.csv --report常用参数组合如下：
参数 | 作用 | 示例 |
|---|---|---|
--data <file> | 指定输入 CSV | --data data/sample_department_15.csv |
--scheme <name> | 锁定某一分配策略 | --scheme night_shift_weighted |
--report | 生成 HTML 报告（默认存 | --report |
--output <dir> | 自定义输出目录 | --output ./my_reports |
--verbose | 输出详细计算过程（调试用） | --verbose |
工程结构
我们按职责切分模块，每个.py文件只做一件事，方便临床管理者或信息科同事按需查阅或二次开发：
模块文件 | 职责 | 关键能力 |
|---|---|---|
fairness_engine.py | 公平感主引擎 | 整合 Shapley 值、基尼系数、纳什均衡三路计算，输出统一评分接口 |
game_theory_engine.py | 博弈论专用层 | 封装 nashpy，将成员贡献矩阵转为收益矩阵，求解混合策略纳什均衡 |
distribution_generator.py | 分配策略实现 | 内置平均、年资、技术难度、夜班权重四种算法，支持自定义公式注入 |
satisfaction_predictor.py | 风险建模 | 基于贡献分残差、横向比较差、岗位敏感度三因子加权预测抱怨概率 |
report_generator.py | 报告组装 | Jinja2 渲染 HTML，嵌入 matplotlib 图表及结构化数据表格 |
cli.py | 命令行胶水 | 解析参数、调度流程、rich 输出进度与结果摘要 |
所有模块通过analyzer.py串联，main.py仅作入口，无业务逻辑。这意味着：如果你只想复用 Shapley 计算，直接 importfairness_engine即可；如果医院已有内部数据平台，只需替换data_models.py中的读取逻辑，其余模块无缝对接。
环境与运行
本项目对运行环境要求极简，不依赖 GPU、不连数据库、不启服务进程。只要你的电脑装了 Python 3.10 或更高版本，就能跑起来：
pip install -r requirements.txt依赖库全部来自 PyPI 官方源，无私有包或编译障碍： -nashpy：提供纳什均衡求解器（核心博弈能力） -scipy：支撑 Shapley 值的数值积分与排列组合计算 -matplotlib：生成洛伦兹曲线、雷达图等交付图表 -rich：让命令行输出带颜色、进度条、表格，提升 CLI 可用性 -Jinja2：将计算结果注入 HTML 模板，生成即用报告
Windows、macOS、Linux 全平台支持。无后台进程，无网络外连（除非你主动加了打赏链接），所有中间数据留在本地，符合医疗数据不出域的基本要求。
数据与扩展
示例数据不是摆设。data/目录下三组 CSV 已按真实科室逻辑构造：
-sample_department_5.csv：内科五区，5人，岗位单一（均为护士），年资跨度小（3–7年），适合验证基础逻辑
-sample_department_10.csv：外科十区，10人，含护士长、护师、护士、技术员四类岗位，夜班比差异大（0.1–0.4），技术难度系数拉到 1.0–1.5，是主力测试场景
-sample_department_15.csv：急诊科，15人，岗位最杂（含行政协调岗），夜班占比普遍超 0.3，技术难度系数出现 1.8 的极端值，考验模型鲁棒性
字段设计遵循临床管理习惯：contribution_score不强制要求量化到小数点后两位，0.8 和 0.82 在模型中无本质区别；night_shift_ratio支持 0.33 这样的近似值，不必精确到班次计数；technical_difficulty允许按病种分级（如气管插管=1.5，静脉采血=1.0）或按设备复杂度赋值。你甚至可以删掉seniority字段，模型会自动降级为仅用贡献分+夜班+技术难度三因子运算，边界清晰，不强求全量数据。
项目地址：
https://github.com/nexorin9/department-bonus-fairness-simulator