提交文件

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,503 @@
+# 服务层开发
+
+<cite>
+**本文档引用的文件**
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [salary_service.py](file://backend/app/services/salary_service.py)
+- [stats_service.py](file://backend/app/services/stats_service.py)
+- [department_service.py](file://backend/app/services/department_service.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [indicator_service.py](file://backend/app/services/indicator_service.py)
+- [finance_service.py](file://backend/app/services/finance_service.py)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+- [template_service.py](file://backend/app/services/template_service.py)
+- [menu_service.py](file://backend/app/services/menu_service.py)
+- [database.py](file://backend/app/core/database.py)
+- [config.py](file://backend/app/core/config.py)
+- [models.py](file://backend/app/models/models.py)
+- [assessments.py](file://backend/app/api/v1/assessments.py)
+- [salary.py](file://backend/app/api/v1/salary.py)
+- [stats.py](file://backend/app/api/v1/stats.py)
+- [departments.py](file://backend/app/api/v1/departments.py)
+- [staff.py](file://backend/app/api/v1/staff.py)
+- [indicators.py](file://backend/app/api/v1/indicators.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向医院绩效系统服务层开发，系统化阐述服务层架构设计、依赖注入模式、业务逻辑封装与协作机制。文档覆盖考核服务、工资服务、统计服务、部门服务、员工服务、指标服务、财务服务、绩效计划服务、模板服务与菜单服务等核心模块，提供方法实现模式、参数校验、返回值处理、事务管理、异常处理与日志记录规范，并给出单元测试编写方法与Mock对象使用建议，以及性能优化与并发处理策略。
+
+## 项目结构
+后端采用分层架构，服务层位于API层与数据访问层之间，负责业务规则封装与跨实体协调。核心目录与文件关系如下：
+
+```mermaid
+graph TB
+subgraph "API 层"
+A1["/api/v1/assessments.py"]
+A2["/api/v1/salary.py"]
+A3["/api/v1/stats.py"]
+A4["/api/v1/departments.py"]
+A5["/api/v1/staff.py"]
+A6["/api/v1/indicators.py"]
+end
+subgraph "服务层"
+S1["assessment_service.py"]
+S2["salary_service.py"]
+S3["stats_service.py"]
+S4["department_service.py"]
+S5["staff_service.py"]
+S6["indicator_service.py"]
+S7["finance_service.py"]
+S8["performance_plan_service.py"]
+S9["template_service.py"]
+S10["menu_service.py"]
+end
+subgraph "核心配置"
+C1["core/config.py"]
+C2["core/database.py"]
+C3["models/models.py"]
+end
+A1 --> S1
+A2 --> S2
+A3 --> S3
+A4 --> S4
+A5 --> S5
+A6 --> S6
+S1 --> C2
+S2 --> C2
+S3 --> C2
+S4 --> C2
+S5 --> C2
+S6 --> C2
+S7 --> C2
+S8 --> C2
+S9 --> C2
+S10 --> C2
+S1 --> C3
+S2 --> C3
+S3 --> C3
+S4 --> C3
+S5 --> C3
+S6 --> C3
+S7 --> C3
+S8 --> C3
+S9 --> C3
+S10 --> C3
+C1 --> C2
+```
+
+**图表来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [database.py](file://backend/app/core/database.py#L1-L39)
+- [config.py](file://backend/app/core/config.py#L1-L47)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+
+**章节来源**
+- [database.py](file://backend/app/core/database.py#L1-L39)
+- [config.py](file://backend/app/core/config.py#L1-L47)
+
+## 核心组件
+服务层由10个核心服务组成，分别对应业务领域：
+- 考核服务：AssessmentService（创建、更新、提交、审核、确认、批量创建）
+- 工资服务：SalaryService（计算绩效奖金、生成工资、批量生成、确认、批量确认）
+- 统计服务：StatsService（BSC维度分析、科室统计、趋势分析、排名、完成度）
+- 部门服务：DepartmentService（列表、树形结构、增删改查）
+- 员工服务：StaffService（列表、详情、增删改查、按科室查询）
+- 指标服务：IndicatorService（列表、模板导入、模板列表）
+- 财务服务：FinanceService（收支明细、收支汇总、分类统计、增删改查）
+- 绩效计划服务：PerformancePlanService（计划生命周期管理、树形结构、统计）
+- 模板服务：TemplateService（模板增删改查、指标关联、标签映射）
+- 菜单服务：MenuService（菜单树、列表、增删改查、默认菜单初始化）
+
+每个服务均采用静态方法设计，便于在FastAPI依赖注入中直接调用，保持无状态与线程安全。
+
+**章节来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+
+## 架构概览
+服务层通过依赖注入从API层接收AsyncSession与当前用户上下文，执行业务逻辑并返回标准化响应。事务管理由数据库会话自动处理，异常通过HTTP异常抛出，日志通过应用日志框架记录。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "API路由"
+participant Service as "服务层"
+participant DB as "数据库会话"
+participant Model as "ORM模型"
+Client->>API : "HTTP请求"
+API->>Service : "调用服务方法(AsyncSession, 参数)"
+Service->>DB : "执行SQL查询/更新"
+DB->>Model : "映射到ORM模型"
+Model-->>DB : "返回结果"
+DB-->>Service : "提交/回滚事务"
+Service-->>API : "业务结果"
+API-->>Client : "标准化响应"
+```
+
+**图表来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+- [stats.py](file://backend/app/api/v1/stats.py#L17-L242)
+- [database.py](file://backend/app/core/database.py#L28-L39)
+
+## 详细组件分析
+
+### 考核服务 AssessmentService
+- 功能职责
+  - 列表查询：支持多条件过滤、分页、总数统计
+  - 详情查询：加载员工、部门、明细与指标
+  - 创建：计算总分与加权得分，批量写入明细
+  - 更新：仅草稿或被拒状态下允许修改；重建明细并重算分数
+  - 提交/审核/确认：状态机流转，记录操作人与时间戳
+  - 批量创建：按科室与指标集合批量生成考核记录
+- 实现模式
+  - 使用selectinload预加载关联，减少N+1查询
+  - flush/refresh确保持久化与读取一致性
+  - 状态前置校验，防止非法状态变更
+- 参数验证与返回值
+  - API层进行输入参数校验与权限控制
+  - 服务层返回实体或None，由API层抛出HTTP异常
+- 事务管理
+  - 单次调用内统一commit/rollback，保证原子性
+- 并发处理
+  - 批量创建时先查询是否存在，避免重复创建
+  - 建议在API层增加幂等键与锁机制
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> CheckState["检查状态是否允许更新"]
+CheckState --> |不允许| ReturnNone["返回None"]
+CheckState --> |允许| DeleteOld["删除旧明细"]
+DeleteOld --> Recalc["遍历新明细计算总分与加权分"]
+Recalc --> Save["保存更新后的实体"]
+Save --> Refresh["刷新实体"]
+Refresh --> End(["结束"])
+ReturnNone --> End
+```
+
+**图表来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+
+**章节来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L263)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+
+### 工资服务 SalaryService
+- 功能职责
+  - 列表查询：支持按员工、科室、周期、状态过滤
+  - 详情查询：加载员工与部门信息
+  - 绩效奖金计算：奖金 = 基数 × (得分/100) × 绩效系数
+  - 创建/更新：计算总工资，仅待确认状态下允许更新
+  - 生成：从已确认考核生成工资记录
+  - 批量生成：按科室批量生成
+  - 确认/批量确认：变更状态并持久化
+- 实现模式
+  - 通过员工信息读取基础工资与绩效系数
+  - 生成时检查重复，避免重复发薪
+  - 使用flush/refresh确保状态一致
+- 参数验证与返回值
+  - API层校验周期与权限
+  - 服务层返回实体或None，API层处理错误
+- 事务管理
+  - 单次操作内commit/rollback
+- 性能优化
+  - 批量生成时一次查询所有已确认考核，减少往返
+
+```mermaid
+sequenceDiagram
+participant API as "API"
+participant SS as "SalaryService"
+participant DB as "数据库"
+API->>SS : "generate_from_assessment(staff_id, year, month)"
+SS->>DB : "查询员工信息"
+DB-->>SS : "员工信息"
+SS->>DB : "查询已确认考核"
+DB-->>SS : "考核记录"
+SS->>SS : "计算绩效奖金"
+SS->>DB : "创建工资记录"
+DB-->>SS : "返回记录"
+SS-->>API : "工资记录"
+```
+
+**图表来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+- [salary.py](file://backend/app/api/v1/salary.py#L96-L129)
+
+**章节来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L21-L260)
+- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+
+### 统计服务 StatsService
+- 功能职责
+  - BSC维度统计：按维度汇总得分、权重与指标数量
+  - 科室统计：按科室汇总人数、总分、平均分、最高/最低分
+  - 趋势分析：月度趋势（支持跨年）
+  - 排名：员工与科室排名
+  - 完成度：指标平均分、目标完成率
+- 实现模式
+  - 使用SQL聚合函数与分组，避免Python侧聚合
+  - 条件动态拼接，支持多维过滤
+- 性能优化
+  - 合理使用索引与分页
+  - 趋势分析中对跨年场景进行区间合并
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> BuildCond["构建查询条件"]
+BuildCond --> ExecQuery["执行聚合查询"]
+ExecQuery --> GroupBy["按维度/科室/月份分组"]
+GroupBy --> CalcAvg["计算平均分与完成率"]
+CalcAvg --> Format["格式化输出"]
+Format --> End(["结束"])
+```
+
+**图表来源**
+- [stats_service.py](file://backend/app/services/stats_service.py#L19-L300)
+
+**章节来源**
+- [stats_service.py](file://backend/app/services/stats_service.py#L19-L300)
+- [stats.py](file://backend/app/api/v1/stats.py#L17-L242)
+
+### 部门服务 DepartmentService
+- 功能职责
+  - 列表查询：按类型与启用状态过滤
+  - 树形结构：手动构建父子关系，避免懒加载问题
+  - 增删改查：层级计算、唯一性校验
+- 实现模式
+  - 手动构建树形结构，确保序列化稳定
+  - 删除前检查子节点，防止破坏层级
+- 错误处理
+  - 不存在或有子节点时返回False/None，由API层抛错
+
+**章节来源**
+- [department_service.py](file://backend/app/services/department_service.py#L16-L150)
+- [departments.py](file://backend/app/api/v1/departments.py#L20-L108)
+
+### 员工服务 StaffService
+- 功能职责
+  - 列表查询：支持关键字搜索（姓名/工号）
+  - 详情查询：加载部门信息
+  - 增删改查：唯一性校验（工号）
+  - 按科室查询：返回在职员工
+- 实现模式
+  - 使用ilike进行模糊匹配
+  - selectinload预加载部门
+
+**章节来源**
+- [staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+### 指标服务 IndicatorService
+- 功能职责
+  - 列表查询：按类型、维度、启用状态过滤
+  - 模板导入：支持覆盖策略
+  - 模板列表：内置模板集合
+- 实现模式
+  - JSON字段存储适用科室类型数组
+  - 导入时检查编码唯一性
+
+**章节来源**
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
+
+### 财务服务 FinanceService
+- 功能职责
+  - 收入/支出明细查询与汇总
+  - 收支结余计算
+  - 按类别统计收入/支出
+  - 增删改查财务记录
+  - 科室汇总：全院科室财务汇总
+- 实现模式
+  - 类别标签映射，增强可读性
+  - 使用coalesce处理空值
+
+**章节来源**
+- [finance_service.py](file://backend/app/services/finance_service.py#L43-L368)
+
+### 绩效计划服务 PerformancePlanService
+- 功能职责
+  - 计划生命周期：草稿→待审批→批准→执行中→完成/取消
+  - 树形结构：支持层级关系
+  - 统计：按状态统计数量
+  - 指标关联：增删改查
+- 实现模式
+  - 状态机严格控制流转
+  - 树形构建使用字典映射
+
+**章节来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L18-L342)
+
+### 模板服务 TemplateService
+- 功能职责
+  - 模板增删改查与指标关联
+  - 指标排序与去重
+  - 标签映射：类型与维度标签
+- 实现模式
+  - 排序字段自动生成
+  - 关联唯一约束避免重复
+
+**章节来源**
+- [template_service.py](file://backend/app/services/template_service.py#L23-L293)
+
+### 菜单服务 MenuService
+- 功能职责
+  - 菜单树形结构与列表查询
+  - 增删改查与默认菜单初始化
+- 实现模式
+  - 递归转字典，支持前端渲染
+  - 初始化时检查是否已有数据
+
+**章节来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L15-L137)
+
+## 依赖分析
+服务层依赖关系清晰，API层通过依赖注入获取AsyncSession与当前用户，服务层仅依赖数据库会话与模型定义，耦合度低、内聚性强。
+
+```mermaid
+graph TB
+API_A["/api/v1/assessments.py"] --> SVC_A["AssessmentService"]
+API_S["/api/v1/salary.py"] --> SVC_S["SalaryService"]
+API_T["/api/v1/stats.py"] --> SVC_T["StatsService"]
+API_D["/api/v1/departments.py"] --> SVC_D["DepartmentService"]
+API_ST["/api/v1/staff.py"] --> SVC_ST["StaffService"]
+API_I["/api/v1/indicators.py"] --> SVC_I["IndicatorService"]
+SVC_A --> DB["get_db() AsyncSession"]
+SVC_S --> DB
+SVC_T --> DB
+SVC_D --> DB
+SVC_ST --> DB
+SVC_I --> DB
+SVC_A --> MODELS["models.py ORM"]
+SVC_S --> MODELS
+SVC_T --> MODELS
+SVC_D --> MODELS
+SVC_ST --> MODELS
+SVC_I --> MODELS
+```
+
+**图表来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [database.py](file://backend/app/core/database.py#L28-L39)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+
+**章节来源**
+- [database.py](file://backend/app/core/database.py#L1-L39)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+
+## 性能考虑
+- 查询优化
+  - 使用selectinload预加载关联，避免N+1查询
+  - 合理使用索引（如staff、assessment、salary等表的复合索引）
+  - 分页参数限制，避免超大结果集
+- 事务与并发
+  - 服务层单次调用内commit/rollback，保证一致性
+  - 批量操作使用flush减少往返
+  - 对重复创建场景增加存在性检查
+- 缓存与降级
+  - 对只读统计结果可引入Redis缓存
+  - 对高频查询结果进行分页与限流
+- 日志与监控
+  - 记录慢查询与异常堆栈
+  - 结合数据库慢查询日志定位瓶颈
+
+## 故障排除指南
+- 常见异常
+  - 未找到实体：返回None，API层抛出404
+  - 状态不允许：返回None，API层抛出400
+  - 唯一性冲突：编码重复导致创建失败，API层抛出400
+- 事务回滚
+  - 数据库会话在异常时自动回滚，确保数据一致性
+- 日志记录
+  - 应用日志与错误日志分离，便于排查
+  - 记录关键业务事件（创建、更新、状态变更）
+
+**章节来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L60-L115)
+- [salary.py](file://backend/app/api/v1/salary.py#L61-L142)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L76-L111)
+- [database.py](file://backend/app/core/database.py#L31-L36)
+
+## 结论
+服务层通过清晰的职责划分、严格的参数校验与状态机控制、完善的事务与异常处理，有效支撑了医院绩效系统的业务闭环。建议在后续迭代中进一步完善单元测试覆盖率、引入缓存与监控告警，并持续优化查询性能与并发处理能力。
+
+## 附录
+
+### 服务方法实现模式清单
+- 列表查询：支持多条件过滤、分页、总数统计
+- 详情查询：加载关联实体，返回完整信息
+- 创建/更新：参数校验、业务计算、flush/refresh
+- 删除：前置检查（如子节点、状态）
+- 批量操作：批量查询、循环处理、一次性commit
+
+### 参数验证与返回值处理
+- API层负责输入参数校验与权限控制
+- 服务层返回实体或None，由API层统一抛出HTTP异常
+- 响应体遵循统一结构（code/message/data/total/page/page_size）
+
+### 事务管理与异常处理
+- 服务层单次调用内commit/rollback
+- 数据库异常自动回滚并抛出
+- 建议在API层捕获并记录异常日志
+
+### 日志记录规范
+- 记录关键业务事件与异常堆栈
+- 区分应用日志与错误日志
+- 包含请求ID、用户ID、操作时间
+
+### 单元测试编写方法与Mock对象使用
+- Mock数据库会话：使用unittest.mock.patch替换get_db依赖
+- Mock服务方法：对复杂业务逻辑进行隔离测试
+- 测试用例覆盖正常路径、边界条件与异常分支
+- 使用pytest与factory_boy生成测试数据
+
+### 性能优化与并发处理
+- 查询优化：预加载、索引、分页
+- 事务优化：批量flush、减少往返
+- 并发控制：幂等键、锁机制、重试策略
+- 监控与告警：慢查询、错误率、吞吐量