提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/API接口文档/工资财务接口.md
+++ b/.qoder/repowiki/zh/content/API接口文档/工资财务接口.md
@@ -0,0 +1,657 @@
+# 工资财务接口
+
+<cite>
+**本文档引用的文件**
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本项目是一个基于FastAPI的医院绩效管理系统，专注于工资核算和财务管理接口。系统实现了完整的工资计算流程，包括绩效奖金计算、基本工资处理、补贴扣除规则等核心功能。同时提供了全面的财务数据统计功能，涵盖收入、支出、收支结余等多维度分析。
+
+系统采用前后端分离架构，后端使用Python FastAPI框架，前端使用Vue.js，数据库采用SQLAlchemy ORM。通过RESTful API接口，实现了与考核系统的数据关联和实时更新机制。
+
+## 项目结构
+
+项目采用模块化设计，主要分为以下几个核心模块：
+
+```mermaid
+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
+```
+
+**图表来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
+
+**章节来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
+
+## 核心组件
+
+### 工资核算模块
+
+工资核算模块实现了完整的工资计算和管理功能，包括：
+
+- **工资计算算法**：基于基本工资、绩效得分、绩效系数计算绩效奖金
+- **工资记录管理**：支持创建、更新、查询、确认工资记录
+- **批量处理功能**：支持按科室批量生成和确认工资记录
+- **状态管理**：支持pending、confirmed等状态流转
+
+### 财务核算模块
+
+财务核算模块提供了全面的财务数据统计和分析功能：
+
+- **收入统计**：按科室、类别、时间段统计收入数据
+- **支出统计**：按科室、类别、时间段统计支出数据
+- **收支结余**：计算科室的总收入、总支出和结余
+- **财务汇总**：提供全院范围的财务数据汇总
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
+
+## 架构概览
+
+系统采用分层架构设计，确保了良好的可维护性和扩展性：
+
+```mermaid
+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
+```
+
+**图表来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
+
+## 详细组件分析
+
+### 工资计算算法
+
+系统实现了标准化的工资计算算法，确保计算的准确性和一致性：
+
+```mermaid
+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](file://backend/app/services/salary_service.py#L127-L190)
+
+#### 绩效奖金计算公式
+
+系统采用标准化的绩效奖金计算公式：
+
+```
+绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
+```
+
+其中：
+- **绩效基数**：固定数值，可根据医院实际情况调整
+- **绩效得分**：来自考核系统的加权得分
+- **绩效系数**：来自员工档案的个人绩效系数
+
+#### 工资总额计算
+
+```mermaid
+classDiagram
+class 工资总额计算 {
+基本工资 : float
+绩效奖金 : float
+补贴 : float
+扣款 : float
+计算公式 : 总额 = 基本工资 + 绩效奖金 + 补贴 - 扣款
+}
+class 基本工资处理 {
+从员工档案获取
+支持手动调整
+参与总额计算
+}
+class 绩效奖金处理 {
+自动计算
+基于考核结果
+参与总额计算
+}
+class 补贴处理 {
+支持多种类型
+可手动调整
+参与总额计算
+}
+class 扣款处理 {
+支持多种类型
+可手动调整
+参与总额计算
+}
+工资总额计算 --> 基本工资处理
+工资总额计算 --> 绩效奖金处理
+工资总额计算 --> 补贴处理
+工资总额计算 --> 扣款处理
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L85-L91)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L311)
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L311)
+
+### 工资记录管理
+
+系统提供了完整的工资记录生命周期管理：
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿 : 创建记录
+草稿 --> 待确认 : 更新记录
+待确认 --> 已确认 : 确认操作
+已确认 --> 发放中 : 工资发放
+已确认 --> 草稿 : 修改记录
+发放中 --> 已完成 : 发放完成
+草稿 --> [*] : 删除记录
+待确认 --> [*] : 删除记录
+已确认 --> [*] : 删除记录
+```
+
+#### 工资记录状态流转
+
+| 状态 | 描述 | 权限要求 | 功能限制 |
+|------|------|----------|----------|
+| pending | 待确认 | 管理员/经理 | 可修改、可删除 |
+| confirmed | 已确认 | 管理员/经理 | 只读状态 |
+| paid | 已发放 | 管理员/经理 | 只读状态 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L299-L311)
+
+### 财务数据统计
+
+财务核算模块提供了多维度的财务数据分析功能：
+
+```mermaid
+graph LR
+subgraph "财务数据源"
+HIS[HIS系统]
+财务系统[财务系统]
+人事系统[人事系统]
+end
+subgraph "数据处理"
+数据采集[数据采集]
+数据清洗[数据清洗]
+数据计算[数据计算]
+end
+subgraph "统计分析"
+收入统计[收入统计]
+支出统计[支出统计]
+结余分析[结余分析]
+趋势分析[趋势分析]
+end
+HIS --> 数据采集
+财务系统 --> 数据采集
+人事系统 --> 数据采集
+数据采集 --> 数据清洗
+数据清洗 --> 数据计算
+数据计算 --> 收入统计
+数据计算 --> 支出统计
+数据计算 --> 结余分析
+数据计算 --> 趋势分析
+```
+
+**图表来源**
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L43-L91)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L93-L141)
+
+#### 财务类别管理
+
+系统支持两类财务类别：
+
+**收入类别**：
+- 检查费、检验费、放射费
+- 床位费、护理费、治疗费
+- 手术费、注射费、吸氧费
+- 其他收入
+
+**支出类别**：
+- 材料费、人员支出
+- 维修费、水电费
+- 其他支出
+
+**章节来源**
+- [backend/app/models/finance.py](file://backend/app/models/finance.py#L16-L43)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L20-L42)
+
+### 批量处理功能
+
+系统提供了高效的批量处理能力：
+
+```mermaid
+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](file://backend/app/services/salary_service.py#L192-L219)
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L113-L129)
+
+## 依赖关系分析
+
+系统采用了清晰的依赖层次结构，确保了模块间的松耦合：
+
+```mermaid
+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
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+
+### 数据模型关系
+
+```mermaid
+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](file://backend/app/models/models.py#L88-L231)
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L231)
+- [docs/database.md](file://docs/database.md#L197-L216)
+
+## 性能考虑
+
+### 数据库优化
+
+系统在数据库层面采用了多项优化策略：
+
+- **索引优化**：为常用查询字段建立复合索引
+- **查询优化**：使用selectinload避免N+1查询问题
+- **分页处理**：支持大数据量的分页查询
+- **连接池**：使用异步连接池提高并发性能
+
+### 缓存策略
+
+```mermaid
+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错误 | 用户权限不足 | 确保用户具有管理员或经理权限 |
+| 数据重复 | 生成工资记录失败 | 工资记录已存在 | 检查是否存在重复的工资记录 |
+| 计算错误 | 工资计算结果异常 | 数据类型转换错误 | 验证输入数据的数值格式 |
+
+### 日志记录
+
+系统提供了完善的日志记录机制：
+
+```mermaid
+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](file://backend/app/core/logging_config.py)
+
+## 结论
+
+本工资财务接口系统实现了医院绩效管理的核心功能，具有以下特点：
+
+1. **完整性**：涵盖了工资核算和财务管理的所有核心功能
+2. **准确性**：采用标准化的计算算法，确保计算结果的准确性
+3. **可扩展性**：模块化设计，易于功能扩展和维护
+4. **安全性**：完善的权限控制和数据验证机制
+5. **高效性**：异步处理和数据库优化，支持高并发场景
+
+系统通过与考核系统的深度集成，实现了从考核到工资发放的完整业务流程自动化，为医院的绩效管理提供了强有力的技术支撑。
+
+## 附录
+
+### 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 | 更新时间 | 当前时间 |
+
+### 使用示例
+
+#### 工资计算示例
+
+```javascript
+// 获取工资列表
+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
+});
+```
+
+#### 财务统计示例
+
+```javascript
+// 获取收入统计
+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
+});
+```
+
+**章节来源**
+- [docs/api.md](file://docs/api.md#L401-L469)
+- [docs/api.md](file://docs/api.md#L471-L538)