feat: 添加汇率服务和缓存服务，优化数据源和日志服务

refactor: 重构数据源工厂和类型定义，提升代码可维护性 fix: 修复类型转换和状态机文档中的错误 docs: 更新服务架构文档，添加新的服务闭环流程 test: 添加汇率服务单元测试 chore: 清理无用代码和注释，优化代码结构
2026-03-19 14:19:01 +08:00
parent 0dac26d781
commit aa2cf560c6
120 changed files with 33383 additions and 4347 deletions
--- a/docs/01_Architecture/Mock_Architecture.md
+++ b/docs/01_Architecture/Mock_Architecture.md
@@ -86,38 +86,133 @@ Mock 应该是:

 ## 前端Mock方案

+### 项目实际采用的两种Mock方式
+
+本项目采用**两种Mock方式并存**的策略，根据不同模块的特点选择合适的方案：
+
+#### 方式一：DataSource内联Mock（推荐用于简单模块）
+
+**特点**：Mock数据直接写在DataSource文件中，通过环境变量切换
+
+**适用场景**：
+- ✅ 数据结构简单，不需要复杂的网络拦截
+- ✅ 快速原型开发，无需配置MSW
+- ✅ Mock逻辑简单，不需要模拟网络延迟和错误
+
+**实现示例**：
+```typescript
+// /dashboard/src/services/productDataSource.ts
+
+class MockProductDataSource implements IProductDataSource {
+  async fetchProducts(): Promise<Product[]> {
+    // Mock数据直接内联
+    return [
+      { id: '1', name: '商品A', price: 99.99 },
+      { id: '2', name: '商品B', price: 199.99 },
+    ];
+  }
+}
+
+class ApiProductDataSource implements IProductDataSource {
+  async fetchProducts(): Promise<Product[]> {
+    const res = await fetch('/api/products');
+    return res.json();
+  }
+}
+
+const useMock = process.env.REACT_APP_USE_MOCK === 'true';
+export const productDataSource = useMock ? new MockProductDataSource() : new ApiProductDataSource();
+```
+
+**已实现的模块**：
+- 产品模块 (productDataSource.ts)
+- 订单模块 (orderDataSource.ts)
+- 库存模块 (inventoryDataSource.ts)
+- 商户模块 (merchantDataSource.ts)
+- 供应商模块 (suppliersDataSource.ts)
+- 物流模块 (logisticsDataSource.ts)
+- 营销模块 (marketingDataSource.ts)
+- 财务模块 (financeDataSource.ts)
+- 报表模块 (reportsDataSource.ts)
+- 设置模块 (settingsDataSource.ts)
+- 售后模块 (afterSalesDataSource.ts)
+- 返回模块 (returnDataSource.ts)
+- 用户资产模块 (userAssetDataSource.ts)
+- 任务中心模块 (taskCenterDataSource.ts)
+- 分析模块 (analyticsDataSource.ts)
+- B2B贸易模块 (b2bTradeDataSource.ts)
+- 排行榜模块 (leaderboardDataSource.ts)
+- 动态定价模块 (dynamicPricingDataSource.ts)
+- 套利模块 (arbitrageDataSource.ts)
+- 店铺报表模块 (shopReportDataSource.ts)
+- 自动执行模块 (autoExecutionDataSource.ts)
+- 广告优化模块 (adOptimizationDataSource.ts)
+- AB测试模块 (abTestDataSource.ts)
+- 黑名单模块 (blacklistDataSource.ts)
+- 独立站点模块 (independentSiteDataSource.ts)
+
+#### 方式二：MSW网络层Mock（推荐用于复杂模块）
+
+**特点**：使用MSW拦截HTTP请求，Mock数据独立在 `/mock/data/` 目录
+
+**适用场景**：
+- ✅ 需要模拟真实的网络请求和响应
+- ✅ 需要模拟网络延迟、错误状态
+- ✅ 需要支持复杂的查询参数和分页
+- ✅ 需要多个组件共享同一Mock数据
+
+**实现示例**：
+```typescript
+// /dashboard/src/mock/data/certificate.mock.ts
+export const mockCertificates = [...];
+
+// /dashboard/src/mock/msw.ts
+export const handlers = [
+  rest.get('/api/v1/certificate/certificates', (req, res, ctx) => {
+    return res(
+      ctx.delay(300), // 模拟网络延迟
+      ctx.json({ success: true, data: mockCertificates })
+    );
+  }),
+];
+
+// /dashboard/src/app.ts
+if (process.env.REACT_APP_USE_MOCK === 'true') {
+  const { worker } = await import('./mock/browser');
+  await worker.start();
+}
+```
+
+**已实现的模块**：
+- 证书模块 (certificateDataSource.ts + msw.ts)
+- 自动选品模块 (productSelectionDataSource.ts + msw.ts)
+
 ### 方案对比

 | 方案 | 侵入性 | 推荐度 | 适用场景 |
 |------|--------|--------|----------|
-| MSW (Mock Service Worker) | ⭐ 最低 | 🥇 最推荐 | 前端开发、UI测试 |
-| DataSource抽象 | ⭐⭐ 低 | 🥈 推荐 | 需要自定义逻辑 |
+| DataSource内联Mock | ⭐⭐ 低 | 🥈 推荐 | 简单模块、快速原型 |
+| MSW网络层Mock | ⭐ 最低 | 🥇 最推荐 | 复杂模块、UI测试 |
 | 本地Mock Server | ⭐⭐⭐ 中 | 🥉 可选 | 团队共享Mock |
 | 硬编码 | ❌ 高 | 🚫 不推荐 | 绝对禁止 |

-### 推荐方案: MSW + DataSource抽象
+### 推荐方案：根据模块复杂度选择

 #### 1. 目录结构

 ```
 /dashboard/src
-  /api                    ← 真实API封装
-    product.ts
-    user.ts
-    order.ts
-    certificate.ts
-  /mock                   ← 所有Mock数据和拦截器
-    /data                 ← Mock数据文件
-      product.mock.ts
-      user.mock.ts
+  /api                    ← 真实API封装（可选）
+    *.ts
+  /mock                   ← MSW Mock数据和拦截器
+    /data                 ← Mock数据文件（仅MSW方式使用）
      certificate.mock.ts
+      productSelection.mock.ts
    msw.ts                ← MSW初始化配置
    browser.ts            ← 浏览器环境启动
-    server.ts             ← Node/测试环境启动
-  /services               ← 数据源抽象层
-    productDataSource.ts
-    userDataSource.ts
-    certificateDataSource.ts
+    README.md             ← Mock使用说明
+  /services               ← 数据源抽象层（所有模块）
+    *DataSource.ts        ← 包含Mock和API两种实现
  /types                  ← 类型定义
    datasource.ts         ← DataSource接口定义
 ```
@@ -618,11 +713,14 @@ AI生成业务代码时必须:
 ```markdown
 ## Mock使用规范

-1. 所有Mock数据必须放 `/mock` 目录
-2. DataSource层是唯一业务入口
-3. `USE_MOCK=true` 时才启用Mock
+1. DataSource层是唯一业务入口，所有业务代码必须通过DataSource获取数据
+2. Mock数据有两种存放方式：
+   - 简单模块：直接写在DataSource文件中的Mock类
+   - 复杂模块：独立在 `/mock/data/` 目录，通过MSW拦截
+3. `REACT_APP_USE_MOCK=true` 时才启用Mock
 4. AI不得将Mock数据当作真实业务逻辑
 5. Mock不代表真实接口结构，仅用于UI开发
+6. 新增模块时，根据复杂度选择合适的Mock方式
 ```

 ---
@@ -633,17 +731,39 @@ AI生成业务代码时必须:

 | 任务ID | 任务描述 | 涉及文件 | 优先级 | 状态 |
 |--------|----------|----------|--------|------|
-| MOCK-001 | 创建DataSource接口定义 | `/dashboard/src/types/datasource.ts` | P0 | ⏳ 待实现 |
-| MOCK-002 | 实现证书DataSource | `/dashboard/src/services/certificateDataSource.ts` | P0 | ⏳ 待实现 |
-| MOCK-003 | 配置MSW拦截器 | `/dashboard/src/mock/msw.ts` | P0 | ⏳ 待实现 |
-| MOCK-004 | 入口文件MSW启动 | `/dashboard/src/index.tsx` | P0 | ⏳ 待实现 |
-| MOCK-005 | BFF层Mock切换器 | `/server/src/bff/services/*.ts` | P1 | ⏳ 待实现 |
-| MOCK-006 | BFF层Mock服务 | `/server/src/bff/mock/*.ts` | P1 | ⏳ 待实现 |
-| MOCK-007 | 产品模块DataSource | `/dashboard/src/services/productDataSource.ts` | P1 | ⏳ 待实现 |
-| MOCK-008 | 订单模块DataSource | `/dashboard/src/services/orderDataSource.ts` | P1 | ⏳ 待实现 |
+| MOCK-001 | 创建DataSource接口定义 | `/dashboard/src/types/datasource.ts` | P0 | ✅ 已完成 |
+| MOCK-002 | 实现证书DataSource | `/dashboard/src/services/certificateDataSource.ts` | P0 | ✅ 已完成 |
+| MOCK-003 | 配置MSW拦截器 | `/dashboard/src/mock/msw.ts` | P0 | ✅ 已完成 |
+| MOCK-004 | 入口文件MSW启动 | `/dashboard/src/app.ts` | P0 | ✅ 已完成 |
+| MOCK-005 | BFF层Mock切换器 | `/server/src/bff/services/certificateService.ts` | P0 | ✅ 已完成 |
+| MOCK-006 | BFF层Mock服务 | `/server/src/bff/mock/certificateMock.ts` | P0 | ✅ 已完成 |
+| MOCK-007 | 产品模块DataSource | `/dashboard/src/services/productDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-008 | 订单模块DataSource | `/dashboard/src/services/orderDataSource.ts` | P1 | ✅ 已完成 |
 | MOCK-009 | 用户模块DataSource | `/dashboard/src/services/userDataSource.ts` | P1 | ⏳ 待实现 |
-| MOCK-010 | 库存模块DataSource | `/dashboard/src/services/inventoryDataSource.ts` | P1 | ⏳ 待实现 |
-| MOCK-011 | 环境变量配置 | `.env.development`, `.env.production` | P0 | ⏳ 待实现 |
+| MOCK-010 | 库存模块DataSource | `/dashboard/src/services/inventoryDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-016 | 商户模块DataSource | `/dashboard/src/services/merchantDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-017 | 供应商模块DataSource | `/dashboard/src/services/suppliersDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-018 | 物流模块DataSource | `/dashboard/src/services/logisticsDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-019 | 营销模块DataSource | `/dashboard/src/services/marketingDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-020 | 财务模块DataSource | `/dashboard/src/services/financeDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-021 | 报表模块DataSource | `/dashboard/src/services/reportsDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-022 | 设置模块DataSource | `/dashboard/src/services/settingsDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-023 | 售后模块DataSource | `/dashboard/src/services/afterSalesDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-024 | 返回模块DataSource | `/dashboard/src/services/returnDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-025 | 用户资产模块DataSource | `/dashboard/src/services/userAssetDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-026 | 任务中心模块DataSource | `/dashboard/src/services/taskCenterDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-027 | 分析模块DataSource | `/dashboard/src/services/analyticsDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-028 | B2B贸易模块DataSource | `/dashboard/src/services/b2bTradeDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-029 | 排行榜模块DataSource | `/dashboard/src/services/leaderboardDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-030 | 动态定价模块DataSource | `/dashboard/src/services/dynamicPricingDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-031 | 套利模块DataSource | `/dashboard/src/services/arbitrageDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-032 | 店铺报表模块DataSource | `/dashboard/src/services/shopReportDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-033 | 自动执行模块DataSource | `/dashboard/src/services/autoExecutionDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-034 | 广告优化模块DataSource | `/dashboard/src/services/adOptimizationDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-035 | AB测试模块DataSource | `/dashboard/src/services/abTestDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-036 | 黑名单模块DataSource | `/dashboard/src/services/blacklistDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-037 | 独立站点模块DataSource | `/dashboard/src/services/independentSiteDataSource.ts` | P1 | ✅ 已完成 |
+| MOCK-011 | 环境变量配置 | `.env.development`, `.env.production` | P0 | ✅ 已完成 |
 | MOCK-012 | 文档完善 | `docs/01_Architecture/Mock_Architecture.md` | P0 | ✅ 已完成 |
 | MOCK-013 | 自动选品模块Mock数据 | `/dashboard/src/mock/data/productSelection.mock.ts` | P0 | ✅ 已完成 |
 | MOCK-014 | 自动选品DataSource | `/dashboard/src/services/productSelectionDataSource.ts` | P0 | ✅ 已完成 |
@@ -702,6 +822,7 @@ npm run build
 | 时间 | 版本 | 更新内容 |
 |------|------|----------|
 | 2026-03-19 | v1.0 | 初始版本，创建完整Mock架构设计 |
+| 2026-03-19 | v1.1 | 更新为两种Mock方式并存策略，完善任务状态，添加27个模块Mock实现 |

 ---