提交文件

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/后端开发指南/API路由实现/系统管理接口.md
+++ b/.qoder/repowiki/zh/content/后端开发指南/API路由实现/系统管理接口.md
@@ -0,0 +1,411 @@
+# 系统管理接口
+
+<cite>
+**本文档引用的文件**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [menus.py](file://backend/app/api/v1/menus.py)
+- [templates.py](file://backend/app/api/v1/templates.py)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+- [menu_service.py](file://backend/app/services/menu_service.py)
+- [template_service.py](file://backend/app/services/template_service.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [security.py](file://backend/app/core/security.py)
+- [database.py](file://backend/app/core/database.py)
+- [main.py](file://backend/app/main.py)
+- [config.py](file://backend/app/core/config.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [002_template.py](file://backend/alembic/versions/002_template.py)
+- [init_templates.py](file://backend/app/scripts/init_templates.py)
+- [logging_config.py](file://backend/app/core/logging_config.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向系统管理接口，围绕绩效计划管理、菜单权限和模板管理三大核心领域，系统化梳理后端API实现、数据模型、服务层逻辑与安全控制机制。文档同时覆盖系统配置的动态管理、角色权限控制、菜单树结构、模板版本与继承、系统初始化与数据迁移、配置备份、日志审计与安全监控，以及性能监控、资源管理与故障恢复策略。
+
+## 项目结构
+后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库的现代架构，按功能域划分API路由、服务层与数据模型，配合Alembic进行数据库版本管理，支持系统初始化脚本与模板数据注入。
+
+```mermaid
+graph TB
+subgraph "应用入口"
+MAIN["app/main.py"]
+CONFIG["app/core/config.py"]
+LOGCFG["app/core/logging_config.py"]
+end
+subgraph "API层"
+PERF_API["app/api/v1/performance_plans.py"]
+MENU_API["app/api/v1/menus.py"]
+TPL_API["app/api/v1/templates.py"]
+end
+subgraph "服务层"
+PERF_SRV["app/services/performance_plan_service.py"]
+MENU_SRV["app/services/menu_service.py"]
+TPL_SRV["app/services/template_service.py"]
+end
+subgraph "核心模块"
+SEC["app/core/security.py"]
+DB["app/core/database.py"]
+end
+subgraph "数据模型与迁移"
+MODELS["app/models/models.py"]
+ALEMBIC1["backend/alembic/versions/001_initial.py"]
+ALEMBIC2["backend/alembic/versions/002_template.py"]
+end
+MAIN --> PERF_API
+MAIN --> MENU_API
+MAIN --> TPL_API
+PERF_API --> PERF_SRV
+MENU_API --> MENU_SRV
+TPL_API --> TPL_SRV
+PERF_SRV --> MODELS
+MENU_SRV --> MODELS
+TPL_SRV --> MODELS
+PERF_API --> SEC
+MENU_API --> SEC
+TPL_API --> SEC
+PERF_API --> DB
+MENU_API --> DB
+TPL_API --> DB
+CONFIG --> MAIN
+LOGCFG --> MAIN
+ALEMBIC1 --> MODELS
+ALEMBIC2 --> 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)
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [config.py](file://backend/app/core/config.py#L1-L47)
+- [logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
+- [002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L15-L77)
+- [config.py](file://backend/app/core/config.py#L9-L47)
+
+## 核心组件
+- 绩效计划管理API：提供计划的CRUD、状态流转、指标关联、树形结构与统计查询。
+- 菜单管理API：提供菜单树、列表、详情、创建/更新/删除与默认菜单初始化。
+- 指标模板管理API：提供模板与模板指标的CRUD、批量导入、维度与类型枚举。
+- 服务层：封装业务逻辑，统一处理状态机、关联关系与查询优化。
+- 数据模型：定义实体、枚举与索引，支撑多维考核与组织结构。
+- 安全与配置：JWT认证、权限校验、数据库连接与日志配置。
+
+**章节来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L18-L310)
+- [menus.py](file://backend/app/api/v1/menus.py#L14-L164)
+- [templates.py](file://backend/app/api/v1/templates.py#L19-L272)
+- [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)
+- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [security.py](file://backend/app/core/security.py#L1-L110)
+- [database.py](file://backend/app/core/database.py#L1-L39)
+
+## 架构概览
+系统采用分层架构：API层负责请求解析与响应封装；服务层承载业务规则与状态机；模型层定义数据结构与约束；核心模块提供安全、数据库与配置能力。API层通过依赖注入获取数据库会话与当前用户，确保权限控制与事务一致性。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "API控制器"
+participant Service as "服务层"
+participant Model as "数据模型"
+participant DB as "数据库"
+Client->>API : 发起请求(携带JWT)
+API->>API : 依赖注入(get_db, get_current_active_user)
+API->>Service : 调用业务方法(带参数)
+Service->>DB : 查询/更新(ORM操作)
+DB-->>Service : 返回结果
+Service-->>API : 业务结果
+API-->>Client : 统一响应格式
+```
+
+**图表来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L31)
+- [menus.py](file://backend/app/api/v1/menus.py#L17-L22)
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L29)
+- [security.py](file://backend/app/core/security.py#L55-L82)
+- [database.py](file://backend/app/core/database.py#L28-L39)
+
+## 详细组件分析
+
+### 绩效计划管理
+- 功能范围：计划列表、树形结构、统计、详情、创建、更新、提交、审批、激活、删除、指标关联增删改。
+- 状态机：草稿 → 待审批 → 已批准 → 执行中 → 已完成/已取消；拒绝后可重新提交。
+- 关键点：指标关联支持目标值、权重、评分方法与参数；支持父子计划形成树形层级。
+- 权限控制：提交、审批、激活、删除等操作需管理员或经理权限。
+
+```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)
+
+**章节来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L18-L342)
+- [models.py](file://backend/app/models/models.py#L270-L339)
+
+### 菜单权限管理
+- 功能范围：菜单树、列表、详情、创建、更新、删除、默认菜单初始化。
+- 树形结构：支持父子关系与可见性过滤；支持按钮级权限标识。
+- 权限控制：创建/更新/删除/初始化默认菜单需管理员或经理权限。
+
+```mermaid
+flowchart TD
+Start(["获取菜单树"]) --> Query["查询根节点(父ID为空)"]
+Query --> Filter["按可见性/启用过滤"]
+Filter --> Order["按排序与ID排序"]
+Order --> Build["递归构建树结构(children)"]
+Build --> End(["返回树形结构"])
+```
+
+**图表来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+- [menu_service.py](file://backend/app/services/menu_service.py#L101-L109)
+
+**章节来源**
+- [menus.py](file://backend/app/api/v1/menus.py#L17-L164)
+- [menu_service.py](file://backend/app/services/menu_service.py#L16-L137)
+- [models.py](file://backend/app/models/models.py#L347-L372)
+
+### 指标模板管理
+- 功能范围：模板列表、详情、类型与维度枚举、创建、更新、删除；模板指标的增删改与批量导入。
+- 版本与继承：模板具备版本号与激活状态；模板指标支持分类、权重、排序与评分参数。
+- 初始化：提供脚本批量注入标准模板与指标数据，支持维度权重与评估周期配置。
+
+```mermaid
+classDiagram
+class IndicatorTemplate {
+template_code
+template_name
+template_type
+dimension_weights
+assessment_cycle
+is_active
+created_at
+updated_at
+}
+class TemplateIndicator {
+template_id
+indicator_id
+category
+weight
+sort_order
+scoring_method
+scoring_params
+remark
+}
+class Indicator {
+code
+name
+indicator_type
+bs_dimension
+weight
+max_score
+calculation_method
+assessment_method
+is_veto
+}
+IndicatorTemplate "1" o-- "*" TemplateIndicator : "包含"
+Indicator "1" o-- "*" TemplateIndicator : "被引用"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L387-L437)
+- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L23-L293)
+- [init_templates.py](file://backend/app/scripts/init_templates.py#L81-L186)
+
+### 数据模型与枚举
+- 组织与人员：Department、Staff、User，支持层级与状态管理。
+- 考核与工资：Assessment、AssessmentDetail、SalaryRecord，支持周期与状态。
+- 计划与指标：PerformancePlan、PlanKpiRelation，支持层级与父子关系。
+- 菜单与模板：Menu、IndicatorTemplate、TemplateIndicator，支持树形与关联。
+- 枚举：科室类型、指标类型、状态、计划层级与菜单类型等。
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L10-L743)
+
+### 安全与权限控制
+- JWT认证：OAuth2密码模式，支持令牌签发、解码与用户解析。
+- 权限校验：当前用户、激活用户、管理员、管理员或经理。
+- 依赖注入：API层通过Depends获取数据库会话与当前用户，确保每个请求的安全上下文。
+
+**章节来源**
+- [security.py](file://backend/app/core/security.py#L18-L110)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L8-L16)
+- [menus.py](file://backend/app/api/v1/menus.py#L8-L12)
+- [templates.py](file://backend/app/api/v1/templates.py#L8-L17)
+
+### 系统配置与数据库
+- 配置中心：应用名、版本、API前缀、数据库URL、JWT密钥与过期时间、跨域白名单、分页参数。
+- 数据库：异步引擎与会话工厂，自动事务提交/回滚与关闭。
+- 迁移：初始版本创建核心表，模板版本增加指标模板与关联表，并扩展指标字段。
+
+**章节来源**
+- [config.py](file://backend/app/core/config.py#L9-L47)
+- [database.py](file://backend/app/core/database.py#L9-L39)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
+
+## 依赖分析
+- API层依赖服务层与安全模块，通过依赖注入获取数据库会话与当前用户。
+- 服务层依赖数据模型与SQLAlchemy ORM，封装查询、状态机与事务。
+- 数据模型定义实体关系与索引，支撑高效查询与数据完整性。
+- 迁移脚本定义数据库演进路径，确保版本一致与数据安全。
+
+```mermaid
+graph LR
+PERF_API["performance_plans.py"] --> PERF_SRV["performance_plan_service.py"]
+MENU_API["menus.py"] --> MENU_SRV["menu_service.py"]
+TPL_API["templates.py"] --> TPL_SRV["template_service.py"]
+PERF_SRV --> MODELS["models.py"]
+MENU_SRV --> MODELS
+TPL_SRV --> MODELS
+PERF_API --> SEC["security.py"]
+MENU_API --> SEC
+TPL_API --> SEC
+PERF_API --> DB["database.py"]
+MENU_API --> DB
+TPL_API --> DB
+ALEMBIC1["001_initial.py"] --> MODELS
+ALEMBIC2["002_template.py"] --> MODELS
+```
+
+**图表来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L10-L16)
+- [menus.py](file://backend/app/api/v1/menus.py#L9-L12)
+- [templates.py](file://backend/app/api/v1/templates.py#L9-L17)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L7-L12)
+- [menu_service.py](file://backend/app/services/menu_service.py#L5-L9)
+- [template_service.py](file://backend/app/services/template_service.py#L6-L13)
+- [models.py](file://backend/app/models/models.py#L6-L13)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
+
+**章节来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L10-L16)
+- [menus.py](file://backend/app/api/v1/menus.py#L9-L12)
+- [templates.py](file://backend/app/api/v1/templates.py#L9-L17)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L7-L12)
+- [menu_service.py](file://backend/app/services/menu_service.py#L5-L9)
+- [template_service.py](file://backend/app/services/template_service.py#L6-L13)
+
+## 性能考虑
+- 异步数据库：使用异步引擎与会话，提升高并发下的IO吞吐。
+- 查询优化：服务层使用selectinload预加载关联，减少N+1查询；索引覆盖常用查询字段。
+- 分页与限制：API层对分页参数进行范围校验，避免过大页大小影响性能。
+- 缓存策略：建议在热点读取场景引入Redis缓存（如菜单树、模板列表），降低数据库压力。
+- 连接池：合理配置数据库连接池大小与溢出，避免连接争用。
+
+[本节为通用指导，无需特定文件引用]
+
+## 故障排查指南
+- 日志系统：应用日志与错误日志分离，按日期轮转，便于定位问题。
+- 异常处理：全局异常捕获与记录，HTTP异常与参数校验异常分别处理。
+- 数据一致性：服务层事务提交/回滚，确保状态变更原子性。
+- 权限问题：确认JWT令牌有效、用户状态正常、角色满足要求。
+- 数据迁移：检查Alembic版本与数据库一致，必要时执行升级/降级。
+
+**章节来源**
+- [logging_config.py](file://backend/app/core/logging_config.py#L17-L64)
+- [main.py](file://backend/app/main.py#L58-L75)
+- [database.py](file://backend/app/core/database.py#L28-L39)
+
+## 结论
+本系统管理接口围绕绩效计划、菜单权限与模板管理构建了完整的API体系，配合严谨的数据模型、服务层状态机与安全控制，实现了可配置、可扩展、可审计的医院绩效管理体系。通过完善的初始化与迁移机制、日志与异常处理、以及性能与故障恢复策略，系统具备良好的稳定性与可维护性。
+
+[本节为总结，无需特定文件引用]
+
+## 附录
+
+### API端点速览
+- 绩效计划
+  - GET /plans：获取计划列表
+  - GET /plans/tree：获取计划树
+  - GET /plans/stats：获取计划统计
+  - GET /plans/{plan_id}：获取计划详情
+  - POST /plans：创建计划
+  - PUT /plans/{plan_id}：更新计划
+  - POST /plans/{plan_id}/submit：提交计划
+  - POST /plans/{plan_id}/approve：审批计划
+  - POST /plans/{plan_id}/activate：激活计划
+  - DELETE /plans/{plan_id}：删除计划
+  - POST /plans/{plan_id}/kpi-relations：添加指标关联
+  - PUT /plans/kpi-relations/{relation_id}：更新指标关联
+  - DELETE /plans/kpi-relations/{relation_id}：删除指标关联
+
+- 菜单管理
+  - GET /menus/tree：获取菜单树
+  - GET /menus：获取菜单列表
+  - GET /menus/{menu_id}：获取菜单详情
+  - POST /menus：创建菜单
+  - PUT /menus/{menu_id}：更新菜单
+  - DELETE /menus/{menu_id}：删除菜单
+  - POST /menus/init：初始化默认菜单
+
+- 指标模板
+  - GET /templates：获取模板列表
+  - GET /templates/types：获取模板类型列表
+  - GET /templates/dimensions：获取BSC维度列表
+  - GET /templates/{template_id}：获取模板详情
+  - POST /templates：创建模板
+  - PUT /templates/{template_id}：更新模板
+  - DELETE /templates/{template_id}：删除模板
+  - GET /templates/{template_id}/indicators：获取模板指标列表
+  - POST /templates/{template_id}/indicators：添加模板指标
+  - PUT /templates/{template_id}/indicators/{indicator_id}：更新模板指标
+  - DELETE /templates/{template_id}/indicators/{indicator_id}：移除模板指标
+  - POST /templates/{template_id}/indicators/batch：批量添加模板指标
+
+**章节来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
+- [menus.py](file://backend/app/api/v1/menus.py#L17-L164)
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L272)
+
+### 系统初始化与数据迁移
+- 初始版本：创建科室、员工、指标、考核、工资、用户等核心表。
+- 模板版本：新增指标模板与模板指标关联表，并扩展指标字段。
+- 初始化脚本：批量创建标准模板与指标，支持维度权重与评估周期配置。
+
+**章节来源**
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
+- [init_templates.py](file://backend/app/scripts/init_templates.py#L189-L272)