nongxiaoyu/.kiro/specs/vue2-to-vue3-migration/requirements.md

Requirements Document

Introduction

本文档定义了将「农小禹智慧农业系统」从 uni-app Vue2 (Options API) 迁移到 uni-app Vue3 (Composition API) 的需求规范。该迁移的核心目标是支持 HarmonyOS 打包,同时保持 Android、iOS 和 H5 平台的完整功能和行为一致性。

Glossary

• System: 农小禹智慧农业系统 uni-app 应用
• Migration_Engine: 负责执行 Vue2 到 Vue3 代码转换的迁移引擎
• Composition_API: Vue3 的组合式 API 编程范式
• Options_API: Vue2 的选项式 API 编程范式
• HarmonyOS: 华为鸿蒙操作系统
• ArkUI: HarmonyOS 的 UI 编译环境
• Platform: 指 Android、iOS、H5、HarmonyOS 等运行平台
• Business_Logic: 应用的业务逻辑,包括接口调用、数据处理、状态管理等
• Lifecycle_Hook: Vue 组件的生命周期钩子函数
• Reactive_Data: Vue 的响应式数据系统
• Component: Vue 组件,包括页面组件和公共组件
• Store: Vuex 状态管理存储
• API_Service: 封装的 API 服务模块
• Utils: 工具函数模块
• Third_Party_Library: 第三方依赖库,如 uview-ui

Requirements

Requirement 1: Vue3 语法迁移

User Story: 作为开发者,我希望所有 Vue2 Options API 代码迁移为 Vue3 Composition API,以便支持 HarmonyOS 编译。

Acceptance Criteria

1. WHEN 迁移 Vue 组件时,THE Migration_Engine SHALL 将 Options API 的 data、methods、computed、watch 转换为 Composition API 的 ref、reactive、computed、watch
2. WHEN 处理组件生命周期时,THE Migration_Engine SHALL 将 Vue2 生命周期钩子(mounted、created 等)转换为 Vue3 对应钩子(onMounted、setup 等)
3. WHEN 迁移响应式数据时,THE Migration_Engine SHALL 使用 ref() 处理基本类型,使用 reactive() 处理对象类型
4. WHEN 处理 this 引用时,THE Migration_Engine SHALL 移除所有 this 关键字,改用 Composition API 的直接引用
5. THE System SHALL 在所有组件中使用 <script setup> 语法糖

Requirement 2: 生命周期钩子转换

User Story: 作为开发者,我希望所有 Vue2 生命周期钩子正确转换为 Vue3 钩子,以确保组件行为一致。

Acceptance Criteria

1. WHEN 遇到 beforeCreate 或 created 钩子时,THE Migration_Engine SHALL 将逻辑移至 setup() 函数顶层
2. WHEN 遇到 mounted 钩子时,THE Migration_Engine SHALL 转换为 onMounted()
3. WHEN 遇到 beforeDestroy 钩子时,THE Migration_Engine SHALL 转换为 onBeforeUnmount()
4. WHEN 遇到 destroyed 钩子时,THE Migration_Engine SHALL 转换为 onUnmounted()
5. WHEN 遇到 uni-app 特有生命周期(onShow、onLoad 等)时,THE Migration_Engine SHALL 保持原有命名和用法

Requirement 3: 状态管理迁移

User Story: 作为开发者,我希望 Vuex 3.x 迁移到 Vuex 4.x 或 Pinia,以兼容 Vue3 生态。

Acceptance Criteria

1. WHEN 迁移 Vuex store 时,THE Migration_Engine SHALL 升级到 Vuex 4.x 或迁移到 Pinia
2. WHEN 在组件中使用 store 时,THE Migration_Engine SHALL 使用 useStore() 替代 this.$store
3. WHEN 访问 store 状态时,THE Migration_Engine SHALL 使用 computed() 包装以保持响应性
4. THE Store SHALL 保持所有现有的 state、getters、mutations、actions 的业务逻辑不变

Requirement 4: 依赖库升级

User Story: 作为开发者,我希望所有第三方依赖升级到 Vue3 兼容版本,以确保系统正常运行。

Acceptance Criteria

1. THE System SHALL 将 Vue 从 2.6.14 升级到 3.x 最新稳定版
2. THE System SHALL 将 @dcloudio/uni-app 升级到支持 Vue3 的版本
3. THE System SHALL 将 uview-ui 升级到 Vue3 兼容版本或替换为兼容方案
4. THE System SHALL 将 Vuex 从 3.6.2 升级到 4.x 或迁移到 Pinia
5. WHEN 第三方库不支持 Vue3 时,THE System SHALL 寻找替代方案或自行实现

Requirement 5: 组件模板兼容性

User Story: 作为开发者,我希望所有组件模板语法兼容 Vue3,以避免运行时错误。

Acceptance Criteria

1. WHEN 模板中使用 v-model 时,THE Migration_Engine SHALL 确保符合 Vue3 的 v-model 语法规范
2. WHEN 使用自定义指令时,THE Migration_Engine SHALL 更新指令钩子名称(bind → beforeMount,update → updated 等)
3. WHEN 使用 $listeners 时,THE Migration_Engine SHALL 移除 $listeners(Vue3 已合并到 $attrs)
4. WHEN 使用 .sync 修饰符时,THE Migration_Engine SHALL 转换为 v-model:propName 语法
5. THE System SHALL 确保所有模板语法符合 Vue3 规范

Requirement 6: 事件处理迁移

User Story: 作为开发者,我希望所有事件处理逻辑正确迁移,以保持交互功能完整。

Acceptance Criteria

1. WHEN 定义事件处理函数时,THE Migration_Engine SHALL 在 setup() 中定义函数并返回
2. WHEN 使用 $emit 时,THE Migration_Engine SHALL 使用 defineEmits() 声明事件
3. WHEN 使用 $refs 时,THE Migration_Engine SHALL 使用 ref() 创建模板引用
4. THE System SHALL 保持所有事件处理的业务逻辑不变

Requirement 7: Props 和 Emits 声明

User Story: 作为开发者,我希望组件的 props 和 emits 使用 Vue3 的声明方式,以获得更好的类型推断。

Acceptance Criteria

1. WHEN 组件接收 props 时,THE Migration_Engine SHALL 使用 defineProps() 声明
2. WHEN 组件发出事件时,THE Migration_Engine SHALL 使用 defineEmits() 声明
3. THE System SHALL 为 props 提供类型定义和默认值
4. THE System SHALL 保持所有 props 验证规则不变

Requirement 8: 计算属性和侦听器迁移

User Story: 作为开发者,我希望计算属性和侦听器正确迁移到 Composition API,以保持响应式逻辑。

Acceptance Criteria

1. WHEN 迁移 computed 属性时,THE Migration_Engine SHALL 使用 computed() 函数包装
2. WHEN 迁移 watch 侦听器时,THE Migration_Engine SHALL 使用 watch() 或 watchEffect() 函数
3. THE System SHALL 保持计算属性的缓存特性
4. THE System SHALL 保持侦听器的 deep、immediate 等选项

Requirement 9: 全局配置迁移

User Story: 作为开发者,我希望全局配置(过滤器、混入、原型方法等)正确迁移到 Vue3,以保持全局功能。

Acceptance Criteria

1. WHEN 迁移全局过滤器时,THE Migration_Engine SHALL 转换为全局方法或组合式函数
2. WHEN 迁移 Vue.prototype 属性时,THE Migration_Engine SHALL 使用 app.config.globalProperties
3. WHEN 迁移全局混入时,THE Migration_Engine SHALL 评估是否可转换为组合式函数
4. THE System SHALL 保持所有全局功能的业务逻辑不变

Requirement 10: HarmonyOS 兼容性

User Story: 作为开发者,我希望迁移后的代码完全兼容 HarmonyOS ArkUI 编译环境,以成功打包鸿蒙应用。

Acceptance Criteria

1. THE System SHALL 移除所有 window 和 document 对象的直接引用
2. THE System SHALL 使用 uni-app 提供的跨平台 API 替代浏览器特定 API
3. THE System SHALL 确保所有条件编译标记正确处理 HarmonyOS 平台
4. THE System SHALL 测试并验证在 HarmonyOS 环境下的功能完整性
5. WHEN 使用平台特定功能时,THE System SHALL 使用条件编译隔离平台代码

Requirement 11: 业务逻辑保持不变

User Story: 作为产品负责人,我希望迁移过程不改变任何业务逻辑,以确保功能一致性。

Acceptance Criteria

1. THE Migration_Engine SHALL 保持所有 API 接口调用的参数和返回值处理逻辑不变
2. THE Migration_Engine SHALL 保持所有数据处理和计算逻辑不变
3. THE Migration_Engine SHALL 保持所有页面跳转和路由逻辑不变
4. THE Migration_Engine SHALL 保持所有条件判断和业务规则不变
5. THE System SHALL 通过功能测试验证业务逻辑的一致性

Requirement 12: 页面结构保持不变

User Story: 作为 UI/UX 设计师,我希望迁移不改变页面结构和样式,以保持用户体验一致。

Acceptance Criteria

1. THE Migration_Engine SHALL 保持所有模板结构不变
2. THE Migration_Engine SHALL 保持所有 CSS/SCSS 样式不变
3. THE Migration_Engine SHALL 保持所有布局和组件层级不变
4. THE System SHALL 通过视觉回归测试验证 UI 一致性

Requirement 13: 跨平台行为一致性

User Story: 作为测试工程师,我希望迁移后的应用在所有平台上行为一致,以确保用户体验统一。

Acceptance Criteria

1. THE System SHALL 在 Android 平台上保持原有功能和性能
2. THE System SHALL 在 iOS 平台上保持原有功能和性能
3. THE System SHALL 在 H5 平台上保持原有功能和性能
4. THE System SHALL 在 HarmonyOS 平台上实现与其他平台一致的功能
5. WHEN 平台差异无法避免时,THE System SHALL 使用条件编译提供平台特定实现

Requirement 14: 代码质量和可维护性

User Story: 作为技术负责人,我希望迁移后的代码质量高、可维护性强,以降低未来维护成本。

Acceptance Criteria

1. THE Migration_Engine SHALL 遵循 Vue3 官方最佳实践
2. THE Migration_Engine SHALL 为无法自动迁移的代码添加 TODO 注释和说明
3. THE Migration_Engine SHALL 保持代码格式和命名规范一致
4. THE System SHALL 提供迁移文档说明关键变更点
5. THE System SHALL 确保迁移后的代码通过 ESLint 检查

Requirement 15: 第三方插件兼容性

User Story: 作为开发者,我希望所有第三方插件和工具正确迁移或替换,以保持功能完整。

Acceptance Criteria

1. WHEN 迁移 Jessibuca 视频播放插件时,THE System SHALL 确保在 H5 平台正常工作
2. WHEN 迁移高德地图 SDK 时,THE System SHALL 确保定位和地图功能正常
3. WHEN 迁移 uview-ui 组件库时,THE System SHALL 升级到 Vue3 兼容版本或寻找替代方案
4. THE System SHALL 测试所有第三方功能在各平台的兼容性

Requirement 16: 性能优化

User Story: 作为用户,我希望迁移后的应用性能不低于原版本,最好有所提升。

Acceptance Criteria

1. THE System SHALL 利用 Vue3 的性能优势优化渲染性能
2. THE System SHALL 使用 Composition API 优化代码复用和逻辑组织
3. THE System SHALL 保持或改善应用启动时间
4. THE System SHALL 保持或改善页面切换流畅度
5. THE System SHALL 通过性能测试验证关键指标不低于原版本

Requirement 17: 错误处理和调试

User Story: 作为开发者,我希望迁移过程中的错误易于发现和调试,以快速解决问题。

Acceptance Criteria

1. THE Migration_Engine SHALL 为每个无法自动迁移的代码添加明确的 TODO 注释
2. THE Migration_Engine SHALL 在 TODO 注释中说明问题原因和推荐解决方案
3. THE System SHALL 提供详细的错误日志和堆栈信息
4. THE System SHALL 在开发环境启用 Vue3 的开发者工具支持

Requirement 18: 渐进式迁移支持

User Story: 作为项目经理,我希望支持渐进式迁移,以降低风险和工作量。

Acceptance Criteria

1. THE System SHALL 支持按页面或模块逐步迁移
2. THE System SHALL 允许 Vue2 和 Vue3 代码在迁移期间共存
3. THE System SHALL 提供迁移进度跟踪机制
4. THE System SHALL 支持回滚到迁移前的状态

Requirement 19: 测试覆盖

User Story: 作为质量保证工程师,我希望有完整的测试覆盖,以确保迁移质量。

Acceptance Criteria

1. THE System SHALL 为关键业务逻辑提供单元测试
2. THE System SHALL 为主要用户流程提供集成测试
3. THE System SHALL 在所有目标平台上进行端到端测试
4. THE System SHALL 进行视觉回归测试验证 UI 一致性
5. THE System SHALL 进行性能测试验证性能指标

Requirement 20: 文档和培训

User Story: 作为团队成员,我希望有完整的迁移文档和培训材料,以快速掌握 Vue3 开发。

Acceptance Criteria

1. THE System SHALL 提供 Vue2 到 Vue3 的迁移指南文档
2. THE System SHALL 提供关键 API 变更对照表
3. THE System SHALL 提供常见问题和解决方案文档
4. THE System SHALL 提供 Vue3 Composition API 最佳实践文档
5. THE System SHALL 提供代码示例和模板