chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
44f250f58e9037d8176b8523c19d27f62558e1b5
hospital_performance/.qoder/repowiki/zh/content/后端开发指南/项目结构说明.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

17 KiB
Raw Blame History

项目结构说明

**本文档引用的文件** - [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/core/security.py](file://backend/app/core/security.py) - [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py) - [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.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/assessment_service.py](file://backend/app/services/assessment_service.py) - [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py) - [backend/alembic/env.py](file://backend/alembic/env.py) - [backend/.env.example](file://backend/.env.example) - [backend/requirements.txt](file://backend/requirements.txt)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

这是一个基于FastAPI的医院绩效管理系统后端项目。系统采用现代化的Python异步Web框架，使用SQLAlchemy 2.0进行数据库操作，PostgreSQL作为数据存储，实现了完整的绩效考核管理功能。

项目结构

项目采用清晰的分层架构设计，主要目录组织如下：

graph TB
subgraph "后端应用 (backend)"
subgraph "应用主体 (app)"
MAIN[app/main.py<br/>应用入口]
CORE[app/core/<br/>核心配置]
API[app/api/v1/<br/>API路由]
MODELS[app/models/<br/>数据模型]
SCHEMAS[app/schemas/<br/>数据模式]
SERVICES[app/services/<br/>业务服务]
UTILS[app/utils/<br/>工具函数]
SCRIPTS[app/scripts/<br/>初始化脚本]
LOGS[app/logs/<br/>日志文件]
end
subgraph "数据库迁移 (alembic)"
ALEMBIC[alembic/versions/<br/>版本化迁移]
ENV[alembic/env.py<br/>迁移环境]
end
subgraph "配置文件"
ENV_EXAMPLE[.env.example<br/>环境配置示例]
REQUIREMENTS[requirements.txt<br/>依赖包]
end
subgraph "测试文件"
TESTS[tests/<br/>测试用例]
end
end

图表来源

目录组织说明

app目录 - 应用主体

  • main.py: 应用程序入口点，创建FastAPI实例并配置中间件
  • core/: 核心配置模块，包含配置管理、数据库连接、安全认证、日志配置
  • api/v1/: API路由模块，按功能模块划分的RESTful接口
  • models/: 数据模型定义，使用SQLAlchemy ORM映射数据库表
  • schemas/: Pydantic数据模式，用于请求响应的数据验证和序列化
  • services/: 业务逻辑服务层，实现具体的业务规则和数据处理
  • scripts/: 初始化脚本，用于数据预填充和系统初始化
  • logs/: 日志文件存储目录

alembic目录 - 数据库迁移管理

  • versions/: 版本化的数据库迁移文件
  • env.py: Alembic迁移环境配置

配置文件

  • .env.example: 环境变量配置示例文件
  • requirements.txt: Python依赖包清单

Section sources

核心组件

应用配置系统

系统采用集中式配置管理，通过Pydantic Settings实现类型安全的配置读取：

classDiagram
class Settings {
+str APP_NAME
+str APP_VERSION
+bool DEBUG
+str API_PREFIX
+str DATABASE_URL
+int DATABASE_POOL_SIZE
+int DATABASE_MAX_OVERFLOW
+str SECRET_KEY
+str ALGORITHM
+int ACCESS_TOKEN_EXPIRE_MINUTES
+str[] CORS_ORIGINS
+int DEFAULT_PAGE_SIZE
+int MAX_PAGE_SIZE
}
class Config {
+str env_file
+bool case_sensitive
}
Settings --> Config : "继承"

图表来源

数据库连接层

使用SQLAlchemy 2.0的异步ORM特性，提供高效的数据库操作能力：

classDiagram
class Base {
<<DeclarativeBase>>
}
class AsyncEngine {
+create_async_engine()
}
class AsyncSession {
+AsyncSession()
}
class SessionMaker {
+async_session_maker
}
Base <|-- Department
Base <|-- Staff
Base <|-- Indicator
Base <|-- Assessment
Base <|-- AssessmentDetail
AsyncEngine --> AsyncSession : "创建"
SessionMaker --> AsyncSession : "管理"

图表来源

安全认证系统

集成JWT令牌认证和密码加密，提供多层级的权限控制：

classDiagram
class SecurityModule {
+OAuth2PasswordBearer oauth2_scheme
+verify_password()
+get_password_hash()
+create_access_token()
+decode_token()
+get_current_user()
+get_current_active_user()
+get_current_admin_user()
+get_current_manager_user()
}
class TokenPayload {
+str exp
+str sub
}
class User {
+int id
+str username
+str role
+bool is_active
}
SecurityModule --> TokenPayload : "验证"
SecurityModule --> User : "获取"

图表来源

Section sources

架构概览

系统采用经典的三层架构模式，实现了清晰的关注点分离：

graph TB
subgraph "表示层 (API Layer)"
ROUTERS[API路由器]
ENDPOINTS[端点处理器]
end
subgraph "业务逻辑层 (Service Layer)"
ASSESSMENT_SERVICE[考核服务]
DEPARTMENT_SERVICE[科室服务]
STAFF_SERVICE[员工服务]
SALARY_SERVICE[薪资服务]
end
subgraph "数据访问层 (Data Access Layer)"
MODELS[ORM模型]
DATABASE[(PostgreSQL数据库)]
end
subgraph "基础设施层"
CONFIG[配置管理]
SECURITY[安全认证]
LOGGING[日志系统]
end
ROUTERS --> ENDPOINTS
ENDPOINTS --> ASSESSMENT_SERVICE
ENDPOINTS --> DEPARTMENT_SERVICE
ENDPOINTS --> STAFF_SERVICE
ASSESSMENT_SERVICE --> MODELS
DEPARTMENT_SERVICE --> MODELS
STAFF_SERVICE --> MODELS
MODELS --> DATABASE
ROUTERS --> SECURITY
ENDPOINTS --> SECURITY
ASSESSMENT_SERVICE --> LOGGING
CONFIG --> ROUTERS
CONFIG --> DATABASE

图表来源

模块间依赖关系

系统遵循依赖倒置原则，上层模块不依赖下层模块的具体实现：

graph LR
subgraph "外部依赖"
FASTAPI[FastAPI框架]
SQLALCHEMY[SQLAlchemy 2.0]
POSTGRESQL[PostgreSQL]
end
subgraph "应用层"
MAIN[main.py]
ROUTERS[API路由器]
SERVICES[业务服务]
MODELS[数据模型]
SCHEMAS[数据模式]
end
subgraph "核心模块"
CONFIG[配置管理]
DATABASE[数据库连接]
SECURITY[安全认证]
LOGGING[日志系统]
end
FASTAPI --> MAIN
SQLALCHEMY --> MODELS
POSTGRESQL --> DATABASE
MAIN --> ROUTERS
ROUTERS --> SERVICES
SERVICES --> MODELS
MODELS --> DATABASE
MAIN --> CONFIG
ROUTERS --> CONFIG
SERVICES --> CONFIG
SERVICES --> SECURITY
MODELS --> SECURITY
MAIN --> LOGGING
SERVICES --> LOGGING

图表来源

Section sources

详细组件分析

API路由模块

系统采用版本化的API设计，v1版本包含完整的功能模块：

graph TB
subgraph "API版本控制"
V1_API[API v1 路由器]
end
subgraph "功能模块"
AUTH[认证模块]
DEPARTMENTS[科室管理]
STAFF[员工管理]
INDICATORS[指标管理]
ASSESSMENTS[考核管理]
SALARY[薪资计算]
STATS[统计分析]
FINANCE[财务管理]
PERFORMANCE_PLANS[绩效计划]
MENUS[菜单管理]
TEMPLATES[模板管理]
end
V1_API --> AUTH
V1_API --> DEPARTMENTS
V1_API --> STAFF
V1_API --> INDICATORS
V1_API --> ASSESSMENTS
V1_API --> SALARY
V1_API --> STATS
V1_API --> FINANCE
V1_API --> PERFORMANCE_PLANS
V1_API --> MENUS
V1_API --> TEMPLATES

图表来源

考核管理API流程

sequenceDiagram
participant Client as 客户端
participant Router as 路由器
participant Service as 服务层
participant Model as 数据模型
participant DB as 数据库
Client->>Router : GET /api/v1/assessments
Router->>Service : get_list()
Service->>DB : 查询考核记录
DB-->>Service : 返回结果集
Service->>Service : 处理分页和过滤
Service-->>Router : 返回处理后的数据
Router-->>Client : JSON响应
Note over Router,Service : 考核状态流转
Client->>Router : POST /api/v1/assessments/{id}/submit
Router->>Service : submit()
Service->>DB : 更新状态为SUBMITTED
DB-->>Service : 确认更新
Service-->>Router : 返回提交结果
Router-->>Client : 状态更新确认

图表来源

Section sources

数据模型设计

系统采用枚举类型确保数据完整性，支持平衡计分卡的四个维度：

erDiagram
DEPARTMENT {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
boolean is_active
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
}
INDICATOR {
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
string applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
ASSESSMENT {
int id PK
int staff_id FK
int period_year
int period_month
string period_type
numeric total_score
numeric weighted_score
enum status
int assessor_id FK
int reviewer_id FK
datetime submit_time
datetime review_time
text remark
datetime created_at
datetime updated_at
}
ASSESSMENT_DETAIL {
int id PK
int assessment_id FK
int indicator_id FK
numeric actual_value
numeric score
text evidence
text remark
datetime created_at
datetime updated_at
}
DEPARTMENT ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENT : "参与"
INDICATOR ||--o{ ASSESSMENT_DETAIL : "被评估"
ASSESSMENT ||--o{ ASSESSMENT_DETAIL : "包含"

图表来源

数据验证流程

flowchart TD
START([请求到达]) --> VALIDATE_INPUT[验证输入参数]
VALIDATE_INPUT --> INPUT_VALID{参数有效?}
INPUT_VALID --> |否| RETURN_ERROR[返回错误响应]
INPUT_VALID --> |是| CHECK_AUTH[检查认证状态]
CHECK_AUTH --> AUTH_VALID{认证有效?}
AUTH_VALID --> |否| RETURN_AUTH_ERROR[返回认证错误]
AUTH_VALID --> |是| CHECK_PERMISSION[检查权限]
CHECK_PERMISSION --> HAS_PERMISSION{有权限?}
HAS_PERMISSION --> |否| RETURN_PERM_ERROR[返回权限错误]
HAS_PERMISSION --> |是| PROCESS_REQUEST[处理业务逻辑]
PROCESS_REQUEST --> SERVICE_CALL[调用服务层]
SERVICE_CALL --> DB_OPERATION[数据库操作]
DB_OPERATION --> DB_SUCCESS{操作成功?}
DB_SUCCESS --> |否| HANDLE_DB_ERROR[处理数据库错误]
DB_SUCCESS --> |是| FORMAT_RESPONSE[格式化响应]
HANDLE_DB_ERROR --> RETURN_ERROR
FORMAT_RESPONSE --> RETURN_SUCCESS[返回成功响应]
RETURN_AUTH_ERROR --> END([结束])
RETURN_PERM_ERROR --> END
RETURN_ERROR --> END
RETURN_SUCCESS --> END

图表来源

Section sources

初始化脚本系统

系统提供完整的数据初始化功能，支持多种科室类型的指标模板：

graph TB
subgraph "初始化流程"
INIT_SCRIPT[init_templates.py]
DATA_SOURCE[指标模板数据]
ENGINE[数据库引擎]
SESSION[异步会话]
end
subgraph "模板类型"
GENERAL[通用模板]
SURGICAL[手术科室模板]
MEDICAL_TECH[医技科室模板]
ADMIN[行政科室模板]
LOGISTICS[后勤科室模板]
end
INIT_SCRIPT --> DATA_SOURCE
INIT_SCRIPT --> ENGINE
ENGINE --> SESSION
DATA_SOURCE --> INIT_SCRIPT
GENERAL --> INIT_SCRIPT
SURGICAL --> INIT_SCRIPT
MEDICAL_TECH --> INIT_SCRIPT
ADMIN --> INIT_SCRIPT
LOGISTICS --> INIT_SCRIPT

图表来源

Section sources

依赖关系分析

外部依赖管理

系统使用requirements.txt统一管理所有Python依赖：

graph TB
subgraph "Web框架"
FASTAPI[fastapi>=0.115.0]
UVICORN[uvicorn[standard]>=0.32.0]
end
subgraph "数据库相关"
SQLALCHEMY[sqlalchemy>=2.0.36]
ASYNCPG[asyncpg>=0.30.0]
ALEMBIC[alembic>=1.14.0]
end
subgraph "数据验证"
PYDANTIC[pydantic>=2.10.0]
SETTINGS[pydantic-settings>=2.6.0]
EMAIL[email-validator>=2.2.0]
end
subgraph "安全认证"
JOSE[python-jose[cryptography]>=3.3.0]
PASSLIB[passlib[bcrypt]>=1.7.4]
end
subgraph "开发工具"
DOTENV[python-dotenv>=1.0.0]
HTTPX[httpx>=0.28.0]
PYTEST[pytest>=8.0.0]
ASYNCIO[pytest-asyncio>=0.24.0]
end
FASTAPI --> UVICORN
SQLALCHEMY --> ASYNCPG
PYDANTIC --> SETTINGS
JOSE --> PASSLIB

图表来源

环境配置管理

系统采用.env.example文件提供配置模板，支持多环境部署：

flowchart LR
ENV_EXAMPLE[.env.example] --> ENV_FILE[实际.env文件]
ENV_FILE --> CONFIG[配置加载]
CONFIG --> SETTINGS[Settings对象]
SETTINGS --> APPLICATION[应用程序]
subgraph "配置类别"
DB_CONFIG[数据库配置]
JWT_CONFIG[JWT配置]
DEBUG_CONFIG[调试配置]
CORS_CONFIG[CORS配置]
end
ENV_FILE --> DB_CONFIG
ENV_FILE --> JWT_CONFIG
ENV_FILE --> DEBUG_CONFIG
ENV_FILE --> CORS_CONFIG

图表来源

Section sources

性能考虑

异步数据库操作

系统全面采用SQLAlchemy 2.0的异步特性，提升并发处理能力：

  • 使用异步引擎和会话工厂
  • 支持连接池管理和溢出控制
  • 实现自动事务管理和异常回滚

缓存策略

  • 配置LRU缓存的Settings单例
  • 数据库连接池优化
  • 请求级别的中间件缓存

日志性能优化

  • 文件轮转避免日志文件过大
  • 多级别日志分离（应用日志、错误日志）
  • 异步日志写入减少阻塞

故障排除指南

常见问题诊断

数据库连接问题

  • 检查DATABASE_URL配置
  • 验证PostgreSQL服务状态
  • 确认网络连接和防火墙设置

JWT认证失败

  • 验证SECRET_KEY配置
  • 检查令牌过期时间设置
  • 确认用户状态为激活

API路由错误

  • 检查API_PREFIX配置
  • 验证路由注册顺序
  • 确认中间件配置正确

调试技巧

  1. 启用调试模式: 设置DEBUG=True查看详细日志
  2. 检查环境变量: 确保.env文件配置正确
  3. 验证数据库迁移: 运行alembic升级检查
  4. 测试API端点: 使用OpenAPI文档测试接口

Section sources

结论

该医院绩效管理系统采用了现代化的软件架构设计，具有以下特点：

架构优势

  • 清晰的分层设计，职责分离明确
  • 异步编程模型，提升系统性能
  • 类型安全的配置管理
  • 完整的认证授权机制

扩展性考虑

  • 模块化设计便于功能扩展
  • 数据库迁移机制支持版本演进
  • 标准化的API设计便于前端集成

最佳实践建议

  • 遵循单一职责原则
  • 使用类型注解提高代码可读性
  • 实施完善的错误处理机制
  • 定期进行性能监控和优化

该系统为医院绩效管理提供了完整的技术解决方案，具备良好的可维护性和扩展性。