# React 到 Vue 完整迁移方案

## 📋 文档说明

本文档提供从 React 技术栈完整迁移到 Vue 3 技术栈的详细方案，包括技术选型、迁移步骤、代码转换示例和测试策略。

---

## 🎯 迁移目标

- **完全移除 React 依赖**
- **使用 Vue 3 Composition API**
- **保持所有现有功能**
- **保持 Tailwind CSS 样式**
- **保持 TypeScript 类型系统**

---

## 🛠️ 技术选型

### 核心框架
- **Vue**: `^3.4.0` (使用 Composition API)
- **TypeScript**: `^5.2.2` (保持不变)
- **Vite**: `^5.0.8` (保持不变，更换插件)

### 状态管理
- **Pinia**: `^2.1.0` (推荐，替代 Context API)

### 路由（可选）
- **Vue Router**: `^4.2.0` (如果需要路由功能)

### UI 库
- **图标库**: `lucide-vue-next`: `^0.344.0`
- **图表库**: `echarts-for-vue`: `^1.2.0` 或 `vue-echarts`: `^6.6.0`

### 样式
- **Tailwind CSS**: `^3.3.6` (保持不变)

---

## 📦 依赖包替换清单

### 需要移除的依赖
```json
{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "lucide-react": "^0.344.0",
  "@vitejs/plugin-react": "^4.2.1",
  "@types/react": "^18.2.43",
  "@types/react-dom": "^18.2.17",
  "eslint-plugin-react-hooks": "^4.6.0",
  "eslint-plugin-react-refresh": "^0.4.5"
}
```

### 需要添加的依赖
```json
{
  "vue": "^3.4.0",
  "@vitejs/plugin-vue": "^5.0.0",
  "vue-tsc": "^1.8.25",
  "lucide-vue-next": "^0.344.0",
  "pinia": "^2.1.0",
  "vue-router": "^4.2.0",
  "@vueuse/core": "^10.7.0"
}
```

### 开发依赖
```json
{
  "@vitejs/plugin-vue": "^5.0.0",
  "@vue/eslint-config-typescript": "^12.0.0",
  "eslint-plugin-vue": "^9.20.0"
}
```

---

## 🗂️ 迁移阶段规划

### 阶段一：项目基础配置（1-2 天）

#### 1.1 更新 package.json
```json
{
  "name": "finyx-frontend",
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx",
    "preview": "vite preview",
    "type-check": "vue-tsc --noEmit"
  },
  "dependencies": {
    "vue": "^3.4.0",
    "pinia": "^2.1.0",
    "vue-router": "^4.2.0",
    "lucide-vue-next": "^0.344.0",
    "@vueuse/core": "^10.7.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "@vue/eslint-config-typescript": "^12.0.0",
    "eslint-plugin-vue": "^9.20.0",
    "typescript": "^5.2.2",
    "vite": "^5.0.8",
    "tailwindcss": "^3.3.6",
    "vue-tsc": "^1.8.25"
  }
}
```

#### 1.2 更新 vite.config.ts
```typescript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  server: {
    host: '0.0.0.0',
    port: 5173,
    strictPort: false,
    open: false,
  },
  preview: {
    host: '0.0.0.0',
    port: 4173,
  },
})
```

#### 1.3 更新 tsconfig.json
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",

    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "references": [{ "path": "./tsconfig.node.json" }]
}
```

#### 1.4 创建 env.d.ts
```typescript
/// <reference types="vite/client" />

declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}
```

### 阶段二：类型定义迁移（1 天）

类型定义文件基本不需要修改，只需确保兼容 Vue。

**src/types/index.ts** - 保持不变

### 阶段三：工具组件迁移（2-3 天）

#### 3.1 ProgressBar 组件

**React 版本** (`src/components/ProgressBar.tsx`):
```typescript
import React from 'react';

interface ProgressBarProps {
  percent: number;
  status: string;
}

export const ProgressBar: React.FC<ProgressBarProps> = ({ percent, status }) => {
  // ...
};
```

**Vue 版本** (`src/components/ProgressBar.vue`):
```vue
<template>
  <div class="w-full bg-slate-200 rounded-full h-2">
    <div 
      :class="colorClass" 
      class="h-2 rounded-full" 
      :style="{ width: `${percent}%` }"
    ></div>
  </div>
</template>

<script setup lang="ts">
interface Props {
  percent: number;
  status: string;
}

const props = defineProps<Props>();

const colorClass = computed(() => {
  const colorMap: Record<string, string> = {
    risk: 'bg-red-500',
    warning: 'bg-amber-500',
    review: 'bg-purple-500',
    new: 'bg-slate-300',
  };
  return colorMap[props.status] || 'bg-blue-500';
});
</script>
```

#### 3.2 Toast 组件迁移

**React 版本** (`src/components/Toast.tsx`):
```typescript
export const useToast = () => {
  const [toasts, setToasts] = React.useState<Toast[]>([]);
  // ...
};
```

**Vue 版本** (`src/components/Toast.vue`):
```vue
<template>
  <div v-if="toasts.length > 0" class="fixed top-4 right-4 z-50 flex flex-col gap-2 pointer-events-none">
    <div 
      v-for="toast in toasts" 
      :key="toast.id" 
      class="pointer-events-auto"
    >
      <ToastItem :toast="toast" @close="closeToast" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import ToastItem from './ToastItem.vue';
import type { Toast, ToastType } from './types';

const toasts = ref<Toast[]>([]);

const showToast = (message: string, type: ToastType = 'info', duration?: number) => {
  const id = Math.random().toString(36).substring(7);
  const newToast: Toast = { id, message, type, duration };
  toasts.value.push(newToast);
  
  setTimeout(() => {
    closeToast(id);
  }, duration || 3000);
  
  return id;
};

const closeToast = (id: string) => {
  const index = toasts.value.findIndex(t => t.id === id);
  if (index > -1) {
    toasts.value.splice(index, 1);
  }
};

defineExpose({
  success: (message: string, duration?: number) => showToast(message, 'success', duration),
  error: (message: string, duration?: number) => showToast(message, 'error', duration),
  warning: (message: string, duration?: number) => showToast(message, 'warning', duration),
  info: (message: string, duration?: number) => showToast(message, 'info', duration),
});
</script>
```

**Toast Context 迁移为 Pinia Store** (`src/stores/toast.ts`):
```typescript
import { defineStore } from 'pinia';
import { ref } from 'vue';
import type { Toast, ToastType } from '@/types';

export const useToastStore = defineStore('toast', () => {
  const toasts = ref<Toast[]>([]);

  const showToast = (message: string, type: ToastType = 'info', duration?: number) => {
    const id = Math.random().toString(36).substring(7);
    const newToast: Toast = { id, message, type, duration };
    toasts.value.push(newToast);
    
    setTimeout(() => {
      closeToast(id);
    }, duration || 3000);
    
    return id;
  };

  const closeToast = (id: string) => {
    const index = toasts.value.findIndex(t => t.id === id);
    if (index > -1) {
      toasts.value.splice(index, 1);
    }
  };

  const success = (message: string, duration?: number) => showToast(message, 'success', duration);
  const error = (message: string, duration?: number) => showToast(message, 'error', duration);
  const warning = (message: string, duration?: number) => showToast(message, 'warning', duration);
  const info = (message: string, duration?: number) => showToast(message, 'info', duration);

  return {
    toasts,
    showToast,
    closeToast,
    success,
    error,
    warning,
    info,
  };
});
```

### 阶段四：布局组件迁移（2-3 天）

#### 4.1 MainLayout 组件

**React 版本**:
```typescript
export const MainLayout: React.FC<MainLayoutProps> = ({
  currentView,
  setCurrentView,
  // ...
}) => (
  <div className="flex h-screen w-full bg-slate-900">
    {/* ... */}
  </div>
);
```

**Vue 版本** (`src/layouts/MainLayout.vue`):
```vue
<template>
  <div class="flex h-screen w-full bg-slate-900 font-sans text-slate-900 overflow-hidden">
    <Sidebar 
      :current-view="currentView" 
      @update:current-view="setCurrentView"
      :is-presentation-mode="isPresentationMode"
    />

    <div class="flex-1 flex flex-col bg-slate-50 relative overflow-hidden">
      <DashboardView 
        v-if="currentView === 'dashboard'"
        @update:current-view="setCurrentView" 
        @update:current-step="setCurrentStep"
      />
      <ProjectListView 
        v-if="currentView === 'projects'"
        @update:current-view="setCurrentView" 
        @update:current-step="setCurrentStep"
      />
      <EngagementView 
        v-if="currentView === 'engagement'"
        :current-step="currentStep"
        @update:current-step="setCurrentStep"
        @update:current-view="setCurrentView"
        :is-presentation-mode="isPresentationMode"
        @update:is-presentation-mode="setIsPresentationMode"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Sidebar } from './Sidebar.vue';
import DashboardView from '@/pages/DashboardView.vue';
import ProjectListView from '@/pages/ProjectListView.vue';
import EngagementView from '@/pages/EngagementView.vue';
import type { ViewMode, Step } from '@/types';

const currentView = ref<ViewMode>('projects');
const currentStep = ref<Step>('setup');
const isPresentationMode = ref(false);

const setCurrentView = (view: ViewMode) => {
  currentView.value = view;
};

const setCurrentStep = (step: Step) => {
  currentStep.value = step;
};

const setIsPresentationMode = (mode: boolean) => {
  isPresentationMode.value = mode;
};
</script>
```

### 阶段五：页面组件迁移（5-7 天）

#### 5.1 SetupStep 组件示例

**React 版本关键代码**:
```typescript
export const SetupStep: React.FC<SetupStepProps> = ({ setCurrentStep }) => {
  const toast = useToast();
  const [projectName, setProjectName] = useState('');
  const [selectedIndustries, setSelectedIndustries] = useState<string[]>([]);
  const [errors, setErrors] = useState({});

  useEffect(() => {
    // 验证逻辑
  }, [projectName, selectedIndustries, touched]);

  return (
    <div className="p-8">
      <input
        value={projectName}
        onChange={(e) => setProjectName(e.target.value)}
      />
    </div>
  );
};
```

**Vue 版本** (`src/pages/engagement/SetupStep.vue`):
```vue
<template>
  <div class="p-8 h-full flex flex-col overflow-y-auto animate-fade-in">
    <div class="text-center mb-8">
      <h2 class="text-3xl font-bold text-slate-900">项目初始化配置</h2>
      <p class="text-slate-500 mt-2">请填写项目基本信息，系统将为您配置数据资产盘点环境</p>
    </div>

    <div class="max-w-4xl mx-auto w-full space-y-6 mb-8">
      <!-- Project Name -->
      <div class="bg-white p-6 rounded-xl border border-slate-200 shadow-sm">
        <label class="block text-sm font-bold text-slate-700 mb-3">
          项目名称 <span class="text-red-500">*</span>
        </label>
        <input
          type="text"
          v-model="projectName"
          @blur="touched.projectName = true"
          :class="[
            'w-full px-4 py-2 border rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-blue-500',
            errors.projectName ? 'border-red-500' : 'border-slate-300'
          ]"
          placeholder="请输入项目名称"
        />
        <p v-if="errors.projectName" class="text-red-500 text-sm mt-1">
          {{ errors.projectName }}
        </p>
      </div>

      <!-- Industries Selection -->
      <div class="bg-white p-6 rounded-xl border border-slate-200 shadow-sm">
        <label class="block text-sm font-bold text-slate-700 mb-3">
          所属行业 <span class="text-red-500">*</span>
        </label>
        <div class="flex flex-wrap gap-2">
          <button
            v-for="industry in industries"
            :key="industry"
            @click="toggleIndustry(industry)"
            :class="[
              'px-4 py-2 rounded-lg border transition-colors',
              selectedIndustries.includes(industry)
                ? 'bg-blue-50 border-blue-500 text-blue-700'
                : 'bg-white border-slate-300 text-slate-700 hover:border-blue-300'
            ]"
          >
            {{ industry }}
          </button>
        </div>
        <p v-if="errors.industries" class="text-red-500 text-sm mt-2">
          {{ errors.industries }}
        </p>
      </div>
    </div>

    <!-- Actions -->
    <div class="max-w-4xl mx-auto w-full flex justify-end gap-4">
      <button
        @click="handleNext"
        :disabled="!isValid"
        class="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed flex items-center gap-2"
      >
        下一步
        <ArrowRight :size="18" />
      </button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed, watch } from 'vue';
import { ArrowRight } from 'lucide-vue-next';
import { useToastStore } from '@/stores/toast';
import type { Step } from '@/types';

interface Props {
  setCurrentStep?: (step: Step) => void;
}

const props = defineProps<Props>();

const toast = useToastStore();

const projectName = ref('');
const companyDescription = ref('');
const owner = ref('');
const selectedIndustries = ref<string[]>([]);
const errors = ref<{
  projectName?: string;
  companyDescription?: string;
  industries?: string;
}>({});
const touched = ref<{
  projectName?: boolean;
  companyDescription?: boolean;
  industries?: boolean;
}>({});

const industries = [
  '零售 - 生鲜连锁',
  '零售 - 快消品',
  '金融 - 商业银行',
  // ... 更多行业
];

// 实时验证
watch([projectName, companyDescription, selectedIndustries, touched], () => {
  const newErrors: typeof errors.value = {};
  
  if (touched.value.projectName && !projectName.value.trim()) {
    newErrors.projectName = '请填写项目名称';
  }
  
  if (touched.value.companyDescription && !companyDescription.value.trim()) {
    newErrors.companyDescription = '请填写企业及主营业务简介';
  }
  
  if (touched.value.industries && selectedIndustries.value.length === 0) {
    newErrors.industries = '请至少选择一个所属行业';
  }
  
  errors.value = newErrors;
}, { deep: true });

const isValid = computed(() => {
  return projectName.value.trim() !== '' &&
         companyDescription.value.trim() !== '' &&
         selectedIndustries.value.length > 0;
});

const toggleIndustry = (industry: string) => {
  const index = selectedIndustries.value.indexOf(industry);
  if (index > -1) {
    selectedIndustries.value.splice(index, 1);
  } else {
    selectedIndustries.value.push(industry);
  }
  touched.value.industries = true;
};

const handleNext = () => {
  if (!isValid.value) {
    toast.error('请完成所有必填项');
    return;
  }
  
  toast.success('项目配置已保存');
  props.setCurrentStep?.('inventory');
};
</script>
```

#### 5.2 InventoryStep 组件迁移要点

**useMemo 转换**:
```typescript
// React
const sortedData = useMemo(() => {
  // 排序逻辑
}, [sortField, sortDirection]);

// Vue
const sortedData = computed(() => {
  if (!sortField.value || !sortDirection.value) return inventoryData;
  // 排序逻辑
});
```

**useEffect 转换**:
```typescript
// React
useEffect(() => {
  if (inventoryMode === 'processing') {
    // 处理逻辑
  }
}, [inventoryMode]);

// Vue
watch(() => props.inventoryMode, (newMode) => {
  if (newMode === 'processing') {
    // 处理逻辑
  }
}, { immediate: true });
```

### 阶段六：主应用入口迁移（1 天）

#### 6.1 main.ts 文件

**React 版本** (`src/main.tsx`):
```typescript
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)
```

**Vue 版本** (`src/main.ts`):
```typescript
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import './index.css'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)
app.mount('#root')
```

#### 6.2 App.vue

**React 版本** (`src/App.tsx`):
```typescript
function App() {
  const [currentView, setCurrentView] = useState<ViewMode>('projects');
  // ...
  return (
    <ToastProvider>
      <MainLayout ... />
    </ToastProvider>
  );
}
```

**Vue 版本** (`src/App.vue`):
```vue
<template>
  <MainLayout
    :current-view="currentView"
    @update:current-view="setCurrentView"
    :current-step="currentStep"
    @update:current-step="setCurrentStep"
    :is-presentation-mode="isPresentationMode"
    @update:is-presentation-mode="setIsPresentationMode"
  />
  <ToastContainer />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MainLayout from '@/layouts/MainLayout.vue';
import ToastContainer from '@/components/ToastContainer.vue';
import type { ViewMode, Step } from '@/types';

const currentView = ref<ViewMode>('projects');
const currentStep = ref<Step>('setup');
const isPresentationMode = ref(false);

const setCurrentView = (view: ViewMode) => {
  currentView.value = view;
};

const setCurrentStep = (step: Step) => {
  currentStep.value = step;
};

const setIsPresentationMode = (mode: boolean) => {
  isPresentationMode.value = mode;
};
</script>
```

### 阶段七：图标库迁移（1 天）

#### 7.1 全局替换图标导入

**查找替换规则**:
```typescript
// 从
import { IconName } from 'lucide-react';
<IconName size={20} />

// 到
import { IconName } from 'lucide-vue-next';
<IconName :size="20" />
```

**批量替换脚本** (`scripts/replace-icons.sh`):
```bash
#!/bin/bash
# 替换所有文件中的 lucide-react 导入
find src -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.tsx" \) -exec sed -i 's/lucide-react/lucide-vue-next/g' {} \;

# 替换图标属性 size={} 为 :size=""
find src -type f -name "*.vue" -exec sed -i 's/size={\([^}]*\)}/:size="\1"/g' {} \;
```

### 阶段八：测试与验证（3-5 天）

#### 8.1 功能测试清单

- [ ] Dashboard 页面渲染正常
- [ ] 项目列表显示正常
- [ ] 项目搜索和筛选功能
- [ ] 项目作业台所有步骤正常
- [ ] 步骤导航功能
- [ ] 表单验证功能
- [ ] Toast 通知功能
- [ ] 演示模式切换
- [ ] 响应式布局
- [ ] 所有交互功能

#### 8.2 性能测试

- [ ] 首屏加载时间
- [ ] 组件渲染性能
- [ ] 大数据量表格性能
- [ ] 内存使用情况

---

## 📝 代码转换对照表

### Hooks 转换对照

| React | Vue 3 |
|-------|-------|
| `useState(value)` | `ref(value)` 或 `reactive({})` |
| `useEffect(() => {}, [deps])` | `watch(() => deps, () => {})` 或 `watchEffect(() => {})` |
| `useMemo(() => value, [deps])` | `computed(() => value)` |
| `useCallback(() => {}, [deps])` | `computed(() => () => {})` 或直接定义函数 |
| `useContext(Context)` | `inject(key)` 或 Pinia store |
| `useRef(initial)` | `ref(initial)` |
| `useReducer(reducer, initial)` | `ref(initial)` + 自定义函数或 Pinia |

### 事件处理转换

| React | Vue 3 |
|-------|-------|
| `onClick={handler}` | `@click="handler"` |
| `onChange={(e) => {}}` | `@change="handler"` 或 `v-model="value"` |
| `onSubmit={handler}` | `@submit.prevent="handler"` |
| `onKeyDown={handler}` | `@keydown="handler"` |

### 条件渲染转换

| React | Vue 3 |
|-------|-------|
| `{condition && <Component />}` | `<Component v-if="condition" />` |
| `{condition ? <A /> : <B />}` | `<A v-if="condition" /><B v-else />` |
| `{items.map(item => <Item key={id} />)}` | `<Item v-for="item in items" :key="id" />` |

### Props 传递转换

| React | Vue 3 |
|-------|-------|
| `<Component prop={value} />` | `<Component :prop="value" />` |
| `<Component onClick={handler} />` | `<Component @click="handler" />` |
| `{...props}` | `v-bind="props"` |

---

## 🔧 配置文件更新清单

### 1. package.json
- [ ] 移除所有 React 相关依赖
- [ ] 添加 Vue 3 相关依赖
- [ ] 更新构建脚本
- [ ] 更新 lint 脚本

### 2. vite.config.ts
- [ ] 替换 `@vitejs/plugin-react` 为 `@vitejs/plugin-vue`
- [ ] 添加路径别名配置
- [ ] 保持服务器配置

### 3. tsconfig.json
- [ ] 更新 `jsx` 选项为 `"preserve"`
- [ ] 添加 Vue 文件类型支持
- [ ] 添加路径别名

### 4. 创建 env.d.ts
- [ ] 添加 Vue 模块声明
- [ ] 添加 Vite 客户端类型

### 5. ESLint 配置
创建 `.eslintrc.cjs`:
```javascript
module.exports = {
  root: true,
  env: {
    node: true,
    browser: true,
    es2021: true,
  },
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/eslint-config-typescript',
  ],
  parserOptions: {
    ecmaVersion: 2021,
  },
  rules: {
    // 自定义规则
  },
};
```

---

## 🚀 迁移执行步骤

### 第一步：备份当前代码
```bash
git checkout -b vue-migration
git commit -am "Backup before Vue migration"
```

### 第二步：安装新依赖
```bash
npm uninstall react react-dom lucide-react @vitejs/plugin-react @types/react @types/react-dom
npm install vue@^3.4.0 pinia@^2.1.0 vue-router@^4.2.0 lucide-vue-next@^0.344.0 @vueuse/core@^10.7.0
npm install -D @vitejs/plugin-vue@^5.0.0 vue-tsc@^1.8.25 @vue/eslint-config-typescript@^12.0.0 eslint-plugin-vue@^9.20.0
```

### 第三步：更新配置文件
按照上述配置文件更新清单逐一更新。

### 第四步：迁移组件（按阶段执行）
1. 先迁移简单组件（ProgressBar、SidebarItem）
2. 迁移工具组件（Toast）
3. 迁移布局组件（Sidebar、MainLayout）
4. 迁移页面组件（按复杂度从低到高）

### 第五步：测试验证
- 运行 `npm run dev` 检查编译错误
- 运行 `npm run type-check` 检查类型错误
- 手动测试所有功能

### 第六步：清理
- 删除所有 `.tsx` 文件
- 删除 React 相关配置
- 更新文档

---

## ⚠️ 常见问题与解决方案

### 问题 1: 图标组件不显示
**解决方案**: 确保使用 `lucide-vue-next` 并正确导入：
```typescript
import { IconName } from 'lucide-vue-next';
// 使用 :size 而不是 size
<IconName :size="20" />
```

### 问题 2: TypeScript 类型错误
**解决方案**: 
- 确保 `env.d.ts` 文件存在
- 检查 `tsconfig.json` 配置
- 使用 `vue-tsc` 进行类型检查

### 问题 3: 响应式数据不更新
**解决方案**: 
- 使用 `ref()` 包装基本类型
- 使用 `reactive()` 包装对象
- 访问 ref 值时使用 `.value`

### 问题 4: 事件处理不工作
**解决方案**: 
- 使用 `@click` 而不是 `onClick`
- 使用 `@submit.prevent` 阻止默认行为
- 事件参数通过 `$event` 访问

---

## 📊 迁移进度跟踪

### 组件迁移清单

#### 基础组件
- [ ] ProgressBar.vue
- [ ] SidebarItem.vue
- [ ] TableCheckItem.vue
- [ ] Toast.vue
- [ ] ToastContainer.vue

#### 布局组件
- [ ] Sidebar.vue
- [ ] MainLayout.vue

#### 页面组件
- [ ] DashboardView.vue
- [ ] ProjectListView.vue
- [ ] EngagementView.vue

#### 工作流步骤组件
- [ ] SetupStep.vue
- [ ] InventoryStep.vue
- [ ] ContextStep.vue
- [ ] ValueStep.vue
- [ ] DeliveryStep.vue

#### 状态管理
- [ ] stores/toast.ts (Pinia)
- [ ] stores/app.ts (可选，全局状态)

#### 配置文件
- [ ] package.json
- [ ] vite.config.ts
- [ ] tsconfig.json
- [ ] env.d.ts
- [ ] .eslintrc.cjs
- [ ] main.ts
- [ ] App.vue

---

## 🎯 验收标准

### 功能完整性
- ✅ 所有原有功能正常工作
- ✅ 所有交互行为保持一致
- ✅ 所有样式保持一致

### 代码质量
- ✅ 无 TypeScript 类型错误
- ✅ 无 ESLint 错误
- ✅ 代码符合 Vue 3 最佳实践

### 性能指标
- ✅ 首屏加载时间 ≤ 2s
- ✅ 页面切换流畅
- ✅ 无内存泄漏

---

## 📚 参考资源

- [Vue 3 官方文档](https://vuejs.org/)
- [Vue 3 Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)
- [Pinia 文档](https://pinia.vuejs.org/)
- [Vue Router 文档](https://router.vuejs.org/)
- [Vite 文档](https://vitejs.dev/)

---

## 📅 时间估算

| 阶段 | 工作量 | 说明 |
|------|--------|------|
| 阶段一：项目配置 | 1-2 天 | 配置文件更新 |
| 阶段二：类型定义 | 1 天 | 类型文件检查 |
| 阶段三：工具组件 | 2-3 天 | 简单组件迁移 |
| 阶段四：布局组件 | 2-3 天 | 布局组件迁移 |
| 阶段五：页面组件 | 5-7 天 | 复杂页面迁移 |
| 阶段六：应用入口 | 1 天 | 主文件迁移 |
| 阶段七：图标库 | 1 天 | 图标替换 |
| 阶段八：测试验证 | 3-5 天 | 功能测试和修复 |
| **总计** | **16-25 天** | **约 3-5 周** |

---

## 📝 更新记录

- **2025-01-XX**: 初始迁移方案创建

---

## 👥 贡献者

- Finyx AI Team