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

修复方案：

# 修改前
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}

修复方案：

# 修改前
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 权限配置

# 在 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：更新角色-菜单关联

# 在 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 路径

# 所有 /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 路径

# 查询配置
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：检查并修复物流任务接口

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

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

# 检查 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. 回归测试：修复后运行全部测试，确保无新增失败

---

🔄 修复后验证

# 运行全部测试
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 维护人: 开发团队