mini-starter/docs/prd/epic-014-mini-ui-component-modularization.md

史诗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中添加对新包的引用
   • 替换现有组件导入为从包中导入
   • 验证构建和运行正常

验收标准：

• mini-shared-ui-components包创建成功，可通过workspace引用
• 所有12个UI组件成功迁移，功能正常
• 包可以独立构建和测试（类型检查和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错误
• 所有测试通过，包括单元测试、集成测试、端到端测试
• 代码审查通过，符合项目编码标准
• 文档更新，反映新的包结构和开发流程
• 内勤检查流程建立并运行正常