feat: 添加MSW模拟服务和数据源集成
refactor: 重构页面组件移除冗余Layout组件 feat: 实现WebSocket和事件总线系统 feat: 添加队列和调度系统 docs: 更新架构文档和服务映射 style: 清理重复接口定义使用数据源 chore: 更新依赖项配置 feat: 添加运行时系统和领域引导 ci: 配置ESLint边界检查规则 build: 添加Redis和WebSocket依赖 test: 添加MSW浏览器环境入口 perf: 优化数据获取逻辑使用统一数据源 fix: 修复类型定义和状态管理问题
This commit is contained in:
708
docs/01_Architecture/Mock_Architecture.md
Normal file
708
docs/01_Architecture/Mock_Architecture.md
Normal file
@@ -0,0 +1,708 @@
|
||||
# 低侵入 Mock 架构设计
|
||||
|
||||
> 文档创建时间: 2026-03-19 (北京时间)
|
||||
> 适用项目: Crawlful Hub
|
||||
> 目标: 实现"不污染代码、AI上下文安全"的Mock方案
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [核心原则](#核心原则)
|
||||
2. [架构概览](#架构概览)
|
||||
3. [前端Mock方案](#前端mock方案)
|
||||
4. [后端/BFF Mock方案](#后端bff-mock方案)
|
||||
5. [目录规范](#目录规范)
|
||||
6. [AI协作规范](#ai协作规范)
|
||||
7. [实施任务](#实施任务)
|
||||
|
||||
---
|
||||
|
||||
## 核心原则
|
||||
|
||||
### 1. Mock ≠ 写死数据
|
||||
|
||||
❌ **错误做法**: 在组件中直接写死数据
|
||||
```typescript
|
||||
const data = [{ id: 1, name: 'Mock商品' }]
|
||||
```
|
||||
|
||||
✅ **正确做法**: 通过数据源抽象层获取
|
||||
```typescript
|
||||
const data = await productDataSource.list()
|
||||
```
|
||||
|
||||
### 2. Mock 必须"可插拔"
|
||||
|
||||
Mock 应该是:
|
||||
- ✅ 可开启 / 可关闭
|
||||
- ✅ 可替换 / 可隔离
|
||||
- ✅ 环境变量控制
|
||||
|
||||
### 3. Mock 属于"数据源层"，不是"业务层"
|
||||
|
||||
```
|
||||
业务代码 → DataSource抽象层 → (Mock/真实API)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构概览
|
||||
|
||||
### 三层数据架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 前端 (React + Umi) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 业务组件 │ → │ DataSource │ → │ API/Mock │ │
|
||||
│ │ │ │ 抽象层 │ │ │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ BFF 层 (服务编排层) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Service │ → │ Mock切换 │ → │ 真实/Mock │ │
|
||||
│ │ │ │ │ │ 服务 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 后端微服务层 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Mock 分布策略
|
||||
|
||||
| 层级 | 是否Mock | 说明 |
|
||||
|------|---------|------|
|
||||
| 前端 | ⚠️ 可选 | 推荐用MSW，保持业务代码纯净 |
|
||||
| DataSource | ✅ 可切换 | 控制入口，环境变量驱动 |
|
||||
| BFF | ✅ 主力Mock | 最真实，前端无感知 |
|
||||
| 后端 | ❌ 不建议 | 除非联调测试 |
|
||||
|
||||
---
|
||||
|
||||
## 前端Mock方案
|
||||
|
||||
### 方案对比
|
||||
|
||||
| 方案 | 侵入性 | 推荐度 | 适用场景 |
|
||||
|------|--------|--------|----------|
|
||||
| MSW (Mock Service Worker) | ⭐ 最低 | 🥇 最推荐 | 前端开发、UI测试 |
|
||||
| DataSource抽象 | ⭐⭐ 低 | 🥈 推荐 | 需要自定义逻辑 |
|
||||
| 本地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
|
||||
certificate.mock.ts
|
||||
msw.ts ← MSW初始化配置
|
||||
browser.ts ← 浏览器环境启动
|
||||
server.ts ← Node/测试环境启动
|
||||
/services ← 数据源抽象层
|
||||
productDataSource.ts
|
||||
userDataSource.ts
|
||||
certificateDataSource.ts
|
||||
/types ← 类型定义
|
||||
datasource.ts ← DataSource接口定义
|
||||
```
|
||||
|
||||
#### 2. DataSource接口定义
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/types/datasource.ts
|
||||
|
||||
/**
|
||||
* [MOCK-001] DataSource抽象接口
|
||||
* 所有数据源必须实现此接口
|
||||
* AI注意: 这是抽象层，不涉及具体实现
|
||||
*/
|
||||
export interface IDataSource<T, QueryParams = any> {
|
||||
list(params?: QueryParams): Promise<T[]>;
|
||||
detail(id: string): Promise<T | null>;
|
||||
create(data: Partial<T>): Promise<T>;
|
||||
update(id: string, data: Partial<T>): Promise<T>;
|
||||
delete(id: string): Promise<void>;
|
||||
}
|
||||
|
||||
export interface ProductQueryParams {
|
||||
keyword?: string;
|
||||
category?: string;
|
||||
status?: string;
|
||||
page?: number;
|
||||
pageSize?: number;
|
||||
}
|
||||
|
||||
export interface CertificateQueryParams {
|
||||
status?: string;
|
||||
type?: string;
|
||||
page?: number;
|
||||
pageSize?: number;
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. DataSource抽象层实现
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/services/certificateDataSource.ts
|
||||
|
||||
import { Certificate } from '@/types/certificate';
|
||||
import { IDataSource, CertificateQueryParams } from '@/types/datasource';
|
||||
|
||||
/**
|
||||
* [MOCK-002] 证书数据源抽象层
|
||||
* 通过环境变量自动切换Mock/真实API
|
||||
* AI注意: 这是唯一入口，业务代码必须调用此层
|
||||
*/
|
||||
|
||||
// 真实API实现
|
||||
class ApiCertificateDataSource implements IDataSource<Certificate, CertificateQueryParams> {
|
||||
async list(params?: CertificateQueryParams): Promise<Certificate[]> {
|
||||
const query = new URLSearchParams(params as any).toString();
|
||||
const response = await fetch(`/api/v1/certificate/certificates?${query}`);
|
||||
const result = await response.json();
|
||||
return result.data || [];
|
||||
}
|
||||
|
||||
async detail(id: string): Promise<Certificate | null> {
|
||||
const response = await fetch(`/api/v1/certificate/certificates/${id}`);
|
||||
const result = await response.json();
|
||||
return result.data || null;
|
||||
}
|
||||
|
||||
async create(data: Partial<Certificate>): Promise<Certificate> {
|
||||
const response = await fetch('/api/v1/certificate/certificates', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(data),
|
||||
});
|
||||
const result = await response.json();
|
||||
return result.data;
|
||||
}
|
||||
|
||||
async update(id: string, data: Partial<Certificate>): Promise<Certificate> {
|
||||
const response = await fetch(`/api/v1/certificate/certificates/${id}`, {
|
||||
method: 'PUT',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(data),
|
||||
});
|
||||
const result = await response.json();
|
||||
return result.data;
|
||||
}
|
||||
|
||||
async delete(id: string): Promise<void> {
|
||||
await fetch(`/api/v1/certificate/certificates/${id}`, {
|
||||
method: 'DELETE',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Mock实现 (完全独立文件)
|
||||
class MockCertificateDataSource implements IDataSource<Certificate, CertificateQueryParams> {
|
||||
private mockData: Certificate[] = [
|
||||
{
|
||||
id: '1',
|
||||
name: 'CE认证证书',
|
||||
type: 'PRODUCT_CERT',
|
||||
status: 'APPROVED',
|
||||
fileUrl: '/files/ce-cert.pdf',
|
||||
fileName: 'CE-Certificate-2026.pdf',
|
||||
uploadDate: '2026-03-15',
|
||||
expiryDate: '2027-03-15',
|
||||
approvedBy: 'admin',
|
||||
approvedDate: '2026-03-16',
|
||||
productId: 'P001',
|
||||
productName: '工业温度传感器',
|
||||
notes: '欧盟市场准入认证',
|
||||
},
|
||||
// ... 更多Mock数据
|
||||
];
|
||||
|
||||
async list(params?: CertificateQueryParams): Promise<Certificate[]> {
|
||||
// 模拟网络延迟
|
||||
await new Promise(resolve => setTimeout(resolve, 300));
|
||||
|
||||
let result = [...this.mockData];
|
||||
|
||||
if (params?.status) {
|
||||
result = result.filter(item => item.status === params.status);
|
||||
}
|
||||
if (params?.type) {
|
||||
result = result.filter(item => item.type === params.type);
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
async detail(id: string): Promise<Certificate | null> {
|
||||
await new Promise(resolve => setTimeout(resolve, 200));
|
||||
return this.mockData.find(item => item.id === id) || null;
|
||||
}
|
||||
|
||||
async create(data: Partial<Certificate>): Promise<Certificate> {
|
||||
await new Promise(resolve => setTimeout(resolve, 500));
|
||||
const newCert: Certificate = {
|
||||
id: `${Date.now()}`,
|
||||
...data as Certificate,
|
||||
status: 'PENDING',
|
||||
uploadDate: new Date().toISOString().split('T')[0],
|
||||
};
|
||||
this.mockData.unshift(newCert);
|
||||
return newCert;
|
||||
}
|
||||
|
||||
async update(id: string, data: Partial<Certificate>): Promise<Certificate> {
|
||||
await new Promise(resolve => setTimeout(resolve, 300));
|
||||
const index = this.mockData.findIndex(item => item.id === id);
|
||||
if (index === -1) throw new Error('Certificate not found');
|
||||
this.mockData[index] = { ...this.mockData[index], ...data };
|
||||
return this.mockData[index];
|
||||
}
|
||||
|
||||
async delete(id: string): Promise<void> {
|
||||
await new Promise(resolve => setTimeout(resolve, 200));
|
||||
this.mockData = this.mockData.filter(item => item.id !== id);
|
||||
}
|
||||
}
|
||||
|
||||
// 导出数据源实例 (环境变量控制)
|
||||
const useMock = process.env.REACT_APP_USE_MOCK === 'true';
|
||||
|
||||
export const certificateDataSource: IDataSource<Certificate, CertificateQueryParams> = useMock
|
||||
? new MockCertificateDataSource()
|
||||
: new ApiCertificateDataSource();
|
||||
|
||||
// 标记Mock状态 (用于调试)
|
||||
export const __MOCK__ = useMock;
|
||||
```
|
||||
|
||||
#### 4. MSW配置
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/mock/msw.ts
|
||||
|
||||
import { setupWorker, rest } from 'msw';
|
||||
import { mockCertificates } from './data/certificate.mock';
|
||||
|
||||
/**
|
||||
* [MOCK-003] MSW Mock配置
|
||||
* 拦截HTTP请求，返回Mock数据
|
||||
* AI注意: 这是网络层拦截，业务代码完全无感知
|
||||
*/
|
||||
|
||||
export const worker = setupWorker(
|
||||
// 证书列表
|
||||
rest.get('/api/v1/certificate/certificates', (req, res, ctx) => {
|
||||
const status = req.url.searchParams.get('status');
|
||||
const type = req.url.searchParams.get('type');
|
||||
|
||||
let data = [...mockCertificates];
|
||||
if (status) data = data.filter(item => item.status === status);
|
||||
if (type) data = data.filter(item => item.type === type);
|
||||
|
||||
return res(
|
||||
ctx.delay(300),
|
||||
ctx.json({
|
||||
success: true,
|
||||
data,
|
||||
total: data.length,
|
||||
})
|
||||
);
|
||||
}),
|
||||
|
||||
// 证书详情
|
||||
rest.get('/api/v1/certificate/certificates/:id', (req, res, ctx) => {
|
||||
const { id } = req.params;
|
||||
const cert = mockCertificates.find(item => item.id === id);
|
||||
|
||||
if (!cert) {
|
||||
return res(
|
||||
ctx.status(404),
|
||||
ctx.json({ success: false, error: '证书不存在' })
|
||||
);
|
||||
}
|
||||
|
||||
return res(
|
||||
ctx.delay(200),
|
||||
ctx.json({ success: true, data: cert })
|
||||
);
|
||||
}),
|
||||
|
||||
// 创建证书
|
||||
rest.post('/api/v1/certificate/certificates', async (req, res, ctx) => {
|
||||
const body = await req.json();
|
||||
const newCert = {
|
||||
id: `${Date.now()}`,
|
||||
...body,
|
||||
status: 'PENDING',
|
||||
uploadDate: new Date().toISOString().split('T')[0],
|
||||
};
|
||||
|
||||
return res(
|
||||
ctx.delay(500),
|
||||
ctx.json({ success: true, data: { id: newCert.id } })
|
||||
);
|
||||
}),
|
||||
|
||||
// 更新证书状态
|
||||
rest.put('/api/v1/certificate/certificates/:id/status', async (req, res, ctx) => {
|
||||
const { id } = req.params;
|
||||
const { status, approvedBy } = await req.json();
|
||||
|
||||
return res(
|
||||
ctx.delay(300),
|
||||
ctx.json({ success: true })
|
||||
);
|
||||
}),
|
||||
|
||||
// 删除证书
|
||||
rest.delete('/api/v1/certificate/certificates/:id', (req, res, ctx) => {
|
||||
return res(
|
||||
ctx.delay(200),
|
||||
ctx.json({ success: true })
|
||||
);
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/mock/browser.ts
|
||||
import { worker } from './msw';
|
||||
export { worker };
|
||||
```
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/index.tsx (入口文件)
|
||||
|
||||
import React from 'react';
|
||||
import ReactDOM from 'react-dom/client';
|
||||
import App from './App';
|
||||
|
||||
/**
|
||||
* [MOCK-004] MSW启动配置
|
||||
* 仅在REACT_APP_USE_MOCK=true时启用
|
||||
*/
|
||||
async function enableMocking() {
|
||||
if (process.env.REACT_APP_USE_MOCK !== 'true') {
|
||||
return;
|
||||
}
|
||||
|
||||
const { worker } = await import('./mock/browser');
|
||||
return worker.start({
|
||||
onUnhandledRequest: 'bypass', // 未拦截的请求直接透传
|
||||
});
|
||||
}
|
||||
|
||||
enableMocking().then(() => {
|
||||
const root = ReactDOM.createRoot(document.getElementById('root')!);
|
||||
root.render(
|
||||
<React.StrictMode>
|
||||
<App />
|
||||
</React.StrictMode>
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
#### 5. 业务组件使用示例
|
||||
|
||||
```typescript
|
||||
// /dashboard/src/pages/Compliance/index.tsx
|
||||
|
||||
import { certificateDataSource } from '@/services/certificateDataSource';
|
||||
|
||||
const ComplianceManagement: React.FC = () => {
|
||||
const fetchData = useCallback(async () => {
|
||||
setLoading(true);
|
||||
try {
|
||||
// 调用DataSource层，完全无感知是Mock还是真实API
|
||||
const data = await certificateDataSource.list({
|
||||
status: activeStatus,
|
||||
type: activeType,
|
||||
});
|
||||
setCertificates(data);
|
||||
} catch (error) {
|
||||
message.error('获取证书列表失败');
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}, [activeStatus, activeType]);
|
||||
|
||||
const handleUploadSubmit = async () => {
|
||||
try {
|
||||
const values = await uploadForm.validateFields();
|
||||
await certificateDataSource.create({
|
||||
name: values.name,
|
||||
type: values.type,
|
||||
expiryDate: values.expiryDate.format('YYYY-MM-DD'),
|
||||
productId: values.productId,
|
||||
productName: values.productName,
|
||||
notes: values.notes,
|
||||
});
|
||||
message.success('证书上传成功');
|
||||
fetchData();
|
||||
} catch (error) {
|
||||
message.error('上传失败');
|
||||
}
|
||||
};
|
||||
|
||||
// ... 其他逻辑
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后端/BFF Mock方案
|
||||
|
||||
### 架构设计
|
||||
|
||||
```
|
||||
BFF层
|
||||
├─ Service (业务逻辑)
|
||||
├─ Mock切换器 (环境变量控制)
|
||||
├─ 真实API客户端
|
||||
└─ Mock服务
|
||||
```
|
||||
|
||||
### 实现示例
|
||||
|
||||
```typescript
|
||||
// /server/src/bff/services/certificateService.ts
|
||||
|
||||
import { CertificateService as RealCertificateService } from '../../services/CertificateService';
|
||||
import { MockCertificateService } from '../mock/certificateMock';
|
||||
|
||||
/**
|
||||
* [MOCK-005] BFF层证书服务
|
||||
* 通过环境变量自动切换Mock/真实服务
|
||||
*/
|
||||
|
||||
const useMock = process.env.USE_MOCK === 'true';
|
||||
|
||||
export const certificateService = useMock
|
||||
? new MockCertificateService()
|
||||
: new RealCertificateService();
|
||||
|
||||
// 类型导出，确保调用方类型安全
|
||||
export type ICertificateService = typeof certificateService;
|
||||
```
|
||||
|
||||
```typescript
|
||||
// /server/src/bff/mock/certificateMock.ts
|
||||
|
||||
import { ICertificateService } from '../services/certificateService';
|
||||
|
||||
/**
|
||||
* [MOCK-006] BFF层Mock服务
|
||||
* 完全独立的Mock实现
|
||||
* AI注意: 这是Mock实现，不是真实业务逻辑
|
||||
*/
|
||||
|
||||
export class MockCertificateService implements ICertificateService {
|
||||
private mockData = [
|
||||
// ... Mock数据
|
||||
];
|
||||
|
||||
async query(options: any) {
|
||||
await this.delay(300);
|
||||
return {
|
||||
items: this.mockData,
|
||||
total: this.mockData.length,
|
||||
};
|
||||
}
|
||||
|
||||
async getById(id: string, tenantId: string, shopId: string) {
|
||||
await this.delay(200);
|
||||
return this.mockData.find(item => item.id === id) || null;
|
||||
}
|
||||
|
||||
async create(input: any) {
|
||||
await this.delay(500);
|
||||
const id = `mock-${Date.now()}`;
|
||||
// ... 创建逻辑
|
||||
return id;
|
||||
}
|
||||
|
||||
private delay(ms: number) {
|
||||
return new Promise(resolve => setTimeout(resolve, ms));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 目录规范
|
||||
|
||||
### 前端目录规范
|
||||
|
||||
```
|
||||
/dashboard/src
|
||||
/mock ← 所有Mock相关
|
||||
/data ← Mock数据定义
|
||||
*.mock.ts
|
||||
msw.ts ← MSW配置
|
||||
browser.ts ← 浏览器入口
|
||||
server.ts ← Node/测试入口
|
||||
README.md ← Mock使用说明
|
||||
/services ← DataSource抽象层
|
||||
*DataSource.ts
|
||||
/api ← 真实API封装
|
||||
*.ts
|
||||
```
|
||||
|
||||
### 后端目录规范
|
||||
|
||||
```
|
||||
/server/src
|
||||
/bff ← BFF层
|
||||
/mock ← Mock服务
|
||||
*.ts
|
||||
/services ← 服务层
|
||||
*.ts
|
||||
/api ← API客户端
|
||||
*.ts
|
||||
/services ← 真实服务
|
||||
*.ts
|
||||
```
|
||||
|
||||
### 标记规范
|
||||
|
||||
所有Mock文件必须包含以下标记:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* [MOCK-XXX] 功能描述
|
||||
* AI注意: 这是Mock实现，不是真实业务逻辑
|
||||
* 仅在USE_MOCK=true时启用
|
||||
*/
|
||||
|
||||
// 或者
|
||||
|
||||
// [MOCK] 此文件为Mock数据，AI请勿当作真实业务逻辑
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI协作规范
|
||||
|
||||
### 1. Mock文件识别规则
|
||||
|
||||
AI在分析代码时:
|
||||
- ✅ 忽略 `/mock` 目录下所有文件
|
||||
- ✅ 忽略包含 `[MOCK]` 标记的文件
|
||||
- ✅ 忽略 `__MOCK__` 变量为真的代码路径
|
||||
|
||||
### 2. 业务代码规范
|
||||
|
||||
AI生成业务代码时必须:
|
||||
- ✅ 调用 DataSource 抽象层
|
||||
- ✅ 不直接调用 API 或 Mock
|
||||
- ✅ 不硬编码任何数据
|
||||
|
||||
### 3. 文档声明
|
||||
|
||||
```markdown
|
||||
## Mock使用规范
|
||||
|
||||
1. 所有Mock数据必须放 `/mock` 目录
|
||||
2. DataSource层是唯一业务入口
|
||||
3. `USE_MOCK=true` 时才启用Mock
|
||||
4. AI不得将Mock数据当作真实业务逻辑
|
||||
5. Mock不代表真实接口结构，仅用于UI开发
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实施任务
|
||||
|
||||
### 任务清单
|
||||
|
||||
| 任务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-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-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 | ✅ 已完成 |
|
||||
| MOCK-015 | 自动选品页面Mock集成 | `/dashboard/src/pages/AutoProductSelection/index.tsx` | P0 | ✅ 已完成 |
|
||||
|
||||
### 环境变量配置
|
||||
|
||||
```bash
|
||||
# .env.development (开发环境)
|
||||
REACT_APP_USE_MOCK=true # 前端启用Mock
|
||||
USE_MOCK=true # 后端启用Mock
|
||||
|
||||
# .env.production (生产环境)
|
||||
REACT_APP_USE_MOCK=false # 前端禁用Mock
|
||||
USE_MOCK=false # 后端禁用Mock
|
||||
```
|
||||
|
||||
### 快速启动命令
|
||||
|
||||
```bash
|
||||
# 开发模式 (带Mock)
|
||||
npm run dev:mock
|
||||
|
||||
# 开发模式 (真实API)
|
||||
npm run dev
|
||||
|
||||
# 生产构建
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 优势总结
|
||||
|
||||
| 特性 | 描述 |
|
||||
|------|------|
|
||||
| 🎯 零侵入 | 业务层完全不感知Mock |
|
||||
| 🔄 可切换 | 环境变量一键切换Mock/真实API |
|
||||
| 🤖 AI安全 | Mock独立文件 + 文档规范 |
|
||||
| 📦 可扩展 | 支持MSW、BFF Mock、本地Mock Server |
|
||||
| 🧪 可测试 | 统一接口便于单元测试 |
|
||||
| 📝 可维护 | 目录清晰，职责分离 |
|
||||
|
||||
---
|
||||
|
||||
## 附录
|
||||
|
||||
### 相关文档
|
||||
|
||||
- [项目特定规则](../.trae/rules/project-specific-rules.md)
|
||||
- [AI协作协议](../.trae/rules/project-specific-rules.md#7-ai-协作协议)
|
||||
- [Task_Overview](../00_Business/Task_Overview.md)
|
||||
|
||||
### 更新记录
|
||||
|
||||
| 时间 | 版本 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| 2026-03-19 | v1.0 | 初始版本，创建完整Mock架构设计 |
|
||||
|
||||
---
|
||||
|
||||
*本文档遵循 Crawlful Hub 项目规范，所有Mock实现必须遵守"低侵入、AI安全"原则。*
|
||||
@@ -145,7 +145,33 @@ Merchant Portal
|
||||
|
||||
---
|
||||
|
||||
## 10. 异常处理闭环
|
||||
## 10. 自动选品闭环
|
||||
|
||||
Flow:
|
||||
Frontend / Scheduler
|
||||
→ ProductSelectionController.execute
|
||||
→ ProductSelectionService.executeSelection
|
||||
→ ProductSelectionService.calculateScore
|
||||
→ ProductPoolRepository.save
|
||||
→ AutoListingService.createListingTask
|
||||
→ Response
|
||||
|
||||
---
|
||||
|
||||
## 11. 自动上架闭环
|
||||
|
||||
Flow:
|
||||
Scheduler / Manual Trigger
|
||||
→ AutoListingController.batchList
|
||||
→ AutoListingService.batchListProducts
|
||||
→ PlatformApiService.publishProduct
|
||||
→ ListingTaskRepository.updateStatus
|
||||
→ NotificationService.notifyListingResult
|
||||
→ Response
|
||||
|
||||
---
|
||||
|
||||
## 12. 异常处理闭环
|
||||
|
||||
Flow:
|
||||
Frontend / System
|
||||
|
||||
@@ -67,3 +67,156 @@
|
||||
- **有 API 平台**: 走 `Connector Bus` 标准协议。
|
||||
- **无 API 平台**: 走 `No-API Bridge`，采用 `Collect -> Clean -> Review -> Publish` 流程。
|
||||
- **统一发布编排**: 由 `PublishOrchestrator` 统一管理。
|
||||
|
||||
---
|
||||
|
||||
## 6. AI决策日志系统（AI Decision Logging System）
|
||||
|
||||
> **说明**：本章节定义AI决策全链路日志记录规范，确保"AI建议→人类确认→系统执行"可追溯、可审计。
|
||||
|
||||
### 6.1 日志系统目标
|
||||
|
||||
- **全链路追溯**：每条操作有唯一ID，AI建议→人操作→系统执行关联
|
||||
- **可审计性**：支持事后审计、问题排查、策略优化
|
||||
- **数据完整性**：日志不可篡改，支持长期存储
|
||||
|
||||
### 6.2 日志类型
|
||||
|
||||
| 日志类型 | 内容 | 存储周期 |
|
||||
|----------|------|----------|
|
||||
| **AI建议日志** | 建议动作、参数、置信度、生成时间 | 180天 |
|
||||
| **人工操作日志** | 操作人、修改内容、理由、确认时间 | 永久 |
|
||||
| **系统执行日志** | 执行结果、执行时间、失败原因 | 90天 |
|
||||
| **异常日志** | 异常类型、堆栈、处理结果 | 180天 |
|
||||
|
||||
### 6.3 日志数据结构
|
||||
|
||||
```typescript
|
||||
interface AIDecisionLog {
|
||||
// 唯一标识
|
||||
operation_id: string; // 格式: YYYYMMDD-序号
|
||||
trace_id: string; // 全链路追踪ID
|
||||
|
||||
// AI建议部分
|
||||
ai_suggestion: {
|
||||
action: string; // 操作类型
|
||||
params: Record<string, any>; // 操作参数
|
||||
confidence: number; // 置信度 (0-1)
|
||||
risk_level: 'low' | 'medium' | 'high'; // 风险等级
|
||||
alternative_solutions?: Array<{
|
||||
action: string;
|
||||
params: Record<string, any>;
|
||||
confidence: number;
|
||||
}>;
|
||||
timestamp: string; // ISO 8601
|
||||
model_version?: string; // AI模型版本
|
||||
};
|
||||
|
||||
// 人工审核部分
|
||||
human_review?: {
|
||||
operator: string; // 操作人
|
||||
operator_id: string; // 操作人ID
|
||||
action: 'approved' | 'modified' | 'rejected'; // 审核动作
|
||||
modified_params?: Record<string, any>; // 修改后的参数
|
||||
reason?: string; // 修改/拒绝理由
|
||||
timestamp: string; // ISO 8601
|
||||
};
|
||||
|
||||
// 系统执行部分
|
||||
system_execution: {
|
||||
status: 'pending' | 'success' | 'failed' | 'retrying';
|
||||
result?: Record<string, any>; // 执行结果
|
||||
error_message?: string; // 错误信息
|
||||
retry_count?: number; // 重试次数
|
||||
timestamp: string; // ISO 8601
|
||||
duration_ms?: number; // 执行耗时
|
||||
};
|
||||
|
||||
// 元数据
|
||||
metadata: {
|
||||
tenant_id: string; // 租户ID
|
||||
shop_id?: string; // 店铺ID
|
||||
business_type: 'TOC' | 'TOB'; // 业务类型
|
||||
module: string; // 模块名称
|
||||
created_at: string; // 创建时间
|
||||
updated_at: string; // 更新时间
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 6.4 日志存储方案
|
||||
|
||||
| 方案 | 适用场景 | 说明 |
|
||||
|------|----------|------|
|
||||
| **MySQL** | 中小规模 | 使用JSON字段存储，支持索引查询 |
|
||||
| **MongoDB** | 大规模 | 原生JSON支持，高性能写入 |
|
||||
| **Elasticsearch** | 日志分析 | 全文搜索、聚合分析、可视化 |
|
||||
|
||||
### 6.5 日志查询API
|
||||
|
||||
```typescript
|
||||
// 查询日志
|
||||
GET /api/v1/logs/ai-decision
|
||||
?operation_id=20260319-001
|
||||
&trace_id=xxx
|
||||
&operator=admin
|
||||
&status=success
|
||||
&start_date=2026-03-01
|
||||
&end_date=2026-03-19
|
||||
&page=1
|
||||
&page_size=20
|
||||
|
||||
// 日志统计
|
||||
GET /api/v1/logs/ai-decision/stats
|
||||
?module=pricing
|
||||
&period=daily
|
||||
```
|
||||
|
||||
### 6.6 日志安全
|
||||
|
||||
- **访问控制**：只有ADMIN和FINANCE角色可查看完整日志
|
||||
- **数据脱敏**：敏感字段（价格、利润）根据权限脱敏显示
|
||||
- **审计追踪**：日志查询操作本身也被记录
|
||||
|
||||
---
|
||||
|
||||
## 7. 自动化程度配置（Automation Level Config）
|
||||
|
||||
> **说明**：定义AI决策自动化程度的配置规范，支持渐进式自动化演进。
|
||||
|
||||
### 7.1 自动化等级
|
||||
|
||||
| 等级 | 名称 | AI角色 | 人类角色 | 适用场景 |
|
||||
|------|------|--------|----------|----------|
|
||||
| **L1** | 辅助决策 | 建议生成 | 全部确认 | 高风险操作 |
|
||||
| **L2** | 部分自动 | 低风险自动 | 高风险确认 | 常规操作 |
|
||||
| **L3** | 有条件自动 | 大部分自动 | 异常介入 | 成熟业务 |
|
||||
| **L4** | 高度自动 | 全链路决策 | 仅监控 | 低风险高频 |
|
||||
|
||||
### 7.2 自动执行阈值配置
|
||||
|
||||
```typescript
|
||||
interface AutoExecutionConfig {
|
||||
module: string; // 模块名称
|
||||
enabled: boolean; // 是否启用自动执行
|
||||
min_confidence: number; // 最低置信度阈值 (默认0.85)
|
||||
max_risk_level: 'low' | 'medium'; // 最大允许风险等级
|
||||
daily_limit?: number; // 每日自动执行上限
|
||||
require_review_actions: string[]; // 必须人工审核的操作
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 模块默认配置
|
||||
|
||||
| 模块 | 默认等级 | 置信度阈值 | 风险限制 |
|
||||
|------|----------|------------|----------|
|
||||
| 定价调整 | L2 | 0.90 | low |
|
||||
| 库存补货 | L2 | 0.85 | low, medium |
|
||||
| 广告投放 | L3 | 0.80 | low, medium |
|
||||
| 订单处理 | L3 | 0.85 | low |
|
||||
| 财务操作 | L1 | 1.00 | - (全部人工) |
|
||||
| 退款审批 | L1 | 1.00 | - (全部人工) |
|
||||
|
||||
---
|
||||
|
||||
*本架构文档遵循 Crawlful Hub 项目规范，所有系统设计必须遵守逻辑集中化原则。*
|
||||
|
||||
Reference in New Issue
Block a user