wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
makemd/docs/ARCHIVE/01_Architecture/07_SEMANTIC_HUB.md
wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题 
- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理
2026-03-23 12:41:35 +08:00

9.1 KiB
Raw Permalink Blame History

语义中心（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. 标准数据模型

实体关系图

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

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