提交文件

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,440 @@
+# 核心功能模块
+
+<cite>
+**本文引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.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/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/services/__init__.py](file://backend/app/services/__init__.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.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)
+- [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. [附录](#附录)
+
+## 简介
+本文件面向医院绩效系统的核心功能模块，围绕用户认证、基础数据管理、绩效考核管理、工资核算管理、数据分析报表、经济核算与系统管理进行系统化说明。文档覆盖业务流程、前后端交互、权限控制、数据流转与状态管理，并提供模块间集成关系、接口调用说明与常见问题排查建议。
+
+## 项目结构
+系统采用前后端分离架构：
+- 后端：FastAPI + SQLAlchemy 2.0 异步 ORM，PostgreSQL 数据库，提供 REST API。
+- 前端：Vue 3 + Element Plus，基于路由守卫实现登录态校验与页面导航。
+
+```mermaid
+graph TB
+FE["前端应用<br/>Vue 3 + Element Plus"] --> BE["后端应用<br/>FastAPI"]
+BE --> DB["数据库<br/>PostgreSQL"]
+BE --> AUTH["认证模块<br/>JWT"]
+BE --> SVC["服务层<br/>业务逻辑"]
+BE --> MODELS["模型层<br/>SQLAlchemy 映射"]
+BE --> SCHEMAS["数据模式<br/>Pydantic 校验"]
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+
+## 核心组件
+- 应用入口与中间件：创建 FastAPI 实例、注册路由前缀、CORS、健康检查与全局异常处理。
+- 配置中心：应用名、版本、API 前缀、数据库连接、JWT 密钥与过期时间、跨域白名单、分页参数等。
+- 数据库层：异步引擎与会话工厂、模型基类、数据库依赖注入。
+- API 路由聚合：按模块注册认证、基础数据、考核、工资、统计、财务、计划、菜单、模板等路由。
+- 数据模型：涵盖科室、员工、指标、考核、工资、用户、计划、菜单、模板等实体与枚举。
+- 数据模式：Pydantic 模型用于请求/响应校验与序列化。
+- 服务层：封装业务逻辑（如部门、员工、指标、考核、工资、统计等服务）。
+- 前端路由：登录、工作台、基础数据、考核、工资、报表、经济核算、绩效计划、系统管理等页面与导航守卫。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [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#L62-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+- [backend/app/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+
+## 架构总览
+系统采用“前端路由 + 后端 API + 数据库”的三层架构。前端通过路由守卫拦截未登录访问；后端通过依赖注入获取数据库会话，统一返回标准化响应结构；服务层负责业务规则与状态机推进；模型层定义实体关系与约束；模式层确保输入输出一致性。
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant FE as "前端应用"
+participant API as "后端API"
+participant SVC as "服务层"
+participant DB as "数据库"
+U->>FE : 访问受保护页面
+FE->>FE : 路由守卫检查本地token
+alt 未登录
+FE-->>U : 跳转登录页
+else 已登录
+FE->>API : 发起带token的请求
+API->>SVC : 调用业务方法
+SVC->>DB : 执行查询/写入
+DB-->>SVC : 返回结果
+SVC-->>API : 返回业务结果
+API-->>FE : 标准化响应
+FE-->>U : 渲染页面/提示
+end
+```
+
+图表来源
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+## 详细组件分析
+
+### 用户认证系统
+- 功能点
+  - 登录：用户名/密码校验，生成访问令牌。
+  - 注册：用户名唯一性校验，密码加密存储，返回用户信息。
+  - 当前用户：基于 JWT 获取当前激活用户信息。
+- 权限与安全
+  - 使用依赖注入获取当前用户，禁用账户不可登录。
+  - JWT 过期时间与密钥在配置中集中管理。
+- 接口与流程
+  - 登录接口接收表单数据，校验失败抛出 401/403。
+  - 注册接口校验用户名唯一性，成功返回自定义响应结构。
+  - 当前用户接口返回用户基本信息。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant A as "认证API"
+participant S as "安全工具"
+participant DB as "数据库"
+C->>A : POST /api/v1/auth/login
+A->>DB : 查询用户
+DB-->>A : 用户对象
+A->>S : 校验密码
+S-->>A : 校验结果
+A->>S : 生成访问令牌
+S-->>A : 返回令牌
+A-->>C : {access_token, token_type}
+C->>A : POST /api/v1/auth/register
+A->>DB : 检查用户名唯一
+DB-->>A : 结果
+A->>S : 密码哈希
+S-->>A : 哈希值
+A->>DB : 创建用户
+DB-->>A : 新用户
+A-->>C : {code, message, data}
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L66)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L200)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+
+### 基础数据管理
+- 科室管理
+  - 列表/树形结构查询、详情、创建、更新、删除。
+  - 创建/更新需管理员或经理权限；删除受父子关系约束。
+- 员工管理
+  - 列表/详情、创建、更新、删除、按科室查询。
+  - 创建/更新需管理员或经理权限；工号唯一。
+- 数据模型与关系
+  - Department 与 Staff 多对一/一对多；Department 支持父子关系树。
+  - Staff 关联 Department、Assessment、SalaryRecord。
+
+```mermaid
+classDiagram
+class Department {
+int id
+string name
+string code
+enum dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+}
+class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+Department "1" o-- "many" Staff : "back_populates"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+章节来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+### 绩效考核管理
+- 功能点
+  - 列表/详情、创建、更新、提交、审核、确认、批量创建。
+  - 支持按员工、科室、年度、月份、状态筛选。
+- 状态机
+  - 草稿 → 已提交 → 已审核 → 已确认/已驳回。
+- 流程图（提交→审核→确认）
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> Create["创建考核记录"]
+Create --> Submit["提交考核"]
+Submit --> Review{"审核通过？"}
+Review --> |是| Finalize["确认考核"]
+Review --> |否| Reject["已驳回"]
+Finalize --> End(["结束"])
+Reject --> End
+```
+
+图表来源
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+
+章节来源
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
+
+### 工资核算管理
+- 功能点
+  - 列表/详情、创建、更新、根据考核生成、批量生成、确认、批量确认。
+  - 支持按员工、科室、年度、月份、状态筛选。
+- 业务规则
+  - 工资记录由已确认的考核生成；重复生成会报错。
+  - 确认后方可进入后续发放流程。
+- 接口时序（批量生成）
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant API as "工资API"
+participant SVC as "工资服务"
+participant ASSESS as "考核服务"
+participant DB as "数据库"
+FE->>API : POST /api/v1/salary/batch-generate
+API->>SVC : 批量生成
+SVC->>ASSESS : 查询已确认考核
+ASSESS->>DB : 查询
+DB-->>ASSESS : 考核结果
+SVC->>DB : 写入工资记录
+DB-->>SVC : 成功
+SVC-->>API : 工资记录集合
+API-->>FE : {code, message, data}
+```
+
+图表来源
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L113-L129)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L200)
+
+章节来源
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
+
+### 数据分析报表
+- 统计维度
+  - 科室统计：员工数、平均分、总奖金。
+  - 周期统计：总人数、已考核人数、平均分、总奖金、分数分布。
+  - 趋势数据：按周期的平均分与总奖金。
+- 用途
+  - 支持管理层决策与绩效对比分析。
+
+章节来源
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L349-L374)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L200)
+
+### 经济核算管理
+- 功能点
+  - 收入/支出记录：支持按类别、金额、周期、来源、备注管理。
+  - 科室收支结余：按科室与周期汇总收入、支出与结余。
+  - 类别汇总：按类别统计金额。
+- 类别枚举
+  - 收入：检查费、检验费、放射费、床位费、护理费、治疗费、手术费、注射费、吸氧费、其他。
+  - 支出：材料费、人员支出、维修费、水电费、其他。
+
+章节来源
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L407-L460)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L443-L452)
+
+### 系统管理
+- 菜单管理
+  - 支持菜单/按钮类型、父子关系、排序、可见性、权限标识等。
+  - 提供树形结构与扁平列表。
+- 权限控制
+  - 菜单与按钮权限标识可用于前端路由与按钮级权限控制。
+- 前端路由
+  - 登录、工作台、基础数据、考核、工资、报表、经济核算、绩效计划、系统管理（菜单管理）等。
+
+```mermaid
+graph TB
+subgraph "前端路由"
+R1["/login"]
+R2["/dashboard"]
+R3["/departments"]
+R4["/staff"]
+R5["/assessments"]
+R6["/salary"]
+R7["/reports"]
+R8["/finance"]
+R9["/plans"]
+R10["/system/menus"]
+end
+subgraph "后端路由"
+A1["/auth/*"]
+A2["/departments/*"]
+A3["/staff/*"]
+A4["/assessments/*"]
+A5["/salary/*"]
+A6["/stats/*"]
+A7["/finance/*"]
+A8["/performance_plans/*"]
+A9["/menus/*"]
+A10["/templates/*"]
+end
+R1 --> A1
+R2 --> A2
+R3 --> A2
+R4 --> A3
+R5 --> A4
+R6 --> A5
+R7 --> A6
+R8 --> A7
+R9 --> A8
+R10 --> A9
+```
+
+图表来源
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L3-L96)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+
+章节来源
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L200)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L590-L638)
+
+## 依赖分析
+- 组件耦合
+  - API 层仅依赖服务层与数据库依赖注入，职责清晰。
+  - 服务层依赖模型层与数据库会话，封装业务规则。
+  - 模型层定义实体与关系，约束数据完整性。
+  - 模式层统一请求/响应结构，便于前后端契约一致。
+- 外部依赖
+  - FastAPI、SQLAlchemy 2.0、PostgreSQL、Element Plus、Vue Router。
+- 潜在循环依赖
+  - 当前结构通过“API → 服务 → 模型/数据库”单向依赖，未见循环。
+
+```mermaid
+graph LR
+API["API 路由"] --> SVC["服务层"]
+SVC --> MODELS["数据模型"]
+MODELS --> DB["数据库"]
+API --> SCHEMAS["数据模式"]
+API --> FE["前端路由"]
+```
+
+图表来源
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+- [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/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+
+## 性能考虑
+- 数据库连接池：通过配置项设置池大小与溢出，避免高并发下的连接瓶颈。
+- 异步 I/O：使用 SQLAlchemy 异步引擎与会话，提升并发吞吐。
+- 分页与索引：API 默认分页参数与模型索引（如科室类型、状态、周期等）有助于查询性能。
+- 前端缓存：路由守卫减少无效请求，结合后端分页降低传输压力。
+- 建议
+  - 对高频查询字段增加复合索引。
+  - 控制一次性批量操作规模，必要时引入任务队列异步生成工资。
+
+## 故障排查指南
+- 登录失败
+  - 确认用户名/密码正确且账户启用；检查后端日志与异常处理器输出。
+- 创建失败（科室/员工）
+  - 编码/工号唯一性冲突；检查是否存在重复记录。
+- 更新/删除受限
+  - 需管理员或经理权限；确认当前用户角色与权限标识。
+- 考核状态异常
+  - 仅允许在特定状态下进行提交/审核/确认；检查状态机流转。
+- 工资生成失败
+  - 未找到已确认的考核记录或已存在同周期工资记录；检查考核状态与重复生成逻辑。
+- 前端路由跳转
+  - 未登录自动跳转登录页；检查本地 token 是否存在。
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L77)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L78)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L100-L101)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L104-L109)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
+
+## 结论
+本系统以清晰的模块划分与标准化的数据契约支撑医院绩效管理全流程：从基础数据维护到绩效考核、工资核算、经济统计与系统管理。通过前后端路由与权限控制、状态机与业务规则约束，确保流程可控、数据一致。建议持续完善索引策略、批量任务异步化与前端权限颗粒度，进一步提升性能与可用性。
+
+## 附录
+- 配置项摘要
+  - 应用名、版本、API 前缀、调试开关、数据库 URL、连接池参数、JWT 密钥与过期时间、跨域白名单、默认/最大分页大小。
+- 数据模型概览
+  - 科室、员工、指标、考核、工资、用户、计划、菜单、模板等实体与枚举。
+- 响应结构
+  - 统一的 code/message/data/total/page/page_size 结构，便于前端统一处理。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L61)
+- [backend/app/main.py](file://backend/app/main.py#L54-L56)