提交文件
This commit is contained in:
673
.qoder/repowiki/zh/content/后端开发指南/项目结构说明.md
Normal file
673
.qoder/repowiki/zh/content/后端开发指南/项目结构说明.md
Normal file
@@ -0,0 +1,673 @@
|
||||
# 项目结构说明
|
||||
|
||||
<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/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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
这是一个基于FastAPI的医院绩效管理系统后端项目。系统采用现代化的Python异步Web框架，使用SQLAlchemy 2.0进行数据库操作，PostgreSQL作为数据存储，实现了完整的绩效考核管理功能。
|
||||
|
||||
## 项目结构
|
||||
|
||||
项目采用清晰的分层架构设计，主要目录组织如下：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
|
||||
|
||||
### 目录组织说明
|
||||
|
||||
**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**
|
||||
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 应用配置系统
|
||||
|
||||
系统采用集中式配置管理，通过Pydantic Settings实现类型安全的配置读取：
|
||||
|
||||
```mermaid
|
||||
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 : "继承"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
|
||||
|
||||
### 数据库连接层
|
||||
|
||||
使用SQLAlchemy 2.0的异步ORM特性，提供高效的数据库操作能力：
|
||||
|
||||
```mermaid
|
||||
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 : "管理"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L23-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L200)
|
||||
|
||||
### 安全认证系统
|
||||
|
||||
集成JWT令牌认证和密码加密，提供多层级的权限控制：
|
||||
|
||||
```mermaid
|
||||
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 : "获取"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
|
||||
|
||||
**Section sources**
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用经典的三层架构模式，实现了清晰的关注点分离：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [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#L1-L200)
|
||||
|
||||
### 模块间依赖关系
|
||||
|
||||
系统遵循依赖倒置原则，上层模块不依赖下层模块的具体实现：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
|
||||
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
|
||||
|
||||
**Section sources**
|
||||
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
|
||||
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### API路由模块
|
||||
|
||||
系统采用版本化的API设计，v1版本包含完整的功能模块：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
|
||||
|
||||
#### 考核管理API流程
|
||||
|
||||
```mermaid
|
||||
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 : 状态更新确认
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L200)
|
||||
|
||||
**Section sources**
|
||||
- [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/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L200)
|
||||
|
||||
### 数据模型设计
|
||||
|
||||
系统采用枚举类型确保数据完整性，支持平衡计分卡的四个维度：
|
||||
|
||||
```mermaid
|
||||
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 : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L200)
|
||||
|
||||
#### 数据验证流程
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
|
||||
|
||||
**Section sources**
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L200)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L200)
|
||||
|
||||
### 初始化脚本系统
|
||||
|
||||
系统提供完整的数据初始化功能，支持多种科室类型的指标模板：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L200)
|
||||
|
||||
**Section sources**
|
||||
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L200)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 外部依赖管理
|
||||
|
||||
系统使用requirements.txt统一管理所有Python依赖：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
|
||||
|
||||
### 环境配置管理
|
||||
|
||||
系统采用.env.example文件提供配置模板，支持多环境部署：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/.env.example](file://backend/.env.example#L1-L11)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
|
||||
|
||||
**Section sources**
|
||||
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
|
||||
- [backend/.env.example](file://backend/.env.example#L1-L11)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 异步数据库操作
|
||||
|
||||
系统全面采用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**
|
||||
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
## 结论
|
||||
|
||||
该医院绩效管理系统采用了现代化的软件架构设计，具有以下特点：
|
||||
|
||||
**架构优势**
|
||||
- 清晰的分层设计，职责分离明确
|
||||
- 异步编程模型，提升系统性能
|
||||
- 类型安全的配置管理
|
||||
- 完整的认证授权机制
|
||||
|
||||
**扩展性考虑**
|
||||
- 模块化设计便于功能扩展
|
||||
- 数据库迁移机制支持版本演进
|
||||
- 标准化的API设计便于前端集成
|
||||
|
||||
**最佳实践建议**
|
||||
- 遵循单一职责原则
|
||||
- 使用类型注解提高代码可读性
|
||||
- 实施完善的错误处理机制
|
||||
- 定期进行性能监控和优化
|
||||
|
||||
该系统为医院绩效管理提供了完整的技术解决方案，具备良好的可维护性和扩展性。
|
||||
Reference in New Issue
Block a user