# 史诗014 - mini小程序UI组件模块化与页面分包

## 史诗目标
将mini小程序中的UI组件拆分为独立的共享UI组件包（类似web项目中的shared-ui-components），并将各个子页面拆分为独立的包，以提高代码复用性、便于集成测试和内勤检查，提升项目的模块化程度和维护性。

## 史诗描述

### 现有系统上下文

**当前相关功能：**
- **mini小程序**：基于Taro 4.1.4的用人方小程序，包含完整的用人业务流程
- **UI组件现状**：mini/src/components/ui/目录下有12个自定义UI组件（avatar-upload, button, card, dialog, form, image, input, label, navbar, page-container, tab-bar, user-status-bar）
- **页面结构**：mini/src/pages/目录下有多个业务页面，特别是yongren模块下的dashboard, order, settings, statistics, talent等子页面
- **共享UI包**：packages/shared-ui-components已有完整的shadcn/ui风格组件库，但未在mini中使用

**技术栈：**
- 前端框架：Taro 4.1.4 + React 18
- 样式方案：Tailwind CSS + weapp-tailwindcss适配
- 状态管理：React Query
- API通信：Hono RPC客户端
- 测试框架：Jest（mini项目）
- 包管理：pnpm workspace

**集成点：**
- 与现有mini项目的构建系统集成
- 与Taro框架的组件系统兼容
- 与现有的模块化架构保持一致，创建专门的mini-ui-packages目录组织所有mini相关UI包
- 与现有的测试框架集成

**当前架构分析：**
1. **UI组件复用性低**：mini中的UI组件是项目内自定义实现，未形成可复用的包
2. **页面耦合度高**：所有页面都在mini/src/pages/目录下，不利于独立测试和部署
3. **与现有共享UI包不兼容**：shared-ui-components使用React 19 + Radix UI，而mini使用React 18 + Taro组件
4. **测试困难**：页面和组件耦合在一起，难以进行独立的集成测试
5. **目录组织不统一**：mini相关UI包应该统一组织在专门的mini-ui-packages目录下，便于管理和维护

### 增强详情

**改造范围：**
本次史诗将分阶段完成以下改造：

**阶段1：创建Taro专用的共享UI组件包（故事014.001）**
1. 创建新的包 `mini-ui-packages/mini-shared-ui-components`
2. 将mini/src/components/ui/中的现有组件迁移到新包
3. 适配Taro框架，确保组件在Taro环境中正常工作
4. 添加完整的类型定义和导出配置
5. 创建独立的测试套件

**阶段2：将yongren模块页面拆分为独立包（故事014.002）**
1. 分析yongren模块的页面结构
2. 创建独立的页面包，如：
   - `mini-ui-packages/yongren-dashboard-ui`
   - `mini-ui-packages/yongren-order-management-ui`
   - `mini-ui-packages/yongren-talent-management-ui`
   - `mini-ui-packages/yongren-settings-ui`
   - `mini-ui-packages/yongren-statistics-ui`
3. 每个页面包包含对应的页面组件、配置和测试
4. 更新mini项目引用，从包中导入页面

**阶段3：建立页面包集成测试框架（故事014.003）**
1. 为每个页面包创建独立的集成测试
2. 建立端到端测试框架，验证页面包在mini中的集成
3. 创建内勤检查（代码质量、类型安全、性能等）自动化流程
4. 确保分包后的构建和部署流程正常

**迁移策略：**
1. **渐进式迁移**：逐个组件和页面迁移，确保不影响现有功能
2. **向后兼容**：保持现有API和组件接口不变
3. **测试驱动**：先编写测试，确保迁移过程中功能不受影响
4. **文档更新**：更新相关文档，反映新的包结构

**成功标准：**
1. mini项目通过`pnpm typecheck`，无类型错误
2. 所有现有功能测试通过，无回归
3. 新的共享UI组件包可以独立发布和使用
4. 页面包可以独立测试和部署
5. 集成测试覆盖主要业务场景
6. 内勤检查（代码质量、安全扫描等）可以针对单个包执行
7. 构建时间和包体积得到优化
8. mini相关UI包统一组织在mini-ui-packages目录下，结构清晰，便于管理

## 故事列表

### 故事014-01：创建Taro专用的共享UI组件包
**背景：** mini小程序中的UI组件目前直接放在项目源码中，复用性差，难以独立测试和维护。需要创建一个Taro专用的共享UI组件包，将现有组件迁移到独立的包中，提高代码复用性和可维护性。

**任务列表：**
1. 创建新的包 `mini-ui-packages/mini-shared-ui-components`
   - 配置package.json，依赖Taro相关包
   - 设置TypeScript配置
   - 配置构建和测试脚本
2. 迁移现有UI组件：
   - 将mini/src/components/ui/下的12个组件迁移到新包
   - 适配Taro的组件API（Button, View, Text等）
   - 保持现有的class-variance-authority变体系统
   - 确保样式适配（weapp-tailwindcss）
3. 创建组件导出配置：
   - 建立完整的exports映射
   - 添加类型定义导出
   - 创建索引文件
4. 创建独立测试套件：
   - 设置Jest测试环境
   - 编写组件单元测试
   - 验证组件在Taro环境中的行为
5. 更新mini项目依赖：
   - 在mini的package.json中添加对新包的引用
   - 替换现有组件导入为从包中导入
   - 验证构建和运行正常

**验收标准：**
- [x] `mini-shared-ui-components`包创建成功，可通过workspace引用
- [x] 所有12个UI组件成功迁移，功能正常
- [x] 包可以独立构建和测试（类型检查和Jest测试通过）
- [ ] mini项目构建成功，无类型错误（依赖已添加，UI组件导入待更新）
- [ ] 现有页面功能正常，无视觉或功能回归（待UI组件导入更新后验证）
- [ ] 组件单元测试覆盖率达标（基础测试框架已建立，待扩展测试覆盖）

**进展状态：**
- ✅ 已完成：创建包结构、迁移12个UI组件、建立独立测试套件、迁移RPC客户端基础设施
- 🔄 进行中：更新mini项目UI组件导入、验证构建和运行时功能
- 📋 待开始：扩展组件单元测试覆盖率

### 故事014-02：将yongren模块页面拆分为独立包
**背景：** yongren模块的页面目前都集中在mini/src/pages/yongren/目录下，耦合度高，不利于独立测试和部署。需要将各个子页面拆分为独立的包，提高模块化程度。

**任务列表：**
1. 分析yongren模块页面结构：
   - 识别各页面的依赖关系
   - 分析页面间共享的组件和逻辑
   - 确定分包方案
2. 创建独立的页面包：
   - `mini-ui-packages/yongren-dashboard-ui`：仪表板页面
   - `mini-ui-packages/yongren-order-management-ui`：订单管理相关页面
   - `mini-ui-packages/yongren-talent-management-ui`：人才管理相关页面
   - `mini-ui-packages/yongren-settings-ui`：设置页面
   - `mini-ui-packages/yongren-statistics-ui`：统计页面
3. 迁移页面代码：
   - 将页面组件、配置文件、样式迁移到对应包
   - 处理页面间的共享依赖
   - 更新导入路径
4. 配置页面包：
   - 每个包独立的package.json
   - TypeScript配置
   - 测试配置
5. 更新mini项目路由配置：
   - 更新页面导入路径
   - 验证路由跳转正常
   - 确保TabBar等布局组件正常工作

**验收标准：**
- [ ] 5个页面包创建成功，结构清晰
- [ ] 所有页面功能正常，无回归
- [ ] 页面包可以独立构建和测试
- [ ] mini项目路由配置更新成功
- [ ] 页面间跳转和状态管理正常
- [ ] 包体积和构建时间得到优化

### 故事014-03：建立页面包集成测试和内勤检查框架
**背景：** 页面拆分为独立包后，需要创建共享的测试工具包，以便所有页面包可以统一使用测试工具，提高测试一致性和开发效率。

**任务列表：**
1. 创建mini专用的共享测试工具包：
   - 创建独立的测试工具包 `mini-ui-packages/mini-testing-utils`
   - 解决模块导出兼容性问题（TypeScript源文件 vs JavaScript运行时）
   - 提供常用的测试工具函数：`setupTestEnv`、`renderTaroComponent`、Taro组件mock等
   - 配置正确的构建和导出设置，确保可以被各个页面包正确引用
   - 提供使用示例和文档
   - 更新现有页面包使用新的测试工具包

**验收标准：**
- [ ] `mini-testing-utils` 包创建完成，包含所有必需的测试工具函数（setupTestEnv、renderTaroComponent、Taro组件mock等）
- [ ] 包解决模块导出兼容性问题（TypeScript源文件 vs JavaScript运行时）
- [ ] 包配置正确的构建和导出设置，可以被所有页面包正确引用
- [ ] 包包含使用示例和文档，便于其他页面包集成
- [ ] 现有页面包更新成功，能够使用新的测试工具包

## 兼容性要求

- [ ] 现有API接口保持不变
- [ ] 用户界面和交互体验无变化
- [ ] 构建产物兼容现有部署环境
- [ ] 性能指标不下降
- [ ] 向后兼容，支持渐进式迁移

## 风险缓解

- **主要风险**：分包过程中可能引入构建错误或运行时问题
- **缓解措施**：渐进式迁移，充分测试，每一步都有回滚计划
- **回滚计划**：如果分包导致严重问题，可以回退到单体结构，保持现有代码不变

## 完成定义

- [ ] 所有故事完成，验收标准满足
- [ ] 类型检查通过，无TypeScript错误
- [ ] 所有测试通过，包括单元测试、集成测试、端到端测试
- [ ] 代码审查通过，符合项目编码标准
- [ ] 文档更新，反映新的包结构和开发流程
- [ ] 内勤检查流程建立并运行正常