wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加货币和汇率管理功能

Browse Source 
refactor: 重构前端路由和登录逻辑

docs: 更新业务闭环、任务和架构文档

style: 调整代码格式和文件结构

chore: 更新依赖项和配置文件
This commit is contained in:
wurenzhi
2026-03-19 19:08:15 +08:00
parent 8de9ea0aaa
commit eafa1bbe94
203 changed files with 20240 additions and 39580 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/01_Architecture/00_Architecture_Index.md Normal file
View File

@@ -0,0 +1,51 @@
# 架构文档索引
> **模块**: 01_Architecture - 系统架构设计
> **更新日期**: 2026-03-19
---
## 核心架构
| 文档 | 描述 | 状态 |
|------|------|------|
| [01_System](01_System.md) | 整体系统架构设计，包含技术栈和部署架构 | ✅ |
| [02_Integration](02_Integration.md) | 系统集成方案，包含第三方服务集成 | ✅ |
| [03_Domain_Model](03_Domain_Model.md) | 领域驱动设计，核心业务实体关系 | ✅ |
| [04_Service_Map](04_Service_Map.md) | 服务映射关系，依赖拓扑图 | ✅ |
| [05_Module_Blueprints](05_Module_Blueprints.md) | 模块蓝图设计规范 | ✅ |
## 架构模式与规范
| 文档 | 描述 | 状态 |
|------|------|------|
| [06_State_Machine](06_State_Machine.md) | 状态机设计规范 | ✅ |
| [07_SEMANTIC_HUB](07_SEMANTIC_HUB.md) | 语义中心架构设计 | ✅ |
| [08_BILLING_RULES](08_BILLING_RULES.md) | 计费规则架构 | ✅ |
| [09_PERMISSION_RULES](09_PERMISSION_RULES.md) | 权限规则架构 | ✅ |
| [10_Currency_Management](10_Currency_Management.md) | 货币管理架构 | ✅ |
| [11_Mock_Architecture](11_Mock_Architecture.md) | 模拟数据架构 | ✅ |
| [12_Operation_Agent](12_Operation_Agent.md) | 运营Agent架构 | ✅ |
## 前端架构
| 文档 | 描述 | 状态 |
|------|------|------|
| [frontend/01_Product](frontend/01_Product.md) | 产品模块前端架构 | ✅ |
| [frontend/02_Orders](frontend/02_Orders.md) | 订单模块前端架构 | ✅ |
| [frontend/03_Ad](frontend/03_Ad.md) | 广告模块前端架构 | ✅ |
| [frontend/04_IndependentSite](frontend/04_IndependentSite.md) | 独立站前端架构 | ✅ |
---
## 关联模块
- [业务模块](../00_Business/Business_Blueprint.md)
- [后端模块](../02_Backend/00_Backend_Index.md)
- [前端模块](../03_Frontend/00_Frontend_Index.md)
---
## 最近更新
- 2026-03-19: 重构架构文档结构，统一命名规范

0
docs/01_Architecture/System_Architecture.md → docs/01_Architecture/01_System.md
View File

557
docs/01_Architecture/02_System_Interoperability.md Normal file
View File

@@ -0,0 +1,557 @@
# 系统互通架构（System Interoperability Architecture）
> 本文档定义 Crawlful Hub 系统各组件之间的互通机制和通信规范。
## 1. 互通架构总览
### 1.1 核心互通模型
```
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ 前端控制台 │────▶│ 后端服务 │────▶│ 运营代理（Agent） │
│ (Frontend Console) │◀────│ (Backend Service) │◀────│ (Operation Agent) │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
│
▼
┌─────────────────────┐
│ 平台适配器 │
│ (Platform Adapter) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 第三方平台 │
│ (External Platform) │
└─────────────────────┘
```
### 1.2 互通层次
| 互通层次 | 通信协议 | 说明 |
|---------|---------|------|
| 前端与后端互通 | RESTful API、WebSocket | 前端控制台与后端服务的通信 |
| 后端与Agent互通 | WebSocket、消息队列（MQ） | 后端服务与运营代理的通信 |
| Agent与平台互通 | 平台API、浏览器自动化 | 运营代理与第三方平台的通信 |
## 2. 前端与后端互通
### 2.1 API通信
| 项目 | 规范 |
|------|------|
| **基础API** | RESTful风格，支持CRUD操作 |
| **认证机制** | JWT Token（JSON Web Token），支持Bearer认证 |
| **请求格式** | JSON格式，统一错误处理 |
| **响应格式** | 统一响应体结构 |
**标准响应格式**：
```json
{
"code": 200,
"message": "success",
"data": { /* 业务数据 */ },
"timestamp": "2026-03-21T10:30:00Z"
}
```
### 2.2 WebSocket通信
| 功能 | 说明 |
|------|------|
| **实时数据推送** | 店铺状态、任务进度、操作结果实时同步 |
| **事件通知** | 操作完成、异常告警、系统通知 |
| **心跳保活** | 保持连接活跃，支持断线重连机制 |
**WebSocket消息格式**：
```json
{
"type": "event|data|heartbeat",
"event": "task_completed|error|notification",
"payload": { /* 消息内容 */ },
"timestamp": "2026-03-21T10:30:00Z"
}
```
### 2.3 前端API调用示例
```typescript
// 绑定店铺
const bindStore = async (storeData) => {
const response = await fetch('/api/operation-agent/stores', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify(storeData)
});
return response.json();
};
// 同步商品
const syncProducts = async (storeId) => {
const response = await fetch(`/api/operation-agent/stores/${storeId}/products/sync`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
}
});
return response.json();
};
```
## 3. 后端与运营代理（Agent）互通
### 3.1 WebSocket通信
| 特性 | 说明 |
|------|------|
| **双向通信** | 后端下发任务，Agent回传执行结果 |
| **加密传输** | TLS/SSL加密，确保通信安全 |
| **认证机制** | Agent注册时进行身份验证（Token-based） |
| **消息格式** | 统一JSON消息格式 |
**任务下发消息格式**：
```json
{
"type": "task",
"taskId": "task-123",
"action": "syncProducts",
"params": {
"storeId": "store-123",
"limit": 100
},
"priority": "high|normal|low",
"timeout": 300000
}
```
### 3.2 消息队列（Message Queue）
| 特性 | 说明 | 技术选型 |
|------|------|---------|
| **任务分发** | 异步任务分发，解耦前后端 | RabbitMQ / Redis / BullMQ |
| **任务优先级** | 支持高、中、低优先级任务 | Priority Queue |
| **任务持久化** | 确保任务不丢失，支持故障恢复 | Persistent Storage |
| **失败重试** | 自动重试机制，支持指数退避（Exponential Backoff） | Retry Policy |
### 3.3 状态同步
| 机制 | 说明 | 频率 |
|------|------|------|
| **心跳保活** | Agent定期发送心跳，报告运行状态 | 每30秒 |
| **状态回传** | 任务执行状态实时回传到后端 | 实时 |
| **健康检查** | 后端定期检查Agent健康状态 | 每60秒 |
### 3.4 后端API调用示例
```typescript
// 向Agent下发任务
const sendTaskToAgent = async (agentId, task) => {
const ws = getAgentWebSocket(agentId);
if (ws && ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({
type: 'task',
taskId: generateTaskId(),
action: task.action,
params: task.params
}));
} else {
// 发送到消息队列
await messageQueue.send('agent-tasks', {
agentId,
task
});
}
};
// 处理Agent回传
const handleAgentResponse = (message) => {
const data = JSON.parse(message);
switch (data.type) {
case 'task_result':
handleTaskResult(data.taskId, data.result);
break;
case 'heartbeat':
updateAgentStatus(data.agentId, data.status);
break;
case 'error':
handleAgentError(data.agentId, data.error);
break;
}
};
```
## 4. 运营代理与第三方平台互通
### 4.1 平台API调用
| 项目 | 说明 |
|------|------|
| **认证机制** | OAuth 2.0、API密钥（API Key）、签名认证等 |
| **请求格式** | 符合各平台API规范（RESTful/GraphQL） |
| **响应处理** | 统一解析和错误处理，标准化输出 |
| **速率限制** | 遵守平台API Rate Limit，实现限流保护 |
### 4.2 浏览器自动化（Browser Automation）
| 技术 | 说明 |
|------|------|
| **无界面浏览器** | Puppeteer / Playwright / Selenium |
| **操作模拟** | 点击、输入、滚动、表单提交等用户行为模拟 |
| **数据提取** | DOM解析、XPath/CSS选择器、数据抓取 |
| **异常处理** | 页面变化检测、验证码识别、反爬策略应对 |
### 4.3 适配器模式（Adapter Pattern）
| 组件 | 说明 |
|------|------|
| **统一接口** | `IPlatformAdapter` 接口定义标准操作 |
| **平台实现** | 每个平台独立实现适配器（Platform-specific Adapter） |
| **数据标准化** | 统一数据模型，标准化输出格式 |
| **错误处理** | 平台特定错误捕获、转换、上报 |
### 4.4 Agent平台调用示例
```typescript
// 使用平台适配器同步商品
async function syncProducts(storeId, platform) {
const adapter = platformAdapterFactory.createAdapter(platform);
try {
// 授权
await adapter.authorize(getAuthInfo(storeId));
// 获取商品列表
const products = await adapter.getProducts(100, 0);
// 处理商品数据
const processedProducts = processProducts(products);
// 回传数据
await sendToBackend({
type: 'products_synced',
storeId,
products: processedProducts
});
} catch (error) {
// 处理错误
await sendToBackend({
type: 'error',
storeId,
error: error.message
});
}
}
```
## 5. 远程人工交互互通
### 5.1 实时屏幕传输（Real-time Screen Streaming）
| 技术 | 说明 |
|------|------|
| **屏幕捕获** | 使用 Puppeteer / Playwright 捕获浏览器屏幕 |
| **编码压缩** | JPEG / WEBP / H.264 编码，降低传输带宽 |
| **实时传输** | WebSocket / WebRTC 实时传输屏幕数据 |
| **前端渲染** | Canvas / Video 元素渲染远程屏幕 |
### 5.2 操作指令传输（Remote Control）
| 环节 | 说明 |
|------|------|
| **操作捕获** | 前端捕获用户点击、输入、滚动等操作 |
| **坐标映射** | 将前端坐标转换为远程浏览器坐标（Resolution Mapping） |
| **指令传输** | WebSocket 传输操作指令到 Agent |
| **指令执行** | Agent 在远程浏览器执行操作指令 |
### 5.3 会话管理（Session Management）
| 功能 | 说明 |
|------|------|
| **会话创建** | 后端创建远程交互会话，分配资源 |
| **权限验证** | 验证用户权限，确保操作安全 |
| **状态跟踪** | 会话状态机：初始化 → 活跃 → 空闲 → 结束 |
| **资源清理** | 会话结束时清理资源，保存操作日志 |
### 5.4 远程交互示例
```typescript
// 前端捕获点击操作
const handleCanvasClick = (e) => {
const rect = canvas.getBoundingClientRect();
const x = e.clientX - rect.left;
const y = e.clientY - rect.top;
// 发送点击指令
ws.send(JSON.stringify({
type: 'user_action',
action: {
type: 'click',
x,
y
}
}));
};
// Agent执行操作指令
const handleUserAction = async (page, action) => {
switch (action.type) {
case 'click':
await page.mouse.click(action.x, action.y);
break;
case 'type':
await page.keyboard.type(action.text);
break;
case 'keypress':
await page.keyboard.press(action.key);
break;
}
};
```
## 6. 多Agent互通
### 6.1 Agent管理服务（Agent Management Service）
| 功能 | 说明 |
|------|------|
| **Agent注册** | Agent启动时向管理服务注册，上报元数据 |
| **资源分配** | 根据店铺需求、任务类型分配Agent资源 |
| **负载均衡** | 基于负载的任务分发（Load Balancing） |
| **健康监控** | 实时监控Agent健康状态、性能指标 |
### 6.2 Agent间通信（Inter-Agent Communication）
| 场景 | 说明 |
|------|------|
| **任务协调** | 避免多Agent操作同一店铺产生冲突 |
| **资源共享** | 共享配置、状态信息、缓存数据 |
| **故障转移** | Agent故障时自动转移任务（Failover） |
### 6.3 多VPS部署（Multi-VPS Deployment）
| 功能 | 说明 |
|------|------|
| **VPS管理** | 管理多VPS资源池，动态分配 |
| **IP隔离** | 同平台店铺使用不同IP，避免关联 |
| **网络配置** | 配置VPS网络、防火墙、代理 |
| **自动化部署** | CI/CD自动化部署和配置Agent |
### 6.4 Agent管理示例
```typescript
// 分配任务到合适的Agent
function assignTask(task) {
const store = getStoreById(task.storeId);
if (store.requiresIpIsolation) {
// 需要IP隔离的店铺，使用专用Agent
return findDedicatedAgent(store);
} else {
// 不需要IP隔离的店铺，使用负载最低的Agent
return findLeastLoadedAgent(store.platform);
}
}
// 监控Agent健康状态
function monitorAgents() {
setInterval(async () => {
const agents = await getAllAgents();
for (const agent of agents) {
if (!agent.heartbeatReceived) {
// Agent可能离线，触发故障转移
await failoverAgent(agent.id);
}
}
}, 30000); // 每30秒检查一次
}
```
## 7. 安全互通
### 7.1 认证与授权（Authentication & Authorization）
| 层级 | 机制 | 说明 |
|------|------|------|
| **API认证** | JWT Token + Refresh Token | 定期轮换，支持无感知续期 |
| **Agent认证** | API Key + HMAC签名 | 基于密钥的双向认证 |
| **权限控制** | RBAC（基于角色的访问控制） | 角色-权限-资源三级管控 |
| **操作审计** | Audit Log | 全链路操作记录，支持追溯 |
### 7.2 数据安全（Data Security）
| 措施 | 说明 |
|------|------|
| **传输加密** | TLS 1.3 / SSL，端到端加密 |
| **存储加密** | AES-256-GCM 加密敏感数据 |
| **凭证管理** | 使用密钥管理服务（KMS），禁止明文存储 |
| **数据脱敏** | API返回数据按需脱敏（PII保护） |
| **访问控制** | 细粒度权限控制，最小权限原则 |
### 7.3 网络安全（Network Security）
| 措施 | 说明 |
|------|------|
| **TLS加密** | 所有通信强制使用TLS 1.3 |
| **防火墙** | VPS防火墙 + 云防火墙双层防护 |
| **速率限制** | API限流（Rate Limiting），防止滥用 |
| **DDoS防护** | 云厂商DDoS防护 + 应用层限流 |
| **IP白名单** | 关键接口限制访问IP范围 |
### 7.4 安全最佳实践
| 实践 | 说明 |
|------|------|
| **最小权限原则** | Agent仅获取执行任务所需的最小权限 |
| **安全审计** | 定期安全审计，检查配置和代码 |
| **漏洞扫描** | 自动化漏洞扫描（SAST/DAST） |
| **依赖管理** | 及时更新依赖，修复安全漏洞 |
| **密钥轮换** | 定期轮换API密钥和证书 |
## 8. 性能优化
### 8.1 通信优化
| 优化手段 | 说明 |
|---------|------|
| **消息压缩** | Gzip / Brotli 压缩传输数据，减少带宽使用 |
| **批量处理** | 批量发送和处理数据，减少请求次数（Batch Processing） |
| **缓存策略** | Redis 缓存常用数据，减少重复请求 |
| **异步处理** | 非关键操作异步处理，提高响应速度（Async/Await） |
| **长连接** | WebSocket 长连接，减少连接建立开销 |
### 8.2 资源优化
| 资源类型 | 优化措施 |
|---------|---------|
| **连接池** | 数据库连接池、HTTP连接池，复用连接 |
| **内存管理** | 优化内存使用，避免内存泄漏，定期GC |
| **CPU优化** | 减少CPU密集型操作，使用Worker线程 |
| **磁盘I/O** | 减少磁盘I/O，使用内存缓存和SSD |
| **网络I/O** | 合并请求，使用HTTP/2或HTTP/3 |
### 8.3 监控与调优
| 环节 | 说明 |
|------|------|
| **性能监控** | APM工具（如Prometheus + Grafana）实时监控系统性能指标 |
| **瓶颈分析** | 识别性能瓶颈（CPU/内存/网络/磁盘），进行针对性优化 |
| **负载测试** | 使用JMeter/k6模拟高负载场景，测试系统性能 |
| **自动调优** | 根据负载自动调整系统参数（Auto-scaling） |
## 9. 容错与灾备（Fault Tolerance & Disaster Recovery）
### 9.1 错误处理（Error Handling）
| 机制 | 说明 |
|------|------|
| **异常捕获** | 全局异常捕获，统一错误处理（Try-Catch + Global Handler） |
| **错误重试** | 自动重试失败操作，支持指数退避（Exponential Backoff） |
| **降级策略** | 服务降级（Degradation），保障核心功能可用 |
| **错误通知** | 实时告警通知（钉钉/飞书/邮件），及时响应 |
### 9.2 故障恢复（Fault Recovery）
| 措施 | 说明 |
|------|------|
| **数据备份** | 定期全量+增量备份，异地多副本存储 |
| **灾难恢复** | 制定DR计划，RPO<1小时，RTO<4小时 |
| **高可用性** | 多Agent部署，无单点故障（HA Architecture） |
| **自动恢复** | Agent故障自动重启，任务自动重分配 |
### 9.3 容灾方案（Disaster Recovery）
| 方案 | 说明 |
|------|------|
| **多区域部署** | 多可用区（AZ）部署，避免单点故障 |
| **数据同步** | 跨区域数据实时同步，确保数据一致性 |
| **故障转移** | 自动故障转移（Automatic Failover） |
| **业务连续性** | 确保业务持续运行（Business Continuity） |
## 10. 总结
系统互通是 Crawlful Hub 的核心设计之一，通过标准化的通信机制和接口，实现了前端控制台、后端服务、运营代理（Agent）和第三方平台之间的无缝互通。这种设计不仅提高了系统的可扩展性和可维护性，也为 100% AI 开发测试落地提供了坚实的技术基础。
在实际部署中，需要根据具体的业务需求和技术环境，选择合适的互通方案，并不断优化和改进，以适应不断变化的业务需求和技术发展。
---
## 11. 互通规范
### 11.1 接口命名规范
| 项目 | 规范 |
|------|------|
| **API路径** | RESTful风格，小写字母，单词间用连字符（kebab-case）<br>示例：`/api/v1/product-management/products` |
| **方法命名** | 驼峰命名法（camelCase），动词+名词格式<br>示例：`getProductList`、`createOrder` |
| **参数命名** | 驼峰命名法（camelCase），清晰表达参数含义<br>示例：`pageSize`、`sortBy` |
### 11.2 消息格式规范
| 项目 | 规范 |
|------|------|
| **数据格式** | 所有通信使用 JSON 格式（application/json） |
| **消息结构** | 统一包含 `type`、`data`、`timestamp`、`traceId` 等字段 |
| **错误处理** | 统一错误码和错误消息格式，支持国际化（i18n） |
**标准消息格式示例**：
```json
{
"type": "event|data|error|heartbeat",
"event": "task_completed|error|notification",
"data": { /* 业务数据 */ },
"timestamp": "2026-03-21T10:30:00Z",
"traceId": "trace-123456",
"code": 200,
"message": "success"
}
```
### 11.3 安全规范
- **认证**：所有API调用必须进行身份认证
- **授权**：基于角色的访问控制
- **加密**：所有传输数据必须加密
- **审计**：所有操作必须记录审计日志
### 11.4 性能规范
- **响应时间**：API响应时间不超过500ms
- **并发处理**：支持高并发请求
- **缓存策略**：合理使用缓存减少响应时间
- **批量处理**：支持批量操作减少请求次数
## 12. 互通示例
### 12.1 完整业务流程示例
#### 商品采集流程
1. **前端**：用户选择平台，设置采集参数
2. **后端**：`ProductController`接收请求，调用`ProductService`
3. **后端**：`ProductService`生成采集任务，发送到消息队列
4. **Agent**：接收任务，调用对应平台Adapter执行采集
5. **Agent**：回传采集结果到后端
6. **后端**：`ProductService`处理采集结果，存储到数据库
7. **后端**：通过WebSocket推送采集结果到前端
8. **前端**：展示采集结果，提供后续操作入口
#### 自动上架流程
1. **前端**：用户设置上架参数，触发自动上架
2. **后端**：`AutoListingController`接收请求，调用`AutoListingService`
3. **后端**：`AutoListingService`生成上架任务，发送到消息队列
4. **Agent**：接收任务，调用平台Adapter执行上架
5. **Agent**：回传上架结果和截图到后端
6. **后端**：`AutoListingService`更新任务状态，存储上架结果
7. **后端**：通过WebSocket推送上架结果到前端
8. **前端**：展示上架状态，提供效果分析
## 13. 未来扩展
### 13.1 微服务架构
- **服务拆分**：将核心服务拆分为独立的微服务
- **服务发现**：使用服务发现机制管理服务实例
- **负载均衡**：自动负载均衡提高系统可用性
- **容错机制**：服务降级和熔断保护
### 13.2 事件驱动架构
- **事件总线**：使用消息队列实现事件驱动
- **事件溯源**：通过事件记录系统状态变更
- **CQRS**：命令查询责任分离，提高系统性能
### 13.3 边缘计算
- **边缘Agent**：在边缘节点部署Agent，减少延迟
- **本地处理**：部分计算在本地完成，减少网络传输
- **智能调度**：根据网络状况和负载自动调度任务

52
docs/01_Architecture/DOMAIN_MODEL.md → docs/01_Architecture/03_Domain_Model.md
View File

@@ -48,6 +48,58 @@
- price_type（free / paid）
- price_value
- description
---
### PlatformIntegration（平台集成）
- id
- merchant_id
- platform_name（Sellbrite / Shoplazza / SaleSmartly）
- api_key
- api_secret
- access_token
- refresh_token
- status
- created_at
- updated_at
---
### CrossBorderProduct（跨境商品）
- id
- product_id
- hs_code
- tariff_rate
- compliance_status
- country_of_origin
- weight
- dimensions
- created_at
- updated_at
---
### CustomsDocument（清关文件）
- id
- order_id
- document_type
- document_url
- status
- created_at
- updated_at
---
### CrossBorderOrder（跨境订单）
- id
- order_id
- customs_status
- shipping_status
- tracking_number
- logistics_provider
- estimated_delivery
- created_at
- updated_at
- category
---

103
docs/01_Architecture/SERVICE_MAP.md → docs/01_Architecture/04_Service_Map.md
View File

@@ -48,6 +48,23 @@ Frontend
→ PaymentService.createPayment
→ PaymentCallbackService.confirm
→ FeatureService.activateFeature
## 2. 跨境电商闭环
Flow:
Frontend
→ CrossBorderController.manageProduct
→ CrossBorderService.checkCompliance
→ CrossBorderService.calculateTariff
→ PlatformIntegrationService.integrateWithSellbrite
→ PlatformIntegrationService.integrateWithShoplazza
→ PlatformIntegrationService.integrateWithSaleSmartly
→ InventorySyncService.syncMultiPlatformInventory
→ LogisticsService.selectLogisticsChannel
→ CustomsService.generateCustomsDocuments
→ PaymentService.processCrossBorderPayment
→ MarketingService.integrateOmniChannelMarketing
→ CustomerService.manageCrossBorderCommunication
→ PermissionService.grant
→ BillingService.record
→ Response
@@ -241,3 +258,89 @@ Frontend / System
→ NotificationService.alert
→ SettlementService.adjust
→ Response
---
## 18. 多语言服务闭环
Flow:
Frontend
→ I18nController.switchLanguage
→ I18nService.setUserLanguage
→ LanguageRepository.updateUserPreference
→ Response
---
## 19. 翻译管理闭环
Flow:
Frontend / Backend
→ TranslationController.createTranslation
→ TranslationService.requestTranslation
→ ExternalTranslationApi.translate
→ TranslationService.reviewTranslation
→ TranslationRepository.save
→ I18nService.refreshLanguageCache
→ Response
---
## 20. 多语言内容发布闭环
Flow:
Frontend
→ ContentController.createContent
→ ContentService.saveContent
→ TranslationService.autoTranslate
→ TranslationService.requestReview
→ TranslationService.approveTranslation
→ ContentService.publishMultiLanguageContent
→ Response
---
## 21. 货币管理闭环
Flow:
Frontend / Backend
→ CurrencyController.getCurrencies
→ CurrencyService.getCurrencies
→ CurrencyRepository.findAll
→ Response
---
## 22. 汇率更新闭环
Flow:
Scheduler
→ ExchangeRateService.updateExchangeRates
→ ExternalExchangeRateApi.fetchRates
→ ExchangeRateRepository.save
→ RedisService.setCache
→ Response
---
## 23. 货币转换闭环
Flow:
Frontend / Backend
→ CurrencyConversionController.convert
→ CurrencyConversionService.convert
→ ExchangeRateService.getExchangeRate
→ CurrencyConversionService.calculate
→ Response
---
## 24. 多货币计算闭环
Flow:
Frontend / Backend
→ CurrencyCalculationController.calculatePrice
→ CurrencyCalculationService.calculatePrice
→ CurrencyConversionService.convert
→ PricingService.applyMarkup
→ Response

0
docs/01_Architecture/Module_Blueprints.md → docs/01_Architecture/05_Module_Blueprints.md
View File

10
docs/01_Architecture/STATE_MACHINE.md → docs/01_Architecture/06_State_Machine.md
View File

@@ -50,6 +50,16 @@ pending
---
## Cross-Border E-Commerce（跨境电商）状态
PENDING
→ PROCESSING
→ CLEARANCE
→ SHIPPING
→ DELIVERED
---
## SubOrder（子订单）状态
pending

0
docs/01_Architecture/SEMANTIC_HUB.md → docs/01_Architecture/07_SEMANTIC_HUB.md
View File

0
docs/01_Architecture/BILLING_RULES.md → docs/01_Architecture/08_BILLING_RULES.md
View File

0
docs/01_Architecture/PERMISSION_RULES.md → docs/01_Architecture/09_PERMISSION_RULES.md
View File

181
docs/01_Architecture/10_Currency_Management.md Normal file
View File

@@ -0,0 +1,181 @@
# 多国跨境货币显示方案
## 一、核心架构
### 1. 货币管理服务
- **CurrencyService**：管理支持的货币列表、货币基本信息
- **ExchangeRateService**：管理汇率数据、汇率更新、汇率缓存
- **数据模型**：
- `cf_currency`：货币基础信息（代码、名称、符号、小数位数）
- `cf_exchange_rate`：最新汇率数据
- `cf_exchange_rate_history`：汇率历史记录
### 2. 货币转换与计算服务
- **CurrencyConversionService**：处理货币间转换
- **CurrencyCalculationService**：处理价格、成本、利润等计算
- **支持的转换策略**：最新汇率、历史汇率、平均汇率、固定汇率
### 3. 货币显示与本地化
- **CurrencyFormatter**：处理货币显示格式
- **LocalizationService**：处理地区特定的显示规则
- **支持的格式**：货币符号位置、千位分隔符、小数位数、小数点符号
## 二、不同场景的货币显示方案
### 1. 报表场景
- **多货币切换**：用户可选择显示货币，系统自动换算
- **汇率选择**：可选择最新汇率、报表生成时汇率或自定义日期汇率
- **多货币并列**：支持主货币+对比货币同时显示
- **总计显示**：支持按主货币汇总，同时显示其他货币换算值
- **导出支持**：Excel/CSV导出时保持货币格式
### 2. 定价场景
- **平台本地货币**：按平台要求显示当地货币
- **目标市场货币**：显示目标客户所在地区货币
- **多货币对比**：同一商品显示多种货币价格
- **价格策略**：基于不同货币的定价策略（如区域定价）
- **动态更新**：汇率变化时自动更新价格显示
### 3. 分析场景
- **基准货币**：可设置分析基准货币
- **多货币对比**：不同货币的销售、利润对比
- **趋势分析**：汇率波动对业务的影响分析
- **预测模型**：基于汇率预测的业务预测
## 三、技术实现
### 1. 后端服务
- **CurrencyService**：管理货币数据，提供货币列表、货币信息查询
- **ExchangeRateService**：对接第三方汇率API（如Open Exchange Rates），定期更新汇率
- **CurrencyConversionService**：提供货币转换功能，支持批量转换
- **CurrencyCalculationService**：提供价格、成本、利润等计算功能
### 2. 前端实现
- **货币显示组件**：`CurrencyDisplay` 组件，支持不同显示格式
- **货币选择器**：`CurrencySelector` 组件，支持货币切换
- **本地化配置**：基于用户地区的自动货币格式
- **实时更新**：汇率变化时自动更新显示
### 3. 数据库设计
- **cf_currency**：货币基础信息表
- **cf_exchange_rate**：最新汇率表
- **cf_exchange_rate_history**：汇率历史表
### 4. API设计
- **GET /api/currencies**：获取支持的货币列表
- **GET /api/exchange-rates**：获取汇率数据
- **POST /api/currency/convert**：货币转换
- **POST /api/currency/calculate**：货币计算
## 四、集成方案
### 1. 与现有服务集成
- **产品服务**：商品价格多货币显示
- **订单服务**：订单金额多货币计算
- **财务服务**：财务报表多货币汇总
- **分析服务**：多货币数据分析
### 2. 与前端集成
- **全局货币设置**：用户偏好货币存储
- **页面级货币切换**：各页面独立货币选择
- **组件级货币显示**：统一的货币显示组件
### 3. 与第三方API集成
- **汇率API**：对接Open Exchange Rates、XE等
- **支付API**：支持多货币支付处理
## 五、性能优化
### 1. 缓存策略
- **汇率缓存**：Redis缓存汇率数据，减少API调用
- **货币格式缓存**：缓存本地化货币格式
- **计算结果缓存**：缓存常用转换结果
### 2. 批量处理
- **批量转换**：支持批量货币转换，减少API调用
- **批量计算**：支持批量价格计算
### 3. 异步更新
- **汇率异步更新**：后台定时更新汇率，不影响用户操作
- **货币数据异步同步**：后台同步货币信息
## 六、示例实现
### 后端服务示例
```typescript
// CurrencyService.ts
export class CurrencyService {
getCurrencies(): Promise<Currency[]> {
// 返回支持的货币列表
}
getCurrencyByCode(code: string): Promise<Currency> {
// 根据代码获取货币信息
}
}
// ExchangeRateService.ts
export class ExchangeRateService {
getExchangeRate(fromCurrency: string, toCurrency: string): Promise<number> {
// 获取汇率
}
updateExchangeRates(): Promise<void> {
// 从第三方API更新汇率
}
}
// CurrencyConversionService.ts
export class CurrencyConversionService {
convert(amount: number, fromCurrency: string, toCurrency: string): Promise<number> {
// 货币转换
}
}
```
### 前端组件示例
```typescript
// CurrencyDisplay.tsx
export const CurrencyDisplay: React.FC<{
amount: number;
currency: string;
formatOptions?: FormatOptions;
}> = ({ amount, currency, formatOptions }) => {
// 货币显示逻辑
return <span>{formattedAmount}</span>;
};
// CurrencySelector.tsx
export const CurrencySelector: React.FC<{
value: string;
onChange: (currency: string) => void;
}> = ({ value, onChange }) => {
// 货币选择逻辑
return <select value={value} onChange={(e) => onChange(e.target.value)}>
{currencies.map(currency => (
<option key={currency.code} value={currency.code}>
{currency.name} ({currency.symbol})
</option>
))}
</select>;
};
```
## 七、总结
本方案提供了一个完整的多国跨境货币显示解决方案，包括：
- 货币管理和汇率服务架构
- 货币显示格式和本地化策略
- 多货币转换和计算服务
- 不同场景的货币显示方案
- 技术实现和集成方案
- 性能优化策略
通过这个方案，系统可以：
- 支持全球主要货币的显示和转换
- 适应不同地区的货币显示习惯
- 提供准确的汇率数据和转换计算
- 在报表、定价、分析等场景中灵活应用
- 与现有系统无缝集成
此方案确保了多国跨境业务中货币显示的一致性、准确性和用户友好性，为全球业务拓展提供了有力支持。

0
docs/01_Architecture/Mock_Architecture.md → docs/01_Architecture/11_Mock_Architecture.md
View File

151
docs/01_Architecture/12_Operation_Agent.md Normal file
View File

@@ -0,0 +1,151 @@
# Operation-Agent 架构设计与实现
## 1. 核心架构
### 1.1 系统层级
```
前端管理面板 → 后端服务 → Operation-Agent → 平台 Adapter → 外部平台
↓ ↑
←---------- 数据回传 -----------------
```
### 1.2 核心组件
- **前端管理面板**：操作入口、状态展示、多店铺管理、数据可视化
- **后端服务**：数据存储、业务逻辑、AI策略、报表系统
- **Operation-Agent**：轻量化守护进程、核心操作、平台适配、监控能力
- **平台Adapter**：模块化设计、操作封装、数据标准化、异常处理
## 2. 浏览器插件实现方案
### 2.1 架构
```
浏览器插件 → 插件后台脚本 → 平台适配器 → 外部平台
↓ ↑
←------------ 数据回传 ------------
```
### 2.2 核心组件
- **插件后台脚本**：替代Operation-Agent的守护进程
- **平台适配器**：保留现有的`IPlatformAdapter`接口，扩展以支持浏览器环境
- **数据存储**：使用浏览器的`chrome.storage`存储配置和状态
- **用户界面**：实现浏览器插件的弹出页面
### 2.3 限制与解决方案
- **截图限制**：使用`chrome.tabs.captureVisibleTab()` API捕获当前标签页
- **文件上传限制**：通过API发送到后端服务
- **权限管理**：明确权限申请，动态权限请求
## 3. 无界面后台服务实现
### 3.1 架构
```
后端服务 → Operation-Agent（无界面后台服务） → 平台 Adapter → 外部平台
↑ ↓
←--------------- 数据回传与状态更新 ---------------
```
### 3.2 核心组件
- **无界面后台服务**：使用Node.js构建的系统服务
- **安全通信层**：与后端服务使用加密WebSocket连接
- **任务执行引擎**：队列化处理任务，支持任务优先级和依赖关系
- **错误处理系统**：自动捕获和处理错误，详细的错误日志和截图
### 3.3 技术实现
- **无界面后台服务**：使用node-windows、systemd等实现系统服务
- **安全通信**：加密WebSocket连接，双向认证机制
- **高权限操作**：系统级权限，可执行全屏截图、系统操作等
- **无界面浏览器自动化**：使用Puppeteer/Playwright进行无界面浏览器操作
## 4. 远程人工交互方案
### 4.1 架构
```
前端管理面板 ←→ 后端服务 ←→ Operation-Agent（远程浏览器） ←→ 平台 Adapter ←→ 外部平台
↑ ↑
←-------- 实时屏幕传输与操作 ---------→
```
### 4.2 核心组件
- **远程浏览器管理**：Operation-Agent启动受控浏览器实例，捕获浏览器屏幕并编码传输
- **实时通信层**：WebRTC或WebSocket实现实时屏幕传输
- **前端交互界面**：实时显示远程浏览器屏幕，捕获用户操作
- **会话管理**：远程交互会话的创建和管理，权限控制和安全验证
### 4.3 技术实现
- **远程屏幕传输**：使用Puppeteer捕获屏幕，压缩编码后传输
- **前端交互界面**：React组件实现实时屏幕显示和操作捕获
- **后端服务集成**：WebSocket处理，会话管理和任务分发
### 4.4 其他方案
- **基于云桌面的方案**：使用AWS WorkSpaces、阿里云无影等
- **基于容器的方案**：使用Docker运行浏览器容器，通过VNC提供Web界面
- **基于API的方案**：为每个平台实现API调用逻辑
- **混合方案**：根据操作类型和平台特性选择最佳执行方式
- **第三方服务集成**：使用BrowserStack、Sauce Labs等服务
- **本地代理方案**：在用户本地运行轻量级代理，通知用户完成操作
## 5. 多店铺管理与VPS控制
### 5.1 架构
```
前端管理面板 ←→ 后端服务 ←→ Agent管理服务 ←→ Operation-Agent实例集群
↓
负载均衡/调度
↓
┌─────────────┼─────────────┐
↓ ↓ ↓
VPS1 (IP1) VPS2 (IP2) VPS3 (IP3)
┌────────┐ ┌────────┐ ┌────────┐
│Agent 1 │ │Agent 2 │ │Agent 3 │
└────────┘ └────────┘ └────────┘
↓ ↓ ↓
多店铺管理 同平台隔离 多店铺管理
```
### 5.2 VPS控制模式
- **SaaS提供商控制**：全托管服务，商家无需关心VPS配置和维护
- **商家自行控制**：完全控制VPS配置、网络环境和安全策略
- **混合控制模式**：关键业务使用自管VPS，一般业务使用SaaS服务
- **第三方代理控制**：由专业代理公司提供VPS管理服务
### 5.3 类SaaS多商户架构下的VPS管理
- **平台运营方控制**：统一采购VPS，建立总VPS池，分配VPS资源
- **假admin客户管理**：管理自己名下的终端商户，在分配的VPS资源内为终端商户分配具体VPS
- **终端商户使用**：在分配的VPS上管理自己的店铺，执行商品采集、上架、调价等操作
### 5.4 技术实现
- **VPS管理系统**：资源池管理、分配策略、隔离机制、自动化部署
- **权限管理**：三级权限体系（平台运营方、假admin客户、终端商户）
- **计费系统**：多级计费，资源使用统计，账单自动生成
- **监控与告警**：VPS状态监控，异常告警，性能分析
- **灾备与恢复**：数据备份，故障恢复，冗余机制
## 6. 实现建议
### 6.1 技术选型
- **运行环境**：Node.js + Electron（跨平台）或独立的系统服务
- **浏览器自动化**：Puppeteer（支持Chrome/Chromium）或Playwright（支持多浏览器）
- **通信机制**：WebSocket + WebRTC（实时屏幕传输）
- **数据存储**：本地数据库（SQLite、LevelDB）+ 与后端服务同步
### 6.2 安全考虑
- **凭证管理**：加密存储店铺凭证，按Agent实例隔离存储，定期凭证轮换
- **错误处理**：Agent故障自动检测和切换，任务失败自动重试，异常情况告警和人工干预
- **监控与告警**：VPS资源监控，Agent健康状态监控，店铺操作异常告警
### 6.3 性能优化
- **资源分配**：根据店铺需求和操作频率合理分配VPS资源
- **任务调度**：优化任务队列和执行顺序，提高并发处理能力
- **网络优化**：使用CDN和缓存，减少网络延迟
- **代码优化**：优化浏览器自动化脚本，减少资源消耗
### 6.4 扩展性
- **模块化设计**：平台适配器和任务执行引擎的模块化设计，便于添加新平台和功能
- **水平扩展**：支持添加新的VPS和Agent实例，应对业务增长
- **API设计**：提供标准化的API接口，便于与其他系统集成
## 7. 总结
Operation-Agent是一个强大的跨境电商平台集成解决方案，通过灵活的架构设计和多种实现方案，可以满足不同场景下的需求。从浏览器插件到无界面后台服务，从远程人工交互到多店铺管理，Operation-Agent提供了一套完整的工具链，帮助商家高效管理多平台店铺，提高运营效率和竞争力。
在实际商业化运营中，需要根据具体的业务需求、技术能力和成本预算选择合适的实现方案，并不断优化和改进，以适应不断变化的市场环境和平台规则。

0
docs/01_Architecture/frontend/Product.front.md → docs/01_Architecture/frontend/01_Product.md
View File

0
docs/01_Architecture/frontend/Orders.front.md → docs/01_Architecture/frontend/02_Orders.md
View File

0
docs/01_Architecture/frontend/Ad.front.md → docs/01_Architecture/frontend/03_Ad.md
View File

0
docs/01_Architecture/frontend/IndependentSite.front.md → docs/01_Architecture/frontend/04_IndependentSite.md
View File