chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e5c82b1a954a05ba1dd3cd224698a1472531059d
hospital_performance/.qoder/repowiki/zh/content/数据库设计/数据字典/数据字典.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

25 KiB
Raw Blame History

数据字典

**本文档引用的文件** - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/models/finance.py](file://backend/app/models/finance.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py) - [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py) - [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py) - [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py) - [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py) - [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py) - [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py) - [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py) - [backend/app/services/department_service.py](file://backend/app/services/department_service.py) - [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py) - [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py) - [backend/app/services/template_service.py](file://backend/app/services/template_service.py) - [docs/database.md](file://docs/database.md)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介

本数据字典面向医院绩效管理系统，系统围绕“科室—员工—考核—工资—财务”主线构建，涵盖指标管理、计划管理、模板管理、财务核算等模块。本文档从字段层面梳理每个实体的数据定义（业务含义、数据类型、长度/精度限制、取值范围、默认值），明确枚举类型及其使用场景，阐述字段与业务实体的对应关系，给出数据流转过程，并提供维护更新规范与查询使用指南。

项目结构

系统采用前后端分离架构，后端基于FastAPI + SQLAlchemy，采用分层设计（API → Service → Model），前端Vue3 + Vite。数据库采用SQLite（开发环境），通过Alembic进行版本化迁移。

graph TB
FE["前端界面<br/>Vue3 + Vite"] --> API["后端API<br/>FastAPI"]
API --> SVC["服务层<br/>各模块Service"]
SVC --> MODELS["模型层<br/>SQLAlchemy ORM"]
MODELS --> DB["数据库<br/>SQLite"]

图表来源

章节来源

核心组件

  • 数据模型层：定义实体、字段、约束、索引、枚举类型
  • 模式层（Pydantic）：定义API输入输出结构、字段校验规则
  • API层：定义REST接口、参数、返回结构
  • 服务层：封装业务逻辑、事务处理、数据聚合

章节来源

架构概览

系统围绕“绩效考核—工资核算—财务分析”的主流程展开，指标与模板驱动考核，考核结果驱动工资生成，财务模块提供收支与结余分析。

graph TB
subgraph "基础数据"
DEPT["科室表<br/>departments"]
STAFF["员工表<br/>staff"]
USERS["用户表<br/>users"]
end
subgraph "指标与计划"
IND["指标表<br/>indicators"]
TPL["模板表<br/>indicator_templates"]
TIND["模板指标关联<br/>template_indicators"]
PLAN["绩效计划表<br/>performance_plans"]
REL["计划指标关联<br/>plan_kpi_relations"]
end
subgraph "考核与工资"
ASSESS["考核记录表<br/>assessments"]
DETAIL["考核明细表<br/>assessment_details"]
SAL["工资记录表<br/>salary_records"]
end
subgraph "财务"
FIN["科室财务记录<br/>department_finances"]
end
DEPT <-- "1:N" --> STAFF
STAFF <-- "N:1" --> DEPT
STAFF <-- "N:1" --> USERS
IND <-- "N:1" --> DETAIL
ASSESS <-- "1:N" --> DETAIL
DETAIL <-- "N:1" --> IND
PLAN <-- "1:N" --> REL
REL <-- "N:1" --> IND
STAFF <-- "N:1" --> ASSESS
STAFF <-- "N:1" --> SAL
DEPT <-- "N:1" --> FIN

图表来源

详细组件分析

1) 基础数据实体

1.1 科室表 departments

  • 字段定义
    • id: 整型, 主键, 自增
    • name: 字符串, 长度100, 非空, 说明: 科室名称
    • code: 字符串, 长度20, 唯一, 非空, 说明: 科室编码
    • dept_type: 枚举, 非空, 说明: 科室类型
    • parent_id: 整型, 外键, 说明: 上级科室
    • level: 整型, 默认1, 说明: 层级
    • sort_order: 整型, 默认0, 说明: 排序
    • is_active: 布尔, 默认true, 说明: 是否启用
    • description: 文本, 说明: 描述
    • created_at/updated_at: 时间戳, 说明: 创建/更新时间
  • 约束与索引
    • 唯一键: code
    • 索引: idx_dept_type, idx_dept_parent
  • 业务含义
    • 支持多级组织架构，支持停用/启用；用于员工归属、计划/模板适用范围等
  • 默认值与取值范围
    • level: 1-5
    • sort_order: 任意整数
    • is_active: true/false
  • 使用场景
    • 员工入职时绑定科室；计划/模板按科室类型筛选适用范围

章节来源

1.2 员工表 staff

  • 字段定义
    • id: 整型, 主键, 自增
    • employee_id: 字符串, 长度20, 唯一, 非空, 说明: 工号
    • name: 字符串, 长度50, 非空, 说明: 姓名
    • department_id: 整型, 外键, 非空, 说明: 所属科室
    • position: 字符串, 长度50, 非空, 说明: 职位
    • title: 字符串, 长度50, 说明: 职称
    • phone/email: 字符串, 长度20/100, 说明: 联系方式
    • base_salary: 数值, 精度(10,2), 默认0, 说明: 基本工资
    • performance_ratio: 数值, 精度(5,2), 默认1.0, 说明: 绩效系数
    • status: 枚举, 默认active, 说明: 员工状态
    • hire_date: 时间戳, 说明: 入职日期
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 唯一键: employee_id
    • 索引: idx_staff_dept, idx_staff_status
  • 业务含义
    • 基于基本工资与绩效系数计算绩效奖金；参与考核与工资生成
  • 默认值与取值范围
    • base_salary ≥ 0
    • 0 ≤ performance_ratio ≤ 5
  • 使用场景
    • 薪资计算、部门统计、计划责任人

章节来源

1.3 用户表 users

  • 字段定义
    • id: 整型, 主键, 自增
    • username: 字符串, 长度50, 唯一, 非空, 说明: 用户名
    • password_hash: 字符串, 长度255, 非空, 说明: 密码哈希
    • staff_id: 整型, 外键, 说明: 关联员工
    • role: 字符串, 长度20, 默认staff, 说明: 角色
    • is_active: 布尔, 默认true, 说明: 是否启用
    • last_login: 时间戳, 说明: 最后登录
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 唯一键: username
    • 索引: idx_user_username
  • 业务含义
    • 系统访问控制与权限管理的基础

章节来源

2) 指标与模板

2.1 指标表 indicators

  • 字段定义
    • id: 整型, 主键, 自增
    • name/code: 字符串, 长度100/20, 唯一, 非空, 说明: 指标名称/编码
    • indicator_type: 枚举, 非空, 说明: 指标类型
    • bs_dimension: 枚举, 非空, 说明: 平衡计分卡维度
    • weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
    • max_score: 数值, 精度(5,2), 默认100, 说明: 最高分值
    • target_value/target_unit: 数值/字符串, 说明: 目标值与单位
    • calculation_method/assessment_method/deduction_standard/data_source: 文本, 说明: 计算/考核/扣分/数据来源
    • applicable_dept_types: 文本(JSON数组), 说明: 适用科室类型
    • is_veto: 布尔, 默认false, 说明: 是否一票否决
    • is_active: 布尔, 默认true, 说明: 是否启用
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 约束: weight > 0
    • 索引: idx_indicator_type
  • 业务含义
    • 考核的最小颗粒，决定评分与权重；支持JSON存储适用范围
  • 默认值与取值范围
    • weight > 0
    • max_score ≥ 0
  • 使用场景
    • 考核打分、计划目标设定、模板匹配

章节来源

2.2 指标模板表 indicator_templates

  • 字段定义
    • id: 整型, 主键, 自增
    • template_name/code: 字符串, 长度200/50, 唯一, 非空
    • template_type: 枚举, 非空, 说明: 模板类型
    • description: 文本, 说明: 模板描述
    • dimension_weights: 文本(JSON), 说明: 维度权重
    • assessment_cycle: 字符串, 长度20, 默认monthly, 说明: 考核周期
    • is_active: 布尔, 默认true
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_template_type, idx_template_active
  • 业务含义
    • 为不同科室类型提供标准化指标集合，支持批量导入

章节来源

2.3 模板指标关联表 template_indicators

  • 字段定义
    • id: 整型, 主键, 自增
    • template_id/indicator_id: 整型, 外键, 非空, 说明: 模板与指标
    • category: 字符串, 长度100, 说明: 指标分类(二级指标)
    • target_value/target_unit: 数值/字符串, 说明: 目标值与单位
    • weight: 数值, 精度(5,2), 默认1.0
    • scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
    • sort_order: 整型, 默认0, 说明: 排序
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_ti_template, idx_ti_indicator, idx_ti_unique(模板+指标唯一)
  • 业务含义
    • 将指标纳入模板，支持排序与评分参数配置

章节来源

3) 考核与工资

3.1 考核记录表 assessments

  • 字段定义
    • id: 整型, 主键, 自增
    • staff_id: 整型, 外键, 非空, 说明: 被考核员工
    • period_year/period_month: 整型, 非空, 说明: 考核年度/月份
    • period_type: 字符串, 长度20, 默认monthly, 说明: 周期类型
    • total_score/weighted_score: 数值, 精度(5,2), 默认0, 说明: 总分/加权得分
    • status: 枚举, 默认draft, 说明: 状态
    • assessor_id/reviewer_id: 整型, 外键, 说明: 考核人/审核人
    • submit_time/review_time: 时间戳, 说明: 提交/审核时间
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_assessment_staff, idx_assessment_period, idx_assessment_status
  • 业务含义
    • 记录一次完整的考核流程，支持草稿、提交、审核、确认、驳回

章节来源

3.2 考核明细表 assessment_details

  • 字段定义
    • id: 整型, 主键, 自增
    • assessment_id/indicator_id: 整型, 外键, 非空
    • actual_value: 数值, 精度(10,2), 说明: 实际值
    • score: 数值, 精度(5,2), 默认0, 说明: 得分
    • evidence: 文本, 说明: 佐证材料
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_detail_assessment, idx_detail_indicator
  • 业务含义
    • 记录每个指标的得分与实际值，支撑总分与加权得分计算

章节来源

3.3 工资记录表 salary_records

  • 字段定义
    • id: 整型, 主键, 自增
    • staff_id: 整型, 外键, 非空
    • period_year/period_month: 整型, 非空
    • base_salary/performance_score/performance_bonus/deduction/allowance: 数值, 精度(10,2)/(5,2), 默认0, 说明: 基本工资/绩效得分/绩效奖金/扣款/补贴
    • total_salary: 数值, 精度(10,2), 默认0, 说明: 应发工资
    • status: 字符串, 长度20, 默认pending, 说明: 状态
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_salary_staff, idx_salary_period
  • 业务含义
    • 基于考核结果生成工资，支持确认与批量确认

章节来源

4) 绩效计划

4.1 绩效计划表 performance_plans

  • 字段定义
    • id: 整型, 主键, 自增
    • plan_name/code: 字符串, 长度200/50, 唯一, 非空
    • plan_level: 枚举, 非空, 说明: 计划层级(hospital/department/individual)
    • plan_year/plan_month: 整型/可选, 说明: 年度/月份
    • plan_type: 字符串, 长度20, 默认annual, 说明: 计划类型(annual/monthly)
    • department_id/staff_id: 整型/可选, 外键, 说明: 所属科室/责任人
    • parent_plan_id: 整型, 外键, 说明: 上级计划
    • description/strategic_goals/key_initiatives: 文本, 说明: 描述/战略目标/关键举措
    • status: 枚举, 默认draft, 说明: 状态
    • submitter_id/approver_id: 整型, 外键, 说明: 提交人/审批人
    • submit_time/approve_time: 时间戳, 说明: 提交/审批时间
    • approve_remark: 文本, 说明: 审批意见
    • version: 整型, 默认1, 说明: 版本号
    • is_active: 布尔, 默认true, 说明: 是否启用
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_plan_level, idx_plan_year, idx_plan_department, idx_plan_status
  • 业务含义
    • 支持医院/科室/个人三级计划，支持父子计划与审批流程

章节来源

4.2 计划指标关联表 plan_kpi_relations

  • 字段定义
    • id: 整型, 主键, 自增
    • plan_id/indicator_id: 整型, 外键, 非空
    • target_value/target_unit: 数值/字符串, 说明: 目标值与单位
    • weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
    • scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 索引: idx_relation_plan, idx_relation_indicator, idx_relation_unique(计划+指标唯一)
  • 业务含义
    • 将指标纳入具体计划，支持目标与权重配置

章节来源

5) 财务核算

5.1 科室财务记录表 department_finances

  • 字段定义
    • id: 整型, 主键, 自增
    • department_id: 整型, 外键, 非空
    • period_year/period_month: 整型, 非空
    • finance_type: 枚举, 非空, 说明: 收入/支出
    • category: 字符串, 长度50, 非空, 说明: 类别
    • amount: 数值, 精度(12,2), 默认0, 说明: 金额
    • source: 字符串, 长度100, 说明: 数据来源
    • remark: 文本, 说明: 备注
    • created_at/updated_at: 时间戳
  • 约束与索引
    • 约束: amount ≥ 0
    • 索引: idx_finance_dept, idx_finance_period, idx_finance_type, idx_finance_category
  • 业务含义
    • 记录各科室的收支明细，支持按类别统计与结余计算

章节来源

6) 枚举类型与取值范围

  • 科室类型 DeptType

    • 取值: clinical_surgical, clinical_nonsurgical_ward, clinical_nonsurgical_noward, medical_tech, medical_auxiliary, nursing, admin, finance, logistics
    • 用途: 控制模板与计划适用范围

  • 员工状态 StaffStatus

    • 取值: active, leave, resigned, retired

  • 考核状态 AssessmentStatus

    • 取值: draft, submitted, reviewed, finalized, rejected

  • 指标类型 IndicatorType

    • 取值: quality, quantity, efficiency, service, cost

  • 计划层级 PlanLevel

    • 取值: hospital, department, individual

  • 计划状态 PlanStatus

    • 取值: draft, pending, approved, rejected, active, completed, cancelled

  • 菜单类型 MenuType

    • 取值: menu, button

  • 模板类型 TemplateType

    • 取值: general, surgical, nonsurgical_ward, nonsurgical_noward, medical_tech, nursing, admin, logistics

  • 财务类型 FinanceType

    • 取值: revenue, expense

  • 收入类别 RevenueCategory

    • 取值: examination, lab_test, radiology, bed, nursing, treatment, surgery, injection, oxygen, other

  • 支出类别 ExpenseCategory

    • 取值: material, personnel, maintenance, utility, other

章节来源

7) 数据流转说明

7.1 考核到工资的流程

sequenceDiagram
participant API as "API"
participant Svc as "SalaryService"
participant DB as "数据库"
API->>Svc : "根据考核生成工资"
Svc->>DB : "查询已确认的考核记录"
DB-->>Svc : "返回考核与明细"
Svc->>Svc : "计算绩效得分/奖金"
Svc->>DB : "写入工资记录"
DB-->>Svc : "返回记录ID"
Svc-->>API : "生成成功"

图表来源

7.2 财务收支统计流程

flowchart TD
Start(["开始"]) --> Fetch["查询科室收支记录"]
Fetch --> Group["按类别分组统计"]
Group --> Sum["计算合计"]
Sum --> Balance["结余 = 收入合计 - 支出合计"]
Balance --> End(["结束"])

图表来源

依赖分析

graph LR
STAFF["staff"] --> DEPT["departments"]
STAFF --> USERS["users"]
ASSESS["assessments"] --> STAFF
ASSESS --> DETAIL["assessment_details"]
DETAIL --> IND["indicators"]
SAL["salary_records"] --> STAFF
PLAN["performance_plans"] --> DEPT
PLAN --> STAFF
PLAN --> REL["plan_kpi_relations"]
REL --> IND
TPL["indicator_templates"] --> TIND["template_indicators"]
TIND --> IND
FIN["department_finances"] --> DEPT

图表来源

章节来源

性能考虑

  • 索引策略
    • 对常用过滤字段建立索引（如科室类型、状态、周期、部门）
    • 对外键字段建立索引，减少连接开销
  • 查询优化
    • 使用selectinload预加载关联对象，避免N+1查询
    • 分页查询配合COUNT子查询，避免全表扫描
  • 数据类型选择
    • 数值使用Decimal保证精度；字符串使用VARCHAR并设置合理上限
  • 缓存建议
    • 对静态枚举与模板列表可做内存缓存，降低数据库压力

故障排除指南

  • 常见错误与定位
    • “指标/模板/科室编码已存在”：检查唯一约束冲突
    • “无法删除，存在子记录”：先清理子项再删除
    • “无法生成/确认工资”：检查考核状态与重复生成
    • “无效的类别”：确认财务类别枚举值
  • 排查步骤
    • 查看API返回状态码与错误信息
    • 检查数据库约束与索引是否生效
    • 核对枚举值是否在允许范围内
    • 使用服务层日志定位业务流程异常点

章节来源

结论

本数据字典系统性梳理了医院绩效管理系统的数据结构与业务规则，明确了字段定义、枚举取值、默认值与约束、索引策略与使用场景，并给出了数据流转与维护规范。建议在后续迭代中持续完善字段注释、扩展审计字段、引入字段变更追踪机制，确保数据治理的可追溯性与一致性。

附录

A. 字段与业务实体对应关系

  • 科室 → 员工：一对多
  • 员工 → 考核：一对多
  • 考核 → 明细：一对多
  • 明细 → 指标：多对一
  • 员工 → 工资：一对多
  • 计划 → 指标：多对多（通过plan_kpi_relations）
  • 模板 → 指标：多对多（通过template_indicators）
  • 科室 → 财务：一对多

章节来源

B. 数据字典维护与更新规范

  • 新增字段
    • 在模型层定义字段与约束，补充Pydantic模式
    • 在API层增加参数校验与默认值
    • 在服务层处理字段映射与业务逻辑
    • 更新数据库迁移脚本并升级数据库
  • 修改字段
    • 评估兼容性与影响范围
    • 通过迁移脚本安全变更，保留历史数据
    • 更新API与模式校验规则
  • 删除字段
    • 确认无业务依赖后，通过迁移脚本删除
    • 清理相关API与服务逻辑

C. 数据字典查询与使用指南

  • 基础查询
    • 通过API参数过滤（如科室类型、状态、周期）
    • 使用分页参数控制返回数量
  • 高级查询
    • 结合多个条件组合查询
    • 使用树形结构查询科室层级
  • 数据导出
    • 指标与模板支持批量导入/导出
    • 财务模块支持按类别统计与汇总

章节来源