taiji-AI-PAD/TESTING_GUIDE.md

权限系统测试指南

文档版本

• 版本: 1.0
• 更新日期: 2025-12-25
• 适用范围: Taiji AI-PAD 后端测试

---

目录

1. 测试概述
2. 环境准备
3. 运行测试
4. 测试用例说明
5. 测试账号
6. 手动测试
7. CI/CD集成

---

测试概述

本项目包含完整的权限系统测试，覆盖以下方面：

测试类型

• ✅ 单元测试: 测试权限检查函数、角色权限映射
• ✅ 集成测试: 测试API端点的权限控制
• ✅ 认证测试: 测试登录、登出、Token刷新
• ✅ 授权测试: 测试基于角色的访问控制（RBAC）

测试覆盖

• 7种用户角色的权限测试
• 10种权限的验证测试
• 50+ API端点的访问控制测试
• JWT Token和API Key认证测试
• 跨角色访问控制测试

---

环境准备

1. 安装依赖

cd /home/taiji/tools/taiji-AI-PAD/services/mcp-server

# 安装项目依赖
pip install -r requirements.txt

# 安装测试依赖
pip install -r requirements-test.txt

2. 测试依赖说明

pytest==7.4.3              # 测试框架
pytest-asyncio==0.21.1     # 异步测试支持
pytest-cov==4.1.0          # 代码覆盖率
httpx==0.25.2              # HTTP客户端（用于API测试）
aiosqlite==0.19.0          # SQLite异步驱动（用于测试数据库）
pytest-mock==3.12.0        # Mock支持
faker==20.1.0              # 测试数据生成

---

运行测试

方法1: 使用测试脚本（推荐）

cd /home/taiji/tools/taiji-AI-PAD/services/mcp-server

# 运行所有测试
./scripts/run_tests.sh all

# 只运行权限测试
./scripts/run_tests.sh permissions

# 只运行API测试
./scripts/run_tests.sh api

# 运行测试并生成覆盖率报告
./scripts/run_tests.sh coverage

# 快速测试（跳过慢速测试）
./scripts/run_tests.sh quick

方法2: 直接使用pytest

cd /home/taiji/tools/taiji-AI-PAD/services/mcp-server

# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_permissions.py -v

# 运行特定测试类
pytest tests/test_permissions.py::TestPermissions -v

# 运行特定测试用例
pytest tests/test_permissions.py::TestPermissions::test_role_permissions_mapping -v

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

# 查看覆盖率报告
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

方法3: 使用pytest标记

# 只运行权限相关测试
pytest -m permissions

# 只运行API测试
pytest -m api

# 只运行单元测试
pytest -m unit

# 只运行集成测试
pytest -m integration

# 跳过慢速测试
pytest -m "not slow"

---

测试用例说明

1. 权限系统测试 (test_permissions.py)

TestPermissions - 权限映射测试

test_role_permissions_mapping()    # 测试角色权限映射
test_has_permission()              # 测试权限检查函数

测试内容:

• 验证每个角色的权限列表
• 验证权限检查函数的正确性
• 验证超级管理员拥有所有权限

TestAuthenticationAPI - 认证API测试

test_login_success()               # 测试成功登录
test_login_wrong_password()        # 测试错误密码
test_login_wrong_role()            # 测试错误角色
test_login_all_roles()             # 测试所有角色登录

测试内容:

• 验证登录流程
• 验证密码验证
• 验证角色验证
• 验证Token生成

TestRoleBasedAccess - 基于角色的访问控制

test_super_admin_access()          # 测试超级管理员访问
test_billing_admin_access()        # 测试计费管理员访问
test_operations_admin_access()     # 测试运营管理员访问
test_user_limited_access()         # 测试普通用户受限访问

测试内容:

• 验证每个角色能访问的API端点
• 验证每个角色不能访问的API端点
• 验证403权限不足响应

TestAPIKeyAuthentication - API密钥认证

test_api_key_authentication()      # 测试API密钥认证
test_invalid_api_key()             # 测试无效API密钥

测试内容:

• 验证API密钥认证流程
• 验证无效密钥的拒绝

TestTokenRefresh - Token刷新

test_refresh_token()               # 测试刷新Token

测试内容:

• 验证Token刷新机制
• 验证新旧Token的区别

TestPasswordChange - 密码修改

test_change_password()             # 测试修改密码
test_change_password_wrong_old_password()  # 测试错误旧密码

测试内容:

• 验证密码修改流程
• 验证旧密码验证

TestCrossRoleAccess - 跨角色访问

test_channel_admin_cannot_access_other_channels()  # 测试渠道隔离

测试内容:

• 验证渠道管理员只能访问自己渠道的数据
• 验证数据隔离

TestPermissionInheritance - 权限继承

test_admin_has_billing_permissions()     # 测试管理员继承计费权限
test_admin_has_operations_permissions()  # 测试管理员继承运营权限
test_super_admin_has_all_permissions()   # 测试超级管理员拥有全部权限

测试内容:

• 验证角色权限的层级关系
• 验证高级角色包含低级角色的权限

2. API端点测试 (test_api_endpoints.py)

TestUserAPIs - 用户端API

test_get_dashboard_stats()         # 测试获取仪表板统计
test_get_billing_records()         # 测试获取计费记录
test_user_cannot_access_admin_apis()  # 测试用户无法访问管理员API

TestChannelAPIs - 渠道端API

test_get_channel_dashboard_stats() # 测试获取渠道仪表板
test_get_channel_tenants()         # 测试获取渠道租户列表

TestAdminAPIs - 管理员API

test_super_admin_get_channels()    # 测试超级管理员获取渠道
test_admin_get_dashboard_stats()   # 测试管理员获取仪表板

TestBillingAdminAPIs - 计费管理员API

test_billing_admin_view_billing()  # 测试查看计费
test_billing_admin_manage_billing() # 测试管理计费
test_billing_admin_cannot_manage_tenants()  # 测试无法管理租户

TestOperationsAdminAPIs - 运营管理员API

test_operations_admin_manage_tenants()  # 测试管理租户
test_operations_admin_manage_resources()  # 测试管理资源
test_operations_admin_cannot_recharge()  # 测试无法充值

TestProviderAPIs - 供应商API

test_provider_admin_get_models()   # 测试获取模型列表
test_provider_admin_cannot_access_admin_apis()  # 测试无法访问管理员API

---

测试账号

自动创建测试账号

运行以下脚本创建所有测试账号：

cd /home/taiji/tools/taiji-AI-PAD/services/mcp-server
python scripts/init_test_accounts.py

测试账号列表

角色	邮箱	密码	登录角色
超级管理员	superadmin@test.com	super123	super_admin
管理员	admin@test.com	admin123	admin
管理员xiaohei	xiaohei@test.com	1233456	admin
计费管理员	billing@test.com	billing123	billing_admin
运营管理员	operations@test.com	ops123	operations_admin
渠道管理员A	channel-admin-a@test.com	channel123	channel
渠道管理员B	channel-admin-b@test.com	channel123	channel
供应商管理员	provider@test.com	provider123	provider
测试用户1	user1@test.com	user123	user
测试用户2	user2@test.com	user123	user
测试用户3	user3@test.com	user123	user

---

手动测试

1. 测试登录

# 超级管理员登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "superadmin@test.com",
    "password": "super123",
    "role": "super_admin"
  }'

# 计费管理员登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "billing@test.com",
    "password": "billing123",
    "role": "billing_admin"
  }'

# 运营管理员登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operations@test.com",
    "password": "ops123",
    "role": "operations_admin"
  }'

2. 测试权限控制

# 保存token
TOKEN="<从登录响应中获取的token>"

# 测试访问用户仪表板（所有角色都应该能访问）
curl -X GET http://localhost:8000/api/user/dashboard/stats \
  -H "Authorization: Bearer $TOKEN"

# 测试访问管理员端点（只有管理员角色能访问）
curl -X GET http://localhost:8000/api/admin/dashboard/stats \
  -H "Authorization: Bearer $TOKEN"

# 测试计费管理（只有计费管理员、管理员、超级管理员能访问）
curl -X GET http://localhost:8000/api/admin/billing/records \
  -H "Authorization: Bearer $TOKEN"

# 测试租户管理（只有运营管理员、管理员、超级管理员能访问）
curl -X GET http://localhost:8000/api/admin/tenants \
  -H "Authorization: Bearer $TOKEN"

3. 测试权限拒绝

# 用普通用户token访问管理员端点（应该返回403）
USER_TOKEN="<普通用户的token>"

curl -X GET http://localhost:8000/api/admin/dashboard/stats \
  -H "Authorization: Bearer $USER_TOKEN"

# 预期响应: 403 Forbidden

---

CI/CD集成

GitHub Actions示例

name: Run Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    
    - name: Install dependencies
      run: |
        cd services/mcp-server
        pip install -r requirements.txt
        pip install -r requirements-test.txt
    
    - name: Run tests
      run: |
        cd services/mcp-server
        pytest tests/ -v --cov=app --cov=models --cov-report=xml
    
    - name: Upload coverage
      uses: codecov/codecov-action@v3
      with:
        file: ./services/mcp-server/coverage.xml

GitLab CI示例

test:
  stage: test
  image: python:3.11
  script:
    - cd services/mcp-server
    - pip install -r requirements.txt
    - pip install -r requirements-test.txt
    - pytest tests/ -v --cov=app --cov=models --cov-report=term
  coverage: '/TOTAL.*\s+(\d+%)$/'

---

测试最佳实践

1. 测试前准备

• ✅ 确保数据库连接正常
• ✅ 清理测试数据库
• ✅ 创建必要的测试账号

2. 测试中注意

• ✅ 每个测试应该独立运行
• ✅ 使用fixtures管理测试数据
• ✅ 测试后清理数据

3. 测试覆盖率目标

• ✅ 总体覆盖率 > 80%
• ✅ 核心权限模块覆盖率 > 95%
• ✅ API路由覆盖率 > 90%

4. 持续改进

• ✅ 定期运行测试
• ✅ 新功能必须有测试
• ✅ Bug修复必须有回归测试

---

常见问题

Q1: 测试失败怎么办？

A: 查看详细错误信息，检查：

• 数据库连接是否正常
• 测试依赖是否完整安装
• 测试数据是否正确创建

Q2: 如何调试单个测试？

A: 使用pytest的调试选项：

pytest tests/test_permissions.py::TestPermissions::test_role_permissions_mapping -vv -s

Q3: 如何查看测试覆盖率？

A: 运行覆盖率测试并查看报告：

./scripts/run_tests.sh coverage
open htmlcov/index.html

Q4: 测试运行很慢怎么办？

A: 使用快速测试模式：

./scripts/run_tests.sh quick

---

参考资料

• Pytest文档
• FastAPI测试文档
• 权限更新说明
• API接口文档

---

文档版本: 1.0
最后更新: 2025-12-25
维护人: Taiji AI-PAD Team