提交文件
This commit is contained in:
289
.qoder/repowiki/zh/content/项目概述/快速开始.md
Normal file
289
.qoder/repowiki/zh/content/项目概述/快速开始.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 快速开始
|
||||
|
||||
<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)
|
||||
Reference in New Issue
Block a user