wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(terminology): 统一术语标准并优化代码类型安全

Browse Source 
- 将B2B统一为TOB术语
- 将状态值统一为大写格式
- 优化类型声明，避免使用any
- 将float类型替换为decimal以提高精度
- 新增术语标准化文档
- 优化路由结构和菜单分类
- 添加TypeORM实体类
- 增强加密模块安全性
- 重构前端路由结构
- 完善任务模板和验收标准
This commit is contained in:
wurenzhi
2026-03-20 09:43:50 +08:00
parent eafa1bbe94
commit 48a78137c5
132 changed files with 13767 additions and 2140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/01_Architecture/00_Architecture_Index.md
View File

@@ -1,40 +1,15 @@
# 架构文档索引
> **模块**: 01_Architecture - 系统架构设计
> **更新日期**: 2026-03-19
> **更新日期**: 2026-03-21
---
## 核心架构
## 架构文档概览
| 文档 | 描述 | 状态 |
|------|------|------|
| [01_System](01_System.md) | 整体系统架构设计，包含技术栈和部署架构 | ✅ |
| [02_Integration](02_Integration.md) | 系统集成方案，包含第三方服务集成 | ✅ |
| [03_Domain_Model](03_Domain_Model.md) | 领域驱动设计，核心业务实体关系 | ✅ |
| [04_Service_Map](04_Service_Map.md) | 服务映射关系，依赖拓扑图 | ✅ |
| [05_Module_Blueprints](05_Module_Blueprints.md) | 模块蓝图设计规范 | ✅ |
架构文档包含系统架构、状态机、服务地图等核心设计文档，详细内容请参考全局文档索引。
## 架构模式与规范
| 文档 | 描述 | 状态 |
|------|------|------|
| [06_State_Machine](06_State_Machine.md) | 状态机设计规范 | ✅ |
| [07_SEMANTIC_HUB](07_SEMANTIC_HUB.md) | 语义中心架构设计 | ✅ |
| [08_BILLING_RULES](08_BILLING_RULES.md) | 计费规则架构 | ✅ |
| [09_PERMISSION_RULES](09_PERMISSION_RULES.md) | 权限规则架构 | ✅ |
| [10_Currency_Management](10_Currency_Management.md) | 货币管理架构 | ✅ |
| [11_Mock_Architecture](11_Mock_Architecture.md) | 模拟数据架构 | ✅ |
| [12_Operation_Agent](12_Operation_Agent.md) | 运营Agent架构 | ✅ |
## 前端架构
| 文档 | 描述 | 状态 |
|------|------|------|
| [frontend/01_Product](frontend/01_Product.md) | 产品模块前端架构 | ✅ |
| [frontend/02_Orders](frontend/02_Orders.md) | 订单模块前端架构 | ✅ |
| [frontend/03_Ad](frontend/03_Ad.md) | 广告模块前端架构 | ✅ |
| [frontend/04_IndependentSite](frontend/04_IndependentSite.md) | 独立站前端架构 | ✅ |
> **详细文档索引**：请参考 [全局文档索引](../10_Documents_Global/DOC_INDEX.md)
---
@@ -48,4 +23,5 @@
## 最近更新
- 2026-03-21: 简化文档索引，引用全局DOC_INDEX.md
- 2026-03-19: 重构架构文档结构，统一命名规范

16
docs/01_Architecture/01_System.md
View File

@@ -12,9 +12,9 @@
- **高可用性**：确保多渠道订单与库存同步的准确性与稳定性。
### 1.2 三层系统架构
- **Console (前端中控台)**：统一登录、订单管理、商品刊登、财务对账、经营报表。
- **Hub (后端服务层)**：业务逻辑处理、数据持久化、任务调度、消息通知。
- **Extension (边缘执行层)**：
- **前端控制台 (Frontend Console)**：统一登录、订单管理、商品刊登、财务对账、经营报表。
- **后端服务 (Backend Service)**：业务逻辑处理、数据持久化、任务调度、消息通知。
- **浏览器插件 (Browser Extension)**：
- 插件负责轻量采集、DOM 解析与自动化执行；
- 负责指纹隔离与环境自检。
@@ -134,12 +134,12 @@ interface AIDecisionLog {
// 元数据
metadata: {
tenant_id: string; // 租户ID
shop_id?: string; // 店铺ID
business_type: 'TOC' | 'TOB'; // 业务类型
tenantId: string; // 租户ID
shopId?: string; // 店铺ID
businessType: 'TOC' | 'TOB'; // 业务类型
module: string; // 模块名称
created_at: string; // 创建时间
updated_at: string; // 更新时间
createdAt: string; // 创建时间
updatedAt: string; // 更新时间
};
}
```

116
docs/01_Architecture/06_State_Machine.md
View File

@@ -2,51 +2,51 @@
## Merchant（商户）状态
pending
→ active
→ inactive
→ suspended
PENDING
→ ACTIVE
→ INACTIVE
→ SUSPENDED
---
## User（用户）状态
pending
→ active
→ inactive
→ locked
PENDING
→ ACTIVE
→ INACTIVE
→ LOCKED
---
## Store（店铺）状态
pending
→ active
→ inactive
→ suspended
PENDING
→ ACTIVE
→ INACTIVE
→ SUSPENDED
---
## Feature（功能）状态
inactive
→ pending_payment
→ active
→ expired
→ suspended
INACTIVE
→ PENDING_PAYMENT
→ ACTIVE
→ EXPIRED
→ SUSPENDED
---
## Order（订单）状态
pending
→ paid
→ split
→ processing
→ shipped
→ completed
→ refunded
→ cancelled
PENDING
→ PAID
→ SPLIT
→ PROCESSING
→ SHIPPED
→ COMPLETED
→ REFUNDED
→ CANCELLED
---
@@ -62,69 +62,69 @@ PENDING
## SubOrder（子订单）状态
pending
→ processing
→ shipped
→ completed
→ refunded
→ cancelled
PENDING
→ PROCESSING
→ SHIPPED
→ COMPLETED
→ REFUNDED
→ CANCELLED
---
## Product（商品）状态
draft
→ pending_approval
→ active
→ inactive
→ discontinued
DRAFT
→ PENDING_APPROVAL
→ ACTIVE
→ INACTIVE
→ DISCONTINUED
---
## Inventory（库存）状态
normal
→ low
→ out_of_stock
→ overstock
NORMAL
→ LOW
→ OUT_OF_STOCK
→ OVERSTOCK
---
## Payment（支付）状态
created
→ processing
→ paid
→ failed
→ refunded
CREATED
→ PROCESSING
→ PAID
→ FAILED
→ REFUNDED
---
## Bill（账单）状态
pending
→ confirmed
→ settled
→ disputed
PENDING
→ CONFIRMED
→ SETTLED
→ DISPUTED
---
## Settlement（结算）状态
pending
→ processing
→ completed
→ failed
PENDING
→ PROCESSING
→ COMPLETED
→ FAILED
---
## Task（任务）状态
pending
→ running
→ success
→ failed
→ cancelled
PENDING
→ RUNNING
→ SUCCESS
→ FAILED
→ CANCELLED
---

5
docs/01_Architecture/07_SEMANTIC_HUB.md
View File

@@ -20,8 +20,11 @@
| 结算（Settlement） | 商户的周期性资金结算 | 全局 |
| 功能（Feature） | 平台提供的可开通服务 | 全局 |
| 任务（Task） | 系统执行的具体操作，如数据同步、商品上架等 | 全局 |
| Operation-Agent | 操作代理，负责与各电商平台的交互 | 全局 |
| 运营代理（Agent） | 负责与各电商平台的交互操作 | 全局 |
| 平台适配器（Platform Adapter） | 对接特定电商平台的接口实现 | 全局 |
| 前端控制台（Frontend Console） | 前端管理界面，用户操作入口 | 全局 |
| 后端服务（Backend Service） | 后端业务逻辑处理服务 | 全局 |
| 第三方平台（External Platform） | 外部电商平台（Amazon、eBay等） | 全局 |
## 2. 标准数据模型

66
docs/01_Architecture/12_Operation_Agent.md
View File

@@ -1,32 +1,32 @@
# Operation-Agent 架构设计与实现
# 运营代理（Agent）架构设计与实现
## 1. 核心架构
### 1.1 系统层级
```
前端管理面板 → 后端服务 → Operation-Agent → 平台 Adapter → 外部平台
↓ ↑
←---------- 数据回传 -----------------
前端控制台（Frontend Console） → 后端服务（Backend Service） → 运营代理（Agent） → 平台适配器（Platform Adapter） → 第三方平台（External Platform）
↓ ↑
←-------------------------- 数据回传 -------------------------------------------
```
### 1.2 核心组件
- **前端管理面板**：操作入口、状态展示、多店铺管理、数据可视化
- **后端服务**：数据存储、业务逻辑、AI策略、报表系统
- **Operation-Agent**：轻量化守护进程、核心操作、平台适配、监控能力
- **平台Adapter**：模块化设计、操作封装、数据标准化、异常处理
- **前端控制台（Frontend Console）**：操作入口、状态展示、多店铺管理、数据可视化
- **后端服务（Backend Service）**：数据存储、业务逻辑、AI策略、报表系统
- **运营代理（Agent）**：轻量化守护进程、核心操作、平台适配、监控能力
- **平台适配器（Platform Adapter）**：模块化设计、操作封装、数据标准化、异常处理
## 2. 浏览器插件实现方案
### 2.1 架构
```
浏览器插件 → 插件后台脚本 → 平台适配器 → 外部平台
↓ ↑
←------------ 数据回传 ------------
浏览器插件 → 插件后台脚本 → 平台适配器（Platform Adapter） → 第三方平台（External Platform）
↓ ↑
←-------------------- 数据回传 -------------------------
```
### 2.2 核心组件
- **插件后台脚本**：替代Operation-Agent的守护进程
- **平台适配器**：保留现有的`IPlatformAdapter`接口，扩展以支持浏览器环境
- **插件后台脚本**：替代运营代理（Agent）的守护进程
- **平台适配器（Platform Adapter）**：保留现有的`IPlatformAdapter`接口，扩展以支持浏览器环境
- **数据存储**：使用浏览器的`chrome.storage`存储配置和状态
- **用户界面**：实现浏览器插件的弹出页面
@@ -39,9 +39,9 @@
### 3.1 架构
```
后端服务 → Operation-Agent（无界面后台服务） → 平台 Adapter → 外部平台
↑ ↓
←--------------- 数据回传与状态更新 ---------------
后端服务（Backend Service） → 运营代理（Agent）（无界面后台服务） → 平台适配器（Platform Adapter） → 第三方平台（External Platform）
↑ ↓
←---------------------- 数据回传与状态更新 ---------------------
```
### 3.2 核心组件
@@ -60,13 +60,13 @@
### 4.1 架构
```
前端管理面板 ←→ 后端服务 ←→ Operation-Agent（远程浏览器） ←→ 平台 Adapter ←→ 外部平台
↑ ↑
←-------- 实时屏幕传输与操作 ---------→
前端控制台（Frontend Console） ←→ 后端服务（Backend Service） ←→ 运营代理（Agent）（远程浏览器） ←→ 平台适配器（Platform Adapter） ←→ 第三方平台（External Platform）
↑ ↑
←--------------------- 实时屏幕传输与操作 ------------------------------→
```
### 4.2 核心组件
- **远程浏览器管理**：Operation-Agent启动受控浏览器实例，捕获浏览器屏幕并编码传输
- **远程浏览器管理**：运营代理（Agent）启动受控浏览器实例，捕获浏览器屏幕并编码传输
- **实时通信层**：WebRTC或WebSocket实现实时屏幕传输
- **前端交互界面**：实时显示远程浏览器屏幕，捕获用户操作
- **会话管理**：远程交互会话的创建和管理，权限控制和安全验证
@@ -88,18 +88,18 @@
### 5.1 架构
```
前端管理面板 ←→ 后端服务 ←→ Agent管理服务 ←→ Operation-Agent实例集群
↓
负载均衡/调度
↓
┌─────────────┼─────────────┐
↓ ↓ ↓
VPS1 (IP1) VPS2 (IP2) VPS3 (IP3)
┌────────┐ ┌────────┐ ┌────────┐
│Agent 1 │ │Agent 2 │ │Agent 3 │
└────────┘ └────────┘ └────────┘
↓ ↓ ↓
多店铺管理 同平台隔离 多店铺管理
前端控制台（Frontend Console） ←→ 后端服务（Backend Service） ←→ Agent管理服务 ←→ 运营代理（Agent）实例集群
↓
负载均衡/调度
↓
┌─────────────────────┼─────────────────────┐
↓ ↓ ↓
VPS1 (IP1) VPS2 (IP2) VPS3 (IP3)
┌────────┐ ┌────────┐ ┌────────┐
│Agent 1 │ │Agent 2 │ │Agent 3 │
└────────┘ └────────┘ └────────┘
↓ ↓ ↓
多店铺管理 同平台隔离 多店铺管理
```
### 5.2 VPS控制模式
@@ -146,6 +146,6 @@
## 7. 总结
Operation-Agent是一个强大的跨境电商平台集成解决方案，通过灵活的架构设计和多种实现方案，可以满足不同场景下的需求。从浏览器插件到无界面后台服务，从远程人工交互到多店铺管理，Operation-Agent提供了一套完整的工具链，帮助商家高效管理多平台店铺，提高运营效率和竞争力。
运营代理（Agent）是一个强大的跨境电商平台集成解决方案，通过灵活的架构设计和多种实现方案，可以满足不同场景下的需求。从浏览器插件到无界面后台服务，从远程人工交互到多店铺管理，运营代理（Agent）提供了一套完整的工具链，帮助商家高效管理多平台店铺，提高运营效率和竞争力。
在实际商业化运营中，需要根据具体的业务需求、技术能力和成本预算选择合适的实现方案，并不断优化和改进，以适应不断变化的市场环境和平台规则。