mini-starter/docs/stories/007.013.shared-ui-components-package.story.md

故事007.013: 共享UI组件包创建

状态

✅ Completed

故事

作为 前端开发者， 我想要 创建一个共享UI组件包， 以便 可以在多个前端应用中复用UI组件、hooks、工具类等，提高开发效率和代码一致性。

验收标准

1. AC 1: 成功创建共享UI组件包 @d8d/shared-ui-components，包含正确的包配置和依赖管理
2. AC 2: 抽离独立的基础UI组件：Button、Input、Card、Table、Dialog等shadcn/ui组件库
3. AC 3: 抽离共享hooks：use-mobile等无业务逻辑的hooks
4. AC 4: 抽离工具类：utils、logger等通用工具函数
5. AC 5: 抽离共享类型定义和常量
6. AC 6: 提供workspace包依赖复用机制，支持独立测试和构建
7. AC 7: 验证现有功能无回归，所有依赖包能正确导入和使用共享组件
8. AC 8: 实现完整的单元测试和集成测试，覆盖率满足标准要求

注意: 不包含带有API客户端依赖的业务组件（如AvatarSelector、FileSelector、MinioUploader等），这些组件应该保留在各自的应用中。 新增: 需要复制无API依赖的通用管理后台组件，如DataTablePagination表格分页组件到共享包中，供其他包按路径导入使用。

任务 / 子任务

• [x] 创建共享UI组件包基础结构 (AC: 1)

  • 创建 packages/shared-ui-components/ 目录
  • 配置 package.json 为 @d8d/shared-ui-components
  • 设置正确的依赖关系：React、TypeScript、Tailwind CSS等
  • 配置构建工具和TypeScript配置
  • 添加workspace依赖管理

• [x] 抽离基础UI组件库 (AC: 2)

  • 批量复制 web/src/client/components/ui/ 目录到共享包（46个组件）
  • 包含所有shadcn/ui组件：Button、Input、Card、Table、Dialog等
  • 更新组件配置支持共享包环境
  • 确保Tailwind CSS样式正确继承
  • 验证所有组件在共享包中正常工作

• [x] 复制管理后台通用组件 (AC: 2)

  • 复制 DataTablePagination 表格分页组件到共享包
  • 修改组件导入路径为共享包路径
  • 验证分页功能正常工作

• [x] 抽离共享hooks (AC: 3)

  • 复制 web/src/client/hooks/use-mobile.ts 到共享包
  • 统一和优化hooks实现
  • 确保hooks在共享包中正常工作

• [x] 抽离工具类 (AC: 4)

  • 复制 web/src/client/lib/utils.ts 到共享包
  • 统一和优化工具类实现
  • 确保工具类在共享包中正常工作

• [x] 抽离共享类型定义和常量 (AC: 5)

  • 创建共享类型定义文件
  • 抽离前端相关的类型定义
  • 创建常量定义文件
  • 确保类型定义完整性和一致性

• [x] 配置workspace包依赖复用机制 (AC: 6)

  • 配置 pnpm-workspace.yaml 包含新包
  • 设置独立测试和构建脚本
  • 配置TypeScript路径映射

• [x] 实现单元测试和集成测试 (AC: 8)

  • 创建组件导入测试
  • 创建hooks单元测试
  • 创建工具类单元测试
  • 实现集成测试验证组件协作
  • 确保测试覆盖率满足标准要求

• [x] 验证现有功能无回归 (AC: 7)

  • 验证所有组件导入和使用正常
  • 运行TypeScript类型检查确保无错误
  • 运行构建流程确保成功

开发说明

先前故事洞察

基于故事007.010（订单模块多租户复制）和之前故事的经验教训：

技术挑战和解决方案 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#实施经验总结]

• 包依赖管理: 确保共享包依赖关系正确，避免循环依赖
• 文件命名规范: 严格使用一致的命名约定
• 测试配置: 配置独立的测试环境
• 类型处理: 确保TypeScript类型正确导出

最佳实践 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#最佳实践]

• 文件命名规范: 保持一致的命名约定
• 测试配置: 配置独立的测试环境
• 类型处理: 确保TypeScript类型正确导出
• 依赖管理: 及时更新包间的依赖关系

数据模型

共享包结构 [Source: docs/architecture/source-tree.md#包架构层次]

• 包根目录: packages/shared-ui-components/
• 组件文件: packages/shared-ui-components/src/components/
• hooks文件: packages/shared-ui-components/src/hooks/
• 工具文件: packages/shared-ui-components/src/utils/
• 类型文件: packages/shared-ui-components/src/types/
• 测试文件: packages/shared-ui-components/tests/unit/

组件规范

管理后台组件 [Source: docs/architecture/component-architecture.md#前端组件架构]

• DataTablePagination: 表格分页组件
• AvatarSelector: 头像选择器组件
• FileSelector: 文件选择器组件
• MinioUploader: MinIO上传器组件
• ProtectedRoute: 路由保护组件
• ErrorPage: 错误页面组件
• NotFoundPage: 404页面组件

基础UI组件 [Source: docs/architecture/component-architecture.md#前端组件架构]

• shadcn/ui组件库: 50+组件包括Button、Input、Card、Table、Dialog等
• 基于Radix UI构建
• 使用Tailwind CSS样式
• 支持TypeScript类型安全

技术约束

前端技术栈 [Source: docs/architecture/tech-stack.md#现有技术栈维护]

• 前端框架: React 19.1.0 + TypeScript
• 路由: React Router v7
• 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
• UI组件库: shadcn/ui (基于Radix UI)
• 构建工具: Vite 7.0.0
• 样式: Tailwind CSS 4.1.11
• HTTP客户端: 基于Hono Client的封装 + axios适配器

包架构 [Source: docs/architecture/source-tree.md#包架构层次]

• 使用workspace包依赖复用机制
• 支持独立测试和构建
• 遵循现有的包结构约定
• 保持与现有基础设施包兼容

性能要求 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#成功标准]

• 构建性能无显著下降
• 组件加载时间优化
• 包体积控制在合理范围

测试

测试标准 [Source: docs/architecture/testing-strategy.md#包测试架构]

• 测试位置: packages/shared-ui-components/tests/unit/
• 测试框架: Vitest + Testing Library
• 覆盖率目标: 单元测试 ≥ 80%
• 测试类型: 单元测试验证组件功能

测试要求 [Source: docs/architecture/testing-strategy.md#测试金字塔策略]

• 单元测试范围: 单个组件、hook、工具函数
• 测试目标: 验证独立单元的正确性
• 执行频率: 每次代码变更

特定测试要求

• 组件渲染和交互测试
• hooks状态管理测试
• 工具函数功能测试
• 类型定义完整性测试
• 样式和主题一致性测试

变更日志

日期	版本	描述	作者
2025-11-15	1.0	初始故事创建	Bob (Scrum Master)

开发代理记录

Agent Model Used

• Claude Code (d8d-model)

Debug Log References

• 2025-11-15: 基于史诗007需求创建共享UI组件包故事

Completion Notes List

• ✅ 已完成: 创建共享UI组件包基础结构
• ✅ 已完成: 批量复制46个基础UI组件到共享包
• ✅ 已完成: 抽离共享hooks (use-mobile)
• ✅ 已完成: 抽离工具类 (cn工具函数)
• ✅ 已完成: 抽离共享类型定义和常量
• ✅ 已完成: 配置workspace包依赖复用机制
• ✅ 已完成: 实现单元测试和集成测试
• ✅ 已完成: 验证现有功能无回归

关键成就

• 成功创建 @d8d/shared-ui-components 包
• 批量复制并修复46个UI组件的导入路径
• 确保所有依赖版本与web项目完全一致
• TypeScript编译和构建成功
• 所有导入测试通过
• 成功复制DataTablePagination组件到共享包并验证功能

File List

• packages/shared-ui-components/package.json - 共享包配置
• packages/shared-ui-components/src/components/admin/ - 管理后台组件
• packages/shared-ui-components/src/components/admin/DataTablePagination.tsx - 表格分页组件
• packages/shared-ui-components/src/components/admin/index.ts - 管理后台组件导出
• packages/shared-ui-components/src/components/ui/ - 基础UI组件
• packages/shared-ui-components/src/hooks/ - 共享hooks
• packages/shared-ui-components/src/utils/ - 工具类
• packages/shared-ui-components/src/types/ - 类型定义
• packages/shared-ui-components/tests/unit/ - 单元测试
• packages/shared-ui-components/tests/unit/DataTablePagination.test.tsx - 分页组件测试
• packages/shared-ui-components/tsconfig.json - TypeScript配置
• packages/shared-ui-components/vitest.config.ts - 测试配置

QA结果

此部分将在质量保证审查过程中由QA代理填充