Home Explore Help
Register Sign In
186-template-175
/
mini-starter
forked from 155-template-138/mini-starter
2
0
Fork 0
Files
Tree: 02aa8e1b96
Branches Tags
mini-starter
/
docs
/
stories
/
007.013.shared-ui-components-package.story.md

007.013.shared-ui-components-package.story.md 8.6 KB
History Raw

故事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代理填充