# 快速开始

<cite>
**本文引用的文件**
- [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)
</cite>

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

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

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

```mermaid
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](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-L83)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)

章节来源
- [docs/backend.md](file://docs/backend.md#L16-L58)
- [docs/frontend.md](file://docs/frontend.md#L17-L48)

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

章节来源
- [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#L69-L79)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)

## 架构总览
系统启动顺序概览如下：

```mermaid
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](file://backend/app/main.py#L19-L51)
- [backend/app/core/config.py](file://backend/app/core/config.py#L13-L16)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)

## 详细组件分析

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

章节来源
- [docs/backend.md](file://docs/backend.md#L454-L468)
- [docs/frontend.md](file://docs/frontend.md#L380-L394)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L1-L27)

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

章节来源
- [backend/.env.example](file://backend/.env.example#L3-L4)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
- [docs/database.md](file://docs/database.md#L274-L285)

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

章节来源
- [backend/init_db.py](file://backend/init_db.py#L11-L83)

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

章节来源
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L47)

### 系统启动与访问
- 启动后端服务
  - 使用 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](file://backend/app/main.py#L83-L92)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
- [docs/backend.md](file://docs/backend.md#L460-L475)

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

章节来源
- [backend/init_db.py](file://backend/init_db.py#L69-L79)

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

章节来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L3-L96)

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

```mermaid
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](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)

章节来源
- [docs/backend.md](file://docs/backend.md#L3-L15)
- [docs/frontend.md](file://docs/frontend.md#L3-L16)

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

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

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

章节来源
- [backend/app/main.py](file://backend/app/main.py#L53-L76)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L63)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L30)

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

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

## 附录

### 常用命令速查
- 后端
  - 安装依赖：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](file://docs/backend.md#L454-L468)
- [docs/frontend.md](file://docs/frontend.md#L380-L394)