# Implementation Plan: Vue2 to Vue3 Migration

## Overview

本实施计划将「农小禹智慧农业系统」从 uni-app Vue2 迁移到 uni-app Vue3,以支持 HarmonyOS 打包。迁移将按照"基础设施 → 工具函数 → 公共组件 → 页面组件"的顺序进行,确保每个阶段都经过充分测试后再进入下一阶段。

实现语言: **JavaScript** (保持当前项目语言,降低迁移成本)

## Tasks

- [x] 1. 环境准备和依赖升级
  - 创建新分支 `feature/vue3-migration`
  - 备份当前项目代码
  - 更新 package.json 中的依赖版本
  - 更新 manifest.json 配置
  - _Requirements: 4.1, 4.2, 4.4_

- [x] 1.1 编写依赖升级验证测试

  - 验证 package.json 中 Vue 版本为 3.x
  - 验证 Vuex 版本为 4.x
  - 验证 uni-app 版本支持 Vue3
  - _Requirements: 4.1, 4.2, 4.4_

- [x] 2. 迁移入口文件 main.js
  - 将 `new Vue()` 改为 `createSSRApp()`
  - 更新 Vuex store 的注册方式
  - 迁移全局过滤器为全局方法
  - 迁移 Vue.prototype 属性到 app.config.globalProperties
  - 更新 uview-ui 导入 (升级到 uview-plus)
  - 处理 Jessibuca 插件的条件编译
  - _Requirements: 9.1, 9.2, 4.3_

- [x] 2.1 编写 main.js 迁移验证测试

  - 验证使用 createSSRApp 创建应用
  - 验证全局属性正确注册
  - 验证插件正确加载
  - _Requirements: 9.1, 9.2_

- [x] 3. 迁移 Vuex Store
  - 将 `new Vuex.Store()` 改为 `createStore()`
  - 移除 `Vue.use(Vuex)`
  - 保持所有 state、getters、mutations、actions 的业务逻辑不变
  - _Requirements: 3.1, 3.4_

- [x] 3.1 编写 Store 功能测试

  - 测试 state 读取
  - 测试 mutations 提交
  - 测试 actions 调度
  - 验证业务逻辑一致性
  - _Requirements: 3.4_

- [x] 4. 迁移工具函数模块
  - 检查 utils 目录下的所有工具函数
  - 移除 window/document 直接引用,替换为 uni-app API
  - 更新导出方式 (如需要)
  - _Requirements: 10.1, 10.2_

- [x] 4.1 编写工具函数单元测试

  - 测试日期格式化函数
  - 测试坐标转换函数
  - 测试存储工具函数
  - _Requirements: 10.1, 10.2_

- [x] 5. 迁移 API 服务模块
  - 检查 api/services 目录下的所有服务文件
  - 确保请求拦截器兼容 Vue3
  - 更新 store 引用方式 (如有)
  - _Requirements: 11.1_

- [x] 6. Checkpoint - 基础设施验证
  - 确保所有基础设施迁移完成
  - 运行所有单元测试
  - 询问用户是否有问题

- [x] 7. 迁移公共组件 - dict-tag.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 props 为 defineProps()
  - 转换 data 为 ref/reactive
  - 转换 computed 为 computed()
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 7.1, 12.1, 12.2_

- [x] 7.1 编写 dict-tag 组件属性测试

  - **Property 1: Options API 完整转换**
  - **Validates: Requirements 1.1, 1.3**

- [x] 7.2 编写 dict-tag 组件单元测试

  - 测试组件渲染
  - 测试 props 传递
  - 测试样式应用
  - _Requirements: 7.1_

- [x] 8. 迁移公共组件 - LocationPicker.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 props 和 emits
  - 转换响应式数据
  - 转换事件处理函数
  - 转换生命周期钩子
  - 确保地图 API 使用 uni-app 统一接口
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 6.2, 7.1, 7.2, 10.2_

- [x] 8.1 编写 LocationPicker 组件属性测试

  - **Property 7: Props 和 Emits 声明**
  - **Validates: Requirements 7.1, 7.2, 7.3**

- [x] 8.2 编写 LocationPicker 组件功能测试

  - 测试地图初始化
  - 测试位置选择
  - 测试事件发出
  - _Requirements: 10.2_

- [x] 9. 迁移公共组件 - video-player.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 $refs 为 ref() 模板引用
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 6.3_

- [x] 9.1 编写 video-player 组件属性测试

  - **Property 8: 模板引用转换**
  - **Validates: Requirements 6.3**

- [x] 10. 迁移公共组件 - jessibuca.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 添加 H5 平台条件编译
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 10.5, 15.1_

- [x] 10.1 编写 jessibuca 组件功能测试

  - 测试 H5 平台视频播放
  - 验证条件编译正确性
  - _Requirements: 15.1_

- [x] 11. Checkpoint - 公共组件验证
  - 确保所有公共组件迁移完成
  - 运行所有组件测试
  - 询问用户是否有问题

- [x] 12. 迁移 App.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 onLaunch、onShow、onHide 生命周期 (保持 uni-app 命名)
  - 转换 methods 为函数定义
  - 移除所有 this 引用
  - 保持 style 不变
  - _Requirements: 1.1, 1.4, 1.5, 2.5_

- [x] 12.1 编写 App.vue 属性测试

  - **Property 3: uni-app 生命周期保持不变**
  - **Validates: Requirements 2.5**

- [x] 13. 迁移登录页面 - pages/login/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 data 为 ref/reactive
  - 转换 methods 为函数定义
  - 转换 computed 为 computed()
  - 转换生命周期钩子
  - 更新 store 使用方式为 useStore()
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 3.2, 3.3, 12.1, 12.2_

- [x] 13.1 编写登录页面属性测试

  - **Property 6: Store 使用方式转换**
  - **Validates: Requirements 3.2, 3.3**

- [x] 13.2 编写登录页面功能测试

  - 测试登录表单提交
  - 测试表单验证
  - 测试登录成功跳转
  - _Requirements: 11.1, 11.3_

- [x] 14. 迁移登录页面 - pages/login/register.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 更新 store 使用方式
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 3.2, 12.1, 12.2_

- [x] 15. 迁移登录页面 - pages/login/forget-password.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 12.1, 12.2_

- [x] 16. Checkpoint - 登录模块验证
  - 确保所有登录相关页面迁移完成
  - 运行登录流程功能测试
  - 询问用户是否有问题


- [x] 17. 迁移首页 - pages/dashboard/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换 data 为 ref/reactive (注意复杂对象使用 reactive)
  - 转换 computed 为 computed()
  - 转换 methods 为函数定义
  - 转换 watch 为 watch() (如有)
  - 转换生命周期钩子 (onShow、onLoad、mounted 等)
  - 更新 store 使用方式为 useStore()
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 3.2, 3.3, 8.1, 12.1, 12.2_

- [x] 17.1 编写首页属性测试

  - **Property 9: 计算属性和侦听器转换**
  - **Validates: Requirements 8.1, 8.2, 8.4**

- [x] 17.2 编写首页功能测试

  - 测试数据加载
  - 测试地块切换
  - 测试图表渲染
  - 测试页面跳转
  - _Requirements: 11.1, 11.2, 11.3_

- [x] 18. 迁移农事活动页面 - pages/activity/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 更新 store 使用方式
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 3.2, 12.1, 12.2_

- [x] 19. 迁移农事活动详情页 - pages/activity/activity-detail.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 20. 迁移设备监测页面 - pages/device/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 更新 store 使用方式
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 3.2, 12.1, 12.2_

- [x] 21. 迁移设备列表页面 - pages/device/device-list/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 22. 迁移设备详情页面 (3个)
  - 迁移 pages/device/device-list/detail-camera.vue
  - 迁移 pages/device/device-list/detail-collector.vue
  - 迁移 pages/device/device-list/detail-machine.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 23. 迁移农机设备页面 - pages/device/device-list/agricultural/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 24. 迁移作业相关页面 (2个)
  - 迁移 pages/device/job-create/index.vue
  - 迁移 pages/device/job-detail/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 25. Checkpoint - 设备模块验证
  - 确保所有设备相关页面迁移完成
  - 运行设备模块功能测试
  - 询问用户是否有问题

- [x] 26. 迁移农业知识页面 - pages/knowledge/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 27. 迁移知识详情页面 - pages/knowledge/detail.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子         
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 28. 迁移 AI 聊天页面 - pages/knowledge/ai-chat/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 29. 迁移用户中心页面 - pages/user/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 更新 store 使用方式
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 3.2, 12.1, 12.2_

- [x] 30. 迁移用户信息页面 - pages/userInfo/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 更新 store 使用方式
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 3.2, 12.1, 12.2_

- [x] 31. 迁移其他页面 (10个)
  - 迁移 pages/machine/index.vue
  - 迁移 pages/field/index.vue
  - 迁移 pages/plots/list.vue
  - 迁移 pages/chart/index.vue
  - 迁移 pages/more/index.vue
  - 迁移 pages/settings/index.vue
  - 迁移 pages/about/index.vue
  - 迁移 pages/privacy/index.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 32. 迁移服务页面 (10个)
  - 迁移 pages/service/mall.vue
  - 迁移 pages/service/mall-detail.vue
  - 迁移 pages/service/sales.vue
  - 迁移 pages/service/sales-detail.vue
  - 迁移 pages/service/sales-publish.vue
  - 迁移 pages/service/purchase-publish.vue
  - 迁移 pages/service/my-publish.vue
  - 迁移 pages/service/expert.vue
  - 迁移 pages/service/expert-detail.vue
  - 迁移 pages/service/expert-chat.vue
  - 迁移 pages/service/certification.vue
  - 迁移 pages/service/insurance.vue
  - 将 Options API 转换为 Composition API
  - 使用 `<script setup>` 语法
  - 转换响应式数据和方法
  - 转换生命周期钩子
  - 移除所有 this 引用
  - 保持 template 和 style 不变
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.5, 12.1, 12.2_

- [x] 33. Checkpoint - 所有页面迁移完成
  - 确保所有页面组件迁移完成
  - 运行所有页面测试
  - 询问用户是否有问题

- [x] 34. 添加 HarmonyOS 平台支持
  - 在所有条件编译中添加 HarmonyOS 支持
  - 检查并更新平台特定代码
  - 确保使用 uni-app 跨平台 API
  - _Requirements: 10.3, 10.5, 13.5_

- [x] 34.1 编写 HarmonyOS 兼容性属性测试

  - **Property 10: 浏览器 API 移除**
  - **Validates: Requirements 10.1, 10.2**

- [x] 34.2 编写 HarmonyOS 兼容性属性测试

  - **Property 11: 条件编译正确使用**
  - **Validates: Requirements 10.5, 13.5**

- [x] 35. 代码质量检查和优化
  - 运行 ESLint 检查所有迁移后的代码
  - 修复所有 ESLint 错误和警告
  - 检查所有 TODO 注释,确保有明确说明
  - 优化代码结构和命名
  - _Requirements: 14.1, 14.2, 14.3, 14.5, 17.2_

- [x] 35.1 编写代码质量属性测试

  - **Property 17: TODO 注释添加**
  - **Validates: Requirements 14.2, 17.1, 17.2**

- [x] 36. 编写综合属性测试
  - 编写 Property 1: Options API 完整转换测试
  - 编写 Property 2: 生命周期钩子正确映射测试
  - 编写 Property 4: this 关键字完全移除测试
  - 编写 Property 5: script setup 语法使用测试
  - 编写 Property 12: 模板结构保持不变测试
  - 编写 Property 13: 样式保持不变测试
  - 编写 Property 14: v-model 语法更新测试
  - 编写 Property 15: $listeners 移除测试
  - 编写 Property 16: 自定义指令钩子更新测试
  - 配置每个测试运行 100 次迭代
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 5.1, 5.2, 5.3, 5.4, 12.1, 12.2_

- [x] 37. 跨平台功能测试
  - 在 Android 平台测试核心功能
  - 在 iOS 平台测试核心功能
  - 在 H5 平台测试核心功能
  - 在 HarmonyOS 平台测试核心功能
  - 验证所有平台行为一致
  - _Requirements: 13.1, 13.2, 13.3, 13.4_

- [x] 37.1 编写跨平台功能测试用例

  - 测试用户登录流程
  - 测试数据列表加载
  - 测试表单提交
  - 测试页面跳转
  - 测试地图定位 (如适用)
  - _Requirements: 13.1, 13.2, 13.3, 13.4_

- [ ] 38. 性能测试和优化
  - 测量应用启动时间
  - 测量页面首次渲染时间
  - 测量页面切换时间
  - 对比迁移前后的性能数据
  - 优化性能瓶颈 (如有)
  - _Requirements: 16.1, 16.3, 16.4_

- [ ]* 38.1 编写性能测试用例
  - 测试应用启动性能
  - 测试页面渲染性能
  - 测试列表滚动性能
  - 验证性能不低于原版本
  - _Requirements: 16.1, 16.3, 16.4_

- [ ] 39. 视觉回归测试
  - 对所有主要页面进行截图对比
  - 验证 UI 布局一致性
  - 验证样式渲染一致性
  - 修复视觉差异 (如有)
  - _Requirements: 12.1, 12.2_

- [ ] 40. 最终验证和文档
  - 运行所有单元测试,确保通过
  - 运行所有属性测试,确保通过
  - 运行所有功能测试,确保通过
  - 完成迁移检查清单
  - 编写迁移总结文档
  - 记录已知问题和 TODO 项
  - _Requirements: 14.4, 20.1, 20.2, 20.3_

- [x] 41. 最终 Checkpoint - 迁移完成
  - 确保所有任务完成
  - 确保所有测试通过
  - 询问用户是否准备合并代码

## Notes

- 任务标记 `*` 的为可选测试任务,可根据项目进度和资源情况决定是否执行
- 每个 Checkpoint 任务都是重要的验证点,确保在继续之前所有功能正常
- 属性测试使用 fast-check 库,每个测试至少运行 100 次迭代
- 所有迁移任务都必须保持业务逻辑、UI 结构和样式不变
- 遇到无法自动迁移的代码,必须添加 TODO 注释并说明原因和解决方案
- HarmonyOS 平台支持是本次迁移的核心目标,必须在所有条件编译中包含
- 建议按顺序执行任务,确保每个阶段稳定后再进入下一阶段