# 工资核算管理 **本文引用的文件** - [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) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构概览](#架构概览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排除指南](#故障排除指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介 本文件为医院绩效系统的工资核算管理模块提供完整的技术文档。该模块负责： - 绩效奖金计算算法与参数配置 - 工资记录的创建、更新与状态管理 - 基于考核结果的批量工资生成 - 工资确认与发放前的状态控制 - 工资条生成、历史记录查询与统计分析 - 数据来源、计算精度与异常处理机制说明 ## 项目结构 工资核算管理模块由后端API路由、服务层、数据模型与前端界面组成，采用分层架构设计，确保职责分离与可扩展性。 ```mermaid graph TB subgraph "前端" FE_API["salary.js
前端API封装"] FE_View["Salary.vue
工资管理视图"] end subgraph "后端" API["salary.py
API路由"] Service["salary_service.py
服务层"] Models["models.py
数据模型"] Schemas["schemas.py
数据模式"] end subgraph "数据库" DB_Schema["001_initial.py
迁移脚本"] ER_Doc["database.md
ER图"] end FE_API --> API FE_View --> FE_API API --> Service Service --> Models Service --> Schemas Models --> DB_Schema ER_Doc --> DB_Schema ``` **图表来源** - [salary.py](file://backend/app/api/v1/salary.py#L1-L156) - [salary_service.py](file://backend/app/services/salary_service.py#L1-L260) - [models.py](file://backend/app/models/models.py#L205-L231) - [schemas.py](file://backend/app/schemas/schemas.py#L272-L311) - [salary.js](file://frontend/src/api/salary.js#L1-L42) - [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245) - [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154) - [database.md](file://docs/database.md#L1-L95) **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L1-L156) - [salary_service.py](file://backend/app/services/salary_service.py#L1-L260) - [models.py](file://backend/app/models/models.py#L205-L231) - [schemas.py](file://backend/app/schemas/schemas.py#L272-L311) - [salary.js](file://frontend/src/api/salary.js#L1-L42) - [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245) - [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154) - [database.md](file://docs/database.md#L1-L95) ## 核心组件 - API路由层：提供工资记录查询、详情、创建、更新、按考核生成、批量生成、确认与批量确认等REST接口。 - 服务层：实现业务逻辑，包括绩效奖金计算、工资记录生成、状态变更与批量操作。 - 数据模型层：定义工资记录、员工、考核等实体及其关系。 - 数据模式层：定义请求/响应数据结构，确保前后端数据一致性。 - 前端界面：展示工资记录列表、支持筛选与编辑，调用后端API完成操作。 **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L20-L156) - [salary_service.py](file://backend/app/services/salary_service.py#L14-L260) - [models.py](file://backend/app/models/models.py#L205-L231) - [schemas.py](file://backend/app/schemas/schemas.py#L272-L311) - [salary.js](file://frontend/src/api/salary.js#L1-L42) - [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245) ## 架构概览 工资核算管理遵循“前端-后端-数据库”的三层架构，通过API路由统一对外提供服务，服务层封装业务规则，数据模型映射数据库表结构。 ```mermaid 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 : 成功响应 ``` **图表来源** - [salary.py](file://backend/app/api/v1/salary.py#L20-L156) - [salary_service.py](file://backend/app/services/salary_service.py#L21-L190) - [models.py](file://backend/app/models/models.py#L205-L231) **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L20-L156) - [salary_service.py](file://backend/app/services/salary_service.py#L21-L190) - [models.py](file://backend/app/models/models.py#L205-L231) ## 详细组件分析 ### 绩效奖金计算算法 - 计算公式 - 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数 - 其中：绩效基数为固定常量；绩效得分来自考核加权得分；绩效系数来自员工配置。 - 参数来源 - 绩效基数：服务层常量字段 - 绩效得分：来自已确认的考核记录的加权得分 - 绩效系数：来自员工表的performance_ratio字段 - 精度与约束 - 绩效基数保留两位小数 - 绩效得分与系数保留两位小数 - 数据库字段使用Numeric类型保证精度 ```mermaid flowchart TD Start(["开始"]) --> LoadAssessment["加载已确认考核记录"] LoadAssessment --> CheckExist{"是否存在？"} CheckExist --> |否| ReturnNull["返回空"] CheckExist --> |是| LoadStaff["加载员工信息"] LoadStaff --> CalcBonus["计算绩效奖金
基数×(得分/100)×系数"] CalcBonus --> CreateRecord["创建工资记录
合计=基本工资+奖金"] CreateRecord --> Save["持久化到数据库"] Save --> End(["结束"]) ``` **图表来源** - [salary_service.py](file://backend/app/services/salary_service.py#L127-L190) - [models.py](file://backend/app/models/models.py#L205-L231) **章节来源** - [salary_service.py](file://backend/app/services/salary_service.py#L70-L75) - [salary_service.py](file://backend/app/services/salary_service.py#L127-L190) - [models.py](file://backend/app/models/models.py#L205-L231) ### 工资记录管理 - 字段定义 - 基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资、状态、备注、创建/更新时间 - 状态流转 - pending（待确认）→ confirmed（已确认） - 仅pending状态可更新与确认 - 计算规则 - 应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款 - 更新时自动重新计算应发工资 ```mermaid 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 : "外键" ``` **图表来源** - [models.py](file://backend/app/models/models.py#L205-L231) - [models.py](file://backend/app/models/models.py#L88-L114) - [models.py](file://backend/app/models/models.py#L149-L179) **章节来源** - [models.py](file://backend/app/models/models.py#L205-L231) - [schemas.py](file://backend/app/schemas/schemas.py#L272-L311) - [salary_service.py](file://backend/app/services/salary_service.py#L77-L124) ### 批量工资生成与发放管理 - 单个生成 - 根据员工ID与年月，检查是否存在已确认的考核记录且无重复工资记录，然后生成工资记录 - 科室批量生成 - 遍历指定科室当月已确认考核的所有员工，逐个生成工资记录 - 批量确认 - 将指定年月（可选科室）下所有pending状态的工资记录批量置为confirmed ```mermaid 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 : 成功响应 ``` **图表来源** - [salary.py](file://backend/app/api/v1/salary.py#L113-L129) - [salary_service.py](file://backend/app/services/salary_service.py#L192-L219) **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L96-L129) - [salary_service.py](file://backend/app/services/salary_service.py#L192-L259) ### 工资条生成、历史记录查询与统计分析 - 工资条生成 - 通过“根据考核生成”或“批量生成”生成工资记录后，可在前端查看与编辑 - 历史记录查询 - 支持按员工、科室、年月、状态筛选，分页显示 - 统计分析 - 前端报表页面提供科室统计、排名等展示（与工资记录数据联动） ```mermaid 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 : 渲染表格 ``` **图表来源** - [salary.py](file://backend/app/api/v1/salary.py#L20-L51) - [salary_service.py](file://backend/app/services/salary_service.py#L21-L58) - [Salary.vue](file://frontend/src/views/salary/Salary.vue#L190-L207) **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L20-L51) - [salary_service.py](file://backend/app/services/salary_service.py#L21-L58) - [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245) ### 数据来源、计算精度与异常处理 - 数据来源 - 员工基本信息与绩效系数来自员工表 - 考核记录来自考核表，需为已确认状态 - 工资记录来自工资记录表 - 计算精度 - 基本工资、绩效奖金、扣款、补贴、应发工资均使用Numeric(10,2) - 绩效得分使用Numeric(5,2) - 绩效基数为浮点型常量 - 异常处理 - 未找到记录或状态不允许时返回错误 - 重复生成工资记录时拒绝 - 更新时仅允许pending状态 **章节来源** - [salary_service.py](file://backend/app/services/salary_service.py#L104-L124) - [salary_service.py](file://backend/app/services/salary_service.py#L127-L190) - [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154) ## 依赖关系分析 - API路由依赖服务层进行业务处理 - 服务层依赖数据模型与数据模式进行数据访问与校验 - 数据模型依赖SQLAlchemy ORM映射数据库表 - 前端通过API封装调用后端接口 ```mermaid graph LR FE["前端"] --> API["API路由"] API --> SVC["服务层"] SVC --> MODELS["数据模型"] SVC --> SCHEMAS["数据模式"] MODELS --> DB["数据库"] ``` **图表来源** - [salary.py](file://backend/app/api/v1/salary.py#L1-L17) - [salary_service.py](file://backend/app/services/salary_service.py#L1-L12) - [models.py](file://backend/app/models/models.py#L1-L14) - [schemas.py](file://backend/app/schemas/schemas.py#L1-L8) **章节来源** - [salary.py](file://backend/app/api/v1/salary.py#L1-L17) - [salary_service.py](file://backend/app/services/salary_service.py#L1-L12) - [models.py](file://backend/app/models/models.py#L1-L14) - [schemas.py](file://backend/app/schemas/schemas.py#L1-L8) ## 性能考虑 - 查询优化 - 工资记录表对staff_id与(period_year, period_month)建立索引，提升筛选与分页性能 - 批量操作 - 批量生成与批量确认采用批量查询与批量更新，减少事务开销 - 数据精度 - 使用Numeric类型避免浮点运算误差累积 - 前端渲染 - 列表分页与按需加载，减轻前端渲染压力 **章节来源** - [001_initial.py](file://backend/alembic/versions/001_initial.py#L153-L154) - [salary_service.py](file://backend/app/services/salary_service.py#L21-L58) - [salary_service.py](file://backend/app/services/salary_service.py#L234-L259) ## 故障排除指南 - 无法生成工资 - 检查是否存在已确认的考核记录 - 确认是否已存在同员工、同年月的工资记录 - 更新失败 - 仅pending状态可更新 - 检查字段范围约束（如非负数） - 批量生成无结果 - 确认科室当月考核状态是否为已确认 - 前端显示异常 - 检查筛选条件与分页参数 - 确认后端接口返回格式 **章节来源** - [salary_service.py](file://backend/app/services/salary_service.py#L127-L190) - [salary_service.py](file://backend/app/services/salary_service.py#L104-L124) - [salary.py](file://backend/app/api/v1/salary.py#L96-L129) ## 结论 工资核算管理模块通过清晰的分层架构与严谨的数据模型，实现了从绩效计算到工资发放的全流程管理。模块具备良好的扩展性与可维护性，能够满足医院绩效工资核算的复杂需求，并为后续的功能增强（如税务处理、多币种支持等）提供了坚实基础。 ## 附录 - 数据库ER图与表结构参考 - [database.md](file://docs/database.md#L1-L95) - [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154) - 详细设计文档 - [详细设计文档.md](file://docs/详细设计文档.md#L642-L662)