hospital_performance/.qoder/repowiki/zh/content/项目概述/快速开始.md

快速开始

**本文引用的文件** - [backend/.env.example](file://backend/.env.example) - [backend/requirements.txt](file://backend/requirements.txt) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/main.py](file://backend/app/main.py) - [backend/init_db.py](file://backend/init_db.py) - [backend/alembic.ini](file://backend/alembic.ini) - [docs/backend.md](file://docs/backend.md) - [docs/frontend.md](file://docs/frontend.md) - [docs/database.md](file://docs/database.md) - [frontend/package.json](file://frontend/package.json) - [frontend/vite.config.js](file://frontend/vite.config.js) - [frontend/src/router/index.js](file://frontend/src/router/index.js) - [frontend/src/api/request.js](file://frontend/src/api/request.js)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能注意事项
8. 故障排除指南
9. 结论
10. 附录

简介

本快速开始指南面向首次部署“医院绩效管理系统”的用户，帮助你在本地完成环境搭建、依赖安装、数据库初始化与配置，并顺利启动后端与前端服务，完成首次登录与基本操作。文档同时提供默认管理员账号与初始密码、常见问题排查与系统访问指引，确保你能快速体验系统核心功能。

项目结构

系统采用前后端分离架构：

• 后端：基于 FastAPI + SQLAlchemy 2.0 + PostgreSQL 的异步 API 服务，提供认证、基础数据、考核、统计与工资等功能模块。
• 前端：基于 Vue 3 + Element Plus + Pinia + Vue Router 的单页应用，通过 Axios 与后端交互，路由守卫保障登录态。

graph TB
subgraph "后端"
A["FastAPI 应用<br/>app/main.py"]
B["配置中心<br/>app/core/config.py"]
C["数据库引擎/会话<br/>app/core/database.py"]
D["初始化脚本<br/>init_db.py"]
E["数据库迁移配置<br/>alembic.ini"]
end
subgraph "前端"
F["Vite 开发服务器<br/>vite.config.js"]
G["路由配置<br/>src/router/index.js"]
H["HTTP 请求封装<br/>src/api/request.js"]
end
U["浏览器/用户"] --> F
F --> A
A --> B
A --> C
A --> D
A --> E
U --> G
G --> H

图表来源

• backend/app/main.py
• backend/app/core/config.py
• backend/init_db.py
• backend/alembic.ini
• frontend/vite.config.js
• frontend/src/router/index.js
• frontend/src/api/request.js

章节来源

• docs/backend.md
• docs/frontend.md

核心组件

• 后端应用入口与中间件：负责创建 FastAPI 实例、注册路由前缀、CORS、健康检查与全局异常处理。
• 配置中心：集中管理应用名称、版本、API 前缀、数据库连接、JWT 密钥与跨域白名单等。
• 初始化脚本：创建数据库表并注入默认测试数据（含默认管理员账户）。
• 前端路由与请求封装：统一 API 基址、请求头携带 Token、统一错误处理与登录态校验。

章节来源

• backend/app/main.py
• backend/app/core/config.py
• backend/init_db.py
• frontend/src/router/index.js
• frontend/src/api/request.js

架构总览

系统启动顺序概览如下：

sequenceDiagram
participant Dev as "开发者"
participant Backend as "后端服务"
participant Frontend as "前端服务"
participant DB as "数据库"
Dev->>Backend : 启动后端(uvicorn)
Backend->>DB : 连接数据库(配置中心)
Backend->>Backend : 注册路由/中间件
Dev->>Frontend : 启动前端(Vite)
Frontend->>Backend : 发起登录请求(/api/v1/auth/login)
Backend-->>Frontend : 返回访问令牌(Token)
Frontend->>Backend : 带Token访问受保护接口
Backend-->>Frontend : 返回业务数据

图表来源

• backend/app/main.py
• backend/app/core/config.py
• frontend/src/api/request.js
• frontend/src/router/index.js

详细组件分析

环境与依赖准备

• Python 环境
  • 使用 Python 3.10+（推荐 3.10 或更高），确保 pip 可用。
  • 在后端目录安装依赖：参考后端开发指南中的安装命令。
• Node.js 环境
  • 使用 Node.js 18+，确保 npm 可用。
  • 在前端目录安装依赖：参考前端开发指南中的安装命令。

章节来源

• docs/backend.md
• docs/frontend.md
• backend/requirements.txt
• frontend/package.json

数据库安装与配置

• 数据库选择
  • 默认配置使用 PostgreSQL（异步驱动），也可使用 SQLite（用于迁移工具）。
• PostgreSQL 安装与准备
  • 安装 PostgreSQL 服务，创建数据库与用户，确保网络可达。
  • 修改后端环境变量或配置文件中的数据库连接串，使其指向你的数据库实例。
• Alembic 迁移配置
  • 迁移工具默认使用 SQLite 路径，若使用 PostgreSQL，需调整迁移配置指向相同数据库。

章节来源

• backend/.env.example
• backend/alembic.ini
• docs/database.md

项目克隆与初始化

• 克隆仓库到本地后，进入后端目录执行依赖安装与数据库初始化。
• 初始化数据库时，系统会自动创建所有表并写入默认测试数据（含默认管理员账户）。

章节来源

• backend/init_db.py

环境变量配置

• 复制示例环境文件并按需修改：
  • 数据库连接串（PostgreSQL）
  • JWT 密钥（生产环境务必替换为足够强度的密钥）
  • 调试模式与跨域白名单
• 配置文件加载优先级与缓存策略由配置模块统一管理。

章节来源

• backend/.env.example
• backend/app/core/config.py

系统启动与访问

• 启动后端服务
  • 使用 uvicorn 启动 FastAPI 应用，默认监听 0.0.0.0:8000。
  • 后端提供健康检查接口与 OpenAPI 文档入口。
• 启动前端服务
  • 使用 Vite 启动前端开发服务器，默认监听 0.0.0.0:5173。
  • 前端通过代理将 /api 前缀转发至后端 8000 端口。
• 访问系统
  • 前端地址：http://localhost:5173
  • 后端文档：http://localhost:8000/api/v1/docs

章节来源

• backend/app/main.py
• frontend/vite.config.js
• docs/backend.md

默认管理员账号与初始密码

• 默认管理员用户名：admin
• 默认管理员初始密码：admin123
• 首次登录后建议立即修改密码并完善角色权限。

章节来源

• backend/init_db.py

首次登录后的基本操作

• 登录后进入工作台，可按需进行以下基础操作：
  • 基础数据管理：维护科室、员工、考核指标与指标模板。
  • 考核管理：创建与管理绩效考核记录。
  • 工资核算：基于考核结果生成工资核算记录。
  • 统计报表：查看部门与个人的绩效统计与趋势。
  • 经济核算：查看财务相关数据。
  • 系统管理：维护菜单与系统参数（如适用）。

章节来源

• frontend/src/router/index.js

依赖关系分析

后端与前端的关键依赖关系如下：

graph LR
subgraph "后端依赖"
R1["FastAPI"]
R2["SQLAlchemy 2.0"]
R3["Pydantic/Settings"]
R4["Alembic"]
R5["asyncpg/aiosqlite"]
R6["Uvicorn"]
end
subgraph "前端依赖"
F1["Vue 3"]
F2["Vue Router"]
F3["Pinia"]
F4["Element Plus/Axios"]
F5["Vite"]
end
R1 --> R2
R1 --> R3
R1 --> R6
R2 --> R5
R4 --> R2
F1 --> F2
F1 --> F3
F4 --> R1
F5 --> F1

图表来源

• backend/requirements.txt
• frontend/package.json

章节来源

• docs/backend.md
• docs/frontend.md

性能注意事项

• 数据库连接池：合理设置连接池大小与溢出数量，避免并发过高导致连接争用。
• 分页与查询：列表接口支持分页与条件过滤，建议前端按需传参，避免一次性拉取大量数据。
• 异步 I/O：后端采用异步 SQLAlchemy 与异步 PostgreSQL 驱动，注意在业务逻辑中正确使用异步上下文。
• 前端渲染：大表格与图表建议开启虚拟滚动与懒加载，减少首屏压力。

[本节为通用建议，不直接分析具体文件]

故障排除指南

• 后端无法启动
  • 检查端口占用与防火墙设置；确认 uvicorn 启动命令与主机/端口配置。
  • 查看后端日志输出，定位异常堆栈。
• 前端无法访问后端接口
  • 确认前端代理配置指向后端地址；检查 /api 前缀是否一致。
  • 若出现跨域问题，检查后端 CORS 配置与前端代理配置。
• 登录失败或 Token 过期
  • 确认用户名与密码正确；Token 过期会触发自动跳转登录页。
  • 检查后端 JWT 密钥配置与前端请求头 Authorization。
• 数据库连接失败
  • 检查数据库连接串、凭据与网络连通性；确认数据库已创建且用户具备权限。
  • 如使用 Alembic 进行迁移，确保迁移配置与实际数据库一致。
• 健康检查失败
  • 访问后端健康检查接口，确认服务状态与版本信息。

章节来源

• backend/app/main.py
• frontend/vite.config.js
• frontend/src/api/request.js
• frontend/src/router/index.js
• backend/app/core/config.py

结论

通过本快速开始指南，你可以在本地完成环境准备、依赖安装、数据库初始化与配置，并成功启动后端与前端服务。首次登录后即可进行基础数据与考核流程的体验。遇到问题时，可依据故障排除指南逐项排查。建议在生产环境中进一步完善安全配置与运维监控。

[本节为总结性内容，不直接分析具体文件]

附录

常用命令速查

• 后端
  • 安装依赖：pip install -r requirements.txt
  • 启动开发服务器：uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
  • 运行测试：pytest
• 前端
  • 安装依赖：npm install
  • 启动开发服务器：npm run dev
  • 构建生产包：npm run build
  • 预览生产包：npm run preview

章节来源

• docs/backend.md
• docs/frontend.md