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

20 KiB
Raw Blame History

基础数据字段

**本文引用的文件** - [models.py](file://backend/app/models/models.py) - [finance.py](file://backend/app/models/finance.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [001_initial.py](file://backend/alembic/versions/001_initial.py) - [002_template.py](file://backend/alembic/versions/002_template.py) - [database.md](file://docs/database.md) - [departments.py](file://backend/app/api/v1/departments.py) - [staff.py](file://backend/app/api/v1/staff.py)

目录

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

简介

本文件聚焦于基础数据字段的详细数据字典，覆盖以下核心表：

  • 科室信息表（Department）
  • 员工信息表（Staff）
  • 用户表（User）

同时补充与基础数据强相关的财务记录表（DepartmentFinance）字段说明，以及与字段相关的枚举类型、索引设计、约束与业务规则。文档提供字段定义、类型与长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、字段间关联关系与外键约束、索引设计与性能考虑，并给出实际使用示例与最佳实践建议。

项目结构

本项目采用前后端分离架构，后端基于 FastAPI + SQLAlchemy ORM，数据库迁移使用 Alembic。基础数据模型集中在 models 模块，API 路由位于 app/api/v1 下，数据字典与 ER 图见 docs/database.md。

graph TB
subgraph "后端"
A["models.py<br/>数据模型"]
B["finance.py<br/>财务模型"]
C["schemas.py<br/>Pydantic模式"]
D["alembic 迁移<br/>001_initial.py / 002_template.py"]
E["API 路由<br/>departments.py / staff.py"]
end
subgraph "文档"
F["docs/database.md<br/>ER图与字段说明"]
end
A --> D
B --> D
C --> E
E --> A
F --> A

图表来源

章节来源

核心组件

  • 科室信息表（Department）
  • 员工信息表（Staff）
  • 用户表（User）
  • 科室财务记录表（DepartmentFinance）

章节来源

架构总览

基础数据字段与业务流程的关系如下：

  • Department 与 Staff 为 1:N 关系（部门-员工）
  • Staff 与 User 为 N:1 关系（员工-用户）
  • DepartmentFinance 与 Department 为 1:N 关系（科室-财务记录）
erDiagram
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
boolean is_active
text description
datetime created_at
datetime updated_at
}
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
decimal base_salary
decimal performance_ratio
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
USERS {
int id PK
string username UK
string password_hash
int staff_id FK
string role
boolean is_active
datetime last_login
datetime created_at
datetime updated_at
}
DEPARTMENT_FINANCES {
int id PK
int department_id FK
int period_year
int period_month
enum finance_type
string category
decimal amount
string source
text remark
datetime created_at
datetime updated_at
}
DEPARTMENTS ||--o{ STAFF : "1:N"
STAFF ||--o{ USERS : "N:1"
DEPARTMENTS ||--o{ DEPARTMENT_FINANCES : "1:N"

图表来源

详细组件分析

科室信息表（Department）

  • 表名：departments
  • 主键：id（自增整数）
  • 唯一键：code（唯一）
  • 外键：parent_id 引用 departments.id（自关联，表示上级科室）
  • 索引：idx_dept_type、idx_dept_parent
  • 枚举：dept_type（来自 DeptType）

字段定义与规则

  • id
    • 类型：整数（主键）
    • 约束：自增、非空
    • 默认值：无
    • 业务含义：科室唯一标识
    • 取值范围：正整数
    • 注释：主键
    • 关联关系：parent_id 自关联指向自身
    • 索引：PK
  • name
    • 类型：字符串（最大长度 100）
    • 约束：非空
    • 默认值：无
    • 业务含义：科室名称
    • 取值范围：长度不超过 100
    • 注释：科室名称
  • code
    • 类型：字符串（最大长度 20）
    • 约束：唯一、非空
    • 默认值：无
    • 业务含义：科室编码（全局唯一）
    • 取值范围：长度不超过 20
    • 注释：科室编码
    • 索引：UK
  • dept_type
    • 类型：枚举（DeptType）
    • 约束：非空
    • 默认值：无
    • 业务含义：科室类型
    • 取值范围：clinical_surgical、clinical_nonsurgical_ward、clinical_nonsurgical_noward、medical_tech、medical_auxiliary、nursing、admin、finance、logistics
    • 注释：科室类型
    • 索引：idx_dept_type
  • parent_id
    • 类型：整数
    • 约束：可空，外键引用 departments.id
    • 默认值：空
    • 业务含义：上级科室 ID（自关联）
    • 取值范围：对应存在的 id 或空
    • 注释：上级科室
    • 索引：idx_dept_parent
  • level
    • 类型：整数
    • 约束：默认 1
    • 默认值：1
    • 业务含义：层级（1-5）
    • 取值范围：1-5
    • 注释：层级
  • sort_order
    • 类型：整数
    • 约束：默认 0
    • 默认值：0
    • 业务含义：排序
    • 注释：排序
  • is_active
    • 类型：布尔
    • 约束：默认 true
    • 默认值：true
    • 业务含义：是否启用
    • 注释：是否启用
  • description
    • 类型：文本
    • 约束：可空
    • 默认值：空
    • 业务含义：描述
    • 注释：描述
  • created_at / updated_at
    • 类型：日期时间
    • 约束：默认当前时间；更新时自动更新
    • 默认值：无
    • 业务含义：创建/更新时间
    • 注释：创建时间、更新时间

业务规则与最佳实践

  • 编码唯一性：code 必须全局唯一，新增前需校验重复
  • 层级与排序：level 与 sort_order 用于树形展示与排序
  • 自关联：parent_id 支持多级组织架构，查询时注意避免环路
  • 索引：dept_type 与 parent_id 建议在过滤与树形查询中使用

章节来源

员工信息表（Staff）

  • 表名：staff
  • 主键：id（自增整数）
  • 唯一键：employee_id（唯一）
  • 外键：department_id 引用 departments.id
  • 索引：idx_staff_dept、idx_staff_status
  • 枚举：status（来自 StaffStatus）

字段定义与规则

  • id
    • 类型：整数（主键）
    • 约束：自增、非空
    • 默认值：无
    • 业务含义：员工唯一标识
    • 注释：主键
  • employee_id
    • 类型：字符串（最大长度 20）
    • 约束：唯一、非空
    • 默认值：无
    • 业务含义：工号（唯一）
    • 取值范围：长度不超过 20
    • 注释：工号
    • 索引：UK
  • name
    • 类型：字符串（最大长度 50）
    • 约束：非空
    • 默认值：无
    • 业务含义：姓名
    • 取值范围：长度不超过 50
    • 注释：姓名
  • department_id
    • 类型：整数
    • 约束：非空，外键引用 departments.id
    • 默认值：无
    • 业务含义：所属科室
    • 注释：所属科室
    • 索引：idx_staff_dept
  • position
    • 类型：字符串（最大长度 50）
    • 约束：非空
    • 默认值：无
    • 业务含义：职位
    • 取值范围：长度不超过 50
    • 注释：职位
  • title
    • 类型：字符串（最大长度 50）
    • 约束：可空
    • 默认值：空
    • 业务含义：职称
    • 注释：职称
  • phone
    • 类型：字符串（最大长度 20）
    • 约束：可空
    • 默认值：空
    • 业务含义：联系电话
    • 注释：联系电话
  • email
    • 类型：字符串（最大长度 100）
    • 约束：可空
    • 默认值：空
    • 业务含义：邮箱
    • 注释：邮箱
  • base_salary
    • 类型：数值（精度 10，小数 2）
    • 约束：默认 0
    • 默认值：0
    • 业务含义：基本工资
    • 取值范围：≥0
    • 注释：基本工资
  • performance_ratio
    • 类型：数值（精度 5，小数 2）
    • 约束：默认 1.0
    • 默认值：1.0
    • 业务含义：绩效系数（0-5）
    • 取值范围：0-5
    • 注释：绩效系数
  • status
    • 类型：枚举（StaffStatus）
    • 约束：默认 active
    • 默认值：active
    • 业务含义：员工状态
    • 取值范围：active、leave、resigned、retired
    • 注释：状态
    • 索引：idx_staff_status
  • hire_date
    • 类型：日期时间
    • 约束：可空
    • 默认值：空
    • 业务含义：入职日期
    • 注释：入职日期
  • created_at / updated_at
    • 类型：日期时间
    • 约束：默认当前时间；更新时自动更新
    • 默认值：无
    • 业务含义：创建/更新时间
    • 注释：创建时间、更新时间

业务规则与最佳实践

  • 工号唯一性：employee_id 必须唯一，新增前需校验重复
  • 状态枚举：仅允许枚举值，避免脏数据
  • 薪资与系数：base_salary 与 performance_ratio 用于后续绩效工资计算
  • 索引：department_id 与 status 用于筛选与分页

章节来源

用户表（User）

  • 表名：users
  • 主键：id（自增整数）
  • 唯一键：username（唯一）
  • 外键：staff_id 引用 staff.id
  • 索引：idx_user_username

字段定义与规则

  • id
    • 类型：整数（主键）
    • 约束：自增、非空
    • 默认值：无
    • 业务含义：用户唯一标识
    • 注释：主键
  • username
    • 类型：字符串（最大长度 50）
    • 约束：唯一、非空
    • 默认值：无
    • 业务含义：用户名
    • 取值范围：长度不超过 50
    • 注释：用户名
    • 索引：UK
  • password_hash
    • 类型：字符串（最大长度 255）
    • 约束：非空
    • 默认值：无
    • 业务含义：密码哈希
    • 注释：密码哈希
  • staff_id
    • 类型：整数
    • 约束：可空，外键引用 staff.id
    • 默认值：空
    • 业务含义：关联员工
    • 注释：关联员工
  • role
    • 类型：字符串（最大长度 20）
    • 约束：默认 staff
    • 默认值：staff
    • 业务含义：角色
    • 取值范围：admin、manager、staff
    • 注释：角色
  • is_active
    • 类型：布尔
    • 约束：默认 true
    • 默认值：true
    • 业务含义：是否启用
    • 注释：是否启用
  • last_login
    • 类型：日期时间
    • 约束：可空
    • 默认值：空
    • 业务含义：最后登录时间
    • 注释：最后登录
  • created_at / updated_at
    • 类型：日期时间
    • 约束：默认当前时间；更新时自动更新
    • 默认值：无
    • 业务含义：创建/更新时间
    • 注释：创建时间、更新时间

业务规则与最佳实践

  • 用户名唯一性：username 必须唯一
  • 角色枚举：仅允许 admin、manager、staff
  • 关联员工：staff_id 可空，表示未绑定员工的系统用户
  • 登录追踪：last_login 用于审计与安全策略

章节来源

科室财务记录表（DepartmentFinance）

  • 表名：department_finances
  • 主键：id（自增整数）
  • 外键：department_id 引用 departments.id
  • 索引：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category
  • 枚举：finance_type（来自 FinanceType）
  • 约束：amount ≥ 0

字段定义与规则

  • id
    • 类型：整数（主键）
    • 约束：自增、非空
    • 默认值：无
    • 业务含义：财务记录唯一标识
    • 注释：主键
  • department_id
    • 类型：整数
    • 约束：非空，外键引用 departments.id
    • 默认值：无
    • 业务含义：所属科室
    • 注释：科室ID
    • 索引：idx_finance_dept
  • period_year / period_month
    • 类型：整数
    • 约束：非空
    • 默认值：无
    • 业务含义：年度/月份
    • 注释：年度、月份
    • 索引：idx_finance_period
  • finance_type
    • 类型：枚举（FinanceType）
    • 约束：非空
    • 默认值：无
    • 业务含义：财务类型（收入/支出）
    • 取值范围：revenue、expense
    • 注释：财务类型
    • 索引：idx_finance_type
  • category
    • 类型：字符串（最大长度 50）
    • 约束：非空
    • 默认值：无
    • 业务含义：类别（如检查费、床位费等）
    • 取值范围：长度不超过 50
    • 注释：类别
    • 索引：idx_finance_category
  • amount
    • 类型：数值（精度 12，小数 2）
    • 约束：默认 0，且 ≥ 0
    • 默认值：0
    • 业务含义：金额
    • 取值范围：≥0
    • 注释：金额
    • 约束：check(amount >= 0)
  • source
    • 类型：字符串（最大长度 100）
    • 约束：可空
    • 默认值：空
    • 业务含义：数据来源
    • 注释：数据来源
  • remark
    • 类型：文本
    • 约束：可空
    • 默认值：空
    • 业务含义：备注
    • 注释：备注
  • created_at / updated_at
    • 类型：日期时间
    • 约束：默认当前时间；更新时自动更新
    • 默认值：无
    • 业务含义：创建/更新时间
    • 注释：创建时间、更新时间

业务规则与最佳实践

  • 金额非负：通过约束保证 amount ≥ 0
  • 类别与类型：category 与 finance_type 组合用于财务归类与统计
  • 周期聚合：period_year 与 period_month 用于月度/年度汇总

章节来源

依赖分析

  • Department 与 Staff 的关系：1:N（部门-员工），通过 department_id 外键关联
  • Staff 与 User 的关系：N:1（员工-用户），通过 staff_id 外键关联
  • Department 与 DepartmentFinance 的关系：1:N（科室-财务记录），通过 department_id 外键关联
graph LR
DEPT["Department"] --> |FK| STAFF["Staff"]
STAFF --> |FK| USER["User"]
DEPT --> |FK| FIN["DepartmentFinance"]

图表来源

章节来源

性能考量

  • 索引设计
    • Department：idx_dept_type、idx_dept_parent，适合按类型过滤与树形查询
    • Staff：idx_staff_dept、idx_staff_status，适合按科室与状态筛选
    • Assessments：idx_assessment_staff、idx_assessment_period、idx_assessment_status，适合按员工、周期与状态查询
    • SalaryRecords：idx_salary_staff、idx_salary_period，适合按员工与周期查询
    • Users：idx_user_username，适合按用户名登录
    • DepartmentFinance：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category，适合财务统计与聚合
  • 约束与校验
    • Staff.performance_ratio 与 Indicator.weight 使用 Pydantic 校验（ge/le），数据库层使用 CheckConstraint（如 DepartmentFinance.amount ≥ 0）
  • 查询建议
    • 分页与过滤：优先使用带索引的列进行 where 条件与 order by
    • 树形查询：Department.parent_id + level 用于层级展示
    • 聚合统计：DepartmentFinance 按 period_year/month + category + type 聚合

章节来源

故障排查指南

  • 新增科室失败（编码重复）
    • 现象：创建接口返回错误，提示编码已存在
    • 排查：检查 departments.code 是否唯一；确认是否已有相同编码
    • 处理：修改编码或删除冲突记录
  • 新增员工失败（工号重复）
    • 现象：创建接口返回错误，提示工号已存在
    • 排查：检查 staff.employee_id 是否唯一
    • 处理：修改工号或删除冲突记录
  • 删除科室失败（存在子科室）
    • 现象：删除接口返回错误，提示无法删除
    • 排查：确认该科室是否存在子科室（parent_id 指向该 id）
    • 处理：先删除子科室或调整组织架构
  • 薪资/财务金额异常
    • 现象：DepartmentFinance.amount 出现负值
    • 排查：检查数据来源与业务逻辑；确认约束是否生效
    • 处理：修正数据或调整业务流程

章节来源

结论

本文档对基础数据字段进行了系统梳理，明确了字段类型、长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、外键关系与索引设计，并提供了性能考量与故障排查建议。遵循这些字段规范与最佳实践，有助于确保数据一致性、查询性能与业务稳定性。

附录

  • 字段使用示例（示意）
    • 新增科室：提供 name、code、dept_type、parent_id、level、sort_order、is_active、description
    • 新增员工：提供 employee_id、name、department_id、position、title、phone、email、base_salary、performance_ratio、status、hire_date
    • 新增用户：提供 username、password_hash、staff_id、role、is_active、last_login
    • 新增财务记录：提供 department_id、finance_type、category、amount、period_year、period_month、source、remark
  • 最佳实践
    • 唯一性：严格维护 code 与 employee_id 的唯一性
    • 枚举：统一使用模型中定义的枚举类型，避免拼写差异
    • 索引：在高频查询列上保持索引，定期评估查询计划
    • 校验：前端与后端双重校验，确保数据质量