提交文件

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,587 @@
+# 绩效计划模型
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [002_template.py](file://backend/alembic/versions/002_template.py)
+- [performance_plan.js](file://frontend/src/api/performance_plan.js)
+- [create_plan_tables.py](file://backend/create_plan_tables.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+本文件详细阐述了医院绩效系统的绩效计划模型设计与实现。该模型支持多层级、多维度的绩效管理需求，涵盖从医院级到个人级的完整计划体系，提供完善的审批流程、版本控制和执行跟踪功能。系统采用现代化的前后端分离架构，后端基于FastAPI和SQLAlchemy，前端使用Vue.js框架。
+
+## 项目结构
+
+绩效计划模型位于后端应用的核心模块中，采用清晰的分层架构设计：
+
+```mermaid
+graph TB
+subgraph "后端架构"
+API[API层<br/>performance_plans.py]
+Service[服务层<br/>performance_plan_service.py]
+Model[模型层<br/>models.py]
+Schema[数据模式<br/>schemas.py]
+DB[(数据库)]
+end
+subgraph "前端架构"
+Frontend[前端应用<br/>Vue.js]
+APIClient[API客户端<br/>performance_plan.js]
+end
+Frontend --> APIClient
+APIClient --> API
+API --> Service
+Service --> Model
+Model --> DB
+```
+
+**图表来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+- [models.py](file://backend/app/models/models.py#L270-L342)
+
+**章节来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+- [models.py](file://backend/app/models/models.py#L270-L342)
+
+## 核心组件
+
+### 计划层级枚举（PlanLevel）
+
+系统定义了三个层级的计划结构，支持从宏观到微观的逐级分解：
+
+```mermaid
+classDiagram
+class PlanLevel {
+<<enumeration>>
+hospital
+department
+individual
+}
+class PerformancePlan {
+int id
+string plan_name
+string plan_code
+PlanLevel plan_level
+int plan_year
+int plan_month
+string plan_type
+int department_id
+int staff_id
+int parent_plan_id
+string description
+string strategic_goals
+string key_initiatives
+PlanStatus status
+int submitter_id
+datetime submit_time
+int approver_id
+datetime approve_time
+string approve_remark
+int version
+bool is_active
+}
+PerformancePlan --> PlanLevel : uses
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L263-L268)
+- [models.py](file://backend/app/models/models.py#L270-L312)
+
+### 计划状态枚举（PlanStatus）
+
+状态管理贯穿整个计划生命周期，确保流程的规范性和可追溯性：
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 待审批 : 提交
+待审批 --> 已批准 : 审批通过
+待审批 --> 已驳回 : 审批驳回
+已批准 --> 执行中 : 激活
+已批准 --> 已完成 : 结束
+执行中 --> 已完成 : 结束
+已完成 --> 取消 : 取消
+草稿 --> 取消 : 删除
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L233-L242)
+
+### 时间维度管理
+
+系统支持年度和月度两种时间维度，满足不同层级的计划管理需求：
+
+| 时间维度 | 字段 | 用途 | 限制 |
+|---------|------|------|------|
+| 年度计划 | plan_year | 计划年度 | 必填 |
+| 月度计划 | plan_year, plan_month | 计划年度和月份 | 月度计划时必填 |
+| 计划类型 | plan_type | annual/monthly | 默认年度 |
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L277-L280)
+
+## 架构概览
+
+### 数据模型关系图
+
+```mermaid
+erDiagram
+PERFORMANCE_PLANS {
+int id PK
+string plan_name
+string plan_code UK
+enum plan_level
+int plan_year
+int plan_month
+string plan_type
+int department_id FK
+int staff_id FK
+int parent_plan_id FK
+text strategic_goals
+text key_initiatives
+enum status
+int submitter_id FK
+datetime submit_time
+int approver_id FK
+datetime approve_time
+text approve_remark
+int version
+bool is_active
+datetime created_at
+datetime updated_at
+}
+PLAN_KPI_RELATIONS {
+int id PK
+int plan_id FK
+int indicator_id FK
+float target_value
+string target_unit
+float weight
+string scoring_method
+text scoring_params
+text remark
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+enum dept_type
+int parent_id FK
+int level
+int sort_order
+bool is_active
+text description
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+numeric base_salary
+numeric performance_ratio
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+USERS {
+int id PK
+string username UK
+string password_hash
+int staff_id FK
+string role
+bool is_active
+datetime last_login
+datetime created_at
+datetime updated_at
+}
+INDICATORS {
+int id PK
+string name
+string code UK
+enum indicator_type
+enum bs_dimension
+numeric weight
+numeric max_score
+numeric target_value
+string target_unit
+text calculation_method
+text assessment_method
+text deduction_standard
+string data_source
+text applicable_dept_types
+bool is_veto
+bool is_active
+datetime created_at
+datetime updated_at
+}
+PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
+PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
+PERFORMANCE_PLANS }o--|| DEPARTMENTS : belongs_to
+PERFORMANCE_PLANS }o--|| STAFF : responsible_for
+PERFORMANCE_PLANS }o--|| USERS : submitted_by
+PERFORMANCE_PLANS }o--|| USERS : approved_by
+DEPARTMENTS ||--o{ PERFORMANCE_PLANS : hosts
+STAFF ||--o{ PERFORMANCE_PLANS : creates
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+
+### API接口架构
+
+```mermaid
+sequenceDiagram
+participant Client as 前端客户端
+participant API as API层
+participant Service as 服务层
+participant DB as 数据库
+Client->>API : GET /plans
+API->>Service : get_list()
+Service->>DB : 查询计划列表
+DB-->>Service : 返回结果集
+Service-->>API : 计划列表
+API-->>Client : JSON响应
+Client->>API : POST /plans
+API->>Service : create()
+Service->>DB : 插入新计划
+DB-->>Service : 返回新ID
+Service-->>API : 完整计划对象
+API-->>Client : 创建成功
+```
+
+**图表来源**
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L66)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L76-L102)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L270-L342)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+
+## 详细组件分析
+
+### PerformancePlan模型详解
+
+PerformancePlan是整个绩效计划系统的核心实体，承载着完整的计划信息和业务逻辑：
+
+#### 核心属性设计
+
+| 属性名 | 类型 | 必填 | 描述 | 约束 |
+|--------|------|------|------|------|
+| plan_name | string | 是 | 计划名称 | 最大长度200 |
+| plan_code | string | 是 | 计划编码 | 唯一约束，最大长度50 |
+| plan_level | PlanLevel | 是 | 计划层级 | 枚举值：hospital/department/individual |
+| plan_year | int | 是 | 计划年度 | 必填 |
+| plan_month | int | 否 | 计划月份 | 月度计划时必填 |
+| plan_type | string | 否 | 计划类型 | 默认annual，可选monthly |
+| department_id | int | 否 | 所属科室ID | 外键约束 |
+| staff_id | int | 否 | 责任人ID | 外键约束 |
+| parent_plan_id | int | 否 | 上级计划ID | 自引用外键 |
+| strategic_goals | text | 否 | 战略目标 | 文本内容 |
+| key_initiatives | text | 否 | 关键举措 | 文本内容 |
+| version | int | 否 | 版本号 | 默认1，自增 |
+| is_active | bool | 否 | 是否启用 | 默认true |
+
+#### 关系映射
+
+```mermaid
+classDiagram
+class PerformancePlan {
+Department department
+Staff staff
+PerformancePlan parent_plan
+PlanKpiRelation[] kpi_relations
+User submitter
+User approver
+PerformancePlan[] child_plans
+}
+class PlanKpiRelation {
+PerformancePlan plan
+Indicator indicator
+}
+class Department {
+PerformancePlan[] performance_plans
+}
+class Staff {
+PerformancePlan[] performance_plans
+}
+PerformancePlan --> Department : belongs_to
+PerformancePlan --> Staff : responsible_for
+PerformancePlan --> PlanKpiRelation : contains
+PlanKpiRelation --> Indicator : links_to
+PerformancePlan --> PerformancePlan : parent_child
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L298-L304)
+- [models.py](file://backend/app/models/models.py#L314-L338)
+
+### 计划层级业务含义
+
+#### 医院级计划（Hospital）
+- **覆盖范围**：整个医院层面的战略规划
+- **制定主体**：医院管理层
+- **关注重点**：医院整体发展战略、资源配置、重大决策
+- **典型内容**：医院发展规划、重大投资计划、体制改革方案
+
+#### 科室级计划（Department）
+- **覆盖范围**：特定临床或医技科室
+- **制定主体**：科室负责人
+- **关注重点**：科室业务发展、质量改进、效率提升
+- **典型内容**：学科建设、人才培养、技术创新
+
+#### 个人级计划（Individual）
+- **覆盖范围**：具体员工个人
+- **制定主体**：员工本人或直接上级
+- **关注重点**：个人能力发展、工作目标达成
+- **典型内容**：技能培训、绩效目标、职业发展规划
+
+### 多级审批流程
+
+系统实现了严格的多级审批机制，确保计划的合规性和权威性：
+
+```mermaid
+flowchart TD
+Start([开始]) --> Create["创建草稿计划"]
+Create --> Submit["提交审批"]
+Submit --> Review{"审批状态"}
+Review --> |通过| Approve["审批通过"]
+Review --> |驳回| Reject["审批驳回"]
+Approve --> Activate["激活执行"]
+Reject --> Edit["修改后重新提交"]
+Activate --> Execute["执行中"]
+Execute --> Complete["完成"]
+Edit --> Submit
+Complete --> Cancel["取消"]
+Cancel --> End([结束])
+```
+
+**图表来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
+
+### 计划与指标关联关系
+
+PlanKpiRelation表建立了计划与指标之间的多对多关联：
+
+#### 关联属性设计
+
+| 属性名 | 类型 | 必填 | 描述 | 约束 |
+|--------|------|------|------|------|
+| target_value | float | 否 | 目标值 | 数值类型 |
+| target_unit | string | 否 | 目标值单位 | 最大长度50 |
+| weight | float | 否 | 权重 | 默认1.0 |
+| scoring_method | string | 否 | 评分方法 | 最大长度50 |
+| scoring_params | text | 否 | 评分参数 | JSON格式 |
+| remark | text | 否 | 备注 | 文本内容 |
+
+#### 关联规则
+
+```mermaid
+erDiagram
+PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
+PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
+PLAN_KPI_RELATIONS {
+unique(plan_id, indicator_id)
+}
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L314-L338)
+
+### 版本控制机制
+
+系统内置版本控制功能，支持计划的迭代更新：
+
+#### 版本管理策略
+
+1. **初始版本**：新建计划时自动设置为1
+2. **版本递增**：每次更新操作时版本号+1
+3. **历史追踪**：通过版本号区分不同版本的计划
+4. **冲突处理**：并发更新时通过版本号避免数据覆盖
+
+#### 版本控制API
+
+| 接口 | 方法 | 功能 | 权限要求 |
+|------|------|------|----------|
+| /plans | POST | 创建新计划 | 普通用户 |
+| /plans/{id} | PUT | 更新计划 | 管理员/经理 |
+| /plans/{id}/submit | POST | 提交审批 | 普通用户 |
+| /plans/{id}/approve | POST | 审批计划 | 管理员/经理 |
+| /plans/{id}/activate | POST | 激活计划 | 管理员/经理 |
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L293)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L105-L128)
+
+## 依赖关系分析
+
+### 数据库依赖关系
+
+```mermaid
+graph LR
+subgraph "核心表"
+PP[performance_plans]
+PKR[plan_kpi_relations]
+IND[indicators]
+DEPT[departments]
+STAFF[staff]
+USR[users]
+end
+PP --> DEPT
+PP --> STAFF
+PP --> USR
+PP --> PP
+PKR --> PP
+PKR --> IND
+DEPT --> DEPT
+```
+
+**图表来源**
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L183)
+- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
+
+### 前后端交互依赖
+
+```mermaid
+sequenceDiagram
+participant FE as 前端
+participant API as 后端API
+participant SVC as 服务层
+participant DB as 数据库
+FE->>API : 发起HTTP请求
+API->>SVC : 调用业务逻辑
+SVC->>DB : 执行数据库操作
+DB-->>SVC : 返回查询结果
+SVC-->>API : 返回业务数据
+API-->>FE : 返回JSON响应
+```
+
+**图表来源**
+- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
+
+### 外部依赖
+
+- **FastAPI**：Web框架和API开发
+- **SQLAlchemy**：ORM框架和数据库抽象
+- **Alembic**：数据库迁移工具
+- **Vue.js**：前端框架
+- **PostgreSQL**：数据库引擎
+
+**章节来源**
+- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
+- [create_plan_tables.py](file://backend/create_plan_tables.py#L1-L19)
+
+## 性能考虑
+
+### 数据库性能优化
+
+1. **索引策略**
+   - 计划层级索引：`idx_plan_level`
+   - 计划年度索引：`idx_plan_year`
+   - 状态索引：`idx_plan_status`
+   - 部门索引：`idx_plan_department`
+
+2. **查询优化**
+   - 使用`selectinload`进行关联查询
+   - 实现分页查询避免大数据量加载
+   - 缓存常用查询结果
+
+3. **连接池管理**
+   - 异步数据库连接
+   - 连接池大小合理配置
+   - 连接超时和重试机制
+
+### 前端性能优化
+
+1. **API调用优化**
+   - 批量数据请求
+   - 请求去重和缓存
+   - 错误重试机制
+
+2. **界面渲染优化**
+   - 组件懒加载
+   - 虚拟滚动处理大量数据
+   - 图表组件按需渲染
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+#### 计划创建失败
+**问题**：创建计划时报错
+**可能原因**：
+- 计划编码重复
+- 必填字段缺失
+- 外键约束错误
+
+**解决步骤**：
+1. 检查计划编码是否唯一
+2. 验证所有必填字段
+3. 确认关联实体存在
+
+#### 审批流程异常
+**问题**：审批状态无法正常流转
+**可能原因**：
+- 当前状态不正确
+- 权限不足
+- 数据库事务未提交
+
+**解决步骤**：
+1. 检查当前计划状态
+2. 验证用户权限
+3. 查看数据库事务日志
+
+#### 性能问题
+**问题**：查询响应缓慢
+**可能原因**：
+- 缺少必要索引
+- 查询条件不当
+- 数据量过大
+
+**解决步骤**：
+1. 添加缺失索引
+2. 优化查询条件
+3. 实施分页查询
+
+**章节来源**
+- [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#L194-L225)
+
+## 结论
+
+绩效计划模型通过精心设计的数据结构和严谨的业务流程，为医院提供了完整的绩效管理体系。系统的主要优势包括：
+
+1. **层次化设计**：支持从医院级到个人级的多层级计划管理
+2. **流程规范化**：完善的审批流程确保计划的合规性
+3. **扩展性强**：灵活的指标关联机制支持个性化配置
+4. **版本控制**：内置版本管理支持计划的迭代演进
+5. **前后端分离**：现代化的技术栈提供良好的开发体验
+
+该模型为医院的绩效管理提供了坚实的技术基础，能够有效支撑医院的战略实施和日常运营管理工作。