dingdanquanliucheng/TEST_FIX_PLAN.md

# 测试修复计划

## 📊 当前测试状态

| 指标 | 数量 |
|------|------|
| 总测试数 | 155 |
| 通过 | 107 ✅ |
| 失败 | 48 ❌ |
| 通过率 | 69.0% |

---

## 🔍 失败测试分类分析

### 第一类：API 路径不匹配（25 个）

**问题描述**：测试中使用的 API 路径与实际路由不一致

| 测试文件 | 失败数 | 实际路径 | 测试路径 | 修复方式 |
|----------|--------|----------|----------|----------|
| test_customers.py | 7 | `/api/customers` | 正确 | 检查权限配置 |
| test_products.py | 5 | `/api/products`, `/api/product-categories` | `/api/products/categories` | 修正路径 |
| test_configs.py | 4 | `/api/configs/{key}` | `/api/configs?key=xxx` | 修正路径 |
| test_reports.py | 7 | `/api/reports/performance` | 正确 | 检查权限配置 |
| test_system.py | 3 | `/api/system/*` | 正确 | 检查权限配置 |

### 第二类：权限配置问题（12 个）

**问题描述**：测试用户的权限码未正确配置或接口权限检查不匹配

| 测试文件 | 失败数 | 问题原因 |
|----------|--------|----------|
| test_audit.py | 2 | 审计日志接口权限码未配置 |
| test_configs.py | 2 | 配置接口权限码未配置 |
| test_logistics.py | 5 | 物流任务接口权限码未配置 |
| test_order_cancel.py | 3 | 取消审批接口权限码未配置 |

### 第三类：接口实现问题（8 个）

**问题描述**：接口未完全实现或返回格式不匹配

| 测试文件 | 失败数 | 问题原因 |
|----------|--------|----------|
| test_logistics.py | 3 | 司机任务接口实现问题 |
| test_order_cancel.py | 3 | 取消流程状态恢复逻辑问题 |
| test_e2e.py | 2 | 端到端流程接口串联问题 |

### 第四类：数据模型问题（3 个）

**问题描述**：测试中的数据字段与实际模型不匹配

| 测试文件 | 失败数 | 问题原因 |
|----------|--------|----------|
| test_orders.py | 1 | 数量为 0 的校验未实现 |
| test_auth.py | 1 | 系统用户接口路径问题 |
| test_files.py | 1 | 文件上传接口路径问题 |

---

## 📋 修复计划

### 阶段一：修复 API 路径问题（预计 1 小时）

#### 1.1 修复 test_products.py

**问题**：分类接口路径错误
- 测试路径：`/api/products/categories`
- 实际路径：`/api/product-categories`

**修复方案**：
```python
# 修改前
resp = client.post("/api/products/categories", headers=admin_headers, json={...})

# 修改后
resp = client.post("/api/product-categories", headers=admin_headers, json={...})
```

**影响文件**：`backend/tests/test_products.py`
**影响用例**：5 个

#### 1.2 修复 test_configs.py

**问题**：配置查询接口路径错误
- 测试路径：`/api/configs?config_key=xxx`
- 实际路径：`/api/configs/{config_key}`

**修复方案**：
```python
# 修改前
resp = client.get("/api/configs?config_key=logistics_timeout_days", headers=admin_headers)

# 修改后
resp = client.get("/api/configs/logistics_timeout_days", headers=admin_headers)
```

**影响文件**：`backend/tests/test_configs.py`
**影响用例**：2 个

#### 1.3 修复 test_customers.py

**问题**：部分接口路径和请求格式不匹配

**修复方案**：检查 customers.py 的实际接口定义，调整测试代码

**影响文件**：`backend/tests/test_customers.py`
**影响用例**：7 个

---

### 阶段二：修复权限配置问题（预计 1.5 小时）

#### 2.1 添加缺失的权限码到 conftest.py

**需要添加的权限码**：

| 权限码 | 说明 | 关联接口 |
|--------|------|----------|
| `audit:list` | 审计日志查看 | GET /api/audit-logs |
| `config:view` | 配置查看 | GET /api/configs/{key} |
| `config:update` | 配置更新 | PUT /api/configs/{key} |
| `logistics:task:create` | 创建物流任务 | POST /api/logistics/tasks |
| `logistics:task:cancel` | 取消物流任务 | POST /api/logistics/tasks/{id}/cancel |
| `order:cancel-approve` | 取消审批 | POST /api/orders/{id}/cancel-approve |

**修复方案**：在 `conftest.py` 的 `seed_menus` 中添加对应的菜单项

**影响文件**：`backend/tests/conftest.py`
**影响用例**：12 个

#### 2.2 更新角色-菜单关联

**需要更新的角色权限**：

| 角色 | 需要添加的权限 |
|------|---------------|
| 管理员 (admin) | 全部权限（已配置） |
| 业务员 (salesman) | `order:cancel-approve`（取消审批） |
| 管理层 (manager) | `audit:list`, `config:view`, `logistics:task:create` |
| 司机 (driver) | `logistics:task:accept`, `logistics:task:pickup`, `logistics:task:deliver` |

---

### 阶段三：修复接口实现问题（预计 2 小时）

#### 3.1 修复物流任务接口

**问题**：
1. 创建任务接口权限检查不正确
2. 司机任务接口返回格式不匹配

**修复方案**：
1. 检查 `backend/app/api/logistics.py` 的权限配置
2. 确保接口返回格式与测试期望一致

**影响文件**：
- `backend/app/api/logistics.py`
- `backend/tests/test_logistics.py`

**影响用例**：5 个

#### 3.2 修复订单取消流程

**问题**：
1. 取消审批拒绝后状态恢复逻辑不正确
2. 履约中取消流程未完全实现

**修复方案**：
1. 检查 `backend/app/services/order_service.py` 的取消逻辑
2. 确保状态恢复逻辑正确

**影响文件**：
- `backend/app/services/order_service.py`
- `backend/tests/test_order_cancel.py`

**影响用例**：3 个

#### 3.3 修复端到端流程

**问题**：
1. 完整订单生命周期测试失败
2. 提醒流程测试失败

**修复方案**：
1. 检查订单状态流转的完整性
2. 确保提醒接口正确实现

**影响文件**：
- `backend/tests/test_e2e.py`

**影响用例**：2 个

---

### 阶段四：修复数据模型问题（预计 0.5 小时）

#### 4.1 修复订单数量校验

**问题**：数量为 0 时未返回 40001 错误

**修复方案**：在 `CreateOrderRequest` 或 `order_service` 中添加数量校验

**影响文件**：
- `backend/app/schemas/orders.py` 或
- `backend/app/services/order_service.py`

**影响用例**：1 个

#### 4.2 修复文件上传接口

**问题**：获取上传凭证接口路径不正确

**修复方案**：检查 `backend/app/api/files.py` 的实际路径

**影响文件**：
- `backend/tests/test_files.py`

**影响用例**：1 个

---

## 📝 修复优先级

### P0 - 必须修复（影响核心功能）

1. **权限配置问题** - 12 个用例
   - 影响登录鉴权、订单管理、系统管理等核心模块
   
2. **订单取消流程** - 3 个用例
   - 影响订单全流程完整性

3. **物流任务接口** - 5 个用例
   - 影响司机履约流程

### P1 - 应该修复（影响功能完整性）

4. **API 路径问题** - 25 个用例
   - 影响客户、产品、配置、报表等模块测试

5. **端到端流程** - 2 个用例
   - 影响整体流程验证

### P2 - 可以延后（影响较小）

6. **数据模型问题** - 3 个用例
   - 影响边界条件测试

---

## 🛠️ 具体修复步骤

### 步骤 1：修复 conftest.py 权限配置

```python
# 在 seed_menus 中添加以下菜单项
Menu(id=17, menu_name="审计日志", menu_path="/audit-logs", menu_type="page",
     permission_code="audit:list", sort_no=11, status=1),
Menu(id=18, menu_name="配置查看", menu_path="", menu_type="button",
     permission_code="config:view", parent_id=6, sort_no=1, status=1),
Menu(id=19, menu_name="配置更新", menu_path="", menu_type="button",
     permission_code="config:update", parent_id=6, sort_no=2, status=1),
Menu(id=20, menu_name="创建物流任务", menu_path="", menu_type="button",
     permission_code="logistics:task:create", parent_id=8, sort_no=4, status=1),
Menu(id=21, menu_name="取消物流任务", menu_path="", menu_type="button",
     permission_code="logistics:task:cancel", parent_id=8, sort_no=5, status=1),
```

### 步骤 2：更新角色-菜单关联

```python
# 在 role_menus 中添加
# 管理层
RoleMenu(role_id=3, menu_id=17),  # audit:list
RoleMenu(role_id=3, menu_id=18),  # config:view
RoleMenu(role_id=3, menu_id=20),  # logistics:task:create

# 司机
RoleMenu(role_id=4, menu_id=20),  # logistics:task:create (查看)
```

### 步骤 3：修复 test_products.py 路径

```python
# 所有 /api/products/categories 替换为 /api/product-categories
resp = client.post("/api/product-categories", headers=admin_headers, json={...})
resp = client.get("/api/product-categories", headers=admin_headers)
resp = client.put(f"/api/product-categories/{cat.id}", headers=admin_headers, json={...})
```

### 步骤 4：修复 test_configs.py 路径

```python
# 查询配置
resp = client.get("/api/configs/logistics_timeout_days", headers=admin_headers)

# 更新配置
resp = client.put("/api/configs/logistics_timeout_days", headers=admin_headers, json={
    "config_value": "3",
})
```

### 步骤 5：检查并修复物流任务接口

```python
# 检查 backend/app/api/logistics.py 的权限配置
# 确保 require_roles 和 require_permissions 正确
```

### 步骤 6：检查并修复订单取消流程

```python
# 检查 backend/app/services/order_service.py
# 确保 cancel_order_approve 方法正确处理拒绝情况
```

---

## 📊 修复后预期结果

| 阶段 | 修复用例数 | 预期通过率 |
|------|-----------|-----------|
| 阶段一 | 25 | 85.2% |
| 阶段二 | 12 | 92.9% |
| 阶段三 | 8 | 98.1% |
| 阶段四 | 3 | 100% |
| **总计** | **48** | **100%** |

---

## ⏰ 时间估算

| 阶段 | 预计时间 | 依赖 |
|------|---------|------|
| 阶段一 | 1 小时 | 无 |
| 阶段二 | 1.5 小时 | 阶段一 |
| 阶段三 | 2 小时 | 阶段二 |
| 阶段四 | 0.5 小时 | 阶段三 |
| **总计** | **5 小时** | - |

---

## 🎯 验收标准

1. **所有 155 个测试用例通过**
2. **测试通过率达到 100%**
3. **无测试警告**
4. **测试执行时间 < 10 秒**

---

## 📌 注意事项

1. **修改接口代码时要谨慎**：确保不影响现有功能
2. **优先修复 P0 问题**：权限和核心流程问题优先解决
3. **测试与代码同步修改**：确保测试和接口代码保持一致
4. **回归测试**：修复后运行全部测试，确保无新增失败

---

## 🔄 修复后验证

```bash
# 运行全部测试
cd backend
python -m pytest tests/ -v

# 运行 P0 测试
python -m pytest tests/ -v -m "p0"

# 生成覆盖率报告
python -m pytest tests/ --cov=app --cov-report=html
```

---

**文档版本**: v1.0
**创建日期**: 2026-06-10
**维护人**: 开发团队