yml/hfb_sys
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Features架构迁移 - P0和P1部分完成

Browse Source 
## 完成的工作

### 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>
This commit is contained in:
yml2213
2026-06-04 08:38:36 +08:00
co-authored by Claude Opus 4.7
parent 10acca637e
commit b5903a169f
42 changed files with 7957 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/FEATURES_ARCHITECTURE_PLAN.md
+382
View File
@@ -0,0 +1,382 @@
# 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
**状态：** 待执行
docs/FEATURES_MIGRATION_PROGRESS.md
+194
View File
@@ -0,0 +1,194 @@
# Features 架构迁移进度报告
**日期：** 2026-06-04
**分支：** refactor/features-architecture
**状态：** 进行中
---
## 已完成的工作
### ✅ P0: 基础设施准备
创建了新的目录结构并迁移共享资源：
```
frontend/src/
├── features/ # 新：业务模块目录
├── shared/ # 新：共享资源层
│ ├── api/ # API 基础设施 (client.ts)
│ ├── composables/ # 通用组合函数 (useMoney, useSmsCountdown, usePricingCalculator)
│ ├── components/ # 共享组件
│ ├── utils/ # 工具函数 (8个文件)
│ ├── types/ # 全局类型定义
│ └── styles/ # 全局样式 (5个CSS文件)
```
**文件统计：**
- shared/ 目录：22个文件
- 已建立模块化导出系统 (index.ts)
---
### ✅ P1.1: 钱包模块（wallet）
完整迁移钱包模块到 `features/wallet/`：
```
features/wallet/
├── api/
│ └── wallet.ts # 钱包 API (5个函数)
├── composables/
│ └── useWallet.ts # 新：钱包状态管理 composable
├── views/
│ └── WalletView.vue # 用户钱包页面
├── types.ts # 模块类型定义
└── index.ts # 模块统一导出
```
**功能：**
- 余额查询、充值、账单明细
- 支付订单、结算金额
- 管理员资金账本
**已修复：**
- ✅ 更新导入路径到 `@/shared/`
- ✅ 类型依赖正确引用
---
### ✅ P1.2: 聊天模块（chats）
完整迁移聊天模块到 `features/chats/`：
```
features/chats/
├── api/
│ └── chats.ts # 聊天 API
├── components/
│ └── ChatAttachmentImage.vue # 聊天附件组件
├── composables/
│ └── useChatSSE.ts # SSE 实时连接
├── views/
│ ├── ChatView.vue # 桌面端聊天页
│ ├── MessagesView.vue # 消息列表
│ ├── MobileChatView.vue # 移动端聊天
│ └── MobileMessagesView.vue # 移动端消息列表
└── index.ts # 模块统一导出
```
**功能：**
- 买卖双方沟通
- 端到端聊天、附件支持
- 实时消息推送（SSE）
- 管理员聊天转接、快速回复
**已修复：**
- ✅ 更新导入路径到 `@/shared/`
---
## 当前存在的类型错误
运行 `npm run typecheck` 发现以下问题（需要在后续修复）：
### 1. 测试文件缺少依赖
```
src/composables/home/__tests__/*.spec.ts - 缺少 vitest
```
**解决方案：** 安装 vitest 或暂时忽略
### 2. 订单模块类型错误
```
src/composables/order/useOrderDetail.ts - evidence 属性不存在
src/composables/order/useOrderSnapshot.ts - listing_snapshot 属性不存在
```
**解决方案：** 在迁移订单模块时统一修复
### 3. Shared 导出问题
- ✅ 已修复：shared/composables/index.ts 的 default 导出改为命名导出
- ✅ 已修复：shared/api/client.ts 导入路径
### 4. 第三方库缺失
```
views/account/OrderDetailView.vue - 缺少 qrcode 类型
```
**解决方案：** `npm install @types/qrcode` (已在 package.json 中)
---
## 下一步工作
### 🔄 P1.3: 订单模块（orders）- 待开始
这是最复杂的模块，需要：
1. **拆分 useOrderDetail.ts**（当前混合了多个领域）
- 提取支付轮询逻辑 → `usePaymentPolling.ts`
- 提取结算逻辑 → `useSettlement.ts`
- 保留核心订单逻辑
2. **迁移文件**
- API: `api/orders.ts`
- Views: 8个页面（桌面3个 + 移动3个 + 管理2个）
- Composables: `order/useOrderDetail.ts`, `order/useOrderSnapshot.ts`
- Components: 订单卡片、状态徽章、支付二维码等
3. **修复类型错误**
- 补充 Order 接口中缺失的属性
- 修复 evidence、listing_snapshot、checkout_info、counter_info
---
## 文件移动统计
| 模块 | 状态 | API | Views | Composables | Components |
|------|------|-----|-------|-------------|------------|
| shared | ✅ | 1 | 0 | 3 | 2 |
| wallet | ✅ | 1 | 1 | 1 | 0 |
| chats | ✅ | 1 | 4 | 1 | 1 |
| orders | 🔄 | 待迁移 | 8 | 2 | 多个 |
| listings | ⏸️ | - | - | - | - |
| auth | ⏸️ | - | - | - | - |
| seller | ⏸️ | - | - | - | - |
| disputes | ⏸️ | - | - | - | - |
| admin | ⏸️ | - | - | - | - |
---
## 风险与注意事项
### ⚠️ 已发现的风险
1. **订单模块复杂度高：** useOrderDetail.ts 混合了多个业务领域，需要谨慎拆分
2. **类型错误积累：** 订单相关的类型定义不完整，需要补充
3. **移动端路由：** 需要同步更新路由配置
### ✅ 已缓解的风险
- 共享资源已成功提取到 shared/ 目录
- 钱包和聊天模块迁移顺利，验证了迁移方案可行性
- 建立了模块化导出体系
---
## 验证清单
### 每个模块完成后：
- [x] 钱包模块：文件已迁移，导入路径已修复
- [x] 聊天模块：文件已迁移，导入路径已修复
- [ ] 运行 `npm run typecheck` - 有既存错误，待订单模块时统一修复
- [ ] 运行 `npm run dev` - 待验证
- [ ] 测试页面功能 - 待验证
---
## 技术债务
1. **测试覆盖不足：** 缺少单元测试，依赖 vitest
2. **类型定义不完整：** Order 接口缺少多个属性
3. **兼容层未建立：** 旧路径的 re-export 尚未创建（如需要）
---
**下次继续：** 迁移订单模块，这是 P1 阶段的最后一个模块，也是最复杂的一个。
**预计剩余工作量：**
- P1 订单模块：4小时
- P2 模块（listings, auth）：6小时
- P3 模块（seller, disputes, admin）：7小时
- 总计：~17小时