hfb_sys/docs/FEATURES_MIGRATION_PROGRESS.md

Features 架构迁移进度报告 - 更新

日期： 2026-06-04
分支： refactor/features-architecture
状态： P1 阶段完成 ✅

---

✅ 已完成的工作（P0 + P1）

P0: 基础设施准备 ✅

创建了新的目录结构并迁移共享资源（22个文件）

P1.1: 钱包模块（wallet） ✅

完整迁移钱包模块到 features/wallet/（5个文件）

P1.2: 聊天模块（chats） ✅

完整迁移聊天模块到 features/chats/（8个文件）

P1.3: 订单模块（orders） ✅ 新增

完整迁移并重构订单模块到 features/orders/（11个文件）

features/orders/
├── api/
│   └── orders.ts                    # 订单 API（已更新导入路径）
├── composables/
│   ├── useOrderDetail.ts            # 核心订单逻辑（重构后）
│   ├── useOrderSnapshot.ts          # 订单快照
│   ├── usePaymentPolling.ts         # ✨ 新：支付轮询逻辑
│   └── useSettlement.ts             # ✨ 新：结算流程逻辑
├── views/
│   ├── OrdersView.vue               # 订单列表
│   ├── OrderDetailView.vue          # 订单详情
│   ├── OrderCreateView.vue          # 创建订单
│   ├── MobileOrdersView.vue         # 移动端订单列表
│   └── MobileOrderDetailView.vue    # 移动端订单详情
├── types.ts                         # 类型定义
└── index.ts                         # 模块统一导出

---

🎯 核心重构成果

1. useOrderDetail.ts 拆分重构

原始问题： 405行代码混合了订单、支付、结算、争议等多个领域

重构方案： 按职责拆分为3个独立 composables

① usePaymentPolling.ts（支付轮询）

职责： 轮询查询支付状态，直到支付完成

export function usePaymentPolling() {
  // 支付轮询逻辑
  // - 开始/停止轮询
  // - 检查支付状态
  // - 自动重新加载订单
}

② useSettlement.ts（结算流程）

职责： 处理订单结算的完整流程

export function useSettlement(order) {
  // 结算流程逻辑
  // - 提交结算单
  // - 接受/反驳结算
  // - 确认最终结算
  // - 结算表单管理
}

③ useOrderDetail.ts（核心订单）

职责： 订单的核心流程，组合使用上面两个 composables

export function useOrderDetail() {
  const paymentPolling = usePaymentPolling()
  const settlement = useSettlement(order)
  
  return {
    // 订单核心逻辑
    // + 支付轮询能力
    // + 结算流程能力
  }
}

重构优势：

• ✅ 职责清晰：每个 composable 专注单一领域
• ✅ 可复用：支付轮询和结算逻辑可独立使用
• ✅ 易测试：独立 composables 更容易编写单元测试
• ✅ 易维护：从 405 行拆分为 3 个文件，每个 ~150 行

---

📊 迁移统计

阶段	模块	状态	文件数	重构点
P0	shared	✅	22	建立共享层
P1	wallet	✅	5	新增 useWallet
P1	chats	✅	8	-
P1	orders	✅	11	拆分 useOrderDetail
总计	4个模块	✅	46	3个新 composables

---

🏗️ 已建立的架构

frontend/src/
├── features/                    ← 业务功能模块
│   ├── wallet/                  ✅ P1
│   ├── chats/                   ✅ P1
│   ├── orders/                  ✅ P1 (已重构)
│   ├── listings/                ⏳ P2
│   ├── auth/                    ⏳ P2
│   ├── seller/                  ⏸️ P3
│   ├── disputes/                ⏸️ P3
│   └── admin/                   ⏸️ P3
└── shared/                      ← 跨模块共享层 ✅
    ├── api/
    ├── composables/
    ├── components/
    ├── utils/
    ├── types/
    └── styles/

---

🔧 技术改进

1. 导入路径规范化

   • ✅ 所有 features 内部使用相对路径
   • ✅ 跨模块引用使用 @/shared/ 或 @/features/
   • ✅ 避免循环依赖

2. 模块化导出体系

   • ✅ 每个 feature 有 index.ts 统一导出
   • ✅ API、composables、types 分层导出

3. 代码质量提升

   • ✅ 拆分臃肿的 composables（405行 → 3个文件）
   • ✅ 单一职责原则
   • ✅ 提高可测试性

---

📝 文档

1. 迁移计划 (docs/FEATURES_ARCHITECTURE_PLAN.md)

   • 完整的9阶段迁移路线图
   • 详细的单模块迁移步骤

2. 进度报告 (本文档)

   • 实时进度跟踪
   • 重构成果记录

---

⏭️ 下一步：P2 阶段

P2.1: 商品浏览模块（listings） - 待开始

预计文件： ~12个

• API: listings.ts, listingOptions.ts, homeConfig.ts
• Views: 5个页面（桌面+移动）
• Composables: home/ 目录下的3个文件
• Components: ListingCard, 多个过滤器组件

P2.2: 用户认证模块（auth） - 待开始

预计文件： ~10个

• API: auth.ts, realname.ts, notifications.ts
• Views: 登录、注册、个人资料等
• Composables: useSmsCountdown 等

---

⚠️ 已知问题（待 P2 时修复）

类型错误

src/composables/order/useOrderDetail.ts - evidence 属性类型不匹配
src/composables/order/useOrderSnapshot.ts - listing_snapshot 属性缺失

原因： 旧的 composables 目录中的文件尚未更新 解决： P2 阶段更新路由和导入后统一清理

测试依赖

src/composables/home/__tests__/*.spec.ts - 缺少 vitest

解决： 安装 vitest 或移动测试文件到对应 feature

---

🎉 里程碑成就

✅ P1 阶段完成！

• 核心业务模块（订单、钱包、聊天）已完成迁移
• 完成了最复杂的重构（useOrderDetail 拆分）
• 建立了可复用的架构模式
• 为 P2/P3 阶段奠定基础

总代码变更： 预计 60+ 文件，10000+ 行代码

---

📅 预计剩余工作量

阶段	模块	预计时间	复杂度
P2	listings	3小时	中
P2	auth	3小时	中
P3	seller	2小时	低
P3	disputes	1小时	低
P3	admin	4小时	高
清理	删除旧文件、更新路由	2小时	-
总计	-	15小时	-

---

当前提交： 准备提交 P1 完整成果
下次继续： P2.1 商品浏览模块（listings）

---

验证清单

• P0 基础设施完成
• P1.1 钱包模块完成
• P1.2 聊天模块完成
• P1.3 订单模块完成并重构
• 运行类型检查（待 P2 清理旧文件后）
• 启动开发服务器验证
• 更新路由配置
• 端到端功能测试