makemd/docs/01_Architecture/SEMANTIC_HUB.md

语义中心（Semantic Hub）

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

1. 统一数据字典

核心术语表

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

2. 标准数据模型

实体关系图

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层
• 状态变更必须记录操作日志

统一状态机

商户状态

stateDiagram
    [*] --> pending
    pending --> active : 审核通过
    pending --> inactive : 审核拒绝
    active --> inactive : 手动停用
    active --> suspended : 违规/逾期
    suspended --> active : 恢复
    suspended --> inactive : 永久停用
    inactive --> [*]

店铺状态

stateDiagram
    [*] --> pending
    pending --> active : 绑定成功
    pending --> inactive : 绑定失败
    active --> inactive : 手动停用
    active --> suspended : 平台违规
    suspended --> active : 恢复
    suspended --> inactive : 永久停用
    inactive --> [*]

订单状态

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 --> [*]

任务状态

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（删除）

统一响应格式

{
  "code": "SUCCESS",
  "message": "操作成功",
  "data": { ... },
  "timestamp": "2026-03-19T00:00:00Z",
  "requestId": "uuid"
}

错误响应格式

{
  "code": "ERROR_CODE",
  "message": "错误描述",
  "data": null,
  "timestamp": "2026-03-19T00:00:00Z",
  "requestId": "uuid"
}

6. 业务规则引擎

规则定义格式

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

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