Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Blame History

工资财务接口

**本文档引用的文件** - [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/services/salary_service.py](file://backend/app/services/salary_service.py) - [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py) - [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) - [frontend/src/api/salary.js](file://frontend/src/api/salary.js) - [frontend/src/api/finance.js](file://frontend/src/api/finance.js) - [docs/api.md](file://docs/api.md) - [docs/database.md](file://docs/database.md) - [docs/详细设计.md](file://docs/详细设计.md)

简介

本项目是一个基于FastAPI的医院绩效管理系统，专注于工资核算和财务管理接口。系统实现了完整的工资计算流程，包括绩效奖金计算、基本工资处理、补贴扣除规则等核心功能。同时提供了全面的财务数据统计功能，涵盖收入、支出、收支结余等多维度分析。

系统采用前后端分离架构，后端使用Python FastAPI框架，前端使用Vue.js，数据库采用SQLAlchemy ORM。通过RESTful API接口，实现了与考核系统的数据关联和实时更新机制。

项目结构

项目采用模块化设计，主要分为以下几个核心模块：

graph TB
subgraph "前端层"
FE_API[前端API接口]
FE_VIEW[视图组件]
end
subgraph "后端层"
API_ROUTER[API路由层]
SERVICE_LAYER[服务层]
MODEL_LAYER[模型层]
SCHEMA_LAYER[数据模式层]
end
subgraph "数据层"
DATABASE[(数据库)]
ASSESSMENT_DB[考核数据库]
SALARY_DB[工资数据库]
FINANCE_DB[财务数据库]
end
FE_API --> API_ROUTER
API_ROUTER --> SERVICE_LAYER
SERVICE_LAYER --> MODEL_LAYER
MODEL_LAYER --> DATABASE
MODEL_LAYER --> ASSESSMENT_DB
MODEL_LAYER --> SALARY_DB
MODEL_LAYER --> FINANCE_DB

图表来源

章节来源

核心组件

工资核算模块

工资核算模块实现了完整的工资计算和管理功能，包括：

工资计算算法：基于基本工资、绩效得分、绩效系数计算绩效奖金
工资记录管理：支持创建、更新、查询、确认工资记录
批量处理功能：支持按科室批量生成和确认工资记录
状态管理：支持pending、confirmed等状态流转

财务核算模块

财务核算模块提供了全面的财务数据统计和分析功能：

收入统计：按科室、类别、时间段统计收入数据
支出统计：按科室、类别、时间段统计支出数据
收支结余：计算科室的总收入、总支出和结余
财务汇总：提供全院范围的财务数据汇总

章节来源

架构概览

系统采用分层架构设计，确保了良好的可维护性和扩展性：

graph TB
subgraph "表现层"
Frontend[Vue.js前端]
API_Client[API客户端]
end
subgraph "应用层"
Auth_API[认证API]
Salary_API[工资API]
Finance_API[财务API]
Stats_API[统计API]
end
subgraph "服务层"
Auth_Service[认证服务]
Salary_Service[工资服务]
Finance_Service[财务服务]
Stats_Service[统计服务]
end
subgraph "数据访问层"
ORM_Models[ORM模型]
Database[(数据库)]
end
Frontend --> API_Client
API_Client --> Auth_API
API_Client --> Salary_API
API_Client --> Finance_API
API_Client --> Stats_API
Auth_API --> Auth_Service
Salary_API --> Salary_Service
Finance_API --> Finance_Service
Stats_API --> Stats_Service
Auth_Service --> ORM_Models
Salary_Service --> ORM_Models
Finance_Service --> ORM_Models
Stats_Service --> ORM_Models
ORM_Models --> Database

图表来源

详细组件分析

工资计算算法

系统实现了标准化的工资计算算法，确保计算的准确性和一致性：

flowchart TD
Start([开始计算]) --> GetStaff[获取员工信息]
GetStaff --> GetAssessment[获取考核记录]
GetAssessment --> CheckExisting{检查是否存在工资记录}
CheckExisting --> |存在| ReturnNull[返回空值]
CheckExisting --> |不存在| CalcBonus[计算绩效奖金]
CalcBonus --> CalcTotal[计算总工资]
CalcTotal --> CreateRecord[创建工资记录]
CreateRecord --> SetPending[设置状态为pending]
SetPending --> End([计算完成])
ReturnNull --> End

图表来源

backend/app/services/salary_service.py

绩效奖金计算公式

系统采用标准化的绩效奖金计算公式：

绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数

其中：

绩效基数：固定数值，可根据医院实际情况调整
绩效得分：来自考核系统的加权得分
绩效系数：来自员工档案的个人绩效系数

工资总额计算

classDiagram
class 工资总额计算 {
+基本工资 : float
+绩效奖金 : float
+补贴 : float
+扣款 : float
+计算公式 : 总额 = 基本工资 + 绩效奖金 + 补贴 - 扣款
}
class 基本工资处理 {
+从员工档案获取
+支持手动调整
+参与总额计算
}
class 绩效奖金处理 {
+自动计算
+基于考核结果
+参与总额计算
}
class 补贴处理 {
+支持多种类型
+可手动调整
+参与总额计算
}
class 扣款处理 {
+支持多种类型
+可手动调整
+参与总额计算
}
工资总额计算 --> 基本工资处理
工资总额计算 --> 绩效奖金处理
工资总额计算 --> 补贴处理
工资总额计算 --> 扣款处理

图表来源

章节来源

工资记录管理

系统提供了完整的工资记录生命周期管理：

stateDiagram-v2
[*] --> 草稿 : 创建记录
草稿 --> 待确认 : 更新记录
待确认 --> 已确认 : 确认操作
已确认 --> 发放中 : 工资发放
已确认 --> 草稿 : 修改记录
发放中 --> 已完成 : 发放完成
草稿 --> [*] : 删除记录
待确认 --> [*] : 删除记录
已确认 --> [*] : 删除记录

工资记录状态流转

状态	描述	权限要求	功能限制
pending	待确认	管理员/经理	可修改、可删除
confirmed	已确认	管理员/经理	只读状态
paid	已发放	管理员/经理	只读状态

章节来源

财务数据统计

财务核算模块提供了多维度的财务数据分析功能：

graph LR
subgraph "财务数据源"
HIS[HIS系统]
财务系统[财务系统]
人事系统[人事系统]
end
subgraph "数据处理"
数据采集[数据采集]
数据清洗[数据清洗]
数据计算[数据计算]
end
subgraph "统计分析"
收入统计[收入统计]
支出统计[支出统计]
结余分析[结余分析]
趋势分析[趋势分析]
end
HIS --> 数据采集
财务系统 --> 数据采集
人事系统 --> 数据采集
数据采集 --> 数据清洗
数据清洗 --> 数据计算
数据计算 --> 收入统计
数据计算 --> 支出统计
数据计算 --> 结余分析
数据计算 --> 趋势分析

图表来源

财务类别管理

系统支持两类财务类别：

收入类别：

检查费、检验费、放射费
床位费、护理费、治疗费
手术费、注射费、吸氧费
其他收入

支出类别：

材料费、人员支出
维修费、水电费
其他支出

章节来源

批量处理功能

系统提供了高效的批量处理能力：

sequenceDiagram
participant Manager as 管理员
participant API as 工资API
participant Service as 工资服务
participant DB as 数据库
Manager->>API : POST /salary/batch-generate
API->>Service : batch_generate_for_department()
Service->>DB : 查询已确认考核记录
DB-->>Service : 考核记录列表
loop 为每个员工生成工资记录
Service->>Service : generate_from_assessment()
Service->>DB : 创建工资记录
end
Service-->>API : 工资记录列表
API-->>Manager : 批量生成结果

图表来源

backend/app/services/salary_service.py

章节来源

依赖关系分析

系统采用了清晰的依赖层次结构，确保了模块间的松耦合：

graph TB
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
PostgreSQL[PostgreSQL数据库]
end
subgraph "核心依赖"
Pydantic[Pydantic数据验证]
AsyncIO[异步I/O支持]
JWT[JWT认证]
end
subgraph "业务依赖"
AssessmentService[考核服务]
StaffService[员工服务]
DepartmentService[科室服务]
end
FastAPI --> Pydantic
FastAPI --> SQLAlchemy
FastAPI --> JWT
SQLAlchemy --> PostgreSQL
AssessmentService --> StaffService
StaffService --> DepartmentService
Pydantic --> AssessmentService
AsyncIO --> FastAPI

图表来源

数据模型关系

erDiagram
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
float base_salary
float performance_ratio
}
ASSESSMENT {
int id PK
int staff_id FK
int period_year
int period_month
float weighted_score
string status
}
SALARY_RECORD {
int id PK
int staff_id FK
int period_year
int period_month
float base_salary
float performance_score
float performance_bonus
float allowance
float deduction
float total_salary
string status
}
DEPARTMENT {
int id PK
string name
string code
string dept_type
}
STAFF ||--o{ ASSESSMENT : has
STAFF ||--o{ SALARY_RECORD : has
DEPARTMENT ||--o{ STAFF : has
ASSESSMENT ||--|| SALARY_RECORD : generates

图表来源

backend/app/models/models.py

章节来源

性能考虑

数据库优化

系统在数据库层面采用了多项优化策略：

索引优化：为常用查询字段建立复合索引
查询优化：使用selectinload避免N+1查询问题
分页处理：支持大数据量的分页查询
连接池：使用异步连接池提高并发性能

缓存策略

graph TD
subgraph "缓存层"
Redis[Redis缓存]
Session[会话缓存]
end
subgraph "应用层"
API[API接口]
Service[服务层]
CacheManager[缓存管理器]
end
subgraph "数据层"
Database[(数据库)]
end
API --> CacheManager
Service --> CacheManager
CacheManager --> Redis
CacheManager --> Session
Redis --> Database
Session --> Database

异步处理

系统广泛采用异步编程模式：

异步数据库操作：使用SQLAlchemy异步引擎
异步文件处理：支持大文件的异步导入导出
异步任务队列：支持长时间运行的任务处理

故障排除指南

常见问题及解决方案

问题类型	症状描述	可能原因	解决方案
工资生成失败	返回400错误	未找到已确认的考核记录	检查考核状态是否为finalized
权限不足	返回403错误	用户权限不足	确保用户具有管理员或经理权限
数据重复	生成工资记录失败	工资记录已存在	检查是否存在重复的工资记录
计算错误	工资计算结果异常	数据类型转换错误	验证输入数据的数值格式

日志记录

系统提供了完善的日志记录机制：

graph LR
subgraph "日志级别"
ERROR[错误日志]
WARN[警告日志]
INFO[信息日志]
DEBUG[调试日志]
end
subgraph "日志内容"
AUTH[认证日志]
SALARY[工资日志]
FINANCE[财务日志]
SYSTEM[系统日志]
end
ERROR --> AUTH
ERROR --> SALARY
ERROR --> FINANCE
ERROR --> SYSTEM
WARN --> AUTH
WARN --> SALARY
WARN --> FINANCE
WARN --> SYSTEM
INFO --> AUTH
INFO --> SALARY
INFO --> FINANCE
INFO --> SYSTEM
DEBUG --> AUTH
DEBUG --> SALARY
DEBUG --> FINANCE
DEBUG --> SYSTEM

章节来源

backend/app/core/logging_config.py

结论

本工资财务接口系统实现了医院绩效管理的核心功能，具有以下特点：

完整性：涵盖了工资核算和财务管理的所有核心功能
准确性：采用标准化的计算算法，确保计算结果的准确性
可扩展性：模块化设计，易于功能扩展和维护
安全性：完善的权限控制和数据验证机制
高效性：异步处理和数据库优化，支持高并发场景

系统通过与考核系统的深度集成，实现了从考核到工资发放的完整业务流程自动化，为医院的绩效管理提供了强有力的技术支撑。

附录

API接口规范

工资核算接口

接口	方法	描述	权限要求
`/salary`	GET	获取工资记录列表	普通用户
`/salary/{id}`	GET	获取工资记录详情	普通用户
`/salary`	POST	创建工资记录	管理员/经理
`/salary/{id}`	PUT	更新工资记录	管理员/经理
`/salary/generate`	POST	根据考核生成工资	管理员/经理
`/salary/batch-generate`	POST	批量生成工资	管理员/经理
`/salary/{id}/confirm`	POST	确认工资	管理员/经理
`/salary/batch-confirm`	POST	批量确认工资	管理员/经理

财务核算接口

接口	方法	描述	权限要求
`/finance/revenue`	GET	获取科室收入	普通用户
`/finance/expense`	GET	获取科室支出	普通用户
`/finance/balance`	GET	获取收支结余	普通用户
`/finance/revenue/by-category`	GET	按类别统计收入	普通用户
`/finance/expense/by-category`	GET	按类别统计支出	普通用户
`/finance/summary`	GET	获取科室财务汇总	普通用户
`/finance/categories`	GET	获取财务类别	普通用户
`/finance`	POST	创建财务记录	管理员/经理
`/finance/{id}`	PUT	更新财务记录	管理员/经理
`/finance/{id}`	DELETE	删除财务记录	管理员/经理

数据模型说明

工资记录字段

字段名	类型	描述	默认值
id	Integer	主键	自增
staff_id	Integer	员工ID	外键
period_year	Integer	年度	必填
period_month	Integer	月份	必填
base_salary	Numeric(10,2)	基本工资	0.00
performance_score	Numeric(5,2)	绩效得分	0.00
performance_bonus	Numeric(10,2)	绩效奖金	0.00
allowance	Numeric(10,2)	补贴	0.00
deduction	Numeric(10,2)	扣款	0.00
total_salary	Numeric(10,2)	应发工资	0.00
status	String(20)	状态	pending
remark	Text	备注	null
created_at	DateTime	创建时间	当前时间
updated_at	DateTime	更新时间	当前时间

财务记录字段

字段名	类型	描述	默认值
id	Integer	主键	自增
department_id	Integer	科室ID	外键
period_year	Integer	年度	必填
period_month	Integer	月份	必填
finance_type	Enum	财务类型	必填
category	String(50)	类别	必填
amount	Numeric(12,2)	金额	0.00
source	String(100)	数据来源	null
remark	Text	备注	null
created_at	DateTime	创建时间	当前时间
updated_at	DateTime	更新时间	当前时间

使用示例

工资计算示例

// 获取工资列表
const response = await getSalaryRecords({
  department_id: 1,
  period_year: 2024,
  period_month: 1,
  status: 'confirmed'
});

// 生成工资记录
const generateResponse = await generateSalary({
  staff_id: 1,
  period_year: 2024,
  period_month: 1
});

// 批量生成工资
const batchResponse = await batchGenerateSalary({
  department_id: 1,
  period_year: 2024,
  period_month: 1
});

财务统计示例

// 获取收入统计
const revenue = await getRevenue({
  department_id: 1,
  period_year: 2024,
  period_month: 1
});

// 获取支出统计
const expense = await getExpense({
  department_id: 1,
  period_year: 2024,
  period_month: 1
});

// 获取收支结余
const balance = await getBalance({
  department_id: 1,
  period_year: 2024,
  period_month: 1
});

章节来源

18 KiB Raw Blame History Unescape Escape

工资财务接口

目录

简介

项目结构

核心组件

工资核算模块

财务核算模块

架构概览

详细组件分析

工资计算算法

绩效奖金计算公式

工资总额计算

工资记录管理

工资记录状态流转

财务数据统计

财务类别管理

批量处理功能

依赖关系分析

数据模型关系

性能考虑

数据库优化

缓存策略

异步处理

故障排除指南

常见问题及解决方案

日志记录

结论

附录

API接口规范

工资核算接口

财务核算接口

数据模型说明

工资记录字段

财务记录字段

使用示例

工资计算示例

财务统计示例

18 KiB

Raw Blame History