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

Story 010.011: 集成统一文件模块到统一广告和租户后台

Status

Approved

Story

As a 超级管理员， I want 统一文件模块集成到统一广告模块和租户后台， so that 可以在租户管理后台统一管理所有文件，统一广告模块使用统一文件实体。

Background

前置条件:

• 故事010.009已完成：统一文件模块 (unified-file-module) 已创建
• 故事010.010已完成：统一文件管理UI (unified-file-management-ui) 已创建

需要完成的集成:

1. 统一广告模块更新为使用 UnifiedFile 实体（而非 FileMt）
2. 统一广告管理UI更新为使用统一文件选择器（而非多租户版本）
3. Server包注册统一文件模块路由
4. 租户后台集成统一文件管理功能

Acceptance Criteria

1. 统一广告模块更新Entity关联，使用 UnifiedFile 替代 FileMt
2. 统一广告管理UI更新依赖，使用 @d8d/unified-file-management-ui
3. Server包注册统一文件模块路由和实体
4. 租户后台添加文件管理菜单项和路由
5. 统一广告模块所有测试通过
6. 统一广告管理UI所有测试通过
7. E2E测试验证文件上传和选择器功能

Tasks / Subtasks

• [ ] 任务1: 更新统一广告模块Entity (AC: 1)

  • 修改 unified-advertisement.entity.ts，将 FileMt 替换为 UnifiedFile
  • 更新导入语句：import { UnifiedFile } from '@d8d/unified-file-module'
  • 更新 @ManyToOne 关联定义
  • 更新 @JoinColumn 定义

• [ ] 任务2: 更新统一广告模块依赖 (AC: 1)

  • 修改 package.json，添加 @d8d/unified-file-module 依赖
  • 移除或保留 @d8d/core-module-mt 依赖（如果其他模块还需要）
  • 运行 pnpm install 更新依赖

• [ ] 任务3: 更新统一广告模块测试 (AC: 5)

  • 更新测试文件中的 FileMt 引用为 UnifiedFile
  • 更新测试数据工厂
  • 运行测试验证修改正确

• [ ] 任务4: 更新统一广告管理UI依赖 (AC: 2)

  • 修改 package.json，添加 @d8d/unified-file-management-ui 依赖
  • 移除 @d8d/file-management-ui-mt 依赖
  • 更新 vitest.config.ts 别名配置
  • 运行 pnpm install 更新依赖

• [ ] 任务5: 更新统一广告管理UI组件 (AC: 2)

  • 修改 UnifiedAdvertisementManagement.tsx，将 FileSelector 替换为 UnifiedFileSelector
  • 更新导入语句
  • 更新组件props（如果有差异）

• [ ] 任务6: 更新统一广告管理UI测试 (AC: 6)

  • 更新所有测试文件中的mock：@d8d/file-management-ui-mt → @d8d/unified-file-management-ui
  • 更新mock组件名称
  • 运行测试验证修改正确

• [ ] 任务7: Server包集成统一文件模块 (AC: 3)

  • 在 packages/server/src/index.ts 中导入统一文件模块
  • 导入 UnifiedFile 实体
  • 导入统一文件管理员路由
  • 注册 UnifiedFile 实体到数据源
  • 注册管理员路由：app.route('/api/v1/admin/unified-files', unifiedFileAdminRoutes)

• [ ] 任务8: 租户后台集成统一文件管理 (AC: 4)

  • 在 web/src/client/tenant/ 添加文件管理路由
  • 在 web/src/client/tenant/ 添加文件管理页面组件
  • 添加文件管理菜单项（Files图标）
  • 初始化API客户端（指向管理员API）

• [ ] 任务9: 编写E2E测试 (AC: 7)

  • 创建 web/tests/e2e/tenant-file-management.spec.ts
  • 测试文件上传流程
  • 测试文件列表显示
  • 测试文件删除功能
  • 测试文件选择器在广告管理中的使用

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

  • 运行 pnpm typecheck 确保无TypeScript错误
  • 运行 pnpm lint 确保代码符合规范
  • 运行所有测试确保通过
  • 更新史诗010文档

Dev Notes

修改的文件清单

统一广告模块 (packages/unified-advertisements-module/):

• src/entities/unified-advertisement.entity.ts - 更新Entity关联
• src/entities/index.ts - 更新导入
• package.json - 添加依赖
• tests/**/*.test.ts - 更新测试

统一广告管理UI (packages/unified-advertisement-management-ui/):

• src/components/UnifiedAdvertisementManagement.tsx - 更新组件
• package.json - 更新依赖
• vitest.config.ts - 更新别名配置
• tests/**/*.test.tsx - 更新mock

Server包 (packages/server/):

• src/index.ts - 注册路由和实体
• package.json - 添加依赖

租户后台 (web/src/client/tenant/):

• 添加路由配置
• 添加页面组件
• 更新菜单

Entity关联更新

更新前:

import { FileMt } from '@d8d/core-module-mt/file-module-mt';

@Entity('unified_advertisement')
export class UnifiedAdvertisement {
  // ...

  @ManyToOne(() => FileMt, { nullable: true })
  @JoinColumn({ name: 'image_file_id' })
  imageFile!: FileMt | null;
}

更新后:

import { UnifiedFile } from '@d8d/unified-file-module';

@Entity('unified_advertisement')
export class UnifiedAdvertisement {
  // ...

  @ManyToOne(() => UnifiedFile, { nullable: true })
  @JoinColumn({ name: 'image_file_id' })
  imageFile!: UnifiedFile | null;
}

测试标准

测试类型	要求
统一广告模块测试	全部通过
统一广告管理UI测试	全部通过
Server包集成测试	全部通过
E2E测试	全部通过

关键测试要求

1. 回归测试: 确保统一广告模块原有功能不受影响
2. 关联测试: 验证 UnifiedFile 关联正确
3. 集成测试: 验证Server包路由注册正确
4. UI测试: 验证文件选择器在广告管理中正常工作
5. E2E测试: 验证完整的文件管理流程

Testing

测试文件位置

• E2E测试: web/tests/e2e/

测试框架

• Playwright: E2E测试

测试执行命令

# 统一广告模块测试
cd packages/unified-advertisements-module
pnpm test

# 统一广告管理UI测试
cd packages/unified-advertisement-management-ui
pnpm test

# E2E测试
cd web
pnpm test:e2e:chromium

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代理填写