提交文件

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/核心功能模块/工资核算管理.md
+++ b/.qoder/repowiki/zh/content/核心功能模块/工资核算管理.md
@@ -0,0 +1,394 @@
+# 工资核算管理
+
+<cite>
+**本文引用的文件**
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件为医院绩效系统的工资核算管理模块提供完整的技术文档。该模块负责：
+- 绩效奖金计算算法与参数配置
+- 工资记录的创建、更新与状态管理
+- 基于考核结果的批量工资生成
+- 工资确认与发放前的状态控制
+- 工资条生成、历史记录查询与统计分析
+- 数据来源、计算精度与异常处理机制说明
+
+## 项目结构
+工资核算管理模块由后端API路由、服务层、数据模型与前端界面组成，采用分层架构设计，确保职责分离与可扩展性。
+
+```mermaid
+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
+```
+
+**图表来源**
+- [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["计算绩效奖金<br/>基数×(得分/100)×系数"]
+CalcBonus --> CreateRecord["创建工资记录<br/>合计=基本工资+奖金"]
+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)