提交文件

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,634 @@
+# 基础数据管理
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [departments.py](file://backend/app/api/v1/departments.py)
+- [staff.py](file://backend/app/api/v1/staff.py)
+- [indicators.py](file://backend/app/api/v1/indicators.py)
+- [templates.py](file://backend/app/api/v1/templates.py)
+- [department_service.py](file://backend/app/services/department_service.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [indicator_service.py](file://backend/app/services/indicator_service.py)
+- [template_service.py](file://backend/app/services/template_service.py)
+- [Departments.vue](file://frontend/src/views/basic/Departments.vue)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
+- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
+- [department.js](file://frontend/src/api/department.js)
+- [staff.js](file://frontend/src/api/staff.js)
+- [indicator.js](file://frontend/src/api/indicator.js)
+- [template.js](file://frontend/src/api/template.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+基础数据管理模块是医院绩效系统的核心基础功能模块，负责维护医院运营所需的基础数据。该模块涵盖四个主要功能领域：
+
+- **科室管理**：支持树形结构组织，实现多层级科室管理
+- **员工信息管理**：维护员工基本信息、职位、职称和薪资数据
+- **考核指标管理**：管理各类绩效考核指标及其属性
+- **指标模板管理**：提供标准化的指标模板体系
+
+该模块采用前后端分离架构，后端使用FastAPI + SQLAlchemy，前端使用Vue.js + Element Plus，实现了完整的CRUD操作、数据验证、权限控制和批量处理功能。
+
+## 项目结构
+
+基础数据管理模块遵循典型的三层架构设计：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE1[Departments.vue<br/>科室管理界面]
+FE2[Staff.vue<br/>员工管理界面]
+FE3[Indicators.vue<br/>指标管理界面]
+FE4[Templates.vue<br/>模板管理界面]
+FE5[API层<br/>department.js<br/>staff.js<br/>indicator.js<br/>template.js]
+end
+subgraph "后端层"
+BE1[API路由层<br/>departments.py<br/>staff.py<br/>indicators.py<br/>templates.py]
+BE2[服务层<br/>department_service.py<br/>staff_service.py<br/>indicator_service.py<br/>template_service.py]
+BE3[数据模型层<br/>models.py]
+BE4[数据验证层<br/>schemas.py]
+end
+subgraph "数据库层"
+DB[(SQLite数据库)]
+end
+FE1 --> FE5
+FE2 --> FE5
+FE3 --> FE5
+FE4 --> FE5
+FE5 --> BE1
+BE1 --> BE2
+BE2 --> BE3
+BE3 --> BE4
+BE3 --> DB
+```
+
+**图表来源**
+- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [models.py](file://backend/app/models/models.py#L1-L438)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+## 核心组件
+
+### 数据模型设计
+
+系统采用SQLAlchemy ORM设计，建立了完整的数据模型层次：
+
+```mermaid
+classDiagram
+class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+DateTime created_at
+DateTime updated_at
+Staff[] staff
+Department parent
+Department[] children
+}
+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
+StaffStatus status
+DateTime hire_date
+DateTime created_at
+DateTime updated_at
+Department department
+Assessment[] assessments
+SalaryRecord[] salary_records
+}
+class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
+DateTime created_at
+DateTime updated_at
+AssessmentDetail[] assessment_details
+}
+class IndicatorTemplate {
+int id
+string template_name
+string template_code
+TemplateType template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
+DateTime created_at
+DateTime updated_at
+TemplateIndicator[] indicators
+}
+class TemplateIndicator {
+int id
+int template_id
+int indicator_id
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+int sort_order
+string remark
+DateTime created_at
+DateTime updated_at
+IndicatorTemplate template
+Indicator indicator
+}
+Department "1" <-- "many" Staff : "has"
+Department "1" <-- "many" Department : "parent"
+IndicatorTemplate "1" <-- "many" TemplateIndicator : "contains"
+TemplateIndicator "1" <-- "1" Indicator : "references"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+
+### API接口设计
+
+系统提供了RESTful API接口，支持标准的CRUD操作：
+
+| 功能模块 | HTTP方法 | 端点 | 描述 |
+|---------|---------|------|------|
+| 科室管理 | GET | `/departments` | 获取科室列表 |
+| 科室管理 | GET | `/departments/tree` | 获取科室树形结构 |
+| 科室管理 | GET | `/departments/{id}` | 获取科室详情 |
+| 科室管理 | POST | `/departments` | 创建科室 |
+| 科室管理 | PUT | `/departments/{id}` | 更新科室 |
+| 科室管理 | DELETE | `/departments/{id}` | 删除科室 |
+| 员工管理 | GET | `/staff` | 获取员工列表 |
+| 员工管理 | GET | `/staff/{id}` | 获取员工详情 |
+| 员工管理 | POST | `/staff` | 创建员工 |
+| 员工管理 | PUT | `/staff/{id}` | 更新员工 |
+| 员工管理 | DELETE | `/staff/{id}` | 删除员工 |
+| 员工管理 | GET | `/staff/department/{id}` | 获取科室员工 |
+| 指标管理 | GET | `/indicators` | 获取指标列表 |
+| 指标管理 | GET | `/indicators/active` | 获取启用指标 |
+| 指标管理 | GET | `/indicators/{id}` | 获取指标详情 |
+| 指标管理 | POST | `/indicators` | 创建指标 |
+| 指标管理 | PUT | `/indicators/{id}` | 更新指标 |
+| 指标管理 | DELETE | `/indicators/{id}` | 删除指标 |
+| 模板管理 | GET | `/templates` | 获取模板列表 |
+| 模板管理 | GET | `/templates/types` | 获取模板类型 |
+| 模板管理 | GET | `/templates/dimensions` | 获取BSC维度 |
+| 模板管理 | GET | `/templates/{id}` | 获取模板详情 |
+| 模板管理 | POST | `/templates` | 创建模板 |
+| 模板管理 | PUT | `/templates/{id}` | 更新模板 |
+| 模板管理 | DELETE | `/templates/{id}` | 删除模板 |
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+
+## 架构概览
+
+系统采用分层架构设计，确保了良好的可维护性和扩展性：
+
+```mermaid
+sequenceDiagram
+participant Client as "前端客户端"
+participant API as "API路由层"
+participant Service as "服务层"
+participant Model as "数据模型层"
+participant DB as "数据库"
+Client->>API : HTTP请求
+API->>Service : 调用业务逻辑
+Service->>Model : 数据映射和验证
+Model->>DB : SQL查询/操作
+DB-->>Model : 查询结果
+Model-->>Service : 处理后的数据
+Service-->>API : 业务结果
+API-->>Client : JSON响应
+Note over Client,DB : 请求处理完整流程
+```
+
+**图表来源**
+- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+
+### 权限控制机制
+
+系统实现了基于角色的权限控制：
+
+```mermaid
+flowchart TD
+A[用户访问] --> B{检查权限}
+B --> |普通用户| C[仅读取权限]
+B --> |管理员| D[完全权限]
+B --> |经理| E[部分写权限]
+C --> F[只允许GET操作]
+D --> G[允许所有操作]
+E --> H[允许CRUD操作]
+F --> I[返回数据]
+G --> I
+H --> I
+```
+
+**图表来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L67-L107)
+- [staff.py](file://backend/app/api/v1/staff.py#L68-L108)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L111)
+- [templates.py](file://backend/app/api/v1/templates.py#L129-L169)
+
+## 详细组件分析
+
+### 科室管理组件
+
+#### 数据模型分析
+
+科室管理采用自引用关系实现树形结构：
+
+```mermaid
+erDiagram
+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
+}
+DEPARTMENTS }o--|| DEPARTMENTS : "parent"
+DEPARTMENTS ||--o{ STAFF : "has"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+
+#### 树形结构算法
+
+系统实现了高效的树形结构构建算法：
+
+```mermaid
+flowchart TD
+A[获取所有科室] --> B[构建ID到对象映射]
+B --> C[遍历科室列表]
+C --> D{检查是否有父节点}
+D --> |是| E[将当前节点添加到父节点children]
+D --> |否| F[添加到根节点列表]
+E --> G[继续下一个科室]
+F --> G
+G --> H[返回根节点树形结构]
+```
+
+**图表来源**
+- [department_service.py](file://backend/app/services/department_service.py#L112-L150)
+
+#### 前端界面设计
+
+前端采用Element Plus组件实现：
+
+- **搜索功能**：支持按名称、编码、类型搜索
+- **树形选择器**：用于上级科室选择
+- **状态切换**：支持启用/禁用切换
+- **分页显示**：支持大数据量分页
+
+**章节来源**
+- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
+- [department.js](file://frontend/src/api/department.js#L1-L32)
+
+### 员工信息管理组件
+
+#### 数据模型设计
+
+员工信息管理涵盖了完整的员工档案：
+
+```mermaid
+erDiagram
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+decimal base_salary
+decimal performance_ratio
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ STAFF : "belongs_to"
+STAFF ||--o{ ASSESSMENTS : "creates"
+STAFF ||--o{ SALARY_RECORDS : "has"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L88-L114)
+
+#### 数据验证规则
+
+系统实现了严格的数据验证：
+
+- **工号唯一性**：防止重复工号
+- **基本工资范围**：0-∞
+- **绩效系数范围**：0-5
+- **状态枚举**：只能是预定义值
+
+**章节来源**
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
+- [staff.js](file://frontend/src/api/staff.js#L1-L32)
+
+### 考核指标管理组件
+
+#### 指标类型体系
+
+系统支持多种类型的考核指标：
+
+| 指标类型 | 描述 | 权重范围 | 最高分值范围 |
+|---------|------|----------|-------------|
+| 质量指标 | 医疗质量相关 | 0.1-10 | 0-1000 |
+| 数量指标 | 工作量相关 | 0.1-10 | 0-1000 |
+| 效率指标 | 工作效率相关 | 0.1-10 | 0-1000 |
+| 服务指标 | 服务质量相关 | 0.1-10 | 0-1000 |
+| 成本指标 | 成本控制相关 | 0.1-10 | 0-1000 |
+
+#### BSC维度设计
+
+平衡计分卡四个维度：
+
+- **财务维度**：财务管理 (30%-40%)
+- **客户维度**：顾客服务 (25%-35%)  
+- **内部流程维度**：内部流程 (20%-30%)
+- **学习与成长维度**：学习与成长 (5%-15%)
+
+**章节来源**
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
+- [indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+### 指标模板管理组件
+
+#### 模板类型体系
+
+系统提供多种科室类型的标准化模板：
+
+| 模板类型 | 适用科室 | 特点 |
+|---------|---------|------|
+| 通用模板 | 全院通用 | 基础通用指标 |
+| 手术临床科室 | 外科系统 | 手术相关指标 |
+| 非手术有病房科室 | 内科系统 | 病房管理指标 |
+| 非手术无病房科室 | 门诊科室 | 门诊服务指标 |
+| 医技科室 | 检验、放射等 | 医技服务指标 |
+| 护理单元 | 护理部门 | 护理质量指标 |
+| 行政科室 | 后勤、财务等 | 行政管理指标 |
+| 后勤科室 | 总务、采购等 | 后勤保障指标 |
+
+#### 模板指标管理
+
+模板采用多对多关系管理：
+
+```mermaid
+erDiagram
+INDICATOR_TEMPLATES {
+int id PK
+string template_name
+string template_code UK
+enum template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
+datetime created_at
+datetime updated_at
+}
+TEMPLATE_INDICATORS {
+int id PK
+int template_id FK
+int indicator_id FK
+string category
+decimal target_value
+string target_unit
+decimal weight
+string scoring_method
+text scoring_params
+int sort_order
+text remark
+datetime created_at
+datetime updated_at
+}
+INDICATORS {
+int id PK
+string name
+string code UK
+enum indicator_type
+enum bs_dimension
+decimal weight
+decimal max_score
+decimal target_value
+string target_unit
+text calculation_method
+text assessment_method
+text deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
+datetime created_at
+datetime updated_at
+}
+INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "contains"
+INDICATORS ||--o{ TEMPLATE_INDICATORS : "references"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L387-L438)
+
+**章节来源**
+- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
+- [template.js](file://frontend/src/api/template.js#L1-L62)
+
+## 依赖关系分析
+
+系统采用了清晰的依赖层次结构：
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+D1[FastAPI]
+D2[SQLAlchemy]
+D3[Element Plus]
+D4[Vue.js]
+end
+subgraph "后端核心"
+C1[models.py]
+C2[schemas.py]
+C3[department_service.py]
+C4[staff_service.py]
+C5[indicator_service.py]
+C6[template_service.py]
+end
+subgraph "前端核心"
+F1[Departments.vue]
+F2[Staff.vue]
+F3[Indicators.vue]
+F4[Templates.vue]
+F5[department.js]
+F6[staff.js]
+F7[indicator.js]
+F8[template.js]
+end
+D1 --> C1
+D2 --> C1
+D3 --> F1
+D4 --> F1
+C1 --> C2
+C3 --> C1
+C4 --> C1
+C5 --> C1
+C6 --> C1
+F5 --> D1
+F6 --> D1
+F7 --> D1
+F8 --> D1
+F1 --> F5
+F2 --> F6
+F3 --> F7
+F4 --> F8
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L1-L13)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L8)
+
+### 数据一致性保证
+
+系统通过多种机制确保数据一致性：
+
+1. **数据库约束**：唯一性约束、外键约束
+2. **业务逻辑验证**：服务层数据验证
+3. **事务处理**：关键操作的事务保证
+4. **级联删除**：模板删除时自动清理关联数据
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L82-L85)
+- [models.py](file://backend/app/models/models.py#L143-L146)
+
+## 性能考虑
+
+### 查询优化策略
+
+1. **索引设计**：为常用查询字段建立索引
+2. **分页查询**：默认每页20条记录
+3. **批量操作**：支持批量添加模板指标
+4. **缓存策略**：模板类型和维度数据缓存
+
+### 前端性能优化
+
+1. **虚拟滚动**：大量数据时使用虚拟滚动
+2. **懒加载**：树形组件懒加载
+3. **防抖搜索**：搜索框输入防抖
+4. **组件复用**：表单组件复用
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+| 问题类型 | 症状 | 原因 | 解决方案 |
+|---------|------|------|---------|
+| 数据重复 | 创建失败，提示已存在 | 唯一性约束冲突 | 检查编码或名称唯一性 |
+| 权限不足 | 操作被拒绝 | 角色权限限制 | 提升用户角色或联系管理员 |
+| 外键约束 | 删除失败 | 存在外键引用 | 先删除子数据再删除父数据 |
+| 数据验证 | 提交失败 | 字段格式不正确 | 检查必填字段和格式要求 |
+
+### 错误处理机制
+
+系统实现了完善的错误处理：
+
+```mermaid
+flowchart TD
+A[请求到达] --> B{数据验证}
+B --> |通过| C[业务处理]
+B --> |失败| D[返回400错误]
+C --> E{业务逻辑}
+E --> |成功| F[返回200成功]
+E --> |失败| G[返回500错误]
+D --> H[错误详情]
+F --> I[成功详情]
+G --> H
+H --> J[日志记录]
+I --> J
+```
+
+**图表来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
+- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+
+## 结论
+
+基础数据管理模块为医院绩效系统提供了坚实的数据基础。通过合理的架构设计、完善的数据模型和严格的权限控制，系统能够有效支撑医院的绩效管理工作。
+
+### 主要优势
+
+1. **模块化设计**：清晰的功能划分和职责分离
+2. **数据完整性**：完善的约束和验证机制
+3. **用户体验**：直观的界面和流畅的操作体验
+4. **扩展性强**：灵活的模板系统支持定制化需求
+5. **性能稳定**：合理的优化策略确保系统稳定性
+
+### 发展建议
+
+1. **增加审计日志**：记录所有数据变更历史
+2. **完善权限粒度**：支持更细粒度的权限控制
+3. **增强数据导入**：支持Excel批量导入功能
+4. **优化移动端**：适配移动设备访问需求
+5. **扩展统计分析**：增加更多维度的统计报表
+
+该模块的成功实现为整个医院绩效系统的稳定运行奠定了重要基础，为后续功能扩展提供了良好的技术支撑。