提交文件

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,568 @@
+# 系统管理服务
+
+<cite>
+**本文档引用的文件**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+- [menu_service.py](file://backend/app/services/menu_service.py)
+- [finance_service.py](file://backend/app/services/finance_service.py)
+- [finance.py](file://backend/app/models/finance.py)
+- [models.py](file://backend/app/models/models.py)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [menus.py](file://backend/app/api/v1/menus.py)
+- [finance.py](file://backend/app/api/v1/finance.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [security.py](file://backend/app/core/security.py)
+- [config.py](file://backend/app/core/config.py)
+- [database.py](file://backend/app/core/database.py)
+- [main.py](file://backend/app/main.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+本文档详细阐述了医院绩效系统的三大核心管理服务：绩效计划服务、菜单服务和财务服务。这些服务构成了整个系统的管理中枢，负责组织架构管理、权限控制和财务核算等关键业务功能。
+
+系统采用现代化的FastAPI + SQLAlchemy架构，支持异步IO操作，具备良好的扩展性和维护性。通过清晰的分层设计，实现了业务逻辑与数据访问的分离，确保了系统的稳定性和可测试性。
+
+## 项目结构
+
+后端项目采用典型的三层架构设计：
+
+```mermaid
+graph TB
+subgraph "表现层 (API Layer)"
+API[API路由]
+Schemas[数据模式]
+end
+subgraph "服务层 (Service Layer)"
+PerfService[绩效计划服务]
+MenuService[菜单服务]
+FinanceService[财务服务]
+end
+subgraph "数据访问层 (Data Access Layer)"
+Models[数据模型]
+DB[数据库]
+end
+subgraph "基础设施层"
+Security[安全认证]
+Config[系统配置]
+Database[数据库连接]
+end
+API --> PerfService
+API --> MenuService
+API --> FinanceService
+PerfService --> Models
+MenuService --> Models
+FinanceService --> Models
+Models --> DB
+Security --> API
+Config --> API
+Database --> Models
+```
+
+**图表来源**
+- [main.py](file://backend/app/main.py#L15-L77)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [finance.py](file://backend/app/api/v1/finance.py#L1-L217)
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L15-L77)
+- [config.py](file://backend/app/core/config.py#L9-L47)
+- [database.py](file://backend/app/core/database.py#L9-L39)
+
+## 核心组件
+
+### 绩效计划服务 (PerformancePlanService)
+
+绩效计划服务是系统的核心业务组件，负责完整的绩效计划生命周期管理：
+
+- **计划创建与管理**：支持多层级、多类型的绩效计划创建
+- **状态流转控制**：严格的审批流程和状态管理
+- **指标关联管理**：灵活的KPI指标配置和权重设置
+- **统计分析功能**：提供全面的计划执行统计和分析
+
+### 菜单服务 (MenuService)
+
+菜单服务提供完整的前端导航管理能力：
+
+- **树形结构管理**：支持多级菜单的层次化管理
+- **权限控制集成**：与用户权限系统深度集成
+- **动态菜单生成**：根据用户角色动态生成菜单树
+- **默认菜单初始化**：系统启动时自动初始化基础菜单结构
+
+### 财务服务 (FinanceService)
+
+财务服务专注于医院经济核算管理：
+
+- **收支管理**：完整的收入和支出记录管理
+- **科室核算**：按科室维度的财务数据分析
+- **预算控制**：支持预算执行情况跟踪
+- **报表统计**：多维度的财务统计和分析报表
+
+**章节来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
+- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
+- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
+
+## 架构概览
+
+系统采用分层架构设计，确保关注点分离和职责明确：
+
+```mermaid
+graph TB
+subgraph "应用入口"
+Main[主应用]
+Router[API路由器]
+end
+subgraph "认证与授权"
+Security[安全模块]
+Auth[认证中间件]
+end
+subgraph "业务服务层"
+PerfSvc[绩效计划服务]
+MenuSvc[菜单服务]
+FinanceSvc[财务服务]
+end
+subgraph "数据模型层"
+PerfModel[绩效模型]
+MenuModel[菜单模型]
+FinanceModel[财务模型]
+end
+subgraph "数据存储层"
+DB[(PostgreSQL)]
+Cache[(Redis)]
+end
+Main --> Router
+Router --> Security
+Security --> PerfSvc
+Security --> MenuSvc
+Security --> FinanceSvc
+PerfSvc --> PerfModel
+MenuSvc --> MenuModel
+FinanceSvc --> FinanceModel
+PerfModel --> DB
+MenuModel --> DB
+FinanceModel --> DB
+DB --> Cache
+```
+
+**图表来源**
+- [main.py](file://backend/app/main.py#L19-L51)
+- [security.py](file://backend/app/core/security.py#L55-L110)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
+- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
+- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
+
+## 详细组件分析
+
+### 绩效计划管理功能
+
+#### 计划生命周期管理
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 待审批 : 提交申请
+待审批 --> 已批准 : 审批通过
+待审批 --> 已驳回 : 审批驳回
+已批准 --> 执行中 : 激活计划
+执行中 --> 已完成 : 计划结束
+执行中 --> 已取消 : 主动取消
+已批准 --> 已取消 : 主动取消
+已驳回 --> 草稿 : 修改后重新提交
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L233-L242)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
+
+#### KPI指标关联管理
+
+绩效计划与KPI指标的关联管理提供了灵活的指标配置能力：
+
+- **权重分配**：支持不同指标的权重设置
+- **目标值设定**：为每个指标设置目标值和单位
+- **评分方法**：支持自定义评分方法和参数
+- **动态调整**：运行期可调整指标配置
+
+**章节来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L196-L249)
+- [models.py](file://backend/app/models/models.py#L314-L338)
+
+### 菜单权限管理功能
+
+#### 菜单树形结构管理
+
+```mermaid
+classDiagram
+class Menu {
+int id
+int parent_id
+MenuType menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+bool is_visible
+bool is_active
+DateTime created_at
+DateTime updated_at
+}
+class MenuService {
+get_tree(visible_only) Dict[]
+get_list(menu_type, is_visible) Menu[]
+get_by_id(menu_id) Menu
+create(menu_data) Menu
+update(menu_id, menu_data) Menu
+delete(menu_id) bool
+init_default_menus() void
+}
+MenuService --> Menu : manages
+Menu --> Menu : children
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L347-L372)
+- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
+
+#### 权限控制机制
+
+系统实现了基于角色的权限控制（RBAC）：
+
+- **用户角色**：admin（管理员）、manager（经理）、staff（员工）
+- **权限验证**：@get_current_active_user（普通用户）、@get_current_manager_user（管理员/经理）
+- **菜单权限**：通过permission字段控制菜单显示和访问
+- **操作权限**：针对不同操作设置不同的权限要求
+
+**章节来源**
+- [security.py](file://backend/app/core/security.py#L85-L110)
+- [menus.py](file://backend/app/api/v1/menus.py#L98-L163)
+
+### 财务相关功能
+
+#### 科室财务核算
+
+```mermaid
+classDiagram
+class DepartmentFinance {
+int id
+int department_id
+int period_year
+int period_month
+FinanceType finance_type
+string category
+float amount
+string source
+string remark
+DateTime created_at
+DateTime updated_at
+}
+class FinanceService {
+get_department_revenue(department_id, year, month) Dict[]
+get_department_expense(department_id, year, month) Dict[]
+get_department_balance(department_id, year, month) Dict
+get_revenue_by_category(department_id, year, month) Dict[]
+get_expense_by_category(department_id, year, month) Dict[]
+create_finance_record(params) DepartmentFinance
+update_finance_record(id, params) DepartmentFinance
+delete_finance_record(id) bool
+get_department_summary(year, month) Dict[]
+}
+FinanceService --> DepartmentFinance : manages
+DepartmentFinance --> Department : belongs_to
+```
+
+**图表来源**
+- [finance.py](file://backend/app/models/finance.py#L45-L74)
+- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
+
+#### 财务类别管理
+
+系统支持标准化的财务类别管理：
+
+- **收入类别**：检查费、检验费、放射费、床位费、护理费、治疗费、手术费、注射费、吸氧费、其他
+- **支出类别**：材料费、人员支出、维修费、水电费、其他
+- **类别验证**：严格的类别有效性检查
+- **标签本地化**：支持中文标签显示
+
+**章节来源**
+- [finance_service.py](file://backend/app/services/finance_service.py#L20-L41)
+- [finance.py](file://backend/app/models/finance.py#L16-L43)
+
+### 系统配置管理
+
+#### 环境配置管理
+
+系统采用集中式配置管理：
+
+- **数据库配置**：支持PostgreSQL异步连接池
+- **JWT配置**：Token过期时间和算法设置
+- **CORS配置**：跨域资源共享设置
+- **分页配置**：默认和最大分页大小设置
+
+#### 数据库连接管理
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant API as API服务
+participant Session as 数据库会话
+participant Pool as 连接池
+participant DB as PostgreSQL
+Client->>API : 请求数据
+API->>Session : 获取数据库会话
+Session->>Pool : 从连接池获取连接
+Pool->>DB : 建立数据库连接
+DB-->>Pool : 返回连接
+Pool-->>Session : 返回连接
+Session-->>API : 返回数据
+API-->>Client : 响应数据
+API->>Session : 提交事务
+Session->>DB : 提交数据
+DB-->>Session : 确认提交
+Session->>Pool : 归还连接
+```
+
+**图表来源**
+- [database.py](file://backend/app/core/database.py#L28-L39)
+- [config.py](file://backend/app/core/config.py#L18-L26)
+
+**章节来源**
+- [config.py](file://backend/app/core/config.py#L9-L47)
+- [database.py](file://backend/app/core/database.py#L9-L39)
+
+## 依赖关系分析
+
+### 服务间依赖关系
+
+```mermaid
+graph TD
+subgraph "API层"
+PerfAPI[绩效计划API]
+MenuAPI[菜单API]
+FinanceAPI[财务API]
+end
+subgraph "服务层"
+PerfService[绩效计划服务]
+MenuService[菜单服务]
+FinanceService[财务服务]
+end
+subgraph "模型层"
+PerfModel[绩效模型]
+MenuModel[菜单模型]
+FinanceModel[财务模型]
+UserModel[用户模型]
+end
+subgraph "基础设施"
+Security[安全模块]
+DB[数据库]
+Config[配置模块]
+end
+PerfAPI --> PerfService
+MenuAPI --> MenuService
+FinanceAPI --> FinanceService
+PerfService --> PerfModel
+MenuService --> MenuModel
+FinanceService --> FinanceModel
+PerfService --> UserModel
+Security --> PerfService
+Security --> MenuService
+Security --> FinanceService
+PerfModel --> DB
+MenuModel --> DB
+FinanceModel --> DB
+UserModel --> DB
+Config --> PerfAPI
+Config --> MenuAPI
+Config --> FinanceAPI
+```
+
+**图表来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L15-L16)
+- [menus.py](file://backend/app/api/v1/menus.py#L11-L12)
+- [finance.py](file://backend/app/api/v1/finance.py#L14-L16)
+
+### 数据模型依赖关系
+
+```mermaid
+erDiagram
+PERFORMANCE_PLANS {
+int id PK
+string plan_name
+string plan_code UK
+enum plan_level
+int plan_year
+int plan_month
+enum status
+int department_id FK
+int staff_id FK
+int parent_plan_id FK
+bool is_active
+datetime created_at
+datetime updated_at
+}
+PLAN_KPI_RELATIONS {
+int id PK
+int plan_id FK
+int indicator_id FK
+float target_value
+string target_unit
+float weight
+datetime created_at
+datetime updated_at
+}
+MENUS {
+int id PK
+int parent_id FK
+enum menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+bool is_visible
+bool is_active
+datetime created_at
+datetime updated_at
+}
+DEPARTMENT_FINANCES {
+int id PK
+int department_id FK
+int period_year
+int period_month
+enum finance_type
+string category
+float amount
+datetime created_at
+datetime updated_at
+}
+USERS {
+int id PK
+string username UK
+string password_hash
+int staff_id FK
+string role
+bool is_active
+datetime last_login
+datetime created_at
+datetime updated_at
+}
+PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
+MENUS ||--o{ MENUS : children
+DEPARTMENT_FINANCES }o--|| DEPARTMENTS : belongs_to
+PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
+PERFORMANCE_PLANS }o--|| DEPARTMENTS : belongs_to
+PERFORMANCE_PLANS }o--|| STAFF : responsible_for
+PERFORMANCE_PLANS }o--|| USERS : submitted_by
+DEPARTMENT_FINANCES }o--|| DEPARTMENTS : belongs_to
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L270-L338)
+- [finance.py](file://backend/app/models/finance.py#L45-L74)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+- [finance.py](file://backend/app/models/finance.py#L16-L79)
+
+## 性能考虑
+
+### 数据库性能优化
+
+系统采用了多项数据库性能优化策略：
+
+- **索引优化**：为常用查询字段建立复合索引
+- **连接池管理**：配置合理的连接池大小和溢出限制
+- **异步操作**：使用SQLAlchemy异步引擎提升并发性能
+- **查询优化**：采用selectinload进行N+1查询优化
+
+### 缓存策略
+
+```mermaid
+flowchart TD
+Request[请求到达] --> CheckCache{检查缓存}
+CheckCache --> |命中| ReturnCache[返回缓存数据]
+CheckCache --> |未命中| QueryDB[查询数据库]
+QueryDB --> ProcessData[处理数据]
+ProcessData --> UpdateCache[更新缓存]
+UpdateCache --> ReturnData[返回数据]
+ReturnCache --> End[请求结束]
+ReturnData --> End
+```
+
+### 异步处理
+
+系统充分利用异步特性：
+
+- **异步数据库操作**：避免阻塞主线程
+- **异步文件处理**：支持大文件上传和下载
+- **异步任务队列**：后台任务处理（如报表生成）
+
+## 故障排除指南
+
+### 常见问题诊断
+
+#### 认证失败问题
+
+当遇到认证失败时，检查以下方面：
+
+1. **Token有效性**：确认Token未过期且格式正确
+2. **用户状态**：验证用户账户是否被激活
+3. **权限级别**：确认用户具有执行操作的权限
+4. **JWT配置**：检查密钥和算法配置
+
+#### 数据库连接问题
+
+```mermaid
+flowchart TD
+ConnectFail[连接失败] --> CheckURL{检查数据库URL}
+CheckURL --> URLCorrect{URL格式正确?}
+URLCorrect --> |否| FixURL[修复数据库URL]
+URLCorrect --> |是| CheckPool{检查连接池配置}
+CheckPool --> PoolOK{连接池正常?}
+PoolOK --> |否| AdjustPool[调整连接池参数]
+PoolOK --> |是| CheckAuth{检查认证信息}
+CheckAuth --> AuthOK{认证成功?}
+AuthOK --> |否| FixAuth[修复认证信息]
+AuthOK --> |是| Success[连接成功]
+```
+
+#### 权限控制问题
+
+当权限控制出现问题时：
+
+1. **检查用户角色**：确认用户角色设置正确
+2. **验证菜单权限**：检查菜单的permission字段
+3. **审查API装饰器**：确认使用了正确的权限装饰器
+4. **查看日志信息**：分析认证和授权日志
+
+**章节来源**
+- [security.py](file://backend/app/core/security.py#L55-L110)
+- [database.py](file://backend/app/core/database.py#L28-L39)
+
+## 结论
+
+本系统通过精心设计的三层架构，成功实现了医院绩效管理的核心功能。三大管理服务各司其职，既保持了高度的内聚性，又确保了适当的耦合度。
+
+系统的主要优势包括：
+
+- **模块化设计**：清晰的职责分离便于维护和扩展
+- **安全性保障**：完善的认证授权机制确保系统安全
+- **性能优化**：异步架构和数据库优化提升系统性能
+- **可扩展性**：灵活的数据模型支持业务发展需求
+
+通过持续的优化和完善，该系统能够有效支撑医院的绩效管理工作，为提升医疗服务质量提供有力的技术保障。