# 系统管理接口

<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)