# 测试指南

<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，便于回归验证。