hfb_sys/docs/FEATURES_ARCHITECTURE_PLAN.md

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: 创建目标目录结构

mkdir -p features/{module}/api
mkdir -p features/{module}/components
mkdir -p features/{module}/composables
mkdir -p features/{module}/views

Step 2: 移动文件

# 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: 更新导入路径

// 旧路径
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

// features/orders/index.ts
export * from './api/orders'
export * from './composables/useOrderDetail'
export * from './composables/useOrderSnapshot'
export type * from './types'

Step 5: 更新路由配置

// router/orderRoutes.ts
import OrdersView from '@/features/orders/views/OrdersView.vue'
import OrderDetailView from '@/features/orders/views/OrderDetailView.vue'

Step 6: 建立兼容层（可选）

在旧路径保留 re-export，逐步迁移其他模块的导入：

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