hospital_performance/.qoder/repowiki/zh/content/测试指南.md

测试指南

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

目录

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 接口规范与响应格式，便于编写测试用例。

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
• backend/app/core/config.py
• backend/app/api/v1/auth.py
• backend/app/services/assessment_service.py
• frontend/src/main.js
• frontend/src/router/index.js
• frontend/src/api/index.js
• docs/api.md

章节来源

• backend/app/main.py
• backend/app/core/config.py
• frontend/src/main.js
• frontend/src/router/index.js
• frontend/src/api/index.js
• docs/api.md

核心组件

• 应用入口与中间件：健康检查、CORS、异常处理、全局路由注册。
• 配置中心：数据库连接、JWT、跨域、分页等配置。
• 认证模块：登录、注册、当前用户信息。
• 考核服务：列表查询、详情加载、创建、更新、提交、审核、终审、批量创建等。
• 前端应用：应用初始化、路由守卫、API 导出。

章节来源

• backend/app/main.py
• backend/app/core/config.py
• backend/app/api/v1/auth.py
• backend/app/services/assessment_service.py
• frontend/src/main.js
• frontend/src/router/index.js

架构总览

后端通过 FastAPI 提供 REST API，前端通过 Axios 调用接口；认证采用 JWT Bearer Token；数据库为 PostgreSQL，使用异步 SQLAlchemy 连接池。

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
• backend/app/core/config.py
• backend/app/api/v1/auth.py
• frontend/src/api/index.js

详细组件分析

认证模块测试

• 单元测试要点
  • 登录接口：用户名/密码正确、错误、账户禁用场景；返回 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：未登录、登录后访问。

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
• docs/api.md

章节来源

• backend/app/api/v1/auth.py
• docs/api.md

考核服务测试

• 单元测试要点
  • 列表查询：按员工、科室、年度、月份、状态过滤与分页。
  • 详情加载：关联加载员工与部门、明细与指标。
  • 创建考核：总分与加权分计算、明细插入。
  • 更新考核：状态限制（草稿/被拒）、替换明细、重新计算分数。
  • 提交/审核/终审：状态流转与时间戳更新。
  • 批量创建：按科室与周期生成考核记录。
• 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：终审。

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

章节来源

• backend/app/services/assessment_service.py
• docs/api.md

前端组件测试

• 单元测试
  • 路由守卫：未登录跳转登录页、登录后放行。
  • API 导出：确认各模块导出齐全。
  • 组件渲染：在无副作用前提下渲染断言。
• Mock 使用
  • 使用 jsdom + Vitest 的 DOM 环境。
  • 使用 axios 的 Mock Adapter 或 vitest 的 mock 实现，拦截 API 请求，返回测试数据。
• 集成测试
  • 登录后访问受保护页面，路由守卫生效。
  • 页面调用 API 层，返回数据驱动视图渲染。
• 端到端测试
  • 使用 Playwright/Cypress 打开浏览器，执行真实用户操作流（登录->导航->查看列表->查看详情）。

章节来源

• frontend/src/router/index.js
• frontend/src/api/index.js
• frontend/src/main.js

API 测试用例实现

• 基于接口文档设计用例
  • 认证：登录、注册、当前用户。
  • 基础数据：科室、员工、指标。
  • 考核管理：列表、详情、创建、更新、提交、审核、删除。
  • 工资核算：列表、生成、确认。
  • 统计报表：科室统计、排名、趋势、分布。
• 用例覆盖
  • 正常用例、边界用例、异常用例（400/401/403/404/422/500）。
  • 分页、过滤、排序参数组合。
• 自动化脚本
  • 可参考现有脚本，扩展为 pytest + httpx 的测试套件，或直接使用 httpx 的异步客户端进行并发测试。

章节来源

• docs/api.md
• backend/test_api.py

依赖分析

• 后端依赖
  • 测试框架：pytest、pytest-asyncio。
  • HTTP 客户端：httpx。
  • 数据库：sqlalchemy、asyncpg、aiosqlite（开发/测试）。
• 前端依赖
  • 测试框架：Vitest（推荐）或 Jest。
  • UI 测试：Playwright/Cypress（端到端）。
  • 构建与脚本：Vite、Vue Test Utils（可选）。

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
• frontend/package.json

章节来源

• backend/requirements.txt
• frontend/package.json

性能考虑

• 测试并发
  • 使用 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
• backend/app/core/config.py
• frontend/src/router/index.js

结论

本测试指南提供了从单元到端到端的系统化测试策略，结合项目现有架构与接口文档，明确了测试用例设计、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
• backend/app/core/config.py
• frontend/src/router/index.js

测试覆盖率与持续集成

• 覆盖率目标
  • 后端：语句≥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，便于回归验证。