提交文件

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,423 @@
+# 部门员工服务
+
+<cite>
+**本文引用的文件**
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_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)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“部门与员工服务”的开发与运维，围绕 DepartmentService 与 StaffService 的实现架构进行系统化说明。内容涵盖：
+- 部门管理：树形结构管理、层级关系维护、增删改查与有效性校验
+- 员工管理：信息维护、职位与职称字段、基本工资与绩效系数、状态管理
+- 数据模型关系映射：部门与员工的外键约束、索引与级联策略
+- 高级能力：树形查询、分页与统计、权限控制、事务处理
+- 实际业务场景示例与最佳实践
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy Async 异步 ORM 架构，服务层位于 app/services，API 路由位于 app/api/v1，数据模型位于 app/models，配置与安全位于 app/core。
+
+```mermaid
+graph TB
+subgraph "API 层"
+A1["/api/v1/departments.py"]
+A2["/api/v1/staff.py"]
+end
+subgraph "服务层"
+S1["services/department_service.py"]
+S2["services/staff_service.py"]
+end
+subgraph "模型层"
+M1["models/models.py"]
+M2["models/finance.py"]
+end
+subgraph "基础设施"
+C1["core/config.py"]
+C2["core/database.py"]
+C3["core/security.py"]
+end
+A1 --> S1
+A2 --> S2
+S1 --> M1
+S2 --> M1
+M1 --> C2
+M2 --> C2
+C1 --> C2
+C1 --> C3
+```
+
+图表来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L74)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+
+章节来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+
+## 核心组件
+- DepartmentService：提供科室列表、树形结构、按编码/ID 查询、创建、更新、删除等能力；自动计算层级并校验删除前置条件（无子部门）
+- StaffService：提供员工列表、按工号/ID 查询、创建、更新、删除、按科室查询在职员工等能力
+- 数据模型 Department/Staff：定义字段、枚举、索引与关系；Department 与 Staff 通过外键建立一对多关系
+- API 路由：提供 REST 接口，绑定权限装饰器，调用服务层并返回统一响应格式
+- 安全与配置：JWT 认证、权限校验、数据库连接池与事务管理
+
+章节来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+## 架构总览
+部门与员工服务遵循“API → 服务 → 模型 → 数据库”的分层架构，配合统一响应体与权限控制，确保数据一致性与安全性。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "FastAPI 路由"
+participant Service as "服务层"
+participant DB as "数据库"
+Client->>API : "HTTP 请求"
+API->>API : "权限校验(Active/Manager)"
+API->>Service : "调用服务方法(参数校验)"
+Service->>DB : "SQL 查询/写入(异步)"
+DB-->>Service : "结果集/受影响行"
+Service-->>API : "领域对象/聚合"
+API-->>Client : "统一响应体(code,message,data,total/page/page_size)"
+```
+
+图表来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L111)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L101)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+## 详细组件分析
+
+### 部门服务 DepartmentService
+- 列表查询：支持按类型与启用状态过滤、分页与总数统计
+- 树形结构：手动构建树，避免懒加载导致的 N+1 问题
+- 创建逻辑：根据父级计算层级 level，插入后刷新实体
+- 删除逻辑：先检查是否存在子部门，避免破坏树形结构
+- 更新与查询：按 ID/编码查询，支持部分字段更新
+
+```mermaid
+classDiagram
+class DepartmentService {
+get_list(db, dept_type, is_active, page, page_size) tuple
+get_by_id(db, dept_id) Department?
+get_by_code(db, code) Department?
+create(db, dept_data) Department
+update(db, dept_id, dept_data) Department?
+delete(db, dept_id) bool
+get_tree(db, dept_type) DepartmentTree[]
+}
+class Department {
+id : int
+name : string
+code : string
+dept_type : DeptType
+parent_id : int?
+level : int
+sort_order : int
+is_active : bool
+description : string?
+children : Department[]
+staff : Staff[]
+}
+DepartmentService --> Department : "读写/树构建"
+```
+
+图表来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+
+章节来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L149)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+
+### 员工服务 StaffService
+- 列表查询：支持按科室、状态、关键词搜索；预加载部门关系
+- 详情查询：按 ID 查询并注入部门名称
+- 创建/更新/删除：基础 CRUD；删除不涉及子记录级联
+- 按科室查询：筛选在职员工
+
+```mermaid
+classDiagram
+class StaffService {
+get_list(db, department_id, status, keyword, page, page_size) tuple
+get_by_id(db, staff_id) Staff?
+get_by_employee_id(db, employee_id) Staff?
+create(db, staff_data) Staff
+update(db, staff_id, staff_data) Staff?
+delete(db, staff_id) bool
+get_by_department(db, department_id) Staff[]
+}
+class Staff {
+id : int
+employee_id : string
+name : string
+department_id : int
+position : string
+title : string?
+phone : string?
+email : string?
+base_salary : float
+performance_ratio : float
+status : StaffStatus
+hire_date : datetime?
+department : Department
+assessments : Assessment[]
+salary_records : SalaryRecord[]
+}
+StaffService --> Staff : "读写/关联查询"
+```
+
+图表来源
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+
+章节来源
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L111)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+
+### 数据模型与关系映射
+- Department 与 Staff：一对多外键关联，Department 作为父表，Staff 通过 department_id 关联
+- 索引：部门表对类型与父级建立索引；员工表对部门与状态建立索引
+- 枚举：科室类型、员工状态、考核状态、指标类型等
+- 财务模型：DepartmentFinance 与 Department 建立一对多关系，用于科室财务核算
+
+```mermaid
+erDiagram
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+enum dept_type
+int parent_id FK
+int level
+int sort_order
+bool is_active
+text description
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+numeric base_salary
+numeric performance_ratio
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ STAFF : "拥有"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+### API 路由与权限控制
+- 部门路由：列表、树形、详情、创建、更新、删除；创建/更新/删除需管理员或经理权限
+- 员工路由：列表、详情、创建、更新、删除、按科室查询；创建/更新/删除需管理员或经理权限
+- 统一响应：code/message/data/total/page/page_size
+- 权限装饰器：get_current_active_user 与 get_current_manager_user
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant DeptAPI as "部门路由"
+participant StaffAPI as "员工路由"
+participant Sec as "安全模块"
+participant Svc as "服务层"
+Client->>DeptAPI : "POST /api/v1/departments"
+DeptAPI->>Sec : "get_current_manager_user()"
+Sec-->>DeptAPI : "用户(管理员/经理)"
+DeptAPI->>Svc : "DepartmentService.create()"
+Svc-->>DeptAPI : "Department"
+DeptAPI-->>Client : "统一响应"
+Client->>StaffAPI : "POST /api/v1/staff"
+StaffAPI->>Sec : "get_current_manager_user()"
+Sec-->>StaffAPI : "用户(管理员/经理)"
+StaffAPI->>Svc : "StaffService.create()"
+Svc-->>StaffAPI : "Staff"
+StaffAPI-->>Client : "统一响应"
+```
+
+图表来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L80)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L68-L81)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
+
+章节来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
+
+### 处理流程与算法
+
+#### 部门树形构建流程
+```mermaid
+flowchart TD
+Start(["进入 get_tree"]) --> Query["查询所有部门并排序"]
+Query --> BuildMap["构建 id->DepartmentTree 映射"]
+BuildMap --> Iterate["遍历部门构造树节点"]
+Iterate --> HasParent{"存在父节点?"}
+HasParent --> |是| AppendChild["加入父节点 children"]
+HasParent --> |否| AddRoot["加入根节点列表"]
+AppendChild --> Next["下一个部门"]
+AddRoot --> Next
+Next --> Done(["返回根节点树"])
+```
+
+图表来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+章节来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+#### 删除部门前置校验流程
+```mermaid
+flowchart TD
+Start(["进入 delete"]) --> Load["按 ID 加载部门"]
+Load --> Exists{"是否存在?"}
+Exists --> |否| Fail["返回 False"]
+Exists --> |是| CountChildren["统计子部门数量"]
+CountChildren --> HasChild{"是否有子部门?"}
+HasChild --> |是| Block["返回 False(不可删除)"]
+HasChild --> |否| Remove["删除部门并返回 True"]
+```
+
+图表来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L96-L110)
+
+章节来源
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L96-L110)
+
+## 依赖分析
+- 服务层依赖模型层（ORM 映射）与数据库会话（异步）
+- API 层依赖服务层与安全模块（权限校验）
+- 配置模块提供数据库 URL、JWT 参数与分页默认值
+- 数据库模块提供异步引擎与会话生命周期（commit/rollback/close）
+
+```mermaid
+graph LR
+API_D["/api/v1/departments.py"] --> SVC_D["services/department_service.py"]
+API_S["/api/v1/staff.py"] --> SVC_S["services/staff_service.py"]
+SVC_D --> MODELS["models/models.py"]
+SVC_S --> MODELS
+MODELS --> DB["core/database.py"]
+API_D --> SEC["core/security.py"]
+API_S --> SEC
+CFG["core/config.py"] --> DB
+CFG --> SEC
+```
+
+图表来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+
+## 性能考虑
+- 异步数据库：使用 AsyncSession 提升并发吞吐
+- 分页与统计：列表查询先统计总数再分页，避免全量扫描
+- 关系预加载：员工列表预加载部门关系，减少 N+1 查询
+- 索引优化：部门类型与父级、员工部门与状态建立索引
+- 事务边界：每个请求会话在依赖中 commit/rollback，异常自动回滚
+- 连接池：配置池大小与溢出，避免高并发下的连接争用
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L26-L49)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L112-L114)
+
+## 故障排查指南
+- 404 未找到：查询员工或部门不存在时返回 404
+- 400 编码冲突：创建部门/员工时编码或工号重复
+- 400 无法删除：删除部门时存在子部门
+- 403 权限不足：非管理员/经理用户尝试创建/更新/删除
+- 500 服务器错误：数据库异常触发回滚并抛出
+
+章节来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L62-L107)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L108)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L34-L36)
+
+## 结论
+DepartmentService 与 StaffService 通过清晰的分层与严格的权限控制，实现了部门与员工的基础管理能力，并以树形结构与分页查询满足了常见的组织管理需求。结合模型层的索引与关系设计，以及异步数据库与事务管理，系统具备良好的扩展性与稳定性。建议后续在批量导入导出、数据同步与审计日志方面继续完善。
+
+## 附录
+
+### 统一响应体与分页
+- 响应体包含 code、message、data、total、page、page_size
+- 分页参数默认值与最大值由配置提供
+
+章节来源
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L60)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L31-L33)
+
+### 数据模型枚举参考
+- 科室类型：临床、医技、护理、行政、财务、后勤等
+- 员工状态：在职、休假、离职、退休
+- 考核状态：草稿、已提交、已审核、已确认、已驳回
+- 指标类型：质量、数量、效率、服务、成本
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L52)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L12-L45)