# 系统介绍

<cite>
**本文引用的文件**
- [docs/index.md](file://docs/index.md)
- [docs/详细设计.md](file://docs/详细设计.md)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/main.js](file://frontend/src/main.js)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本系统面向县级中医院，围绕“战略目标—执行—考核—改进”的闭环管理，构建覆盖全院的绩效管理体系。系统以平衡计分卡（BSC）理论为指导，将医院战略目标逐级分解到科室与个人层面，通过信息化手段实现指标定义、数据采集、自动计算、流程审批与结果应用，最终形成“目标-执行-考核-改进”的可持续管理模式。系统支持多维度、可量化的KPI体系，覆盖全院各类科室与岗位，支撑绩效工资核算、统计分析与可视化决策。

## 项目结构
系统采用前后端分离架构，后端基于 FastAPI + SQLAlchemy 2.0（异步），前端基于 Vue 3 + Element Plus，数据库采用 PostgreSQL。核心模块包括基础数据管理、绩效考核、工资核算、统计报表、系统管理等，路由与视图清晰划分，便于扩展与维护。

```mermaid
graph TB
FE["前端应用<br/>Vue 3 + Element Plus"] --> BE["后端应用<br/>FastAPI + SQLAlchemy"]
BE --> DB["数据库<br/>PostgreSQL"]
FE --> API["API 接口<br/>/api/v1/*"]
API --> Services["服务层<br/>assessment_service / salary_service / stats_service"]
Services --> Models["数据模型<br/>Department / Staff / Indicator / Assessment / SalaryRecord"]
```

图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

章节来源
- [docs/index.md](file://docs/index.md#L16-L71)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

## 核心组件
- 基础数据管理：科室、员工、指标、指标模板、菜单等基础信息维护。
- 绩效考核管理：支持草稿→提交→审核→确认的流程化管理，支持批量创建与生成。
- 工资核算管理：基于考核结果自动生成工资记录，支持单条与批量确认。
- 统计报表：提供 BSC 维度分析、科室统计、趋势分析、周期统计、关键指标仪表盘等。
- 系统管理：菜单管理、用户与权限、工作流与日志等。

章节来源
- [docs/index.md](file://docs/index.md#L18-L26)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L200)

## 架构总览
系统采用分层架构：前端负责交互与可视化，后端提供 REST API 与业务服务，数据层持久化到 PostgreSQL。核心业务流程包括“指标定义—方案配置—数据采集—自动计算—流程审批—结果应用”。

```mermaid
graph TB
subgraph "表现层"
UI["工作台 / 科室管理 / 员工管理 / 考核管理 / 工资核算 / 报表 / 系统管理"]
end
subgraph "应用层"
APIS["API 路由层<br/>/api/v1/*"]
SVC["服务层<br/>assessment_service / salary_service / stats_service"]
end
subgraph "数据层"
MODELS["数据模型<br/>Department / Staff / Indicator / Assessment / SalaryRecord / Menu / PerformancePlan / IndicatorTemplate"]
DB["PostgreSQL"]
end
UI --> APIS
APIS --> SVC
SVC --> MODELS
MODELS --> DB
```

图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

## 详细组件分析

### 平衡计分卡（BSC）理论应用
- 维度设计：系统内置财务、客户（患者/内部客户）、内部流程、学习与成长四个维度，指标可标注对应维度，支持按维度聚合分析。
- 战略落地：通过“绩效计划”模块将医院战略目标逐级分解到科室与个人，形成“计划—执行—考核—改进”的闭环。
- 多元化评分：支持区间法、目标参照法、加分/扣分法、比较法等评分方法，确保客观公正。
- 结果应用：考核结果与绩效工资、晋升、评优等联动，驱动持续改进。

章节来源
- [docs/详细设计.md](file://docs/详细设计.md#L3-L26)
- [docs/详细设计.md](file://docs/详细设计.md#L59-L196)
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)

### 绩效考核管理流程
- 流程状态：草稿、已提交、已审核、已确认、已驳回，支持逐级审批与退回修正。
- 关键能力：单条创建/更新、批量创建、提交、审核、确认；支持按员工、科室、周期、状态过滤查询。
- 数据模型：考核主表、明细表、指标关联、员工与科室关系，保证数据完整性与可追溯性。

```mermaid
sequenceDiagram
participant U as "用户"
participant API as "API 路由"
participant Svc as "AssessmentService"
participant DB as "数据库"
U->>API : "POST /api/v1/assessments"
API->>Svc : "create(assessment_data)"
Svc->>DB : "插入 Assessment + AssessmentDetail"
DB-->>Svc : "返回主键与时间戳"
Svc-->>API : "Assessment 对象"
API-->>U : "{code : 200, data : {id}}"
U->>API : "POST /api/v1/assessments/{id}/submit"
API->>Svc : "submit(id)"
Svc->>DB : "更新状态=SUBMITTED"
DB-->>Svc : "刷新状态"
Svc-->>API : "Assessment 对象"
API-->>U : "{code : 200, message : '提交成功'}"
```

图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L116)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L170)

章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L200)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)

### 工资核算管理流程
- 自动计算：根据已确认的考核加权得分与员工绩效系数，按固定公式计算绩效奖金，自动汇总应发工资。
- 批量生成：支持按科室批量生成工资记录，避免重复劳动。
- 状态控制：仅“待确认”状态可更新与确认，保证数据一致性。

```mermaid
sequenceDiagram
participant U as "用户"
participant API as "API 路由"
participant Svc as "SalaryService"
participant DB as "数据库"
U->>API : "POST /api/v1/salary/generate?staff_id=...&year=&month="
API->>Svc : "generate_from_assessment(staff_id, year, month)"
Svc->>DB : "查询 Staff 与已确认 Assessment"
Svc->>Svc : "calculate_performance_bonus()"
Svc->>DB : "插入 SalaryRecord(total_salary=pending)"
DB-->>Svc : "返回记录"
Svc-->>API : "SalaryRecord 对象"
API-->>U : "{code : 200, data : {id}}"
```

图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L191)

章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L200)

### 统计报表与分析
- BSC 维度分析：按财务、客户、内部流程、学习与成长四个维度聚合统计。
- 科室绩效统计：支持按周期查看各科室平均分、人数、排名等。
- 趋势分析：支持按月度趋势查看科室与个人得分变化。
- 关键指标仪表盘：床位使用率、药占比、材料占比、患者满意度等关键指标可视化。
- 周期统计：汇总当期周期内的科室数量、员工数量、平均分等。

章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L200)
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)

### 数据模型与关系
系统通过清晰的实体关系支撑业务闭环，核心实体包括：科室、员工、指标、考核主表与明细、工资记录、菜单、绩效计划、指标模板等。

```mermaid
erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "参与"
STAFF ||--o{ SALARY_RECORDS : "产生"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被评分"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
USERS ||--o{ ASSESSMENTS : "审核/确认"
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "关联指标"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被关联"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATORS ||--o{ TEMPLATE_INDICATORS : "被引用"
MENUS ||--o{ MENUS : "父子关系"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

## 依赖分析
- 前端依赖：Vue 3、Element Plus、Pinia、Vite、ECharts，路由与图标注册，国际化配置。
- 后端依赖：FastAPI、SQLAlchemy 2.0（异步）、Pydantic v2、PostgreSQL、CORS 中间件。
- 模块耦合：API 路由层薄封装，服务层集中业务逻辑，模型层定义数据与约束，降低耦合、提升可测试性。

```mermaid
graph LR
FE_Main["frontend/src/main.js"] --> FE_Router["frontend/src/router/index.js"]
BE_Main["backend/app/main.py"] --> API_Init["backend/app/api/v1/__init__.py"]
API_Init --> API_Assess["backend/app/api/v1/assessments.py"]
API_Init --> API_Salary["backend/app/api/v1/salary.py"]
API_Init --> API_Stats["backend/app/api/v1/stats.py"]
API_Assess --> Svc_Assess["backend/app/services/assessment_service.py"]
API_Salary --> Svc_Salary["backend/app/services/salary_service.py"]
Svc_Assess --> Models["backend/app/models/models.py"]
Svc_Salary --> Models
```

图表来源
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L200)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L200)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L200)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

章节来源
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

## 性能考虑
- 异步数据库访问：使用 SQLAlchemy 2.0 异步会话，提升并发与吞吐。
- 查询优化：模型层建立索引（如科室类型、状态、周期等），服务层分页与条件过滤，减少全表扫描。
- 缓存策略：可引入 Redis 缓存热点指标与报表结果，降低数据库压力。
- 前端渲染：ECharts 与 Element Plus 组件按需加载，路由懒加载，减少首屏体积。
- 批量操作：批量生成工资与批量确认接口，减少重复请求与事务开销。

## 故障排查指南
- 常见错误与定位
  - 404：资源不存在（如考核/工资记录），检查 ID 与查询条件。
  - 400：状态不允许（如非草稿/已确认状态下更新），检查流程状态机。
  - 权限不足：审核/确认接口需管理员或经理权限，确认当前用户角色。
  - 数据异常：核查指标权重、目标值、计算方法与数据来源配置。
- 日志与健康检查
  - 后端提供健康检查接口，便于快速判断服务可用性。
  - 全局异常与校验异常处理器记录请求 URL、状态码与异常信息，便于定位问题。
- 前端路由守卫
  - 登录态校验失败将重定向至登录页，检查本地存储 token 是否有效。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L54-L75)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L91-L116)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L132-L156)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)

## 结论
本系统以平衡计分卡为核心理念，结合现代技术栈，构建了覆盖全院的绩效管理体系。通过标准化的流程、可量化的指标与自动化的计算，实现从“战略—执行—考核—改进”的闭环，支撑绩效工资核算与多维度分析，助力医院提升运营效率、医疗质量与服务水平。

## 附录
- 快速开始与默认账号
  - 后端启动命令、前端启动命令与访问地址详见项目文档。
  - 默认账号：用户名 admin，密码 admin123。
- 技术栈概览
  - 后端：FastAPI + SQLAlchemy 2.0（异步）+ PostgreSQL + Pydantic v2。
  - 前端：Vue 3 + Element Plus + Pinia + Vite + ECharts。

章节来源
- [docs/index.md](file://docs/index.md#L41-L71)