chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fd53ff36a89fa32a6914edcf2d4357326ac85a2f
hospital_performance/.qoder/repowiki/zh/content/快速开始.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

333 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 快速开始
<cite>
**本文引用的文件**
- [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)
</cite>
## 目录
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 与 参考文档 目录，便于对照业务背景与设计说明。
```mermaid
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](file://backend/app/main.py#L15-L80)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L260)
- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L43)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L73-L89)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L12-L30)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L80)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
## 核心组件
- 应用入口与路由：后端通过主程序创建 FastAPI 实例，注册路由前缀、CORS 中间件与健康检查端点。
- 配置模块：集中管理应用名、版本、API 前缀、数据库连接、JWT 密钥与跨域白名单等。
- 认证与安全：提供密码哈希、JWT 令牌签发与校验、OAuth2 密码流、当前用户解析与权限校验。
- 数据模型：定义科室、员工、指标、考核、计划、菜单、模板等核心实体及其关系。
- 初始化脚本：创建数据库表并填充示例数据，包含默认管理员账号。
- 前端登录与代理：前端本地开发服务器代理到后端，登录成功写入本地存储并跳转首页。
章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L80)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L43)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L146)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L73-L89)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
## 架构总览
系统采用前后端分离部署：
- 前端通过 Vite 开发服务器启动，本地代理将 /api 前缀请求转发至后端。
- 后端使用 FastAPI 提供 REST API，支持异步数据库访问与 JWT 认证。
- 数据库初始化可通过脚本自动完成，或结合 Alembic 进行迁移管理。
```mermaid
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](file://frontend/vite.config.js#L12-L20)
- [backend/app/main.py](file://backend/app/main.py#L83-L91)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L146)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
## 详细组件分析
### 后端安装与配置
- Python 版本与虚拟环境
- 使用 Python 3.10+，建议在虚拟环境中进行隔离开发。
- 依赖安装
- 在 backend 目录执行安装命令，安装后端所需依赖。
- 环境变量
- 复制示例文件为 .env 并按需修改数据库连接、密钥与调试开关。
- 数据库初始化
- 可选择使用初始化脚本创建表与示例数据；或使用 Alembic 进行迁移。
- 启动后端服务
- 在 backend 目录运行主程序，监听 8000 端口。
章节来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L103-L110)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
- [backend/app/main.py](file://backend/app/main.py#L83-L91)
### 前端安装与配置
- 依赖安装
- 在 frontend 目录执行安装命令，安装 Vue 3、路由、状态管理与开发工具。
- 开发服务器与代理
- Vite 默认端口 5173，配置将 /api 前缀代理到后端 8000 端口。
- 启动前端
- 在 frontend 目录运行开发命令，浏览器访问本地地址。
章节来源
- [frontend/package.json](file://frontend/package.json#L1-L27)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
### 数据库配置与初始化
- 数据库类型与驱动
- 后端默认使用 PostgreSQL 异步驱动，Alembic 配置中也包含 SQLite 示例。
- 初始化策略
- 方式一：使用初始化脚本创建表与示例数据，包含默认管理员账号。
- 方式二：使用 Alembic 进行迁移管理，适用于生产或更复杂的版本演进场景。
- 初始数据
- 脚本会创建示例科室、员工、指标与管理员用户，便于快速体验。
章节来源
- [backend/.env.example](file://backend/.env.example#L4)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L103-L110)
### 系统启动流程（后端）
```mermaid
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](file://backend/app/main.py#L15-L80)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/init_db.py](file://backend/init_db.py#L11-L18)
### 登录与认证流程（前后端）
```mermaid
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](file://frontend/src/views/Login.vue#L73-L89)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L43)
### 默认管理员账号与首次登录
- 默认账号
- 用户名：admin
- 密码：admin123
- 登录入口
- 前端登录页内置默认值，也可手动输入。
- 登录后行为
- 成功后前端保存 token 并跳转首页。
章节来源
- [backend/init_db.py](file://backend/init_db.py#L69-L76)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L64-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
### 验证步骤
- 后端健康检查
- 访问后端健康端点，确认返回健康状态与版本信息。
- 前端代理连通性
- 在前端开发环境下，登录页能正常发起 /api/v1/auth/login 请求并收到响应。
- 数据库可用性
- 初始化脚本执行后，相关表与示例数据存在，可查询验证。
章节来源
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
## 依赖关系分析
- 后端依赖
- Web 框架与 ASGI 服务器、SQLAlchemy 2.0、异步数据库驱动、Pydantic、JWT、密码哈希、环境变量加载等。
- 前端依赖
- Vue 3、路由、状态管理、HTTP 客户端、UI 组件库与开发工具。
- 代理关系
- 前端开发服务器将 /api 前缀请求代理到后端，避免跨域问题。
```mermaid
graph LR
R["requirements.txt"] --> BE["后端依赖"]
P["package.json"] --> FE["前端依赖"]
VCFG["vite.config.js"] --> PROXY["/api 代理"]
PROXY --> BE
```
图表来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
章节来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
## 性能注意事项
- 数据库连接池
- 后端配置了连接池大小与溢出数量，可根据并发需求调整。
- 异步 I/O
- 后端采用异步数据库访问，前端请求通过代理转发，整体具备较好的并发处理能力。
- 前端打包
- 生产构建时建议开启压缩与 Tree Shaking，减少包体积。
章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
## 故障排查指南
- 端口冲突
- 后端默认 8000，前端默认 5173；若端口被占用，请在相应配置中修改。
- 代理未生效
- 确认前端代理配置指向正确的后端地址与端口。
- 数据库连接失败
- 检查环境变量中的数据库 URL 是否正确，数据库服务是否启动。
- 登录失败
- 确认初始化脚本已执行，管理员账号存在；检查密码是否正确。
- CORS 问题
- 确认后端 CORS 白名单包含前端地址，或在开发环境下允许本地源。
章节来源
- [backend/app/main.py](file://backend/app/main.py#L42-L48)
- [backend/app/core/config.py](file://backend/app/core/config.py#L29)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
- [backend/.env.example](file://backend/.env.example#L4)
- [backend/init_db.py](file://backend/init_db.py#L69-L76)
## 结论
按照本指南完成环境准备、依赖安装、数据库初始化与系统启动后，即可在本地运行完整的前后端系统。默认管理员账号可用于首次登录与功能验证。如需扩展或接入真实数据库，可在配置模块与环境变量中进行相应调整。
## 附录
### 环境变量配置说明
- 数据库连接
- 用于 PostgreSQL 的连接字符串，包含主机、端口、数据库名与凭据。
- JWT 密钥
- 用于签发与校验访问令牌，生产环境需足够复杂且保密。
- 调试模式
- 控制日志与异常输出级别，开发阶段可开启。
章节来源
- [backend/.env.example](file://backend/.env.example#L4-L10)
### 初始数据导入方法
- 使用初始化脚本
- 执行脚本创建表与示例数据，包含默认管理员账号。
- 使用 Alembic
- 通过迁移配置与版本化脚本管理数据库演进。
章节来源
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L103-L110)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
Reference in New Issue View Git Blame Copy Permalink