mini-starter/docs/stories/014.001.mini-shared-ui-components.md

Story 014.001: Create Taro Shared UI Components Package

Status

Ready for Review

Story

作为 mini小程序开发者， 我希望 将现有的UI组件从mini项目迁移到独立的共享UI包中， 以便 这些组件可以被复用、独立测试和维护，提高代码的可维护性。

Acceptance Criteria

1. mini-shared-ui-components包创建成功，可通过workspace引用
2. 所有12个UI组件成功迁移，功能正常
3. 包可以独立构建和测试
4. mini项目构建成功，无类型错误
5. 现有页面功能正常，无视觉或功能回归
6. 组件单元测试覆盖率达标

Tasks / Subtasks

• 任务1：创建新的包 mini-ui-packages/mini-shared-ui-components (验收标准: 1)
  • 配置package.json，包含Taro依赖
  • 设置TypeScript配置
  • 配置构建和测试脚本
  • 创建导出映射和索引文件
• 任务2：从 mini/src/components/ui/ 迁移现有的UI组件 (验收标准: 2)
  • 迁移avatar-upload.tsx组件
  • 迁移button.tsx组件
  • 迁移card.tsx组件
  • 迁移dialog.tsx组件
  • 迁移form.tsx组件
  • 迁移image.tsx组件
  • 迁移input.tsx组件
  • 迁移label.tsx组件
  • 迁移navbar.tsx组件
  • 迁移page-container.tsx组件
  • 迁移tab-bar.tsx组件
  • 迁移user-status-bar.tsx组件
  • 适配组件到Taro API (Button, View, Text等)
  • 保留现有的class-variance-authority变体系统
  • 确保样式兼容性（weapp-tailwindcss）
• 任务3：创建独立的测试套件 (验收标准: 3, 6)
  • 设置Jest测试环境用于Taro组件
  • 编写组件单元测试
  • 验证组件在Taro环境中的行为
  • 确保测试覆盖率达到标准
  • 创建可复用的测试基础设施（供其他mini UI包使用）
  • 创建 tests/__helpers__/ 目录，包含可复用的测试工具函数
  • 导出标准化的Taro组件mock配置
  • 创建测试环境设置工具，支持其他mini UI包复用
  • 建立测试配置导出机制
• 任务4：更新mini项目依赖 (验收标准: 4, 5)
  • 在mini的package.json中添加对新包的引用
  • 将现有的组件导入替换为从包中导入
  • 验证构建和运行时功能
  • 运行类型检查以确保无TypeScript错误

开发说明

先前故事洞察

Epic 014中没有先前故事。

数据模型

UI组件包不需要特定的数据模型。[来源：architecture/data-model-schema-changes.md#现有数据模型状态]

API规范

UI组件包不需要API端点。[来源：architecture/api-design-integration.md#api集成策略]

组件规范

• 现有UI组件: 12个自定义UI组件位于 mini/src/components/ui/ [来源：architecture/source-tree.md#实际项目结构]
• 组件类型: avatar-upload, button, card, dialog, form, image, input, label, navbar, page-container, tab-bar, user-status-bar
• Taro框架: 组件必须适配Taro组件API (Button, View, Text等) [来源：architecture/tech-stack.md#现有技术栈维护]
• 样式: 使用Tailwind CSS配合weapp-tailwindcss适配小程序 [来源：architecture/tech-stack.md#现有技术栈维护]
• 变体系统: 保留现有的class-variance-authority变体系统用于组件样式

文件位置

• 源组件: mini/src/components/ui/ [来源：architecture/source-tree.md#实际项目结构]
• 新包位置: mini-ui-packages/mini-shared-ui-components/ (项目根目录下的新目录)
• 包结构:
  • mini-ui-packages/mini-shared-ui-components/package.json
  • mini-ui-packages/mini-shared-ui-components/tsconfig.json
  • mini-ui-packages/mini-shared-ui-components/src/ (组件源码)
  • mini-ui-packages/mini-shared-ui-components/tests/ (测试文件)
• 项目结构: 使用pnpm workspace的Monorepo [来源：architecture/source-tree.md#集成指南]

具体组件文件参考（迁移时需要对照的文件）

迁移组件时必须参考mini项目中现有的组件实现：

1. Button组件参考: mini/src/components/ui/button.tsx - 使用class-variance-authority变体系统，封装Taro Button组件
2. Form组件参考: mini/src/components/ui/form.tsx - 复杂表单组件的实现模式
3. Dialog组件参考: mini/src/components/ui/dialog.tsx - 对话框组件的实现
4. 其他组件: 位于mini/src/components/ui/目录下的12个组件文件都需要参考

迁移注意事项：

• 保持现有的组件API接口不变
• 保留class-variance-authority变体系统
• 确保样式兼容性（Tailwind CSS + weapp-tailwindcss）
• 组件导出方式保持一致

测试要求

• 测试框架: Jest (mini项目使用Jest) [来源：architecture/coding-standards.md#现有标准合规性]
• 测试位置: tests/文件夹与源码并行 [来源：architecture/coding-standards.md#增强特定标准]
• 覆盖率目标: 核心业务逻辑 > 80% [来源：architecture/coding-standards.md#增强特定标准]
• 测试类型: 组件单元测试
• UI包标准: 必须遵循UI包开发标准 [来源：architecture/coding-standards.md#ui包开发提示]

测试配置参考（基于mini项目现有测试结构）

必须参照mini项目中现有的测试配置模式和文件结构：

1. Jest配置文件: mini/jest.config.js - 包含Taro组件mock、测试匹配规则、覆盖率配置等
2. 测试环境设置: mini/tests/setup.ts - 包含Taro组件的完整mock实现、全局环境变量设置、DOM API模拟
3. 测试目录结构: mini/tests/ - 包含以下子目录：
   • __mocks__/ - 模拟文件（样式、文件等）
   • __snapshots__/ - 快照测试文件
   • components/ - 组件测试（如Button.test.tsx）
4. 组件测试模式: 参考mini/tests/components/Button.test.tsx - 使用@testing-library/react进行组件渲染和交互测试
5. Taro组件mock: setup.ts中包含了完整的@tarojs/components mock实现，需要在新包的测试配置中复制类似的mock逻辑
6. 环境变量设置: 测试中需要设置process.env.TARO_ENV = 'h5'等环境变量以模拟Taro运行环境

关键注意事项：

• 新的UI组件包需要建立与mini项目一致的测试环境配置
• Taro组件的mock必须完整，确保组件在测试环境中正常工作
• 测试文件命名遵循.test.tsx模式，与现有项目保持一致

可复用测试基础设施设计

目标: 为所有mini相关的UI包创建统一的可复用测试基础设施，避免重复配置。

实现方案:

1. 测试工具目录结构: 在 mini-ui-packages/mini-shared-ui-components/tests/ 下创建：

   • __helpers__/ - 可复用的测试工具函数
     • taro-mocks.ts - 标准化的Taro组件mock配置
     • test-utils.ts - 通用的测试工具函数（渲染、断言等）
     • env-setup.ts - 测试环境设置工具
   • __config__/ - 测试配置
     • jest-preset.js - 可复用的Jest预设配置
     • tsconfig.test.json - 测试专用的TypeScript配置

2. 导出机制:

   • 在包的根目录创建 testing.ts 或 testing/index.ts 作为测试工具入口
   • 导出所有测试工具函数和配置
   • 其他mini UI包可以通过 import { setupTaroTest } from '@d8d/mini-shared-ui-components/testing' 使用

3. 包含的内容:

   • Taro组件mock: 完整的@tarojs/components mock实现
   • 测试环境设置: 包括环境变量、DOM API模拟等
   • 工具函数: 通用的组件测试工具（渲染、事件模拟等）
   • Jest配置: 可复用的Jest预设配置

收益:

• 后续的mini UI包（如yongren页面包）可以直接复用测试基础设施
• 保持所有mini UI包的测试配置一致性
• 减少重复配置工作，提高开发效率

技术约束

• Taro版本: 4.1.4
• React版本: 18 (mini项目) 与其他项目的React 19不同 [来源：architecture/tech-stack.md#现有技术栈维护]
• 包管理: pnpm workspace [来源：architecture/source-tree.md#集成指南]
• TypeScript: 严格模式启用 [来源：architecture/coding-standards.md#现有标准合规性]
• 构建系统: Workspace包引用，无需单独的构建步骤

项目结构说明

• 当前项目使用monorepo结构，packages/目录用于共享包 [来源：architecture/source-tree.md#实际项目结构]
• 史诗指定创建mini-ui-packages/目录来组织所有mini相关的UI包
• 这与项目中建立的模块化架构模式一致
• 需要确保新目录遵循现有的workspace配置模式

测试

测试标准

• 测试文件位置: tests/文件夹与源码并行 [来源：architecture/coding-standards.md#增强特定标准]
• 测试标准: 遵循mini项目中现有的测试模式 (Jest)
• 测试框架: mini项目组件使用Jest [来源：architecture/coding-standards.md#现有标准合规性]
• 特定要求:
  • 所有迁移的UI组件的组件单元测试
  • 测试覆盖率报告
  • 与现有的mini项目测试套件集成
  • 遵循UI包测试标准 [来源：architecture/ui-package-standards.md#测试规范]
  • 创建可复用的测试基础设施，供其他mini UI包使用：
  • 建立标准化的测试工具目录结构（__helpers__/, __config__/）
  • 导出可复用的Taro组件mock配置和测试环境设置工具
  • 提供清晰的测试工具导入接口（如 @d8d/mini-shared-ui-components/testing）

Change Log

Date	Version	Description	Author
2025-12-19	1.0	Initial story creation	Scrum Master Bob

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Reference any debug logs or traces generated during development

Completion Notes List

Notes about the completion of tasks and any issues encountered

File List

List all files created, modified, or affected during story implementation

QA Results

Results from QA Agent QA review of the completed story implementation