# 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属性
- [ ] 验证所有测试通过且覆盖率达标