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

Story 010.010: 创建统一文件管理UI包

Status

Approved

Story

As a 超级管理员， I want 一个统一的文件管理UI包， so that 可以在租户管理后台统一管理所有文件，统一广告管理UI使用统一的文件选择器组件。

Background

当前问题:

• 统一广告管理UI (unified-advertisement-management-ui) 使用 @d8d/file-management-ui-mt 的 FileSelector 组件（多租户）
• 不一致性: 统一广告管理UI本身是无租户隔离的，但使用的文件选择器却是多租户版本

解决方案:

• 参照统一广告管理UI的设计模式，从单租户的 file-management-ui 复制创建统一版本
• 创建 unified-file-management-ui（API指向统一文件模块）

Acceptance Criteria

1. 创建 packages/unified-file-management-ui 包，从 file-management-ui 复制并改造为指向统一文件模块
2. 实现文件管理组件（列表、上传、删除）
3. 实现文件选择器组件（供其他UI包使用）
4. API客户端指向统一文件模块端点（/api/v1/admin/unified-files）
5. 包含完整的组件测试和集成测试

Tasks / Subtasks

• [ ] 任务1: 创建UI包结构和配置文件 (AC: 1)

  • 创建 packages/unified-file-management-ui 目录
  • 创建 package.json，配置包名为 @d8d/unified-file-management-ui
  • 创建 tsconfig.json
  • 创建 vitest.config.ts（设置 fileParallelism: false，配置别名）
  • 创建 src/ 子目录：components/, api/, hooks/, types/, utils/
  • 创建 tests/ 子目录：integration/, unit/

• [ ] 任务2: 创建API客户端 (AC: 4)

  • 创建 src/api/client.ts，使用 hc RPC客户端
  • 配置API端点指向 /api/v1/admin/unified-files
  • 创建类型定义（从RPC推断）
  • 创建API方法：uploadFile, getFiles, getFile, deleteFile

• [ ] 任务3: 创建React Hooks (AC: 1)

  • 创建 src/hooks/useUnifiedFiles.ts（文件列表）
  • 创建 src/hooks/useUnifiedFileUpload.ts（文件上传）
  • 创建 src/hooks/useUnifiedFileDelete.ts（文件删除）

• [ ] 任务4: 实现文件管理组件 (AC: 2)

  • 创建 src/components/UnifiedFileList.tsx（文件列表）
  • 创建 src/components/UnifiedFileUpload.tsx（文件上传）
  • 创建 src/components/UnifiedFileManagement.tsx（管理页面主组件）

• [ ] 任务5: 实现文件选择器组件 (AC: 3)

  • 创建 src/components/UnifiedFileSelector.tsx（文件选择器）
  • 支持单选和多选模式
  • 支持文件类型过滤
  • 支持搜索功能
  • 添加 data-testid 属性用于测试

• [ ] 任务6: 创建包导出入口 (AC: 1)

  • 创建 src/index.ts，导出组件、Hooks、API客户端
  • 配置 package.json 的 exports 字段

• [ ] 任务7: 编写组件测试 (AC: 5)

  • 创建 tests/unit/UnifiedFileSelector.test.tsx
  • 创建 tests/unit/UnifiedFileList.test.tsx
  • 创建 tests/unit/UnifiedFileUpload.test.tsx

• [ ] 任务8: 编写集成测试 (AC: 5)

  • 创建 tests/integration/file-selector.integration.test.tsx
  • 创建 tests/integration/file-upload.integration.test.tsx
  • 创建 tests/integration/file-management.integration.test.tsx

• [ ] 任务9: 代码质量检查

  • 运行 pnpm typecheck 确保无TypeScript错误
  • 运行 pnpm lint 确保代码符合规范
  • 运行 pnpm test 确保所有测试通过
  • 运行 pnpm test:coverage 确保覆盖率达标

Dev Notes

项目结构信息

新包位置:

packages/unified-file-management-ui/
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src/
│   ├── components/
│   │   ├── UnifiedFileList.tsx
│   │   ├── UnifiedFileUpload.tsx
│   │   ├── UnifiedFileSelector.tsx
│   │   └── UnifiedFileManagement.tsx
│   ├── api/
│   │   └── client.ts
│   ├── hooks/
│   │   ├── useUnifiedFiles.ts
│   │   ├── useUnifiedFileUpload.ts
│   │   └── useUnifiedFileDelete.ts
│   ├── types/
│   │   └── index.ts
│   ├── utils/
│   │   └── file-utils.ts
│   └── index.ts
└── tests/
    ├── integration/
    │   ├── file-selector.integration.test.tsx
    │   ├── file-upload.integration.test.tsx
    │   └── file-management.integration.test.tsx
    └── unit/
        ├── UnifiedFileSelector.test.tsx
        ├── UnifiedFileList.test.tsx
        └── UnifiedFileUpload.test.tsx

参考模块:

• 单租户文件管理UI: packages/file-management-ui
• 统一广告管理UI: packages/unified-advertisement-management-ui

API客户端设计

RPC客户端使用:

import { hc } from '@d8d/shared-ui-components/utils/hc';
import type { UnifiedFileRoutes } from '@d8d/unified-file-module';

export const unifiedFileClient = hc<UnifiedFileRoutes>('/api/v1/admin/unified-files');

组件设计规范

文件选择器 (UnifiedFileSelector.tsx):

• 使用RPC推断类型（不直接导入schema类型）
• 添加 data-testid 属性用于测试
• 支持单选和多选模式
• 支持文件类型过滤
• 支持搜索功能

测试标准

测试类型	最低要求	目标要求
单元测试	70%	80%
集成测试	50%	60%

关键测试要求

1. 组件测试: 验证组件渲染正确
2. 交互测试: 验证用户交互（上传、删除、选择）
3. API集成测试: 验证API调用正确
4. 文件选择器测试: 验证选择器功能（单选、多选、搜索）

Testing

测试文件位置

• 单元测试: tests/unit/
• 集成测试: tests/integration/

测试框架

• Vitest: 主要测试运行器
• Testing Library: React组件测试
• Happy DOM: 轻量级DOM环境

测试执行命令

# 进入UI包目录
cd packages/unified-file-management-ui

# 运行所有测试
pnpm test

# 运行集成测试
pnpm test:integration

# 生成覆盖率报告
pnpm test:coverage

# 类型检查
pnpm typecheck

Change Log

Date	Version	Description	Author
2026-01-03	1.0	初始故事创建	James (Claude Code)

Dev Agent Record

Agent Model Used

待开发时填写

Debug Log References

待开发时填写

Completion Notes List

待开发时填写

File List

待开发时填写

QA Results

待QA代理填写