yml2213andClaude Opus 4.7
b5903a169f
## 完成的工作 ### P0: 基础设施准备 - 创建 features/ 和 shared/ 目录结构 - 迁移共享资源：API基础设施、工具函数、类型定义 - 迁移通用composables：useMoney, useSmsCountdown, usePricingCalculator - 迁移全局样式文件 - 建立模块化导出系统 ### P1.1: 钱包模块 (wallet) - 迁移 API: wallet.ts - 迁移 Views: WalletView.vue - 新增 Composable: useWallet.ts (封装钱包状态管理) - 更新导入路径到 shared/ ### P1.2: 聊天模块 (chats) - 迁移 API: chats.ts - 迁移 Views: ChatView, MessagesView (桌面+移动) - 迁移 Composables: useChatSSE.ts - 迁移 Components: ChatAttachmentImage.vue - 更新导入路径到 shared/ ## 技术改进 - 修复 shared/composables 导出问题 (default → 命名导出) - 修复 shared/api/client.ts 类型导入路径 - 建立清晰的模块边界和导出规范 ## 文档 - 添加完整的迁移计划文档 - 添加进度跟踪文档 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
383 lines
13 KiB
Markdown
383 lines
13 KiB
Markdown
# Features 架构迁移计划
|
||
|
||
## 目标架构设计
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
frontend/src/
|
||
├── features/ # 业务功能模块（按业务领域组织）
|
||
│ ├── auth/ # 认证与账户
|
||
│ │ ├── api/ # API 调用
|
||
│ │ ├── components/ # 该模块专属组件
|
||
│ │ ├── composables/ # 业务逻辑
|
||
│ │ ├── views/ # 页面视图
|
||
│ │ ├── types.ts # 类型定义
|
||
│ │ └── index.ts # 模块导出
|
||
│ ├── listings/ # 商品浏览与搜索
|
||
│ ├── orders/ # 订单管理
|
||
│ ├── chats/ # 聊天消息
|
||
│ ├── wallet/ # 钱包支付
|
||
│ ├── disputes/ # 争议仲裁
|
||
│ ├── seller/ # 卖家中心
|
||
│ └── admin/ # 管理后台
|
||
├── shared/ # 跨模块共享资源
|
||
│ ├── components/ # 通用UI组件
|
||
│ │ ├── ui/ # 基础组件 (Button, Input...)
|
||
│ │ ├── business/ # 业务组件 (ListingCard, OrderStatus...)
|
||
│ │ └── layout/ # 布局组件
|
||
│ ├── composables/ # 通用工具函数
|
||
│ │ ├── useDebounce.ts
|
||
│ │ ├── useLazyLoad.ts
|
||
│ │ └── useMoney.ts
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── types/ # 全局类型定义
|
||
│ ├── styles/ # 全局样式
|
||
│ └── api/ # API 基础设施
|
||
│ ├── client.ts # axios 实例
|
||
│ └── types.ts # 通用 API 类型
|
||
├── stores/ # 全局状态管理（仅全局状态）
|
||
├── router/ # 路由配置
|
||
├── layouts/ # 布局模板
|
||
├── App.vue
|
||
└── main.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 渐进式迁移策略
|
||
|
||
### 阶段 1：基础设施准备（P0）
|
||
**目标：** 创建新的目录结构，建立共享层
|
||
|
||
**任务：**
|
||
1. 创建 `features/` 和 `shared/` 目录
|
||
2. 迁移共享资源到 `shared/`：
|
||
- `shared/api/` ← `api/client.ts`, `api/types.ts`
|
||
- `shared/utils/` ← `utils/`
|
||
- `shared/types/` ← `types/`
|
||
- `shared/composables/` ← 通用 composables
|
||
3. 保持原有路径的 re-export 兼容层
|
||
|
||
---
|
||
|
||
### 阶段 2：第一批核心模块迁移（P1）
|
||
**优先级排序依据：** 边界清晰 + 高复用 + 当前开发热点
|
||
|
||
#### 2.1 订单模块（orders）- 最高优先级
|
||
**理由：** 当前开发重点，边界清晰，依赖关系多
|
||
|
||
**迁移内容：**
|
||
```
|
||
features/orders/
|
||
├── api/
|
||
│ └── orders.ts ← api/orders.ts
|
||
├── components/
|
||
│ ├── OrderCard.vue ← views/account/components/
|
||
│ ├── OrderStatusBadge.vue
|
||
│ └── PaymentQRCode.vue
|
||
├── composables/
|
||
│ ├── useOrderDetail.ts ← composables/order/useOrderDetail.ts（需拆分）
|
||
│ ├── useOrderSnapshot.ts ← composables/order/useOrderSnapshot.ts
|
||
│ ├── usePaymentPolling.ts # 新：从 useOrderDetail 拆分
|
||
│ └── useSettlement.ts # 新：从 useOrderDetail 拆分
|
||
├── views/
|
||
│ ├── OrdersView.vue ← views/account/OrdersView.vue
|
||
│ ├── OrderDetailView.vue ← views/account/OrderDetailView.vue
|
||
│ ├── OrderCreateView.vue ← views/account/OrderCreateView.vue
|
||
│ ├── MobileOrdersView.vue ← views/mobile/MobileOrdersView.vue
|
||
│ └── MobileOrderDetailView.vue
|
||
├── types.ts
|
||
└── index.ts
|
||
```
|
||
|
||
**重构点：**
|
||
- 拆分 `useOrderDetail.ts`（目前混合了订单、支付、结算、争议逻辑）
|
||
- 提取支付轮询逻辑到独立 composable
|
||
- 提取结算逻辑到独立 composable
|
||
|
||
---
|
||
|
||
#### 2.2 钱包模块（wallet）
|
||
**理由：** 边界清晰，被订单依赖
|
||
|
||
**迁移内容：**
|
||
```
|
||
features/wallet/
|
||
├── api/
|
||
│ └── wallet.ts ← api/wallet.ts
|
||
├── composables/
|
||
│ ├── useWallet.ts # 新：封装钱包状态
|
||
│ ├── useMoney.ts ← composables/useMoney.ts
|
||
│ └── usePricingCalculator.ts ← composables/usePricingCalculator.ts
|
||
├── views/
|
||
│ └── WalletView.vue ← views/account/WalletView.vue
|
||
├── types.ts
|
||
└── index.ts
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.3 聊天模块（chats）
|
||
**理由：** 边界清晰，独立性强
|
||
|
||
**迁移内容：**
|
||
```
|
||
features/chats/
|
||
├── api/
|
||
│ └── chats.ts ← api/chats.ts
|
||
├── components/
|
||
│ ├── ChatBubble.vue ← views/account/components/
|
||
│ ├── MessageInput.vue
|
||
│ └── ChatAttachmentImage.vue ← components/ChatAttachmentImage.vue
|
||
├── composables/
|
||
│ └── useChatSSE.ts ← composables/useChatSSE.ts
|
||
├── views/
|
||
│ ├── ChatView.vue ← views/account/ChatView.vue
|
||
│ ├── MessagesView.vue ← views/account/MessagesView.vue
|
||
│ ├── MobileChatView.vue ← views/mobile/MobileChatView.vue
|
||
│ └── MobileMessagesView.vue
|
||
├── types.ts
|
||
└── index.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 阶段 3：第二批模块迁移（P2）
|
||
|
||
#### 3.1 商品浏览模块（listings）
|
||
```
|
||
features/listings/
|
||
├── api/
|
||
│ ├── listings.ts ← api/listings.ts
|
||
│ ├── listingOptions.ts ← api/listingOptions.ts
|
||
│ └── homeConfig.ts ← api/homeConfig.ts
|
||
├── components/
|
||
│ ├── ListingCard.vue ← views/public/components/
|
||
│ ├── HomeFilters.vue
|
||
│ ├── RangeFilter.vue
|
||
│ └── SkinFilter.vue
|
||
├── composables/
|
||
│ ├── useHomeFilters.ts ← composables/home/useHomeFilters.ts
|
||
│ ├── useFilterOptions.ts ← composables/home/useFilterOptions.ts
|
||
│ └── useListingQuery.ts ← composables/home/useListingQuery.ts
|
||
├── views/
|
||
│ ├── HomeView.vue ← views/public/HomeView.vue
|
||
│ ├── ListingsView.vue ← views/public/ListingsView.vue
|
||
│ ├── ListingDetailView.vue ← views/public/ListingDetailView.vue
|
||
│ ├── MobileHomeView.vue ← views/mobile/MobileHomeView.vue
|
||
│ └── MobileListingDetailView.vue
|
||
├── types.ts
|
||
└── index.ts
|
||
```
|
||
|
||
#### 3.2 用户认证模块（auth）
|
||
```
|
||
features/auth/
|
||
├── api/
|
||
│ ├── auth.ts ← api/auth.ts
|
||
│ ├── realname.ts ← api/realname.ts
|
||
│ └── notifications.ts ← api/notifications.ts
|
||
├── composables/
|
||
│ ├── useSmsCountdown.ts ← composables/useSmsCountdown.ts
|
||
│ └── useAuth.ts # 新：封装认证逻辑
|
||
├── views/
|
||
│ ├── LoginView.vue ← views/public/LoginView.vue
|
||
│ ├── ProfileView.vue ← views/account/ProfileView.vue
|
||
│ ├── RealnameView.vue ← views/account/RealnameView.vue
|
||
│ ├── NotificationsView.vue ← views/account/NotificationsView.vue
|
||
│ └── Mobile*.vue
|
||
├── types.ts
|
||
└── index.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 阶段 4：剩余模块迁移（P3）
|
||
|
||
#### 4.1 卖家中心（seller）
|
||
```
|
||
features/seller/
|
||
├── api/ # 复用 listings.ts
|
||
├── composables/
|
||
│ ├── usePublishForm.ts ← composables/usePublishForm.ts
|
||
│ └── usePublishDraft.ts ← composables/usePublishDraft.ts
|
||
├── views/
|
||
│ ├── SellerListingsView.vue
|
||
│ ├── SellerListingCreateView.vue
|
||
│ ├── SellerHandoffsView.vue
|
||
│ └── SellerEarningsView.vue
|
||
└── index.ts
|
||
```
|
||
|
||
#### 4.2 争议模块（disputes）
|
||
```
|
||
features/disputes/
|
||
├── api/
|
||
│ └── disputes.ts ← api/disputes.ts
|
||
├── components/
|
||
│ └── DisputeDialog.vue # 从 OrderDetail 拆分
|
||
├── composables/
|
||
│ └── useDispute.ts # 从 useOrderDetail 拆分
|
||
└── index.ts
|
||
```
|
||
|
||
#### 4.3 管理后台（admin）
|
||
```
|
||
features/admin/
|
||
├── api/
|
||
│ ├── adminAuth.ts
|
||
│ ├── adminDashboard.ts
|
||
│ ├── adminUsers.ts
|
||
│ └── ...（其他admin API）
|
||
├── components/
|
||
│ └── （管理端组件）
|
||
├── composables/
|
||
│ ├── useAdminTable.ts ← composables/useAdminTable.ts
|
||
│ └── useAdminPaginatedTable.ts
|
||
├── views/
|
||
│ └── Admin*.vue ← views/admin/
|
||
└── index.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 迁移实施步骤（单个模块）
|
||
|
||
### Step 1: 创建目标目录结构
|
||
```bash
|
||
mkdir -p features/{module}/api
|
||
mkdir -p features/{module}/components
|
||
mkdir -p features/{module}/composables
|
||
mkdir -p features/{module}/views
|
||
```
|
||
|
||
### Step 2: 移动文件
|
||
```bash
|
||
# API
|
||
mv src/api/{module}.ts features/{module}/api/
|
||
|
||
# Views
|
||
mv src/views/account/{Module}*.vue features/{module}/views/
|
||
mv src/views/mobile/Mobile{Module}*.vue features/{module}/views/
|
||
|
||
# Composables
|
||
mv src/composables/{module}/ features/{module}/composables/
|
||
```
|
||
|
||
### Step 3: 更新导入路径
|
||
```typescript
|
||
// 旧路径
|
||
import { getOrders } from '@/api/orders'
|
||
import { useOrderDetail } from '@/composables/order/useOrderDetail'
|
||
|
||
// 新路径
|
||
import { getOrders } from '@/features/orders/api/orders'
|
||
import { useOrderDetail } from '@/features/orders/composables/useOrderDetail'
|
||
|
||
// 或通过模块入口
|
||
import { getOrders, useOrderDetail } from '@/features/orders'
|
||
```
|
||
|
||
### Step 4: 创建模块 index.ts
|
||
```typescript
|
||
// features/orders/index.ts
|
||
export * from './api/orders'
|
||
export * from './composables/useOrderDetail'
|
||
export * from './composables/useOrderSnapshot'
|
||
export type * from './types'
|
||
```
|
||
|
||
### Step 5: 更新路由配置
|
||
```typescript
|
||
// router/orderRoutes.ts
|
||
import OrdersView from '@/features/orders/views/OrdersView.vue'
|
||
import OrderDetailView from '@/features/orders/views/OrderDetailView.vue'
|
||
```
|
||
|
||
### Step 6: 建立兼容层（可选）
|
||
在旧路径保留 re-export，逐步迁移其他模块的导入：
|
||
```typescript
|
||
// api/orders.ts（旧路径）
|
||
export * from '@/features/orders/api/orders'
|
||
```
|
||
|
||
### Step 7: 验证与测试
|
||
- 运行 `npm run typecheck` 检查类型错误
|
||
- 运行 `npm run dev` 验证运行时无误
|
||
- 手动测试迁移模块的功能
|
||
|
||
---
|
||
|
||
## 迁移优先级总结
|
||
|
||
| 阶段 | 模块 | 优先级 | 预计工作量 | 依赖关系 |
|
||
|------|------|--------|-----------|---------|
|
||
| P0 | 基础设施 | 最高 | 2小时 | 无 |
|
||
| P1 | orders | 最高 | 4小时 | 依赖 wallet, chats |
|
||
| P1 | wallet | 高 | 2小时 | 无 |
|
||
| P1 | chats | 高 | 2小时 | 无 |
|
||
| P2 | listings | 中 | 3小时 | 无 |
|
||
| P2 | auth | 中 | 3小时 | 无 |
|
||
| P3 | seller | 低 | 2小时 | 依赖 listings |
|
||
| P3 | disputes | 低 | 1小时 | 依赖 orders |
|
||
| P3 | admin | 低 | 4小时 | 依赖所有模块 |
|
||
|
||
**总计：** ~23小时工作量
|
||
|
||
---
|
||
|
||
## 迁移检查清单
|
||
|
||
### 每个模块完成后需要验证：
|
||
- [ ] 类型检查通过 (`npm run typecheck`)
|
||
- [ ] 开发服务器启动正常 (`npm run dev`)
|
||
- [ ] 路由访问正常
|
||
- [ ] API 调用正常
|
||
- [ ] 页面功能正常
|
||
- [ ] 移动端兼容性正常
|
||
- [ ] 无 console 错误
|
||
|
||
### 全部迁移完成后：
|
||
- [ ] 删除旧的 `api/`、`views/`、部分 `composables/` 目录
|
||
- [ ] 删除兼容层 re-export
|
||
- [ ] 更新 `tsconfig.json` 路径别名（如需要）
|
||
- [ ] 更新团队文档
|
||
|
||
---
|
||
|
||
## 风险与注意事项
|
||
|
||
### 高风险点：
|
||
1. **循环依赖问题：** features 间互相导入可能导致循环依赖
|
||
- **解决方案：** 将共享类型提取到 `shared/types/`，严格控制跨 feature 导入
|
||
|
||
2. **导入路径大量变更：** 可能引入遗漏的导入错误
|
||
- **解决方案：** 每迁移一个模块立即运行 typecheck，使用 VS Code 的"查找所有引用"
|
||
|
||
3. **移动端与桌面端组件复用：** 同一 feature 内可能有多个平台的 view
|
||
- **解决方案：** 在 `views/` 下按平台分组或使用文件命名区分
|
||
|
||
### 中风险点：
|
||
1. **路由配置分散：** 当前路由已按模块分离，需同步更新
|
||
2. **Stores 依赖：** session/adminSession 是全局状态，保留在 `stores/`
|
||
3. **composables 拆分：** `useOrderDetail.ts` 需要拆分，可能影响现有功能
|
||
|
||
---
|
||
|
||
## 后续优化建议
|
||
|
||
迁移完成后可以进一步优化：
|
||
|
||
1. **模块懒加载优化：** 利用 Vite 的动态导入，按 feature 分包
|
||
2. **类型安全增强：** 为每个 feature 定义严格的类型边界
|
||
3. **测试覆盖：** 为每个 feature 添加单元测试和集成测试
|
||
4. **文档完善：** 为每个 feature 添加 README.md 说明职责和使用方法
|
||
5. **性能监控：** 利用 `composables/performance/` 对每个 feature 进行性能监控
|
||
|
||
---
|
||
|
||
**创建时间：** 2026-06-04
|
||
**负责人：** yml
|
||
**状态：** 待执行
|