|
|
@@ -0,0 +1,203 @@
|
|
|
+# 史诗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组件成功迁移，功能正常
|
|
|
+- [ ] 包可以独立构建和测试
|
|
|
+- [ ] mini项目构建成功，无类型错误
|
|
|
+- [ ] 现有页面功能正常，无视觉或功能回归
|
|
|
+- [ ] 组件单元测试覆盖率达标
|
|
|
+
|
|
|
+### 故事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：建立页面包集成测试和内勤检查框架
|
|
|
+**背景：** 页面拆分为独立包后，需要建立相应的集成测试框架，确保页面包在mini项目中集成正常。同时需要建立内勤检查（代码质量、安全、性能等）自动化流程，提高代码质量。
|
|
|
+
|
|
|
+**任务列表：**
|
|
|
+1. 建立集成测试框架：
|
|
|
+ - 创建端到端测试配置
|
|
|
+ - 编写页面包在mini环境中的集成测试
|
|
|
+ - 测试页面路由、数据加载、用户交互等关键场景
|
|
|
+2. 创建内勤检查自动化：
|
|
|
+ - 代码质量检查（ESLint, Stylelint）
|
|
|
+ - 类型安全检查（TypeScript严格模式）
|
|
|
+ - 性能检查（包体积分析，构建时间监控）
|
|
|
+ - 安全扫描（依赖漏洞检查）
|
|
|
+3. 配置CI/CD流水线：
|
|
|
+ - 为每个页面包配置独立的测试任务
|
|
|
+ - 集成内勤检查到PR流程
|
|
|
+ - 设置自动化报告和告警
|
|
|
+4. 创建监控和告警：
|
|
|
+ - 测试覆盖率监控
|
|
|
+ - 构建性能监控
|
|
|
+ - 代码质量趋势分析
|
|
|
+
|
|
|
+**验收标准：**
|
|
|
+- [ ] 集成测试框架建立，覆盖主要业务场景
|
|
|
+- [ ] 内勤检查自动化流程配置完成
|
|
|
+- [ ] CI/CD流水线可以并行测试各个页面包
|
|
|
+- [ ] 测试覆盖率报告和代码质量报告可查看
|
|
|
+- [ ] 发现问题可以及时告警和跟踪
|
|
|
+
|
|
|
+## 兼容性要求
|
|
|
+
|
|
|
+- [ ] 现有API接口保持不变
|
|
|
+- [ ] 用户界面和交互体验无变化
|
|
|
+- [ ] 构建产物兼容现有部署环境
|
|
|
+- [ ] 性能指标不下降
|
|
|
+- [ ] 向后兼容，支持渐进式迁移
|
|
|
+
|
|
|
+## 风险缓解
|
|
|
+
|
|
|
+- **主要风险**：分包过程中可能引入构建错误或运行时问题
|
|
|
+- **缓解措施**：渐进式迁移，充分测试，每一步都有回滚计划
|
|
|
+- **回滚计划**：如果分包导致严重问题，可以回退到单体结构，保持现有代码不变
|
|
|
+
|
|
|
+## 完成定义
|
|
|
+
|
|
|
+- [ ] 所有故事完成，验收标准满足
|
|
|
+- [ ] 类型检查通过，无TypeScript错误
|
|
|
+- [ ] 所有测试通过，包括单元测试、集成测试、端到端测试
|
|
|
+- [ ] 代码审查通过，符合项目编码标准
|
|
|
+- [ ] 文档更新，反映新的包结构和开发流程
|
|
|
+- [ ] 内勤检查流程建立并运行正常
|
yourname