14 KiB
14 KiB
工资核算管理
**本文引用的文件** - [salary.py](file://backend/app/api/v1/salary.py) - [salary_service.py](file://backend/app/services/salary_service.py) - [models.py](file://backend/app/models/models.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [salary.js](file://frontend/src/api/salary.js) - [Salary.vue](file://frontend/src/views/salary/Salary.vue) - [001_initial.py](file://backend/alembic/versions/001_initial.py) - [database.md](file://docs/database.md) - [详细设计文档.md](file://docs/详细设计文档.md)目录
简介
本文件为医院绩效系统的工资核算管理模块提供完整的技术文档。该模块负责：
- 绩效奖金计算算法与参数配置
- 工资记录的创建、更新与状态管理
- 基于考核结果的批量工资生成
- 工资确认与发放前的状态控制
- 工资条生成、历史记录查询与统计分析
- 数据来源、计算精度与异常处理机制说明
项目结构
工资核算管理模块由后端API路由、服务层、数据模型与前端界面组成，采用分层架构设计，确保职责分离与可扩展性。
graph TB
subgraph "前端"
FE_API["salary.js<br/>前端API封装"]
FE_View["Salary.vue<br/>工资管理视图"]
end
subgraph "后端"
API["salary.py<br/>API路由"]
Service["salary_service.py<br/>服务层"]
Models["models.py<br/>数据模型"]
Schemas["schemas.py<br/>数据模式"]
end
subgraph "数据库"
DB_Schema["001_initial.py<br/>迁移脚本"]
ER_Doc["database.md<br/>ER图"]
end
FE_API --> API
FE_View --> FE_API
API --> Service
Service --> Models
Service --> Schemas
Models --> DB_Schema
ER_Doc --> DB_Schema
图表来源
章节来源
核心组件
- API路由层：提供工资记录查询、详情、创建、更新、按考核生成、批量生成、确认与批量确认等REST接口。
- 服务层：实现业务逻辑，包括绩效奖金计算、工资记录生成、状态变更与批量操作。
- 数据模型层：定义工资记录、员工、考核等实体及其关系。
- 数据模式层：定义请求/响应数据结构，确保前后端数据一致性。
- 前端界面：展示工资记录列表、支持筛选与编辑，调用后端API完成操作。
章节来源
架构概览
工资核算管理遵循“前端-后端-数据库”的三层架构，通过API路由统一对外提供服务，服务层封装业务规则，数据模型映射数据库表结构。
sequenceDiagram
participant FE as "前端界面"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 查询工资记录列表
API->>SVC : get_list(...)
SVC->>DB : 查询salary_records
DB-->>SVC : 返回记录集
SVC-->>API : 记录列表+总数
API-->>FE : JSON响应
FE->>API : 根据考核生成工资
API->>SVC : generate_from_assessment(...)
SVC->>DB : 读取staff/assessments
SVC->>SVC : calculate_performance_bonus(...)
SVC->>DB : 插入salary_records
DB-->>SVC : 提交事务
SVC-->>API : 新建记录ID
API-->>FE : 成功响应
图表来源
章节来源
详细组件分析
绩效奖金计算算法
- 计算公式
- 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
- 其中：绩效基数为固定常量；绩效得分来自考核加权得分；绩效系数来自员工配置。
- 参数来源
- 绩效基数：服务层常量字段
- 绩效得分：来自已确认的考核记录的加权得分
- 绩效系数：来自员工表的performance_ratio字段
- 精度与约束
- 绩效基数保留两位小数
- 绩效得分与系数保留两位小数
- 数据库字段使用Numeric类型保证精度
flowchart TD
Start(["开始"]) --> LoadAssessment["加载已确认考核记录"]
LoadAssessment --> CheckExist{"是否存在？"}
CheckExist --> |否| ReturnNull["返回空"]
CheckExist --> |是| LoadStaff["加载员工信息"]
LoadStaff --> CalcBonus["计算绩效奖金<br/>基数×(得分/100)×系数"]
CalcBonus --> CreateRecord["创建工资记录<br/>合计=基本工资+奖金"]
CreateRecord --> Save["持久化到数据库"]
Save --> End(["结束"])
图表来源
章节来源
工资记录管理
- 字段定义
- 基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资、状态、备注、创建/更新时间
- 状态流转
- pending（待确认）→ confirmed（已确认）
- 仅pending状态可更新与确认
- 计算规则
- 应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
- 更新时自动重新计算应发工资
classDiagram
class SalaryRecord {
+int id
+int staff_id
+int period_year
+int period_month
+float base_salary
+float performance_score
+float performance_bonus
+float deduction
+float allowance
+float total_salary
+string status
+text remark
+datetime created_at
+datetime updated_at
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+float base_salary
+float performance_ratio
+string status
+datetime hire_date
}
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+text remark
}
SalaryRecord --> Staff : "外键"
Assessment --> Staff : "外键"
图表来源
章节来源
批量工资生成与发放管理
- 单个生成
- 根据员工ID与年月，检查是否存在已确认的考核记录且无重复工资记录，然后生成工资记录
- 科室批量生成
- 遍历指定科室当月已确认考核的所有员工，逐个生成工资记录
- 批量确认
- 将指定年月（可选科室）下所有pending状态的工资记录批量置为confirmed
sequenceDiagram
participant Manager as "管理员/经理"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
Manager->>API : POST /salary/batch-generate?department_id&period_year&period_month
API->>SVC : batch_generate_for_department(...)
SVC->>DB : 查询已确认考核员工
loop 对每个员工
SVC->>SVC : generate_from_assessment(...)
SVC->>DB : 插入工资记录
end
SVC-->>API : 返回生成记录数
API-->>Manager : 成功响应
图表来源
章节来源
工资条生成、历史记录查询与统计分析
- 工资条生成
- 通过“根据考核生成”或“批量生成”生成工资记录后，可在前端查看与编辑
- 历史记录查询
- 支持按员工、科室、年月、状态筛选，分页显示
- 统计分析
- 前端报表页面提供科室统计、排名等展示（与工资记录数据联动）
sequenceDiagram
participant User as "用户"
participant FE as "前端界面"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
User->>FE : 输入筛选条件
FE->>API : GET /salary?page&page_size&filters...
API->>SVC : get_list(...)
SVC->>DB : 查询salary_records
DB-->>SVC : 记录集+总数
SVC-->>API : 返回数据
API-->>FE : 渲染表格
图表来源
章节来源
数据来源、计算精度与异常处理
- 数据来源
- 员工基本信息与绩效系数来自员工表
- 考核记录来自考核表，需为已确认状态
- 工资记录来自工资记录表
- 计算精度
- 基本工资、绩效奖金、扣款、补贴、应发工资均使用Numeric(10,2)
- 绩效得分使用Numeric(5,2)
- 绩效基数为浮点型常量
- 异常处理
- 未找到记录或状态不允许时返回错误
- 重复生成工资记录时拒绝
- 更新时仅允许pending状态
章节来源
依赖关系分析
- API路由依赖服务层进行业务处理
- 服务层依赖数据模型与数据模式进行数据访问与校验
- 数据模型依赖SQLAlchemy ORM映射数据库表
- 前端通过API封装调用后端接口
graph LR
FE["前端"] --> API["API路由"]
API --> SVC["服务层"]
SVC --> MODELS["数据模型"]
SVC --> SCHEMAS["数据模式"]
MODELS --> DB["数据库"]
图表来源
章节来源
性能考虑
- 查询优化
- 工资记录表对staff_id与(period_year, period_month)建立索引，提升筛选与分页性能
- 批量操作
- 批量生成与批量确认采用批量查询与批量更新，减少事务开销
- 数据精度
- 使用Numeric类型避免浮点运算误差累积
- 前端渲染
- 列表分页与按需加载，减轻前端渲染压力
章节来源
故障排除指南
- 无法生成工资
- 检查是否存在已确认的考核记录
- 确认是否已存在同员工、同年月的工资记录
- 更新失败
- 仅pending状态可更新
- 检查字段范围约束（如非负数）
- 批量生成无结果
- 确认科室当月考核状态是否为已确认
- 前端显示异常
- 检查筛选条件与分页参数
- 确认后端接口返回格式
章节来源
结论
工资核算管理模块通过清晰的分层架构与严谨的数据模型，实现了从绩效计算到工资发放的全流程管理。模块具备良好的扩展性与可维护性，能够满足医院绩效工资核算的复杂需求，并为后续的功能增强（如税务处理、多币种支持等）提供了坚实基础。
附录
- 数据库ER图与表结构参考
- 详细设计文档