提交文件

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,280 @@
+# 系统介绍
+
+<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)