martial-master/docs/TEST_PLAN.md

# 武术比赛评分系统 - 测试规划文档

## 一、测试现状分析

### 1.1 现有测试类（4个）
| 测试类 | 覆盖模块 | 测试数量 | 状态 |
|--------|----------|----------|------|
| MartialAthleteServiceTest | 运动员服务 | 15 | 基础 |
| MartialScoreServiceTest | 评分服务 | 10 | 基础 |
| MartialResultServiceTest | 成绩服务 | - | 待检查 |
| MartialSchedulePlanServiceTest | 赛程计划 | - | 待检查 |

### 1.2 待测试模块（24个Service）
| 优先级 | 模块 | 复杂度 | 业务重要性 |
|--------|------|--------|------------|
| P0 | MartialCompetitionService | 高 | 核心 |
| P0 | MartialProjectService | 高 | 核心 |
| P0 | MartialScoreService | 高 | 核心 |
| P0 | MartialResultService | 高 | 核心 |
| P0 | MartialScheduleArrangeService | 高 | 核心 |
| P1 | MartialAthleteService | 中 | 重要 |
| P1 | MartialRegistrationOrderService | 中 | 重要 |
| P1 | MartialJudgeService | 中 | 重要 |
| P1 | MartialTeamService | 中 | 重要 |
| P1 | MartialVenueService | 低 | 重要 |
| P2 | MartialSchedulePlanService | 中 | 一般 |
| P2 | MartialScheduleAthleteService | 中 | 一般 |
| P2 | MartialDeductionItemService | 低 | 一般 |
| P2 | MartialExceptionEventService | 低 | 一般 |
| P3 | MartialBannerService | 低 | 辅助 |
| P3 | MartialInfoPublishService | 低 | 辅助 |
| P3 | MartialLiveUpdateService | 低 | 辅助 |
| P3 | MartialContactService | 低 | 辅助 |
| P3 | MartialActivityScheduleService | 低 | 辅助 |
| P3 | MartialCompetitionAttachmentService | 低 | 辅助 |
| P3 | MartialCompetitionRulesService | 低 | 辅助 |
| P3 | MartialJudgeInviteService | 低 | 辅助 |
| P3 | MartialJudgeProjectService | 低 | 辅助 |
| P3 | MartialScheduleService | 低 | 辅助 |

## 二、测试策略

### 2.1 测试金字塔
```
           /\
          /  \     E2E Tests (5%)
         /----\    - API集成测试
        /      \
       /--------\  Integration Tests (20%)
      /          \ - Service层集成测试
     /------------\- 数据库交互测试
    /              \
   /----------------\ Unit Tests (75%)
                      - Service单元测试
                      - 工具类测试
                      - 验证逻辑测试
```

### 2.2 测试类型
1. **单元测试 (Unit Tests)**
   - 使用 Mockito 模拟依赖
   - 测试业务逻辑正确性
   - 测试边界条件和异常处理

2. **集成测试 (Integration Tests)**
   - 使用 @SpringBootTest
   - 测试数据库交互
   - 测试事务处理

3. **API测试 (Controller Tests)**
   - 使用 MockMvc
   - 测试请求/响应格式
   - 测试权限验证

## 三、测试规范

### 3.1 命名规范
```
测试类命名:
  {被测类名}Test.java            - 单元测试
  {被测类名}IntegrationTest.java - 集成测试
  {Controller名}ApiTest.java     - API测试

测试方法命名:
  test_{方法名}_{场景}_{预期结果}()
  
示例:
  test_calculateScore_validInput_returnsCorrectScore()
  test_submitScore_duplicateSubmit_throwsException()
```

### 3.2 测试结构 (AAA模式)
```java
@Test
@DisplayName("描述测试场景")
void test_methodName_scenario_expectedResult() {
    // Arrange - 准备测试数据
    
    // Act - 执行被测方法
    
    // Assert - 验证结果
}
```

### 3.3 断言规范
- 使用 AssertJ 或 JUnit5 断言
- 每个测试方法只测试一个场景
- 断言信息要清晰明确

## 四、实施计划

### Phase 1: P0 核心模块测试 (Week 1)
| 任务 | 测试类 | 测试用例数 | 状态 |
|------|--------|------------|------|
| 1.1 | MartialCompetitionServiceTest | 20+ | 待开发 |
| 1.2 | MartialProjectServiceTest | 15+ | 待开发 |
| 1.3 | MartialScoreServiceTest | 25+ | 增强 |
| 1.4 | MartialResultServiceTest | 20+ | 增强 |
| 1.5 | MartialScheduleArrangeServiceTest | 30+ | 待开发 |

### Phase 2: P1 重要模块测试 (Week 2)
| 任务 | 测试类 | 测试用例数 | 状态 |
|------|--------|------------|------|
| 2.1 | MartialAthleteServiceTest | 25+ | 增强 |
| 2.2 | MartialRegistrationOrderServiceTest | 20+ | 待开发 |
| 2.3 | MartialJudgeServiceTest | 15+ | 待开发 |
| 2.4 | MartialTeamServiceTest | 15+ | 待开发 |
| 2.5 | MartialVenueServiceTest | 10+ | 待开发 |

### Phase 3: P2 一般模块测试 (Week 3)
| 任务 | 测试类 | 测试用例数 | 状态 |
|------|--------|------------|------|
| 3.1 | MartialSchedulePlanServiceTest | 15+ | 增强 |
| 3.2 | MartialScheduleAthleteServiceTest | 15+ | 待开发 |
| 3.3 | MartialDeductionItemServiceTest | 10+ | 待开发 |
| 3.4 | MartialExceptionEventServiceTest | 10+ | 待开发 |

### Phase 4: P3 辅助模块 + 集成测试 (Week 4)
| 任务 | 测试类 | 测试用例数 | 状态 |
|------|--------|------------|------|
| 4.1 | 辅助模块单元测试 | 50+ | 待开发 |
| 4.2 | Controller API测试 | 30+ | 待开发 |
| 4.3 | 集成测试 | 20+ | 待开发 |

## 五、测试用例设计

### 5.1 MartialCompetitionServiceTest (赛事管理)
```
创建赛事:
  - test_createCompetition_validData_success
  - test_createCompetition_duplicateCode_throwsException
  - test_createCompetition_invalidDateRange_throwsException
  - test_createCompetition_missingRequiredFields_throwsException

更新赛事:
  - test_updateCompetition_validData_success
  - test_updateCompetition_notFound_throwsException
  - test_updateCompetition_statusLocked_throwsException

查询赛事:
  - test_getCompetitionById_exists_returnsCompetition
  - test_getCompetitionById_notExists_returnsNull
  - test_listCompetitions_withPagination_returnsPage
  - test_listCompetitions_byStatus_filtersCorrectly

赛事状态:
  - test_startCompetition_validState_success
  - test_startCompetition_alreadyStarted_throwsException
  - test_endCompetition_validState_success
  - test_endCompetition_notStarted_throwsException

统计功能:
  - test_getCompetitionStats_returnsCorrectCounts
  - test_getTotalParticipants_calculatesCorrectly
```

### 5.2 MartialScoreServiceTest (评分管理)
```
提交评分:
  - test_submitScore_validScore_success
  - test_submitScore_outOfRange_throwsException
  - test_submitScore_duplicateSubmit_throwsException
  - test_submitScore_invalidJudge_throwsException
  - test_submitScore_invalidAthlete_throwsException

评分计算:
  - test_calculateFinalScore_normalCase_success
  - test_calculateFinalScore_removeHighLow_success
  - test_calculateFinalScore_withDifficultyCoefficient_success
  - test_calculateFinalScore_withDeductions_success

异常检测:
  - test_detectAnomaly_largeDeviation_flagged
  - test_detectAnomaly_normalDeviation_notFlagged
  - test_detectAnomaly_allSameScore_flagged

评分修改:
  - test_modifyScore_withinTimeLimit_success
  - test_modifyScore_exceedTimeLimit_throwsException
  - test_modifyScore_requiresApproval_pendingStatus
```

### 5.3 MartialScheduleArrangeServiceTest (赛程编排)
```
自动编排:
  - test_autoArrange_validInput_generatesSchedule
  - test_autoArrange_conflictDetection_resolvesConflicts
  - test_autoArrange_venueCapacity_respectsLimits
  - test_autoArrange_timeSlots_noOverlap

分组逻辑:
  - test_groupAthletes_byProject_correctGroups
  - test_groupAthletes_maxPerGroup_respectsLimit
  - test_groupAthletes_balancedDistribution_success

冲突处理:
  - test_detectConflict_sameAthleteOverlap_detected
  - test_detectConflict_venueOverbook_detected
  - test_resolveConflict_autoReassign_success

调整功能:
  - test_adjustSchedule_swapSlots_success
  - test_adjustSchedule_changeVenue_success
  - test_adjustSchedule_logChanges_recorded
```

## 六、测试覆盖率目标

| 模块类型 | 行覆盖率 | 分支覆盖率 | 方法覆盖率 |
|----------|----------|------------|------------|
| P0 核心模块 | >= 80% | >= 70% | >= 90% |
| P1 重要模块 | >= 70% | >= 60% | >= 85% |
| P2 一般模块 | >= 60% | >= 50% | >= 80% |
| P3 辅助模块 | >= 50% | >= 40% | >= 70% |
| **整体目标** | **>= 70%** | **>= 60%** | **>= 85%** |

## 七、测试工具和依赖

### 7.1 已有依赖
- JUnit 5 (Jupiter)
- Mockito
- Spring Boot Test

### 7.2 建议添加
```xml
<!-- AssertJ - 流式断言 -->
<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <scope>test</scope>
</dependency>

<!-- Testcontainers - 集成测试 -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mysql</artifactId>
    <scope>test</scope>
</dependency>

<!-- JaCoCo - 覆盖率报告 -->
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
</plugin>
```

## 八、执行和报告

### 8.1 运行测试
```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=MartialScoreServiceTest

# 生成覆盖率报告
mvn test jacoco:report
```

### 8.2 CI/CD 集成
- 每次 PR 自动运行测试
- 测试失败阻止合并
- 覆盖率低于阈值警告

---

**文档版本**: 1.0  
**创建日期**: 2026-01-16  
**作者**: QA Team