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

- [x] 任务5：迁移RPC客户端基础设施 (验收标准: 1, 3)
  - [x] 迁移rpc-client.ts并创建通用可配置版本
  - [x] 迁移response-polyfill.ts
  - [x] 迁移headers-polyfill.js
  - [x] 更新共享包的index.ts导出RPC工具
  - [x] 处理重复文件(cn.ts, platform.ts)从共享包重新导出

## 开发说明

### 先前故事洞察
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*