feat: 实现Operation-Agent核心功能及电商平台适配器

refactor: 重构项目结构,分离server和dashboard代码
style: 统一代码风格,修复lint警告
test: 添加平台适配器工厂测试用例
ci: 更新CI/CD流程,增加语义验证和性能测试
docs: 添加语义中心文档,定义统一数据模型和状态机
This commit is contained in:
2026-03-19 15:23:56 +08:00
parent aa2cf560c6
commit 8de9ea0aaa
41 changed files with 5615 additions and 497 deletions

View File

@@ -2,6 +2,60 @@
> **说明**:本闭环文档是战略层业务流程,关注"做什么、为什么做、顺序和决策点"为下层模块功能和系统实现提供指引。TOC零售/前端)和 TOBB2B贸易共享通用模块特有流程用 `businessType` 标记。共 **58个业务闭环**。
## 🧠 系统核心架构
### 系统层级
```
前端管理面板 → 后端服务 → Operation-Agent → 平台 Adapter → 外部平台
↓ ↑
←---------- 数据回传 -----------------
```
### 核心组件
#### 1. 前端管理面板
- **操作入口**:商品采集、上架/下架、调价、店铺管理
- **状态展示**:实时操作状态、执行日志、截图回传
- **多店铺管理**:统一面板展示,独立操作流程
- **数据可视化**销售报表、ROI分析、库存监控
#### 2. 后端服务
- **数据存储**统一接收Operation-Agent回传数据
- **业务逻辑**:服务编排、状态管理、权限控制
- **AI策略**:定价策略、选品推荐、套利分析
- **报表系统**:多维度数据分析、导出功能
#### 3. SystemOrchestrator系统大脑
- **全局决策**:资源分配、任务优先级、风险控制
- **信号层**:接收店铺、商品、财务、风控等指标
- **决策层**多目标优化生成Action建议
- **执行层**通过TaskGraph执行决策
- **反馈层**:收集执行结果,优化决策模型
#### 4. TaskGraph任务依赖引擎
- **DAG有向无环图**:任务依赖关系管理
- **自动执行**:选品 → 定价 → 上架 → 广告 → 监控
- **状态管理**pending → waiting_approval → ready → running → success/failed
- **失败重试**:异常处理、指数退避
#### 5. Operation-Agent操作代理
- **轻量化守护进程**运行在VPS/客户端
- **核心操作**:采集、上架、调价、数据回传
- **平台适配**模块化Adapter支持多平台Amazon、Shopee、AliExpress、eBay、TikTok Shop等
- **监控能力**:关键位置截图、状态心跳
- **安全边界**:只执行业务操作,禁止系统级操作
- **绑定流程**:选择平台 → 提交认证信息 → 平台授权 → 店铺信息同步 → 校验与状态更新 → 测试同步
- **支持平台**
- 全球性平台Amazon、eBay、AliExpress、Shopee、Lazada、Wish、Shein、JD Worldwide、Walmart Marketplace
- 社交与直营平台TikTok Shop、Etsy、Target Plus、Newegg
- 区域性平台Cdiscount法国、Allegro波兰、Otto德国、Rakuten日本、Qoo10新加坡/日本/韩国)
#### 6. 平台Adapter
- **模块化设计**:每个平台独立实现
- **操作封装**模拟浏览器或调用API
- **数据标准化**:统一输出格式,便于后端处理
- **异常处理**:捕获错误,触发截图回传
## 📑 目录
1. [数据采集与清洗闭环](#1⃣-数据采集与清洗闭环product-data-collection--cleansing)
@@ -62,12 +116,22 @@
56. [AI动态定价系统](#5⃣6⃣-ai动态定价系统ai-dynamic-pricing-loop) 🆕
57. [多店铺管理闭环](#5⃣7⃣-多店铺管理闭环multi-shop-management-loop) 🆕
58. [多租户层级管理闭环](#5⃣8⃣-多租户层级管理闭环multi-tenant-hierarchy-loop) 🆕
59. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
60. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
61. [关键绩效指标](#📊-关键绩效指标kpi)
62. [追踪与审计](#🔍-追踪与审计)
63. [业务审核状态机](#📋-业务审核状态机)
64. [说明](#💡-说明)
59. [安全与风控闭环](#5⃣9⃣-安全与风控闭环security--risk-control-loop) 🆕
60. [用户管理与权限系统闭环](#6⃣0⃣-用户管理与权限系统闭环user-management--permission-system-loop) 🆕
61. [多租户隔离闭环](#6⃣1⃣-多租户隔离闭环multi-tenant-isolation-loop) 🆕
62. [支付与结算系统闭环](#6⃣2⃣-支付与结算系统闭环payment--settlement-system-loop) 🆕
63. [API文档与开发者工具闭环](#6⃣3⃣-api文档与开发者工具闭环api-documentation--developer-tools-loop) 🆕
64. [系统监控与运维闭环](#6⃣4⃣-系统监控与运维闭环system-monitoring--operation-loop) 🆕
65. [国际化与本地化闭环](#6⃣5⃣-国际化与本地化闭环internationalization--localization-loop) 🆕
66. [合规性与法律闭环](#6⃣6⃣-合规性与法律闭环compliance--legal-loop) 🆕
67. [技术债务管理闭环](#6⃣7⃣-技术债务管理闭环technical-debt-management-loop) 🆕
68. [用户教育与支持闭环](#6⃣8⃣-用户教育与支持闭环user-education--support-loop) 🆕
69. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
70. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
71. [关键绩效指标](#📊-关键绩效指标kpi)
72. [追踪与审计](#🔍-追踪与审计)
73. [业务审核状态机](#📋-业务审核状态机)
74. [说明](#💡-说明)
***
@@ -817,12 +881,13 @@ export default function(initialState: InitialState) {
### 🔹 统一闭环依赖TOC + TOB
```text
[数据采集] ↓[数据清洗] ↓[套利/利润评估] ↓[商品主数据] ↓[SKU变体与结构] ↓[商品刊登] ←→ [素材管理] ↓[定价与利润决策] ↓[广告/营销 (TOC) / 企业营销 (TOB)] ↓[订单履约 (OMS)] ↓[订单拆分与合并] ↓[异常订单处理] ↓[物流策略与渠道选择] ↓[库存 & WMS] ←→ [供应链 & 补货] ↓[售后逆向] ↓[资金对账] ↓[利润核算] ↓[B2B/TOB 贸易管理 (TOB)] ↓[用户/客户资产] ↓[A/B测试 & 策略优化] ↓[治理与审批中心] ↓[合规 & 证书] ↓[风控] ↓[报表 & 分析] ↺(反馈所有环节)
[Operation-Agent] → [数据采集] ↓[数据清洗] ↓[套利/利润评估] ↓[商品主数据] ↓[SKU变体与结构] ↓[商品刊登] ←→ [素材管理] ↓[定价与利润决策] ↓[广告/营销 (TOC) / 企业营销 (TOB)] ↓[订单履约 (OMS)] ↓[订单拆分与合并] ↓[异常订单处理] ↓[物流策略与渠道选择] ↓[库存 & WMS] ←→ [供应链 & 补货] ↓[售后逆向] ↓[资金对账] ↓[利润核算] ↓[B2B/TOB 贸易管理 (TOB)] ↓[用户/客户资产] ↓[A/B测试 & 策略优化] ↓[治理与审批中心] ↓[合规 & 证书] ↓[风控] ↓[报表 & 分析] ↺(反馈所有环节)
外挂条线:
外挂条线:
用户资产 ← 订单 / 售后 → 广告 / B2B
店铺健康度 ← 所有行为 → 限制商品 / 广告
店铺隔离与自动化 ← 店铺操作 → 所有店铺相关行为
Operation-Agent ← 多平台数据 → 所有跨境电商相关行为
```
**说明**
@@ -874,20 +939,243 @@ export default function(initialState: InitialState) {
36. **用户/客户资产闭环** → **广告计划与营销闭环**:提供用户画像和营销建议
37. **用户/客户资产闭环** → **B2B / TOB 贸易管理闭环**:提供企业客户信息
38. **广告计划与营销闭环** → **A/B测试与策略优化闭环**:提供广告策略数据
39. **商品刊登闭环** → **A/B测试与策略优化闭环**:提供商品定价和展示数据
40. **A/B测试与策略优化闭环** → **报表与分析闭环**:提供测试结果和优化建议
41. **所有敏感操作** → **治理与审批中心闭环**:触发审批流程
42. **治理与审批中心闭环** → **所有业务闭环**:提供审批结果
43. **订单履约闭环** → **合规与证书管理闭环**:触发证书生成
44. **合规与证书管理闭环** → **订单履约闭环**:提供合规证书
45. **所有业务闭环** → **账号/店铺健康度闭环**:提供违规记录、发货延迟、差评率、退款率等数据
46. **账号/店铺健康度闭环** → **广告计划与营销闭环**:提供是否暂停广告、降预算的决策
47. **账号/店铺健康度闭环** → **商品刊登闭环**:提供是否限制上新、下架高风险商品的决策
48. **所有店铺操作** → **店铺隔离与自动化闭环**:提供店铺操作数据
49. **店铺隔离与自动化闭环** → **所有店铺相关行为**:提供隔离环境和自动化执行能力
50. **所有闭环** → **合规与风控闭环**:提供全流程数据用于风险监控
51. **所有业务闭环** → **报表与分析闭环**:提供各闭环的输出数据用于报表生成和分析
52. **报表与分析闭环** → **所有业务闭环**:反馈数据异常、业务波动、优化建议,指导各闭环的操作调整
## 5⃣9⃣ 安全与风控闭环Security & Risk Control Loop
- **目标**:统一风控,确保系统安全和业务合规。
- **流程**
1. **风险分级**Level 1安全、Level 2中风险、Level 3高风险
2. **人机协同**AI生成建议 → 人工确认 → 执行
3. **数据安全**:统一数据回传、权限控制、操作审计
- **决策点**
- Level 1自动执行
- Level 2小规模执行 + 确认
- Level 3仅建议需人工确认
- **输入**全流程数据TOC + TOB
- **输出**:风险处理记录、规则优化
## 6⃣0⃣ 用户管理与权限系统闭环User Management & Permission System Loop
- **目标**:管理用户账户和权限,确保系统安全和数据隔离。
- **流程**
1. **用户管理**:注册、登录、个人信息管理、商户管理
2. **权限体系**:角色定义、权限粒度、权限分配
- **决策点**
- 角色权限分配
- 数据访问控制
- **输入**:用户信息、角色信息、权限信息
- **输出**:用户账户、权限配置、访问控制结果
## 6⃣1⃣ 多租户隔离闭环Multi-Tenant Isolation Loop
- **目标**:实现商户→部门→店铺三层架构的数据隔离和权限控制。
- **流程**
1. **数据隔离**数据库级、Schema级、表级隔离
2. **资源隔离**:计算资源、存储资源、网络资源隔离
3. **租户配置**:独立配置、品牌定制、业务规则
- **决策点**
- 隔离级别选择
- 资源配额管理
- **输入**:租户信息、店铺信息、资源配置
- **输出**:隔离环境、配置管理、资源监控
## 6⃣2⃣ 支付与结算系统闭环Payment & Settlement System Loop
- **目标**:管理支付流程和商户结算,确保财务透明。
- **流程**
1. **支付管理**:支付网关集成、支付流程、退款处理
2. **账单与结算**:账单生成、结算周期、结算流程、税务处理
- **决策点**
- 支付方式选择
- 结算周期设置
- **输入**:订单数据、支付信息、商户信息
- **输出**:支付记录、账单、结算结果
## 6⃣3⃣ API文档与开发者工具闭环API Documentation & Developer Tools Loop
- **目标**提供标准化的API接口和开发者工具支持第三方集成。
- **流程**
1. **API管理**RESTful API设计、API文档、版本控制
2. **开发者工具**SDK、开发者门户、Webhook
- **决策点**
- API版本管理
- 开发者权限控制
- **输入**API需求、开发者信息
- **输出**API文档、SDK、开发者工具
## 6⃣4⃣ 系统监控与运维闭环System Monitoring & Operation Loop
- **目标**:监控系统健康状态,确保系统稳定运行。
- **流程**
1. **监控体系**:系统健康、性能监控、异常监控
2. **日志管理**:集中化日志、日志分析、告警机制
3. **运维工具**:自动化部署、配置管理、灾备方案
- **决策点**
- 监控阈值设置
- 告警策略配置
- **输入**:系统数据、日志数据、监控指标
- **输出**:监控报告、告警通知、运维操作记录
## 6⃣5⃣ 国际化与本地化闭环Internationalization & Localization Loop
- **目标**:支持多语言和地区规则,适应全球业务需求。
- **流程**
1. **多语言支持**:界面多语言、内容翻译
2. **本地化配置**:时区处理、地区规则、货币与单位
- **决策点**
- 语言支持范围
- 本地化规则适配
- **输入**:语言资源、地区规则
- **输出**:多语言界面、本地化配置
## 6⃣6⃣ 合规性与法律闭环Compliance & Legal Loop
- **目标**:确保业务合规,符合数据隐私和平台规则要求。
- **流程**
1. **数据隐私**GDPR合规、CCPA合规、数据保护
2. **平台规则**:电商平台合规、市场规范
3. **合同管理**:商户协议、条款管理
- **决策点**
- 合规策略制定
- 合同条款审核
- **输入**:用户数据、平台规则、合同模板
- **输出**:合规报告、合同文档、隐私政策
## 6⃣7⃣ 技术债务管理闭环Technical Debt Management Loop
- **目标**:管理技术债务,确保代码质量和系统可维护性。
- **流程**
1. **代码质量**:代码规范、代码审查、单元测试
2. **技术栈管理**:依赖管理、技术选型
3. **架构演进**:架构评估、技术债务识别与管理
- **决策点**
- 技术栈更新策略
- 代码质量标准
- **输入**:代码库、依赖信息、架构文档
- **输出**:代码质量报告、技术债务评估、架构优化建议
## 6⃣8⃣ 用户教育与支持闭环User Education & Support Loop 🆕
- **目标**:提供全面的用户教育和支持,提高用户体验和系统使用效率。
- **流程**
1. **文档与培训**:用户文档、培训课程、视频教程
2. **支持系统**:客服工单、知识库、在线支持
3. **反馈机制**:用户反馈、功能投票
- **决策点**
- 培训内容设计
- 支持优先级设置
- 反馈处理流程
- **输入**:用户需求、系统功能、用户反馈
- **输出**:用户文档、培训材料、支持工单处理结果、功能优化建议
***
## 6⃣9⃣ Operation-Agent 管理闭环Operation-Agent Management Loop 🆕
- **目标**:统一管理多平台跨境店铺,实现数据聚合、订单管理、商品同步、价格控制和报表分析闭环。
- **流程**
1. **店铺绑定**
- 选择平台 → 提交认证信息 → 平台授权 → 店铺信息同步 → 校验与状态更新 → 测试同步
2. **商品管理**
- 商品抓取:自动或手动同步平台商品信息
- 上架/下架:可选择单个平台操作或全平台同步
- 商品信息修改:价格、库存、标题、描述、图片统一管理
- 商品分类与标签:统一标准,便于分析和报表生成
3. **订单管理**
- 订单抓取:按时间/状态抓取多平台订单
- 订单处理:统一查看、标记发货、取消、退款
- 订单回写:状态更新自动同步至各平台
4. **库存与价格管理**
- 库存同步:实时或定时同步各平台库存
- 价格管理支持统一定价、浮动定价、AI推荐价格
- 异常提示:库存不足、价格冲突等提醒
5. **报表与分析**
- 商品报表:库存、销量、价格变动历史
- 订单报表:各平台销售汇总、退货率、利润计算
- AI分析定价建议、套利机会、热销商品推荐
- 导出格式CSV / JSON / Excel
- **决策点**
- 平台选择:根据业务需求选择合适的跨境电商平台
- 绑定策略API、插件或Node-Agent接入方式
- 定价策略:基于成本、市场和竞争情况
- **输入**
- 平台认证信息API Key、授权Token等
- 商品数据、订单数据、库存数据
- 成本数据、运费数据、税费数据
- **输出**
- 聚合店铺管理界面
- 统一的商品、订单、库存数据
- 分析报表和AI决策建议
- **技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| --- | --- | --- | --- |
| 后端 | Operation-Agent管理 | `OperationAgentService.ts` | BE-AGENT001 |
| 后端 | 店铺绑定服务 | `ShopBindingService.ts` | BE-AGENT002 |
| 后端 | 数据聚合服务 | `DataAggregationService.ts` | BE-AGENT003 |
| 前端 | 聚合管理面板 | `OperationAgentDashboard.tsx` | FE-AGENT001 |
| 前端 | 店铺管理页面 | `ShopManagementPage.tsx` | FE-AGENT002 |
| 前端 | 商品管理页面 | `ProductManagementPage.tsx` | FE-AGENT003 |
- **状态变化**
- 店铺绑定:`PENDING` → `AUTHORIZING` → `SYNCHRONIZING` → `ACTIVE` / `FAILED`
- 商品管理:`RAW` → `SYNCHRONIZED` → `UPDATED`
- 订单管理:`PULLED` → `PROCESSED` → `SHIPPED` → `COMPLETED`
***
## 6⃣8⃣ 用户教育与支持闭环User Education & Support Loop 🆕
- **目标**:提供用户教育和支持,提高用户满意度和系统使用率。
- **流程**
1. **文档与培训**:用户文档、培训课程、视频教程
2. **支持系统**:客服工单、知识库、在线支持
3. **反馈机制**:用户反馈、功能投票
- **决策点**
- 培训内容设计
- 支持优先级设置
- **输入**:用户需求、系统功能、反馈信息
- **输出**:用户文档、培训资料、支持记录、反馈处理结果
***
### 🔗 闭环依赖关系TOC + TOB
1. **数据采集与清洗闭环** → **商品主数据闭环**:提供原始商品数据
2. **数据采集与清洗闭环** → **素材管理闭环**:提供采集的商品图片和视频素材
3. **数据采集与清洗闭环** → **定价与利润决策闭环**:提供成本和市场数据
4. **商品主数据闭环** → **SKU变体与结构闭环**:提供商品基础信息
5. **SKU变体与结构闭环** → **商品刊登闭环**:提供结构化的商品信息
6. **素材管理闭环** → **商品刊登闭环**:提供商品图片和视频素材
7. **商品刊登闭环** → **订单履约闭环**:提供已刊登商品信息
8. **订单履约闭环** → **库存与仓储管理闭环**:触发库存扣减
9. **订单履约闭环** → **售后逆向闭环**:触发售后处理
10. **售后逆向闭环** → **库存与仓储管理闭环**:触发库存回补
11. **订单履约闭环** → **资金对账闭环**:提供订单交易数据
12. **售后逆向闭环** → **资金对账闭环**:提供售后退款数据
13. **库存与仓储管理闭环** → **供应链与供应商管理闭环**:触发补货
14. **供应链与供应商管理闭环** → **库存与仓储管理闭环**:提供采购入库数据
15. **资金对账闭环** → **利润核算闭环**:提供财务数据
16. **商品刊登闭环** → **广告计划与营销闭环**:提供已刊登商品信息
17. **广告计划与营销闭环** → **订单履约闭环**:增加订单量
18. **订单履约闭环** → **用户/客户资产闭环**:提供订单数据
19. **用户/客户资产闭环** → **广告计划与营销闭环**:提供用户画像和行为数据
20. **商品刊登闭环** → **A/B测试与策略优化闭环**:提供商品定价和展示数据
21. **A/B测试与策略优化闭环** → **报表与分析闭环**:提供测试结果和优化建议
22. **所有敏感操作** → **治理与审批中心闭环**:触发审批流程
23. **治理与审批中心闭环** → **所有业务闭环**:提供审批结果
24. **订单履约闭环** → **合规与证书管理闭环**:触发证书生成
25. **合规与证书管理闭环** → **订单履约闭环**:提供合规证书
26. **所有业务闭环** → **账号/店铺健康度闭环**:提供违规记录、发货延迟、差评率、退款率等数据
27. **账号/店铺健康度闭环** → **广告计划与营销闭环**:提供是否暂停广告、降预算的决策
28. **账号/店铺健康度闭环** → **商品刊登闭环**:提供是否限制上新、下架高风险商品的决策
29. **所有店铺操作** → **店铺隔离与自动化闭环**:提供店铺操作数据
30. **店铺隔离与自动化闭环** → **所有店铺相关行为**:提供隔离环境和自动化执行能力
31. **所有闭环** → **合规与风控闭环**:提供全流程数据用于风险监控
32. **所有业务闭环** → **报表与分析闭环**:提供各闭环的输出数据用于报表生成和分析
33. **报表与分析闭环** → **所有业务闭环**:反馈数据异常、业务波动、优化建议,指导各闭环的操作调整
34. **Operation-Agent 管理闭环** → **数据采集与清洗闭环**:提供多平台商品数据
35. **Operation-Agent 管理闭环** → **订单履约闭环**:提供多平台订单数据
36. **Operation-Agent 管理闭环** → **库存与仓储管理闭环**:提供多平台库存数据
37. **Operation-Agent 管理闭环** → **报表与分析闭环**:提供聚合数据用于分析
***
@@ -963,6 +1251,16 @@ export default function(initialState: InitialState) {
| 仓储操作效率 | 每单处理时间 | TOC + TOB |
| 跨仓调拨时效 | 调拨完成时间 | TOC + TOB |
#### Operation-Agent 管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ------------- | --------- |
| 店铺绑定成功率 | 成功绑定的店铺比例 | TOC + TOB |
| 数据同步时效 | 数据同步完成的平均时间 | TOC + TOB |
| 平台覆盖度 | 已绑定平台占目标平台的比例 | TOC + TOB |
| 操作成功率 | 成功执行的操作比例 | TOC + TOB |
| 异常处理率 | 自动处理的异常比例 | TOC + TOB |
#### 供应链与供应商管理闭环
| KPI 指标 | 描述 | 适用业务类型 |