hospital_performance/.qoder/repowiki/zh/content/快速开始.md

快速开始

**本文引用的文件** - [backend/.env.example](file://backend/.env.example) - [backend/requirements.txt](file://backend/requirements.txt) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/init_db.py](file://backend/init_db.py) - [backend/app/core/init_db.py](file://backend/app/core/init_db.py) - [backend/alembic.ini](file://backend/alembic.ini) - [frontend/package.json](file://frontend/package.json) - [frontend/vite.config.js](file://frontend/vite.config.js) - [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js) - [frontend/src/api/auth.js](file://frontend/src/api/auth.js) - [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/core/security.py](file://backend/app/core/security.py)

目录

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

简介

本指南面向希望快速搭建并运行“医院绩效管理系统”的开发者，覆盖后端 FastAPI 服务、前端 Vue 3 应用、数据库初始化与配置、环境变量设置、默认管理员账号与首次登录流程，以及常见问题排查与验证步骤。系统采用前后端分离架构，后端提供 REST API，前端通过代理访问后端接口。

项目结构

• 后端（Python/FastAPI）位于 backend 目录，包含 API 路由、核心配置、数据库模型、安全模块与初始化脚本。
• 前端（Vue 3/Vite）位于 frontend 目录，包含页面组件、状态管理、API 请求封装与开发服务器配置。
• 文档与参考材料位于 docs 与 参考文档 目录，便于对照业务背景与设计说明。

graph TB
subgraph "后端"
A["app/main.py<br/>应用入口与路由挂载"]
B["app/core/config.py<br/>配置加载(settings)"]
C["app/api/v1/*.py<br/>API 路由"]
D["app/models/models.py<br/>数据模型"]
E["app/core/security.py<br/>认证与令牌"]
F["init_db.py / app/core/init_db.py<br/>初始化脚本"]
end
subgraph "前端"
G["vite.config.js<br/>开发服务器与代理"]
H["src/views/Login.vue<br/>登录页"]
I["src/stores/user.js<br/>用户状态"]
J["src/api/auth.js<br/>认证请求封装"]
end
K["backend/.env.example<br/>环境变量示例"]
L["backend/requirements.txt<br/>依赖清单"]
H --> J --> C
I --> J
G --> C
A --> C
B --> A
E --> C
F --> D
K -.-> B
L -.-> A

图表来源

• backend/app/main.py
• backend/app/core/config.py
• backend/app/api/v1/auth.py
• backend/app/models/models.py
• backend/app/core/security.py
• frontend/vite.config.js
• frontend/src/views/Login.vue
• frontend/src/stores/user.js
• frontend/src/api/auth.js
• backend/init_db.py
• backend/app/core/init_db.py
• backend/.env.example
• backend/requirements.txt

章节来源

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

核心组件

• 应用入口与路由：后端通过主程序创建 FastAPI 实例，注册路由前缀、CORS 中间件与健康检查端点。
• 配置模块：集中管理应用名、版本、API 前缀、数据库连接、JWT 密钥与跨域白名单等。
• 认证与安全：提供密码哈希、JWT 令牌签发与校验、OAuth2 密码流、当前用户解析与权限校验。
• 数据模型：定义科室、员工、指标、考核、计划、菜单、模板等核心实体及其关系。
• 初始化脚本：创建数据库表并填充示例数据，包含默认管理员账号。
• 前端登录与代理：前端本地开发服务器代理到后端，登录成功写入本地存储并跳转首页。

章节来源

• backend/app/main.py
• backend/app/core/config.py
• backend/app/core/security.py
• backend/app/models/models.py
• backend/init_db.py
• frontend/src/views/Login.vue
• frontend/vite.config.js

架构总览

系统采用前后端分离部署：

• 前端通过 Vite 开发服务器启动，本地代理将 /api 前缀请求转发至后端。
• 后端使用 FastAPI 提供 REST API，支持异步数据库访问与 JWT 认证。
• 数据库初始化可通过脚本自动完成，或结合 Alembic 进行迁移管理。

graph TB
FE["前端开发服务器<br/>vite.config.js: 5173"]
API["后端服务<br/>app/main.py: 8000"]
DB["数据库<br/>PostgreSQL/SQLite(迁移)"]
AUTH["认证模块<br/>app/core/security.py"]
MODELS["数据模型<br/>app/models/models.py"]
FE --> |"/api 代理"| API
API --> AUTH
API --> MODELS
MODELS --> DB

图表来源

• frontend/vite.config.js
• backend/app/main.py
• backend/app/core/security.py
• backend/app/models/models.py
• backend/alembic.ini

详细组件分析

后端安装与配置

• Python 版本与虚拟环境
  • 使用 Python 3.10+，建议在虚拟环境中进行隔离开发。
• 依赖安装
  • 在 backend 目录执行安装命令，安装后端所需依赖。
• 环境变量
  • 复制示例文件为 .env 并按需修改数据库连接、密钥与调试开关。
• 数据库初始化
  • 可选择使用初始化脚本创建表与示例数据；或使用 Alembic 进行迁移。
• 启动后端服务
  • 在 backend 目录运行主程序，监听 8000 端口。

章节来源

• backend/requirements.txt
• backend/.env.example
• backend/init_db.py
• backend/app/core/init_db.py
• backend/alembic.ini
• backend/app/main.py

前端安装与配置

• 依赖安装
  • 在 frontend 目录执行安装命令，安装 Vue 3、路由、状态管理与开发工具。
• 开发服务器与代理
  • Vite 默认端口 5173，配置将 /api 前缀代理到后端 8000 端口。
• 启动前端
  • 在 frontend 目录运行开发命令，浏览器访问本地地址。

章节来源

• frontend/package.json
• frontend/vite.config.js

数据库配置与初始化

• 数据库类型与驱动
  • 后端默认使用 PostgreSQL 异步驱动，Alembic 配置中也包含 SQLite 示例。
• 初始化策略
  • 方式一：使用初始化脚本创建表与示例数据，包含默认管理员账号。
  • 方式二：使用 Alembic 进行迁移管理，适用于生产或更复杂的版本演进场景。
• 初始数据
  • 脚本会创建示例科室、员工、指标与管理员用户，便于快速体验。

章节来源

• backend/.env.example
• backend/alembic.ini
• backend/init_db.py
• backend/app/core/init_db.py

系统启动流程（后端）

sequenceDiagram
participant Dev as "开发者"
participant Backend as "后端进程(app/main.py)"
participant DB as "数据库"
Dev->>Backend : 启动后端服务
Backend->>Backend : 加载配置(settings)
Backend->>DB : 建立连接/创建表(可选)
Backend-->>Dev : 监听 8000 端口

图表来源

• backend/app/main.py
• backend/app/core/config.py
• backend/init_db.py

登录与认证流程（前后端）

sequenceDiagram
participant User as "用户"
participant Front as "前端(Login.vue)"
participant Store as "Pinia(user.js)"
participant API as "后端(auth.py)"
participant Sec as "安全模块(security.py)"
User->>Front : 输入用户名/密码
Front->>Store : 调用 login(username,password)
Store->>API : POST /api/v1/auth/login
API->>Sec : 校验密码/生成JWT
API-->>Store : 返回 access_token
Store->>Store : 写入localStorage并保存token
Store-->>Front : 登录成功回调
Front-->>User : 跳转首页

图表来源

• frontend/src/views/Login.vue
• frontend/src/stores/user.js
• frontend/src/api/auth.js
• backend/app/api/v1/auth.py
• backend/app/core/security.py

默认管理员账号与首次登录

• 默认账号
  • 用户名：admin
  • 密码：admin123
• 登录入口
  • 前端登录页内置默认值，也可手动输入。
• 登录后行为
  • 成功后前端保存 token 并跳转首页。

章节来源

• backend/init_db.py
• frontend/src/views/Login.vue
• frontend/src/stores/user.js

验证步骤

• 后端健康检查
  • 访问后端健康端点，确认返回健康状态与版本信息。
• 前端代理连通性
  • 在前端开发环境下，登录页能正常发起 /api/v1/auth/login 请求并收到响应。
• 数据库可用性
  • 初始化脚本执行后，相关表与示例数据存在，可查询验证。

章节来源

• backend/app/main.py
• frontend/vite.config.js
• backend/init_db.py

依赖关系分析

• 后端依赖
  • Web 框架与 ASGI 服务器、SQLAlchemy 2.0、异步数据库驱动、Pydantic、JWT、密码哈希、环境变量加载等。
• 前端依赖
  • Vue 3、路由、状态管理、HTTP 客户端、UI 组件库与开发工具。
• 代理关系
  • 前端开发服务器将 /api 前缀请求代理到后端，避免跨域问题。

graph LR
R["requirements.txt"] --> BE["后端依赖"]
P["package.json"] --> FE["前端依赖"]
VCFG["vite.config.js"] --> PROXY["/api 代理"]
PROXY --> BE

图表来源

• backend/requirements.txt
• frontend/package.json
• frontend/vite.config.js

章节来源

• backend/requirements.txt
• frontend/package.json
• frontend/vite.config.js

性能注意事项

• 数据库连接池
  • 后端配置了连接池大小与溢出数量，可根据并发需求调整。
• 异步 I/O
  • 后端采用异步数据库访问，前端请求通过代理转发，整体具备较好的并发处理能力。
• 前端打包
  • 生产构建时建议开启压缩与 Tree Shaking，减少包体积。

章节来源

• backend/app/core/config.py
• backend/requirements.txt

故障排查指南

• 端口冲突
  • 后端默认 8000，前端默认 5173；若端口被占用，请在相应配置中修改。
• 代理未生效
  • 确认前端代理配置指向正确的后端地址与端口。
• 数据库连接失败
  • 检查环境变量中的数据库 URL 是否正确，数据库服务是否启动。
• 登录失败
  • 确认初始化脚本已执行，管理员账号存在；检查密码是否正确。
• CORS 问题
  • 确认后端 CORS 白名单包含前端地址，或在开发环境下允许本地源。

章节来源

• backend/app/main.py
• backend/app/core/config.py
• frontend/vite.config.js
• backend/.env.example
• backend/init_db.py

结论

按照本指南完成环境准备、依赖安装、数据库初始化与系统启动后，即可在本地运行完整的前后端系统。默认管理员账号可用于首次登录与功能验证。如需扩展或接入真实数据库，可在配置模块与环境变量中进行相应调整。

附录

环境变量配置说明

• 数据库连接
  • 用于 PostgreSQL 的连接字符串，包含主机、端口、数据库名与凭据。
• JWT 密钥
  • 用于签发与校验访问令牌，生产环境需足够复杂且保密。
• 调试模式
  • 控制日志与异常输出级别，开发阶段可开启。

章节来源

• backend/.env.example

初始数据导入方法

• 使用初始化脚本
  • 执行脚本创建表与示例数据，包含默认管理员账号。
• 使用 Alembic
  • 通过迁移配置与版本化脚本管理数据库演进。

章节来源

• backend/init_db.py
• backend/app/core/init_db.py
• backend/alembic.ini