lty/qy-lty-admin/.planning/codebase/TESTING.md

测试模式

分析日期： 2026-05-07

测试框架

当前状态： 未检测到测试基础设施

• 运行器： 未配置（package.json 中无 Jest、Vitest、Playwright 等依赖）
• 断言库： 未配置
• 测试脚本： 未在 package.json 中定义（仅有 dev、build、start、lint）

测试文件组织

当前： 无测试文件

项目中未发现 *.test.ts、*.test.tsx、*.spec.ts、*.spec.tsx、__tests__/ 目录等标准测试文件结构。

测试覆盖

要求： 未强制

影响：

• 新增代码（尤其是 API 集成、表单验证、权限逻辑）缺乏自动化验证
• 技术债风险：next.config.mjs 中 typescript.ignoreBuildErrors: true 和 eslint.ignoreDuringBuilds: true，导致构建时不检查类型和 lint 错误
• 手动测试依赖性高

关键需要测试的区域

API 集成层

位置： lib/api/*.ts

建议测试：

• 认证流程（emailLogin、saveAuthToken、logout）
• API 请求拦截器（token 注入、过期处理）
• 响应拦截器（401 处理、重定向）
• 数据适配器（如 mapBackendOutfit() 将后端结构映射到前端类型）
• 错误处理（handleApiException、handleApiRequest 的成功/失败路径）

示例测试需求：

// 应测试：token 自动注入
test('请求拦截器应在请求头中添加 Bearer token', () => {
  // 前置条件：localStorage 中有 auth_token
  // 发送 API 请求
  // 验证：Authorization 头包含 "Bearer <token>"
})

// 应测试：401 处理
test('响应拦截器应在收到 401 时清除 token 并重定向到登录', () => {
  // 前置条件：发送请求后服务器返回 401
  // 验证：localStorage 中 auth_token 被移除
  // 验证：浏览器重定向到 /login
})

// 应测试：数据适配
test('mapBackendOutfit 应正确转换后端服装数据', () => {
  const backendData = { id: 1, name: '测试服装', image_url: '...' }
  const result = mapBackendOutfit(backendData)
  expect(result).toHaveProperty('imageUrl') // 字段映射
  expect(result.id).toBe('1') // 类型转换
})

权限控制

位置： lib/permissions.ts

建议测试：

• hasPermission(module) 根据用户角色返回正确的权限
• getUserRole() 从 localStorage 获取当前角色
• getModuleFromPath(pathname) 正确提取路径中的模块
• hasPathPermission(pathname) 组合权限检查

示例测试需求：

test('超级管理员应有所有模块的权限', () => {
  // 前置：localStorage.user_role = '超级管理员'
  // 验证：hasPermission('users') === true
  // 验证：hasPermission('ai-model') === true
  // 等等所有模块
})

test('内容管理员应无权限访问用户管理', () => {
  // 前置：localStorage.user_role = '内容管理员'
  // 验证：hasPermission('users') === false
  // 验证：hasPermission('outfits') === true
})

表单验证与提交

位置： components/*/add-*-dialog.tsx、app/*/page.tsx

当前模式：

• 使用 useState 管理表单状态
• 基本的非空检查（如 if (!formData.name || !formData.description) 在 add-achievement-dialog.tsx）
• 客户端验证不完整

建议测试：

• 必填字段验证（空值拒绝）
• 表单提交成功调用正确的 API
• 提交过程中加载状态变化（isSubmitting）
• 表单重置（关闭后清空状态）
• 错误显示（API 失败时显示 toast）

示例测试需求：

test('添加服装对话框应在名称为空时禁用提交', () => {
  // 渲染 AddOutfitDialog
  // 验证：提交按钮禁用状态
})

test('提交表单应调用 createOutfit API', () => {
  // 填写表单字段
  // 点击提交
  // 验证：createOutfit 被调用，参数正确
})

组件交互

位置： components/

建议测试：

• 对话框打开/关闭状态
• 模态框表单的步骤导航（step 状态变化）
• 确认对话框的确认/取消操作
• 列表分页和搜索

示例测试需求：

test('AddOutfitDialog 应在提交后关闭', () => {
  // 渲染对话框
  // 填写并提交表单
  // 验证：对话框关闭（open === false）
})

test('多步表单应在点击"下一步"时更新步骤', () => {
  // 验证：初始 step === 1
  // 点击"下一步"按钮
  // 验证：step === 2
})

中间件和路由保护

位置： middleware.ts

建议测试：

• 无 token 访问受保护路由时重定向到 /login
• 有 token 时允许访问受保护路由
• 公共路由（登录、注册）不需要 token

示例测试需求：

test('中间件应将无 token 的请求重定向到登录', () => {
  // 模拟请求：GET /outfits，无 auth_token cookie
  // 验证：重定向到 /login?callbackUrl=/outfits
})

test('中间件应允许有 token 的请求', () => {
  // 模拟请求：GET /users，包含有效 auth_token cookie
  // 验证：通过，继续处理
})

建议的测试设置

推荐框架组合

单元/集成测试：

• 运行器： Vitest（与 Next.js 15 兼容，开发体验优于 Jest）
• 断言： Vitest 内置（或 @testing-library/jest-dom）
• Mock 库： vitest 的 vi 模块或 @testing-library/react

E2E 测试（可选）：

• 框架： Playwright 或 Cypress
• 用途： 完整登录流、权限控制、多步表单

安装建议

# 安装 Vitest 和相关工具
npm install -D vitest @vitest/ui @testing-library/react @testing-library/jest-dom

# 创建配置文件 vitest.config.ts

最小化配置示例

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./test/setup.ts'],
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, '.'),
    },
  },
})

// test/setup.ts
import '@testing-library/jest-dom'

package.json 脚本建议

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage",
    "test:run": "vitest run"
  }
}

测试文件结构建议

project-root/
├── lib/
│   ├── api/
│   │   ├── auth.ts
│   │   ├── auth.test.ts          # API 认证测试
│   │   ├── outfits.ts
│   │   ├── outfits.test.ts       # API 服装测试
│   │   └── ...
│   ├── permissions.ts
│   └── permissions.test.ts        # 权限逻辑测试
├── components/
│   ├── add-outfit-dialog.tsx
│   ├── add-outfit-dialog.test.tsx # 组件交互测试
│   └── ...
├── app/
│   ├── login/
│   │   ├── page.tsx
│   │   └── page.test.tsx          # 登录页测试
│   └── ...
├── test/
│   ├── setup.ts                   # 测试环境初始化
│   ├── mocks/
│   │   ├── handlers.ts            # MSW 请求拦截器
│   │   └── server.ts              # MSW 服务器配置
│   └── fixtures/
│       ├── auth.fixture.ts        # 认证数据 fixtures
│       └── outfits.fixture.ts     # 服装数据 fixtures
└── vitest.config.ts

当前缺失的覆盖范围

高优先级（生产关键）：

• ✗ API 集成和数据适配
• ✗ 认证流程（登录、token 管理、登出）
• ✗ 权限检查和路由保护
• ✗ 表单验证和提交

中优先级（功能完整性）：

• ✗ 错误处理和用户通知
• ✗ 组件交互（对话框、模态框）
• ✗ 列表管理（分页、搜索）

低优先级（UX 细节）：

• ✗ 样式和响应性
• ✗ 无障碍访问 (a11y)

---

测试分析日期：2026-05-07

关键建议： 该项目缺乏测试基础设施，强烈建议在新增核心功能（特别是认证、权限、API 集成）时同步添加测试。考虑从 API 层和权限控制开始，这些是最容易产生 bug 的关键区域。