# 🏗 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 项目规范，所有系统设计必须遵守逻辑集中化原则。*