makemd/docs/ARCHIVE/01_Architecture/01_System.md

🏗 System Architecture (Crawlful Hub)

定位：Crawlful Hub 系统架构与设计蓝图 - 包含后端、前端、插件、事件总线及项目依赖规则。 更新日期: 2026-03-17

---

1. 架构总览 (Architecture Overview)

1.1 核心目标

• 业务闭环：构建完整的跨境电商贸易管理系统。
• 高可用性：确保多渠道订单与库存同步的准确性与稳定性。

1.2 三层系统架构

• 前端控制台 (Frontend Console)：统一登录、订单管理、商品刊登、财务对账、经营报表。
• 后端服务 (Backend Service)：业务逻辑处理、数据持久化、任务调度、消息通知。
• 浏览器插件 (Browser 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 日志数据结构

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: {
    tenantId: string;            // 租户ID
    shopId?: string;             // 店铺ID
    businessType: 'TOC' | 'TOB'; // 业务类型
    module: string;               // 模块名称
    createdAt: string;           // 创建时间
    updatedAt: string;           // 更新时间
  };
}

6.4 日志存储方案

方案	适用场景	说明
MySQL	中小规模	使用JSON字段存储，支持索引查询
MongoDB	大规模	原生JSON支持，高性能写入
Elasticsearch	日志分析	全文搜索、聚合分析、可视化

6.5 日志查询API

// 查询日志
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 自动执行阈值配置

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