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测试
  • 文件操作（重命名、删除）工作流测试

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

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

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

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: 当前覆盖率25%（2/8方法），需要重点测试核心方法
• MinioService: 当前覆盖率待测试，需要完整测试覆盖
• 文件API: 当前覆盖率82%，需要完善异常测试
• Admin界面: 已有Files.tsx组件，需要集成测试

测试策略 [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集成测试（待创建）
  tests/e2e/
    specs/admin/
      files.spec.ts                   # Admin文件管理E2E测试（待创建）

Risk Assessment

高风险:

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

缓解策略:

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

Testing

测试场景

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

覆盖率目标

• 文件服务层: > 70%
• 文件API端点: > 90%
• 整体测试覆盖率提升到达标水平

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 (待创建)
• tests/e2e/specs/admin/files.spec.ts (待创建)