makemd/docs/01_Architecture/07_SEMANTIC_HUB.md

# 语义中心（Semantic Hub）

> 统一全局语义定义，确保AI开发的一致性和可维护性

## 1. 统一数据字典

### 核心术语表

| 术语 | 定义 | 适用范围 |
|------|------|----------|
| 商户（Merchant） | 平台的注册用户，可拥有多个店铺 | 全局 |
| 用户（User） | 商户下的具体操作人员，拥有不同角色权限 | 全局 |
| 店铺（Store） | 商户在特定电商平台上的销售渠道 | 全局 |
| 商品（Product） | 可销售的具体物品，包含SKU、价格、库存等信息 | 全局 |
| 订单（Order） | 客户的购买请求，包含商品、数量、金额等信息 | 全局 |
| 子订单（SubOrder） | 主订单拆分后的单个店铺订单 | 全局 |
| 库存（Inventory） | 商品在仓库中的存储数量 | 全局 |
| 支付（Payment） | 商户或客户的资金交易 | 全局 |
| 账单（Bill） | 商户的收支记录 | 全局 |
| 结算（Settlement） | 商户的周期性资金结算 | 全局 |
| 功能（Feature） | 平台提供的可开通服务 | 全局 |
| 任务（Task） | 系统执行的具体操作，如数据同步、商品上架等 | 全局 |
| 运营代理（Agent） | 负责与各电商平台的交互操作 | 全局 |
| 平台适配器（Platform Adapter） | 对接特定电商平台的接口实现 | 全局 |
| 前端控制台（Frontend Console） | 前端管理界面，用户操作入口 | 全局 |
| 后端服务（Backend Service） | 后端业务逻辑处理服务 | 全局 |
| 第三方平台（External Platform） | 外部电商平台（Amazon、eBay等） | 全局 |

## 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. 未来演进

- 支持更多电商平台的适配
- 扩展业务规则引擎能力
- 增加机器学习模型的集成
- 提供更丰富的语义验证工具