# 快速开始

<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)