345 lines
14 KiB
Markdown
345 lines
14 KiB
Markdown
# 测试指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [backend/requirements.txt](file://backend/requirements.txt)
|
||
- [backend/.env.example](file://backend/.env.example)
|
||
- [backend/app/main.py](file://backend/app/main.py)
|
||
- [backend/app/core/config.py](file://backend/app/core/config.py)
|
||
- [backend/test_api.py](file://backend/test_api.py)
|
||
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
|
||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
|
||
- [frontend/package.json](file://frontend/package.json)
|
||
- [frontend/src/main.js](file://frontend/src/main.js)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
|
||
- [frontend/src/api/index.js](file://frontend/src/api/index.js)
|
||
- [docs/api.md](file://docs/api.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本测试指南面向“医院绩效系统”，覆盖后端 FastAPI 服务、前端 Vue 3 应用以及端到端测试的完整测试策略。内容包括单元测试、集成测试、API 测试、前端组件测试、端到端测试最佳实践；涵盖测试数据准备、Mock 对象使用、测试环境配置；并给出测试覆盖率要求、持续集成配置建议与自动化测试流程，以及测试报告生成、缺陷跟踪与回归测试策略。
|
||
|
||
## 项目结构
|
||
- 后端采用 FastAPI + SQLAlchemy 2.0 + PostgreSQL 异步架构，提供 REST API。
|
||
- 前端采用 Vue 3 + Pinia + Vue Router + Element Plus，通过 Axios 发起 API 请求。
|
||
- 文档化了 API 接口规范与响应格式，便于编写测试用例。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "后端"
|
||
M["app/main.py<br/>应用入口与路由注册"]
|
||
CFG["app/core/config.py<br/>配置中心"]
|
||
AUTH["app/api/v1/auth.py<br/>认证路由"]
|
||
AS["app/services/assessment_service.py<br/>考核服务"]
|
||
end
|
||
subgraph "前端"
|
||
MAINJS["src/main.js<br/>应用初始化"]
|
||
ROUTER["src/router/index.js<br/>路由与守卫"]
|
||
APIIDX["src/api/index.js<br/>API 导出"]
|
||
end
|
||
subgraph "外部"
|
||
DB["PostgreSQL"]
|
||
DOCS["docs/api.md<br/>接口文档"]
|
||
end
|
||
MAINJS --> ROUTER
|
||
MAINJS --> APIIDX
|
||
M --> AUTH
|
||
AUTH --> DB
|
||
AS --> DB
|
||
DOCS --> AUTH
|
||
DOCS --> AS
|
||
```
|
||
|
||
图表来源
|
||
- [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#L14-L74)
|
||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
|
||
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
|
||
- [docs/api.md](file://docs/api.md#L1-L557)
|
||
|
||
章节来源
|
||
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
|
||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
|
||
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
|
||
- [docs/api.md](file://docs/api.md#L1-L557)
|
||
|
||
## 核心组件
|
||
- 应用入口与中间件：健康检查、CORS、异常处理、全局路由注册。
|
||
- 配置中心：数据库连接、JWT、跨域、分页等配置。
|
||
- 认证模块：登录、注册、当前用户信息。
|
||
- 考核服务：列表查询、详情加载、创建、更新、提交、审核、终审、批量创建等。
|
||
- 前端应用：应用初始化、路由守卫、API 导出。
|
||
|
||
章节来源
|
||
- [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#L14-L74)
|
||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
|
||
|
||
## 架构总览
|
||
后端通过 FastAPI 提供 REST API，前端通过 Axios 调用接口；认证采用 JWT Bearer Token；数据库为 PostgreSQL，使用异步 SQLAlchemy 连接池。
|
||
|
||
```mermaid
|
||
graph TB
|
||
FE["前端应用<br/>Vue 3 + Axios"]
|
||
BE["后端服务<br/>FastAPI + SQLAlchemy"]
|
||
DB["数据库<br/>PostgreSQL"]
|
||
AUTH["认证服务<br/>JWT"]
|
||
FE --> |HTTP/HTTPS| BE
|
||
BE --> |SQLAlchemy| DB
|
||
FE --> |登录/鉴权| AUTH
|
||
AUTH --> |签发/校验| BE
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/main.py](file://backend/app/main.py#L19-L51)
|
||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
|
||
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
|
||
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
|
||
|
||
## 详细组件分析
|
||
|
||
### 认证模块测试
|
||
- 单元测试要点
|
||
- 登录接口：用户名/密码正确、错误、账户禁用场景；返回 Token 的结构与有效期。
|
||
- 注册接口：重复用户名、密码加密存储、角色与员工绑定。
|
||
- 当前用户接口：未登录拦截、Token 过期/无效处理。
|
||
- Mock 使用
|
||
- 使用 SQLAlchemy 异步会话 Mock 替换真实数据库交互。
|
||
- 使用密码哈希与 JWT 工具函数的 Mock，避免真实加密与签名开销。
|
||
- 集成测试要点
|
||
- 登录后携带 Authorization 头访问受保护资源。
|
||
- 未携带或携带无效 Token 的 401/403 场景。
|
||
- API 测试用例示例
|
||
- POST /api/v1/auth/login：用户名/密码为空、错误凭据、禁用账户。
|
||
- POST /api/v1/auth/register：重复用户名、正常注册。
|
||
- GET /api/v1/auth/me：未登录、登录后访问。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant A as "认证路由(auth.py)"
|
||
participant S as "安全工具(security)"
|
||
participant D as "数据库(AsyncSession)"
|
||
C->>A : POST /api/v1/auth/login
|
||
A->>D : 查询用户
|
||
D-->>A : 用户信息
|
||
A->>S : 校验密码
|
||
S-->>A : 校验结果
|
||
A->>S : 生成访问令牌
|
||
S-->>A : 访问令牌
|
||
A-->>C : {access_token, token_type}
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
|
||
- [docs/api.md](file://docs/api.md#L39-L78)
|
||
|
||
章节来源
|
||
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L14-L74)
|
||
- [docs/api.md](file://docs/api.md#L39-L78)
|
||
|
||
### 考核服务测试
|
||
- 单元测试要点
|
||
- 列表查询：按员工、科室、年度、月份、状态过滤与分页。
|
||
- 详情加载：关联加载员工与部门、明细与指标。
|
||
- 创建考核：总分与加权分计算、明细插入。
|
||
- 更新考核：状态限制（草稿/被拒）、替换明细、重新计算分数。
|
||
- 提交/审核/终审：状态流转与时间戳更新。
|
||
- 批量创建：按科室与周期生成考核记录。
|
||
- Mock 使用
|
||
- 使用 SQLAlchemy Mock 会话模拟查询、插入、更新。
|
||
- 使用枚举与日期工具的 Mock，确保测试稳定。
|
||
- 集成测试要点
|
||
- 考核创建后，详情能正确返回关联数据。
|
||
- 状态机正确性：草稿->提交->审核/拒绝->终审。
|
||
- API 测试用例示例
|
||
- GET /api/v1/assessments：分页、过滤参数。
|
||
- GET /api/v1/assessments/{id}：详情与关联数据。
|
||
- POST /api/v1/assessments：创建考核与明细。
|
||
- PUT /api/v1/assessments/{id}：更新明细与备注。
|
||
- POST /api/v1/assessments/{id}/submit：提交。
|
||
- POST /api/v1/assessments/{id}/review：审核通过/拒绝。
|
||
- POST /api/v1/assessments/{id}/finalize：终审。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["进入创建考核"]) --> CalcScore["计算总分与加权分"]
|
||
CalcScore --> SaveAssessment["保存考核主表"]
|
||
SaveAssessment --> SaveDetails["逐条保存明细"]
|
||
SaveDetails --> Flush["刷新并获取ID"]
|
||
Flush --> End(["返回完整考核记录"])
|
||
style Start fill:#fff,stroke:#333
|
||
style End fill:#fff,stroke:#333
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||
|
||
章节来源
|
||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||
- [docs/api.md](file://docs/api.md#L298-L397)
|
||
|
||
### 前端组件测试
|
||
- 单元测试
|
||
- 路由守卫：未登录跳转登录页、登录后放行。
|
||
- API 导出：确认各模块导出齐全。
|
||
- 组件渲染：在无副作用前提下渲染断言。
|
||
- Mock 使用
|
||
- 使用 jsdom + Vitest 的 DOM 环境。
|
||
- 使用 axios 的 Mock Adapter 或 vitest 的 mock 实现，拦截 API 请求，返回测试数据。
|
||
- 集成测试
|
||
- 登录后访问受保护页面，路由守卫生效。
|
||
- 页面调用 API 层，返回数据驱动视图渲染。
|
||
- 端到端测试
|
||
- 使用 Playwright/Cypress 打开浏览器，执行真实用户操作流（登录->导航->查看列表->查看详情）。
|
||
|
||
章节来源
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
|
||
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
|
||
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
|
||
|
||
### API 测试用例实现
|
||
- 基于接口文档设计用例
|
||
- 认证：登录、注册、当前用户。
|
||
- 基础数据：科室、员工、指标。
|
||
- 考核管理：列表、详情、创建、更新、提交、审核、删除。
|
||
- 工资核算：列表、生成、确认。
|
||
- 统计报表：科室统计、排名、趋势、分布。
|
||
- 用例覆盖
|
||
- 正常用例、边界用例、异常用例（400/401/403/404/422/500）。
|
||
- 分页、过滤、排序参数组合。
|
||
- 自动化脚本
|
||
- 可参考现有脚本，扩展为 pytest + httpx 的测试套件，或直接使用 httpx 的异步客户端进行并发测试。
|
||
|
||
章节来源
|
||
- [docs/api.md](file://docs/api.md#L1-L557)
|
||
- [backend/test_api.py](file://backend/test_api.py#L1-L33)
|
||
|
||
## 依赖分析
|
||
- 后端依赖
|
||
- 测试框架：pytest、pytest-asyncio。
|
||
- HTTP 客户端：httpx。
|
||
- 数据库：sqlalchemy、asyncpg、aiosqlite（开发/测试）。
|
||
- 前端依赖
|
||
- 测试框架：Vitest（推荐）或 Jest。
|
||
- UI 测试：Playwright/Cypress（端到端）。
|
||
- 构建与脚本：Vite、Vue Test Utils（可选）。
|
||
|
||
```mermaid
|
||
graph LR
|
||
PY["pytest"] --> BA["backend/app/*"]
|
||
PYA["pytest-asyncio"] --> BA
|
||
HTTPX["httpx"] --> BA
|
||
VIT["Vitest/Jest"] --> FE["frontend/src/*"]
|
||
PW["Playwright/Cypress"] --> FE
|
||
VITE["Vite"] --> FE
|
||
```
|
||
|
||
图表来源
|
||
- [backend/requirements.txt](file://backend/requirements.txt#L15-L16)
|
||
- [frontend/package.json](file://frontend/package.json#L21-L26)
|
||
|
||
章节来源
|
||
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
|
||
- [frontend/package.json](file://frontend/package.json#L1-L27)
|
||
|
||
## 性能考虑
|
||
- 测试并发
|
||
- 使用 pytest-asyncio 与 httpx 异步客户端提升 API 测试吞吐。
|
||
- Mock 策略
|
||
- 尽量使用内存数据库（如 aiosqlite）与 Mock 替代真实外部服务，减少 I/O。
|
||
- 覆盖率
|
||
- 建议后端语句/分支覆盖率≥80%，前端组件/路由覆盖率≥70%。
|
||
- 资源隔离
|
||
- 使用独立测试数据库实例或容器，避免多团队并行测试冲突。
|
||
|
||
## 故障排查指南
|
||
- 常见问题
|
||
- 登录失败：检查用户名/密码、账户状态、JWT 密钥与算法配置。
|
||
- 401/403：确认 Authorization 头、Token 过期、路由守卫逻辑。
|
||
- 数据库连接：检查 DATABASE_URL、连接池大小、PostgreSQL 可达性。
|
||
- CORS：确认前端端口在 CORS_ORIGINS 白名单中。
|
||
- 日志与调试
|
||
- 后端异常处理器输出请求与错误详情，便于定位。
|
||
- 前端路由守卫打印 token 状态，辅助判断鉴权链路。
|
||
- 回归测试
|
||
- 对认证、核心业务流程（创建/更新/提交/审核）建立回归用例集，每次变更后运行。
|
||
|
||
章节来源
|
||
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
|
||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
|
||
|
||
## 结论
|
||
本测试指南提供了从单元到端到端的系统化测试策略，结合项目现有架构与接口文档，明确了测试用例设计、Mock 使用、环境配置与自动化流程的关键点。建议优先完善后端服务与认证模块的单元/集成测试，再推进前端组件与端到端测试，并在 CI 中引入覆盖率与回归测试，确保系统质量与交付效率。
|
||
|
||
## 附录
|
||
|
||
### 测试数据准备
|
||
- 用户数据：管理员账号（用于登录与后续接口调用）。
|
||
- 基础数据：科室、员工、指标、模板等基础数据。
|
||
- 考核数据：按月度周期生成若干考核记录，覆盖不同状态（草稿、已提交、已审核、已终审）。
|
||
|
||
### Mock 对象使用清单
|
||
- 后端
|
||
- SQLAlchemy 异步会话 Mock：查询、插入、更新、删除。
|
||
- 安全工具 Mock：密码哈希、JWT 生成与校验。
|
||
- 前端
|
||
- axios Mock Adapter：拦截 API 请求，返回测试数据。
|
||
- 路由守卫 Mock：模拟 localStorage 中 token 的存在与失效。
|
||
|
||
### 测试环境配置
|
||
- 后端
|
||
- 环境变量：DATABASE_URL、SECRET_KEY、DEBUG、CORS_ORIGINS。
|
||
- 建议使用独立测试数据库，避免污染生产数据。
|
||
- 前端
|
||
- 开发服务器端口：Vite 默认端口。
|
||
- 路由守卫：确保本地开发时 Token 存储可用。
|
||
|
||
章节来源
|
||
- [backend/.env.example](file://backend/.env.example#L1-L11)
|
||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
|
||
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
|
||
|
||
### 测试覆盖率与持续集成
|
||
- 覆盖率目标
|
||
- 后端：语句≥80%，分支≥70%。
|
||
- 前端：组件/路由≥70%，关键逻辑≥80%。
|
||
- CI 建议
|
||
- 触发条件：push 到 develop/main 分支，PR 打开/更新。
|
||
- 步骤：安装依赖、启动测试数据库、运行测试与覆盖率、上传覆盖率、端到端测试（可选）。
|
||
- 报告：生成 HTML/XML 报告，集成到 CI 平台。
|
||
|
||
### 自动化测试流程
|
||
- 单元/集成测试：pytest + pytest-asyncio（后端），Vitest（前端）。
|
||
- API 测试：pytest-httpx 或 httpx 异步客户端。
|
||
- 端到端测试：Playwright/Cypress，覆盖登录、导航、CRUD 主流程。
|
||
- 回归测试：对核心业务流程（认证、考核、工资）建立回归套件，每日/每次变更运行。
|
||
|
||
### 测试报告与缺陷跟踪
|
||
- 报告
|
||
- pytest：HTML 报告；覆盖率：xml/html。
|
||
- 前端：Vitest HTML 报告；覆盖率：cobertura。
|
||
- 缺陷跟踪
|
||
- 使用 Issue 模板记录缺陷，包含步骤、期望/实际结果、日志与截图。
|
||
- 关联测试用例 ID，便于回归验证。 |