feat: 添加货币和汇率管理功能
refactor: 重构前端路由和登录逻辑 docs: 更新业务闭环、任务和架构文档 style: 调整代码格式和文件结构 chore: 更新依赖项和配置文件
This commit is contained in:
222
docs/01_Architecture/01_System.md
Normal file
222
docs/01_Architecture/01_System.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 🏗 System Architecture (Crawlful Hub)
|
||||
|
||||
> **定位**：Crawlful Hub 系统架构与设计蓝图 - 包含后端、前端、插件、事件总线及项目依赖规则。
|
||||
> **更新日期**: 2026-03-17
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构总览 (Architecture Overview)
|
||||
|
||||
### 1.1 核心目标
|
||||
- **业务闭环**：构建完整的跨境电商贸易管理系统。
|
||||
- **高可用性**：确保多渠道订单与库存同步的准确性与稳定性。
|
||||
|
||||
### 1.2 三层系统架构
|
||||
- **Console (前端中控台)**：统一登录、订单管理、商品刊登、财务对账、经营报表。
|
||||
- **Hub (后端服务层)**：业务逻辑处理、数据持久化、任务调度、消息通知。
|
||||
- **Extension (边缘执行层)**：
|
||||
- 插件负责轻量采集、DOM 解析与自动化执行；
|
||||
- 负责指纹隔离与环境自检。
|
||||
|
||||
---
|
||||
|
||||
## 2. 后端技术架构 (Backend Infra)
|
||||
|
||||
### 2.1 技术栈与目录
|
||||
- **Runtime**: Node.js v20+, TypeScript (Strict Mode).
|
||||
- **Domains (领域)**: Trade, Finance, Product, Logistics, Supplier.
|
||||
- **Service (逻辑)**: 领域操作、仓储协调、定价计算。
|
||||
- **Repository (存储)**: 数据库查询 (Knex.js)、缓存策略 (Redis)。
|
||||
|
||||
### 2.2 事件总线架构 (Event Bus)
|
||||
- **机制**: 异步通信、削峰填谷、系统解耦。
|
||||
- **应用**: 跨域同步（如：订单创建后触发库存预留、财务预记账）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 前端与插件设计 (Frontend & Extension)
|
||||
|
||||
### 3.1 前端控制台 (Console)
|
||||
- **核心模式**: 业务审核工作流 (Business-Review-Workflow)。
|
||||
- **状态管理**: **Zustand** (全局状态) + **TanStack Query** (服务端缓存)。
|
||||
- **全链路溯源**: 每一笔操作必须绑定 `traceId`，UI 可视化操作链路。
|
||||
|
||||
### 3.2 插件端 (Extension)
|
||||
- **采集引擎**: 多平台适配器 (1688, Amazon, Shopee)。
|
||||
- **执行逻辑**: 接收 Hub 指令，在浏览器侧模拟点击、填充表单。
|
||||
- **安全**: 独立 Proxy 配置、指纹隔离、速率限制。
|
||||
|
||||
---
|
||||
|
||||
## 4. 项目结构与依赖规则 (Project Structure)
|
||||
|
||||
### 4.1 允许的依赖方向 (Allowed)
|
||||
- `API` → `Service` → `Repository` → `Models`
|
||||
- `Service` → `Utils`
|
||||
- `Domains` → `Service`
|
||||
|
||||
### 4.2 禁止的依赖方向 (Forbidden)
|
||||
- **Repository ✗ Service**: 下层不能依赖上层。
|
||||
- **API ✗ Repository**: 接口层严禁直接操作数据库。
|
||||
- **Service ✗ API**: 业务逻辑层不应感知 HTTP 请求。
|
||||
|
||||
---
|
||||
|
||||
## 5. 关键状态机与流程 (State Machines)
|
||||
|
||||
- **有 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