mini-starter/docs/stories/001.006.story.md

Story 001.006: 文件管理测试覆盖

Status

Ready for Development

Story

As a 开发人员 I want 完整的文件管理功能测试覆盖 so that 确保文件上传、下载、管理功能的稳定性和可靠性

Acceptance Criteria

• [ ] 文件服务层单元测试覆盖 (目标 > 70%)

  • FileService核心方法测试（createFile, deleteFile, getFileUrl, getFileDownloadUrl）
  • MinioService集成测试（generateUploadPolicy, getPresignedFileUrl, deleteObject）
  • 文件操作异常场景测试

• [ ] 文件API端点集成测试覆盖 (目标 > 90%)

  • 文件上传策略API测试（POST /api/v1/files）
  • 文件下载URL生成测试（GET /api/v1/files/{id}/download）
  • 文件访问URL生成测试（GET /api/v1/files/{id}/url）
  • 文件删除操作测试（DELETE /api/v1/files/{id}）
  • 文件列表和搜索功能测试

• [ ] MinIO存储服务集成测试

  • 文件存储验证测试
  • 预签名URL生成验证
  • 多部分上传功能测试

• [ ] Admin文件管理界面测试

  • 文件上传/下载功能集成测试
  • 文件列表和搜索功能E2E测试（⚠️ 需要与实际组件对齐）
  • 文件操作（重命名、删除）工作流测试
  • 为组件添加必要的data-testid属性以支持E2E测试

• [ ] 测试覆盖率报告和监控集成

• [ ] 所有测试通过且无回归

• [ ] 遵循现有测试模式和代码规范

Tasks / Subtasks

• 创建FileService单元测试文件
• 创建MinioService单元测试文件
• 创建文件API端点集成测试
• 创建MinIO存储服务集成测试
• 创建Admin文件管理界面集成测试
• 配置测试环境和mock数据
• 验证测试覆盖率达标
• 集成到CI/CD流水线

Dev Notes

技术栈 [基于现有架构]

• 测试框架: Vitest + Testing Library
• API测试: Hono Testing Utilities
• 数据库: PostgreSQL + TypeORM
• 文件存储: MinIO
• 前端测试: React Testing Library + Playwright

现有代码分析

• FileService: 已有完整单元测试覆盖（创建、删除、URL生成、多部分上传等）
• MinioService: 已有完整单元测试覆盖（桶管理、上传策略、预签名URL等）
• 文件API: 已有完整集成测试覆盖（CRUD操作、上传策略、多部分上传等）
• Admin界面: 已有Files.tsx和FileSelector.tsx组件，但缺少单元测试和集成测试，已有E2E测试但需要与实际组件对齐

测试策略 [Source: architecture/testing-strategy.md]

• 单元测试位于 src/**/__tests__/ 目录
• 集成测试位于 src/**/__integration_tests__/ 目录
• E2E测试使用Playwright
• 遵循现有测试模式和结构

测试环境要求

• 需要MinIO测试实例或mock
• 需要数据库测试数据
• 需要认证上下文mock

文件结构

项目根目录/
  src/server/
    modules/files/
      __tests__/                      # ✅ 已存在
        file.service.test.ts          # ✅ FileService单元测试（已存在）
        minio.service.test.ts         # ✅ MinioService单元测试（已存在）
    api/files/
      __tests__/                      # ✅ 已存在
        files.integration.test.ts     # ✅ 文件API集成测试（已存在）
    __integration_tests__/            # ✅ 已存在
      minio.integration.test.ts       # ✅ MinIO集成测试（已存在）
  src/client/
    admin/pages/
      __tests__/                      # ❌ 需要创建
        Files.test.tsx                # ❌ FilesPage单元测试（待创建）
    admin/components/
      __tests__/                      # ❌ 需要创建
        FileSelector.test.tsx         # ❌ FileSelector单元测试（待创建）
    __integration_tests__/admin/
      files.test.tsx                  # ❌ Admin文件管理集成测试（待创建）
  tests/e2e/
    specs/admin/
      files.spec.ts                   # ✅ Admin文件管理E2E测试（已存在）

Risk Assessment

高风险:

• MinIO集成测试可能依赖外部服务
• 文件操作涉及异步流程，测试复杂度较高

缓解策略:

• 使用mock和stub减少外部依赖
• 分阶段实施，先单元测试后集成测试
• 充分的错误处理和回滚机制

Testing

测试场景

• 正常文件上传下载流程
• 大文件上传测试
• 文件权限验证
• 异常场景测试（文件不存在、权限不足等）
• 性能基准测试

覆盖率目标

• 文件服务层: > 80% (当前已有完整单元测试)
• 文件API端点: > 90% (当前已有完整集成测试)
• MinIO集成测试: 100% (当前已有完整集成测试)
• Admin组件单元测试: > 70% (待创建)
• Admin组件集成测试: > 80% (待创建)
• Admin界面E2E测试: 主要功能覆盖 (需要与实际组件对齐)

Change Log

Date	Version	Description	Author
2025-09-20	v1.0	初始故事创建	Sarah
2025-09-20	v1.1	更新测试覆盖率数据，添加Dev Agent Record	Bob

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

• 测试执行日志记录
• 覆盖率报告生成记录
• 集成测试执行跟踪

Completion Notes List

• 文件服务单元测试完成
• MinIO集成测试验证
• API端点测试覆盖
• E2E测试场景执行

File List

• src/server/modules/files/__tests__/file.service.test.ts (✅ 已存在)
• src/server/modules/files/__tests__/minio.service.test.ts (✅ 已存在)
• src/server/api/files/__tests__/files.integration.test.ts (✅ 已存在)
• src/server/__integration_tests__/minio.integration.test.ts (✅ 已存在)
• src/client/admin/pages/__tests__/Files.test.tsx (❌ 待创建)
• src/client/admin/components/__tests__/FileSelector.test.tsx (❌ 待创建)
• src/client/__integration_tests__/admin/files.test.tsx (❌ 待创建)
• tests/e2e/specs/admin/files.spec.ts (✅ 已存在，但需要与实际组件对齐)

待完成任务

• 创建FilesPage组件单元测试
• 创建FileSelector组件单元测试
• 创建Admin文件管理集成测试
• 更新E2E测试以匹配实际组件结构
• 为Admin组件添加必要的data-testid属性
• 验证所有测试通过且覆盖率达标