提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/快速开始.md
+++ b/.qoder/repowiki/zh/content/快速开始.md
@@ -0,0 +1,333 @@
+# 快速开始
+
+<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)