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

refactor: 重构项目结构，分离server和dashboard代码 style: 统一代码风格，修复lint警告 test: 添加平台适配器工厂测试用例 ci: 更新CI/CD流程，增加语义验证和性能测试 docs: 添加语义中心文档，定义统一数据模型和状态机
2026-03-19 15:23:56 +08:00
parent aa2cf560c6
commit 8de9ea0aaa
41 changed files with 5615 additions and 497 deletions
--- a/docs/01_Architecture/SEMANTIC_HUB.md
+++ b/docs/01_Architecture/SEMANTIC_HUB.md
@@ -0,0 +1,335 @@
+# 语义中心（Semantic Hub）
+
+> 统一全局语义定义，确保AI开发的一致性和可维护性
+
+## 1. 统一数据字典
+
+### 核心术语表
+
+| 术语 | 定义 | 适用范围 |
+|------|------|----------|
+| 商户（Merchant） | 平台的注册用户，可拥有多个店铺 | 全局 |
+| 用户（User） | 商户下的具体操作人员，拥有不同角色权限 | 全局 |
+| 店铺（Store） | 商户在特定电商平台上的销售渠道 | 全局 |
+| 商品（Product） | 可销售的具体物品，包含SKU、价格、库存等信息 | 全局 |
+| 订单（Order） | 客户的购买请求，包含商品、数量、金额等信息 | 全局 |
+| 子订单（SubOrder） | 主订单拆分后的单个店铺订单 | 全局 |
+| 库存（Inventory） | 商品在仓库中的存储数量 | 全局 |
+| 支付（Payment） | 商户或客户的资金交易 | 全局 |
+| 账单（Bill） | 商户的收支记录 | 全局 |
+| 结算（Settlement） | 商户的周期性资金结算 | 全局 |
+| 功能（Feature） | 平台提供的可开通服务 | 全局 |
+| 任务（Task） | 系统执行的具体操作，如数据同步、商品上架等 | 全局 |
+| Operation-Agent | 操作代理，负责与各电商平台的交互 | 全局 |
+| 平台适配器（Platform Adapter） | 对接特定电商平台的接口实现 | 全局 |
+
+## 2. 标准数据模型
+
+### 实体关系图
+
+```mermaid
+erDiagram
+    Merchant ||--o{ User : has
+    Merchant ||--o{ Store : manages
+    Merchant ||--o{ Order : places
+    Merchant ||--o{ Product : sells
+    Merchant ||--o{ Inventory : owns
+    Merchant ||--o{ Payment : makes
+    Merchant ||--o{ Bill : receives
+    Merchant ||--o{ Settlement : processes
+    Merchant ||--o{ MerchantFeature : subscribes
+    
+    Store ||--o{ Product : lists
+    Store ||--o{ SubOrder : fulfills
+    
+    Order ||--o{ SubOrder : splits
+    
+    Product ||--o{ Inventory : has
+    
+    Feature ||--o{ MerchantFeature : is_subscribed
+```
+
+### 数据模型规范
+
+#### 通用字段
+
+| 字段名 | 数据类型 | 描述 | 适用实体 |
+|--------|----------|------|----------|
+| id | UUID | 唯一标识符 | 所有实体 |
+| created_at | Timestamp | 创建时间 | 所有实体 |
+| updated_at | Timestamp | 更新时间 | 所有实体 |
+| status | String | 状态 | 所有实体 |
+
+#### 商户（Merchant）
+
+| 字段名 | 数据类型 | 描述 | 约束 |
+|--------|----------|------|--------|
+| name | String | 商户名称 | 必填 |
+| business_type | String | 业务类型（B2B/B2C） | 必填 |
+| contact_person | String | 联系人 | 必填 |
+| contact_email | String | 联系邮箱 | 必填，邮箱格式 |
+| contact_phone | String | 联系电话 | 必填 |
+| address | String | 地址 | 可选 |
+
+#### 店铺（Store）
+
+| 字段名 | 数据类型 | 描述 | 约束 |
+|--------|----------|------|--------|
+| merchant_id | UUID | 商户ID | 必填 |
+| name | String | 店铺名称 | 必填 |
+| platform | String | 电商平台 | 必填 |
+| platform_shop_id | String | 平台店铺ID | 必填 |
+| description | String | 店铺描述 | 可选 |
+
+#### 商品（Product）
+
+| 字段名 | 数据类型 | 描述 | 约束 |
+|--------|----------|------|--------|
+| merchant_id | UUID | 商户ID | 必填 |
+| store_id | UUID | 店铺ID | 必填 |
+| name | String | 商品名称 | 必填 |
+| sku | String | 商品SKU | 必填 |
+| price | Decimal(10,2) | 商品价格 | 必填，大于0 |
+| stock | Integer | 商品库存 | 必填，大于等于0 |
+
+#### 订单（Order）
+
+| 字段名 | 数据类型 | 描述 | 约束 |
+|--------|----------|------|--------|
+| user_id | UUID | 用户ID | 必填 |
+| merchant_id | UUID | 商户ID | 必填 |
+| total_amount | Decimal(10,2) | 订单总金额 | 必填，大于0 |
+| shipping_address | JSON | 收货地址 | 必填 |
+| payment_method | String | 支付方式 | 必填 |
+
+## 3. 状态机统一
+
+### 状态定义规范
+
+- 状态名称使用小写蛇形命名法
+- 状态流转必须符合预定义路径
+- 状态变更必须通过Service层
+- 状态变更必须记录操作日志
+
+### 统一状态机
+
+#### 商户状态
+
+```mermaid
+stateDiagram
+    [*] --> pending
+    pending --> active : 审核通过
+    pending --> inactive : 审核拒绝
+    active --> inactive : 手动停用
+    active --> suspended : 违规/逾期
+    suspended --> active : 恢复
+    suspended --> inactive : 永久停用
+    inactive --> [*]
+```
+
+#### 店铺状态
+
+```mermaid
+stateDiagram
+    [*] --> pending
+    pending --> active : 绑定成功
+    pending --> inactive : 绑定失败
+    active --> inactive : 手动停用
+    active --> suspended : 平台违规
+    suspended --> active : 恢复
+    suspended --> inactive : 永久停用
+    inactive --> [*]
+```
+
+#### 订单状态
+
+```mermaid
+stateDiagram
+    [*] --> pending
+    pending --> paid : 支付成功
+    pending --> cancelled : 取消订单
+    paid --> processing : 开始处理
+    processing --> split : 拆分订单
+    split --> shipping : 准备发货
+    shipping --> shipped : 已发货
+    shipped --> completed : 已完成
+    processing --> refunded : 退款
+    shipping --> refunded : 退款
+    shipped --> refunded : 退款
+    cancelled --> [*]
+    completed --> [*]
+    refunded --> [*]
+```
+
+#### 任务状态
+
+```mermaid
+stateDiagram
+    [*] --> pending
+    pending --> running : 开始执行
+    running --> success : 执行成功
+    running --> failed : 执行失败
+    running --> cancelled : 取消执行
+    success --> [*]
+    failed --> [*]
+    cancelled --> [*]
+```
+
+## 4. 错误码体系
+
+### 错误码结构
+
+```
+[模块]-[类型]-[编号]
+```
+
+- 模块：如MERCHANT、STORE、PRODUCT、ORDER等
+- 类型：如VALIDATION、AUTH、SYSTEM、BUSINESS等
+- 编号：3位数字，从001开始
+
+### 通用错误码
+
+| 错误码 | 描述 | HTTP状态码 |
+|--------|------|------------|
+| SYSTEM-ERROR-001 | 系统内部错误 | 500 |
+| SYSTEM-ERROR-002 | 数据库错误 | 500 |
+| AUTH-ERROR-001 | 认证失败 | 401 |
+| AUTH-ERROR-002 | 权限不足 | 403 |
+| VALIDATION-ERROR-001 | 参数验证失败 | 400 |
+| VALIDATION-ERROR-002 | 数据格式错误 | 400 |
+
+### 业务错误码
+
+| 错误码 | 描述 | HTTP状态码 |
+|--------|------|------------|
+| MERCHANT-ERROR-001 | 商户不存在 | 404 |
+| MERCHANT-ERROR-002 | 商户状态异常 | 400 |
+| STORE-ERROR-001 | 店铺不存在 | 404 |
+| STORE-ERROR-002 | 店铺绑定失败 | 400 |
+| PRODUCT-ERROR-001 | 商品不存在 | 404 |
+| PRODUCT-ERROR-002 | 商品库存不足 | 400 |
+| ORDER-ERROR-001 | 订单不存在 | 404 |
+| ORDER-ERROR-002 | 订单状态异常 | 400 |
+| OPERATION-ERROR-001 | 操作执行失败 | 400 |
+| OPERATION-ERROR-002 | 平台API调用失败 | 400 |
+
+## 5. API规范
+
+### 接口命名规范
+
+- 使用RESTful风格
+- 资源名称使用复数形式
+- 操作使用HTTP方法：GET（查询）、POST（创建）、PUT（更新）、DELETE（删除）
+
+### 统一响应格式
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "操作成功",
+  "data": { ... },
+  "timestamp": "2026-03-19T00:00:00Z",
+  "requestId": "uuid"
+}
+```
+
+### 错误响应格式
+
+```json
+{
+  "code": "ERROR_CODE",
+  "message": "错误描述",
+  "data": null,
+  "timestamp": "2026-03-19T00:00:00Z",
+  "requestId": "uuid"
+}
+```
+
+## 6. 业务规则引擎
+
+### 规则定义格式
+
+```json
+{
+  "ruleId": "PRICING_RULE_001",
+  "name": "定价规则",
+  "description": "基于成本和利润率的定价规则",
+  "conditions": [
+    {
+      "field": "cost",
+      "operator": ">",
+      "value": 100
+    },
+    {
+      "field": "category",
+      "operator": "in",
+      "value": ["electronics", "clothing"]
+    }
+  ],
+  "actions": [
+    {
+      "type": "calculate",
+      "formula": "cost * (1 + margin)"
+    }
+  ],
+  "priority": 10
+}
+```
+
+### 规则执行流程
+
+1. 规则匹配：根据输入数据匹配适用规则
+2. 规则排序：按优先级排序规则
+3. 规则执行：依次执行规则动作
+4. 结果返回：返回执行结果
+
+## 7. 版本管理
+
+### 语义版本控制
+
+- 主版本：重大变更，不兼容旧版本
+- 次版本：新增功能，兼容旧版本
+- 补丁版本：bug修复，兼容旧版本
+
+### 变更记录
+
+| 版本 | 变更内容 | 日期 |
+|------|----------|------|
+| 1.0.0 | 初始版本 | 2026-03-19 |
+
+## 8. 验证工具
+
+### 语义验证
+
+- 数据模型验证：确保数据符合模型定义
+- 状态流转验证：确保状态变更符合规则
+- API规范验证：确保API符合接口规范
+
+### 验证流程
+
+1. 代码提交前验证
+2. CI/CD流水线验证
+3. 部署前验证
+
+## 9. 使用指南
+
+### 开发者指南
+
+1. 参考语义中心定义开发代码
+2. 使用统一的数据模型和状态机
+3. 遵循API规范和错误码体系
+4. 利用业务规则引擎实现业务逻辑
+
+### AI开发指南
+
+1. 读取语义中心定义作为开发基础
+2. 生成符合规范的代码
+3. 自动验证代码符合语义规范
+4. 持续监控和优化代码质量
+
+## 10. 未来演进
+
+- 支持更多电商平台的适配
+- 扩展业务规则引擎能力
+- 增加机器学习模型的集成
+- 提供更丰富的语义验证工具