# 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  
**状态：** 待执行