chore: 清理归档文件和文档模板

删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
2026-03-18 01:21:15 +08:00
parent 56b8a2e2f8
commit 72cd7f6f45
147 changed files with 5982 additions and 16716 deletions
--- a/docs/00_Business/Business_ClosedLoops.md
+++ b/docs/00_Business/Business_ClosedLoops.md
@@ -1,6 +1,6 @@
 # 📌 Crawlful Hub 业务闭环（TOC + TOB Unified Business Loops）

-> **说明**：本闭环文档是战略层业务流程，关注“做什么、为什么做、顺序和决策点”，为下层模块功能和系统实现提供指引。TOC（零售/前端）和 TOB（B2B贸易）共享通用模块，特有流程用 `businessType` 标记。
+> **说明**：本闭环文档是战略层业务流程，关注"做什么、为什么做、顺序和决策点"，为下层模块功能和系统实现提供指引。TOC（零售/前端）和 TOB（B2B贸易）共享通用模块，特有流程用 `businessType` 标记。共 **35个业务闭环**。

 ## 📑 目录

@@ -34,6 +34,11 @@
 28. [利润核算闭环](#2️⃣8️⃣-利润核算闭环profit-calculation-loop)
 29. [用户/客户资产闭环](#2️⃣9️⃣-用户客户资产闭环usercustomer-asset-loop)
 30. [A/B测试与策略优化闭环](#3️⃣0️⃣-ab测试与策略优化闭环ab-testing--strategy-optimization-loop)
+31. [多商户入驻与认证闭环](#3️⃣1️⃣-多商户入驻与认证闭环merchant-registration--authentication-loop)
+32. [功能模块化与权限控制闭环](#3️⃣2️⃣-功能模块化与权限控制闭环feature-modularization--permission-control-loop)
+33. [功能开通与支付闭环](#3️⃣3️⃣-功能开通与支付闭环feature-activation--payment-loop)
+34. [多商户结算与财务闭环](#3️⃣4️⃣-多商户结算与财务闭环multi-merchant-settlement--finance-loop)
+35. [多商户商品与订单管理闭环](#3️⃣5️⃣-多商户商品与订单管理闭环multi-merchant-product--order-management-loop)
 31. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
 32. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
 33. [关键绩效指标](#📊-关键绩效指标kpi)
@@ -46,12 +51,26 @@
 ## 1️⃣ 数据采集与清洗闭环（Product Data Collection & Cleansing）

 - **目标**：收集多平台商品信息，确保数据完整、有效、可用于盈利分析（TOC）或报价计算（TOB）。
+- **采集策略矩阵**：
+
+| 平台类型 | 采集方式 | 执行位置 | 登录要求 | 反爬策略 |
+|----------|----------|----------|----------|----------|
+| **有API平台** (Amazon MWS, eBay API) | 官方API | 后端 | OAuth/密钥 | 频率限制 |
+| **无API平台** (TikTok Shop, Temu) | 浏览器插件 | 插件 | 需登录 | 指纹隔离+IP代理 |
+| **公开数据** (1688公开页) | 浏览器插件 | 插件 | 无需登录 | 频率控制 |
+| **需登录数据** (供应商后台) | 浏览器插件 | 插件 | 需登录 | 店铺隔离 |
+
 - **流程**：
  1. **多平台采集**：
-     - TOC：抓取 Amazon、eBay、Shopee、1688 等平台商品信息。
-     - TOB：抓取供应商报价、批发价格、企业定制产品信息。
-     - 支持 API 对接和爬虫采集。
-     - 采集字段：标题、价格、库存、SKU、图片、描述、评价、供应商信息（TOB）。
+     - **有API平台**（Amazon MWS、eBay API、Shopee Open API）：
+       - 后端通过官方API获取数据
+       - 使用 `PlatformApiService` 统一对接
+       - 支持 OAuth 认证和密钥管理
+     - **无API平台**（TikTok Shop、Temu、部分1688页面）：
+       - **严禁后端直接爬取**（IP封禁风险、法律合规）
+       - 通过浏览器插件在用户端采集
+       - 插件使用店铺隔离环境（独立指纹+代理IP）
+     - **采集字段**：标题、价格、库存、SKU、图片、描述、评价、供应商信息（TOB）
  2. **数据清洗**：
     - 去重：平台+productId 唯一约束
     - 格式化：统一字段格式和单位
@@ -66,6 +85,19 @@
  - TOB：B2B 利润率 < 15% 禁止报价
 - **输入**：平台商品原始数据
 - **输出**：清洗后的可售商品/报价数据，包含完整套利/利润分析
+- **⚠️ 重要约束**：
+  - **后端严禁直接爬取电商平台页面**（IP封禁、法律风险）
+  - 所有网页级采集必须通过浏览器插件在用户端执行
+  - 插件必须实现店铺隔离（一店一IP一指纹）
+
+- **📋 技术实现指引**：
+  | 层级 | 实现模块 | 关键文件 | 任务ID |
+  |------|----------|----------|--------|
+  | 后端 | 平台API对接 | `PlatformApiService.ts` | BE-P005, BE-P006, BE-P007 |
+  | 后端 | 数据清洗引擎 | `DataPipelineService.ts` | DT-P001, DT-P002 |
+  | 插件 | 网页采集器 | `crawlerService.ts` | PL-C001, PL-C002 |
+  | 插件 | DOM解析 | `amazonCrawler.ts`, `tiktokCrawler.ts` | PL-C002 |
+  | AI | 套利分析 | `ArbitrageService.ts` | AI-A001 |

 ***

@@ -322,6 +354,49 @@
  2. 自动化落地，提高效率与可扩展性
  3. 支持多云部署，增强业务弹性和成本优化能力

+- **📋 技术实现指引**：
+  | 层级 | 实现模块 | 关键文件 | 任务ID |
+  |------|----------|----------|--------|
+  | 后端 | 店铺隔离管理 | `ShopIsolationService.ts` | BE-G003 |
+  | 后端 | 云镜像管理 | `CloudInstanceService.ts` | BE-G003 |
+  | 后端 | 任务调度器 | `TaskScheduler.ts` | BE-G003 |
+  | 插件 | 浏览器指纹管理 | `fingerprintService.ts` | PL-A001 |
+  | 插件 | 代理IP管理 | `proxyService.ts` | PL-A001 |
+  | 插件 | 自动化执行器 | `automationService.ts` | PL-A001, PL-A002 |
+  | 运维 | 健康监控 | `HealthMonitor.ts` | OP-M001 |
+
+- **🔗 插件管理架构**：
+  ```
+  ┌─────────────────────────────────────────────────────────────┐
+  │                    插件生命周期管理                          │
+  ├─────────────────────────────────────────────────────────────┤
+  │                                                              │
+  │  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
+  │  │   安装/更新   │───►│   配置初始化  │───►│   店铺绑定    │   │
+  │  └──────────────┘    └──────────────┘    └──────────────┘   │
+  │         │                   │                   │          │
+  │         ▼                   ▼                   ▼          │
+  │  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
+  │  │  任务接收    │◄──►│   任务执行    │◄──►│   结果上报    │   │
+  │  │  (Backend)   │    │  (Extension) │    │   (Backend)   │   │
+  │  └──────────────┘    └──────────────┘    └──────────────┘   │
+  │         │                   │                   │          │
+  │         ▼                   ▼                   ▼          │
+  │  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
+  │  │   状态同步   │◄──►│   异常处理    │◄──►│   日志归档    │   │
+  │  └──────────────┘    └──────────────┘    └──────────────┘   │
+  │                                                              │
+  └─────────────────────────────────────────────────────────────┘
+  ```
+
+- **📡 插件通讯协议**：
+  | 通讯方向 | 协议 | 用途 | 消息类型 |
+  |----------|------|------|----------|
+  | 后端 → 插件 | WebSocket | 实时任务下发 | `TASK_ASSIGN`, `CONFIG_UPDATE` |
+  | 插件 → 后端 | HTTP POST | 执行结果上报 | `TASK_COMPLETE`, `TASK_FAILED` |
+  | 插件 ↔ 后端 | HTTP GET | 状态查询/心跳 | `HEARTBEAT`, `STATUS_QUERY` |
+  | 插件内部 | Chrome Message | 组件间通讯 | `CRAWL_DATA`, `AUTO_ACTION` |
+
 ***

 ## 1️⃣8️⃣ 订单集中管理闭环（Order Centralized Management Loop）
@@ -918,11 +993,198 @@
 | 测试覆盖率   | 覆盖的业务策略比例    | TOC + TOB |
 | 决策支持准确率 | 测试结果对决策的支持程度 | TOC + TOB |

+#### 多商户入驻与认证闭环
+
+| KPI 指标   | 描述           | 适用业务类型    |
+| -------- | ------------ | --------- |
+| 入驻转化率    | 注册到入驻成功的比例   | TOC + TOB |
+| 资质审核时效   | 资质审核的平均时间    | TOC + TOB |
+| 认证通过率    | 通过认证的商户比例    | TOC + TOB |
+| 店铺绑定成功率  | 成功绑定平台店铺的比例  | TOC + TOB |
+| 商户活跃度    | 商户月活跃比例      | TOC + TOB |
+
+#### 功能模块化与权限控制闭环
+
+| KPI 指标   | 描述           | 适用业务类型    |
+| -------- | ------------ | --------- |
+| 模块使用率    | 各功能模块的使用比例   | TOC + TOB |
+| 权限配置准确率  | 权限配置的准确性     | TOC + TOB |
+| 数据隔离有效性  | 数据隔离的成功率     | TOC + TOB |
+| 功能开关响应时效 | 功能开关生效的时间    | TOC + TOB |
+| 配额利用率    | 商户使用配额的比例    | TOC + TOB |
+
+#### 功能开通与支付闭环
+
+| KPI 指标  | 描述           | 适用业务类型    |
+| ------- | ------------ | --------- |
+| 支付成功率   | 支付成功的比例      | TOC + TOB |
+| 开通时效    | 从支付到开通的时间    | TOC + TOB |
+| 续费率     | 功能到期后续费的比例   | TOC + TOB |
+| 退款率     | 申请退款的比例      | TOC + TOB |
+| 发票开具及时率 | 发票按时开具的比例    | TOC + TOB |
+
+#### 多商户结算与财务闭环
+
+| KPI 指标  | 描述           | 适用业务类型    |
+| ------- | ------------ | --------- |
+| 结算准确率   | 结算金额的准确性     | TOC + TOB |
+| 结算时效    | 从交易到结算的时间    | TOC + TOB |
+| 分润准确率   | 分润计算的准确性     | TOC + TOB |
+| 提现成功率   | 提现申请成功的比例    | TOC + TOB |
+| 对账差异率   | 财务对账的差异比例    | TOC + TOB |
+
+#### 多商户商品与订单管理闭环
+
+| KPI 指标   | 描述           | 适用业务类型    |
+| -------- | ------------ | --------- |
+| 商品审核通过率  | 通过审核的商品比例    | TOC + TOB |
+| 订单分配准确率  | 订单分配的准确性     | TOC + TOB |
+| 库存同步准确率  | 多商户库存同步的准确性  | TOC + TOB |
+| 超卖率      | 库存超卖的比例      | TOC + TOB |
+| 物流轨迹覆盖率  | 可追踪物流的订单比例   | TOC + TOB |
+
+***
+
+## 3️⃣1️⃣ 多商户入驻与认证闭环（Merchant Registration & Authentication Loop）
+
+- **目标**：支持多商户入驻、资质认证、店铺创建，实现平台化运营。
+- **流程**：
+  1. **商户注册**：
+     - 商户自助注册（邮箱/手机/企业信息）
+     - 资质文件上传（营业执照、法人身份证等）
+     - 账户类型选择（企业/个人）
+  2. **资质认证**：
+     - 自动审核 + 人工复核
+     - 企业信息验证、信用检查
+     - 行业资质合规检查
+  3. **店铺创建**：
+     - 店铺基础信息配置
+     - 绑定平台店铺（Amazon、Shopee等）
+     - 支付账户配置
+- **决策点**：
+  - 资质审核标准（行业合规、信用评级）
+  - 商户等级划分（普通/优质/战略）
+  - 入驻门槛设置
+- **输入**：商户注册信息、资质文件、企业证明
+- **输出**：商户ID、认证状态、店铺ID
+
+***
+
+## 3️⃣2️⃣ 功能模块化与权限控制闭环（Feature Modularization & Permission Control Loop）
+
+- **目标**：将系统功能模块化，支持按商户收费，精细化权限控制。
+- **流程**：
+  1. **功能模块定义**：
+     - 基础功能（商品管理、订单管理）
+     - 增值功能（广告投放、数据分析）
+     - 高级功能（API对接、定制化开发）
+  2. **模块配置**：
+     - 功能开关控制
+     - 使用配额限制
+     - 计费规则配置
+  3. **权限体系**：
+     - 角色定义（管理员、运营、财务等）
+     - 细粒度权限分配
+     - 数据隔离（租户/商户/店铺）
+- **决策点**：
+  - 模块定价策略
+  - 权限继承规则
+  - 数据隔离级别
+- **输入**：商户ID、功能需求、角色配置
+- **输出**：功能模块列表、权限配置、数据隔离规则
+
+***
+
+## 3️⃣3️⃣ 功能开通与支付闭环（Feature Activation & Payment Loop）
+
+- **目标**：商户选购功能模块、支付费用、开通服务。
+- **流程**：
+  1. **功能选购**：
+     - 展示功能模块和价格
+     - 选择订阅周期（月/季/年）
+     - 选择配套服务（培训、技术支持）
+  2. **费用计算**：
+     - 基础费用 + 增值服务费用
+     - 使用量计费（订单数、商品数等）
+     - 优惠活动计算
+  3. **支付流程**：
+     - 在线支付（支付宝、微信、银行卡）
+     - 账户余额扣款
+     - 发票开具
+  4. **服务开通**：
+     - 支付成功后自动开通
+     - 配置生效通知
+     - 服务期开始计时
+- **决策点**：
+  - 支付方式选择
+  - 发票类型（普通/增值税）
+  - 续费提醒策略
+- **输入**：商户ID、选购功能、支付方式
+- **输出**：开通记录、支付凭证、服务状态
+
+***
+
+## 3️⃣4️⃣ 多商户结算与财务闭环（Multi-Merchant Settlement & Finance Loop）
+
+- **目标**：多商户资金结算、收益分润、账务核对。
+- **流程**：
+  1. **交易清算**：
+     - 订单收入汇总
+     - 平台服务费扣除
+     - 商户应得收益计算
+  2. **结算周期**：
+     - 按日/周/月结算
+     - 自动打款或申请提现
+     - 结算单生成
+  3. **分润管理**：
+     - 分润规则配置
+     - 多级分销/代理分润
+     - 分润计算与发放
+  4. **财务对账**：
+     - 商户账户流水核对
+     - 异常交易处理
+     - 财务报表生成
+- **决策点**：
+  - 结算门槛（最低提现金额）
+  - 手续费规则
+  - 账期调整
+- **输入**：交易数据、商户结算规则、分润配置
+- **输出**：结算单、账户余额、财务报表
+
+***
+
+## 3️⃣5️⃣ 多商户商品与订单管理闭环（Multi-Merchant Product & Order Management Loop）
+
+- **目标**：多商户商品上架、订单分配、库存同步管理。
+- **流程**：
+  1. **商品管理**：
+     - 商户自有商品上传
+     - 平台商品池共享
+     - 商品审核（合规、质量）
+  2. **订单分配**：
+     - 订单智能分配（有库存优先/距离优先/评分优先）
+     - 商户抢单模式
+     - 异常订单人工处理
+  3. **库存同步**：
+     - 多商户库存汇总
+     - 实时库存同步
+     - 预占/扣减机制
+  4. **多商户物流**：
+     - 商户自有物流或平台物流
+     - 物流轨迹共享
+     - 签收确认
+- **决策点**：
+  - 商品上架审核标准
+  - 订单分配策略
+  - 库存超卖防护
+- **输入**：商品数据、订单数据、库存数据
+- **输出**：商品状态、订单分配结果、物流信息
+
 ***

 ### 🔍 追踪与审计

- **追踪四元组**：
+- **追踪五元组**：
  - `tenantId`：租户 ID（业务隔离）
  - `shopId`：店铺 ID（平台/店铺隔离）
  - `taskId`：任务 ID（任务/规则触发归档）
@@ -962,3 +1224,59 @@

 ***

+### 🗄️ 数据库规范与约束
+
+#### 表命名规范
+
+| 规则 | 要求 | 示例 |
+|------|------|------|
+| **表前缀** | 所有表必须以 `cf_` 开头 | `cf_product`, `cf_order`, `cf_shop` |
+| **模块标识** | 按模块添加子前缀 | `cf_ai_` (AI模块), `cf_logistics_` (物流) |
+| **命名风格** | 小写 + 下划线分隔 | `cf_consumer_orders`, `cf_ad_campaigns` |
+
+#### 核心表清单
+
+| 表名 | 模块 | 说明 | 五元组追踪 |
+|------|------|------|------------|
+| `cf_tenant` | 租户 | 租户信息 | ✅ tenantId |
+| `cf_shop` | 店铺 | 店铺信息 | ✅ tenantId, shopId |
+| `cf_product` | 商品 | 商品主数据 | ✅ tenantId, shopId, traceId |
+| `cf_product_sku` | 商品 | SKU变体 | ✅ tenantId, shopId, traceId |
+| `cf_consumer_orders` | 订单 | C端订单 | ✅ tenantId, shopId, traceId |
+| `cf_supplier` | 供应链 | 供应商信息 | ✅ tenantId, traceId |
+| `cf_inventory` | 库存 | 库存记录 | ✅ tenantId, shopId, traceId |
+| `cf_user` | 用户 | 系统用户 | ✅ tenantId |
+| `cf_audit_log` | 审计 | 操作日志 | ✅ 五元组完整 |
+
+#### 字段规范
+
+| 字段类型 | 规范 | 禁止 |
+|----------|------|------|
+| **金额** | `decimal(10,2)` | ❌ float/double |
+| **物理属性** | 长度(cm), 重量(kg), 体积(m³) | - |
+| **JSON数据** | 序列化存储，解析后使用 | - |
+| **时间戳** | `created_at`, `updated_at` 必填 | - |
+
+#### 追踪五元组字段（所有业务表必须）
+
+```typescript
+{
+  tenantId: string;      // 租户ID - 业务隔离
+  shopId: string;        // 店铺ID - 平台/店铺隔离
+  taskId: string;        // 任务ID - 任务追踪
+  traceId: string;       // 链路追踪ID - 全链路唯一
+  businessType: 'TOC' | 'TOB';  // 业务类型
+}
+```
+
+#### 数据完整性约束
+
+| 约束 | 要求 |
+|------|------|
+| **唯一约束** | `cf_product` 表必须保证 (platform, productId) 唯一 |
+| **外键约束** | 关键关联必须建立外键 |
+| **幂等性** | 所有建表语句必须使用 `db.schema.hasTable` 前置校验 |
+| **安全约束** | **⚠️ 严禁** 执行 `DROP`, `TRUNCATE` 等破坏性操作 |
+
+***
+