本版数据库快照已自动验证；接口与引用说明继承 0.0.1，请在发布前核对并补充本版业务变化。

电商系统 0.0.2 接口文档

当前版本为 0.0.1，仅提供管理端接口，统一前缀为 /admin/plugin/ecommerce。所有接口注册在 Permission 路由组，需要管理端登录令牌以及对应的 METHOD:/path 菜单权限。

通用约定

请求头：

Header	必填	说明
`Authorization`	是	`Bearer <管理端 token>`
`Content-Type`	POST 是	`application/json`

统一响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {}
}

字段	类型	说明
`code`	integer	`0` 成功；参数或业务错误返回非 0
`msg`	string	成功提示或错误原因
`data`	object/array/null	接口业务数据；无返回数据的写接口为 `null`

业务资源统一使用字符串 uid，不接受或返回数据库自增 id。金额字段使用两位小数字符串，重量和体积使用三位小数字符串。接口时间可能包含时区和毫秒，管理端统一展示为 YYYY-MM-DD HH:mm:ss。

常用枚举：

枚举	值
通用状态	`1` 启用/展示/上架，`2` 停用/下架
商品类型	`1` 普通商品，`2` 虚拟商品
规格类型	`1` 单规格，`2` 多规格
配送方式	`1` 快递配送，`2` 到店自提
运费计费方式	`1` 件数，`2` 重量，`3` 体积
订单状态	`1` 待支付，`2` 待发货，`3` 待收货，`4` 待评价，`5` 已完成，`6` 已取消，`7` 已退款
支付状态	`1` 未支付，`2` 已支付，`3` 已退款

商品分类

查询分类树

text

GET /admin/plugin/ecommerce/category/list

权限：GET:/admin/plugin/ecommerce/category/list

Query 参数	类型	必填	约束	说明
`keyword`	string	否	最长 64	分类名称关键词
`status`	integer	否	`1`、`2`	状态

响应 data 为分类树数组：

字段	类型	说明
`uid`	string	分类 UID
`parent_uid`	string	父分类 UID，顶级为空字符串
`name`	string	分类名称
`image`	string	按当前存储渠道补全的图片地址
`sort`	integer	排序值
`status`	integer	`1` 启用，`2` 停用
`created_at`	string	创建时间
`updated_at`	string	更新时间
`children`	array	子分类，字段结构相同

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "uid": "ecat8x2k4m1",
      "parent_uid": "",
      "name": "数码家电",
      "image": "https://cdn.example.com/uploads/ecommerce/category/digital.png",
      "sort": 10,
      "status": 1,
      "created_at": "2026-10-02T10:20:30.123+08:00",
      "updated_at": "2026-10-02T10:20:30.123+08:00",
      "children": [
        {
          "uid": "ecat8x2k4m2",
          "parent_uid": "ecat8x2k4m1",
          "name": "手机",
          "image": "",
          "sort": 10,
          "status": 1,
          "created_at": "2026-10-02T10:21:00+08:00",
          "updated_at": "2026-10-02T10:21:00+08:00",
          "children": []
        }
      ]
    }
  ]
}

新增或修改分类

text

POST /admin/plugin/ecommerce/category/save

权限：POST:/admin/plugin/ecommerce/category/save

Body 参数	类型	必填	约束	说明
`uid`	string	修改时是	最长 32	分类 UID；新增为空
`parent_uid`	string	否	最长 32	父分类 UID；空为顶级
`name`	string	是	最长 64	分类名称
`image`	string	否	最长 1024	上传接口返回的图片地址
`sort`	integer	是	≥ 0	排序值
`status`	integer	是	`1`、`2`	状态

json

{
  "uid": "",
  "parent_uid": "ecat8x2k4m1",
  "name": "手机",
  "image": "https://cdn.example.com/uploads/temp/phone.png",
  "sort": 10,
  "status": 1
}

成功时 data 返回保存后的完整分类对象，字段与分类列表节点一致。父分类必须存在，分类不能选择自身作为父级。

删除分类

text

POST /admin/plugin/ecommerce/category/delete

权限：POST:/admin/plugin/ecommerce/category/delete

json

{ "uid": "ecat8x2k4m2" }

Body 参数	类型	必填	说明
`uid`	string	是	分类 UID，最长 32

存在子分类或商品引用时拒绝删除。成功响应：{"code":0,"msg":"success","data":null}。

商品管理

查询商品列表

text

GET /admin/plugin/ecommerce/product/list

权限：GET:/admin/plugin/ecommerce/product/list

Query 参数	类型	必填	约束	说明
`keyword`	string	否	最长 200	商品名称或编码
`category_uid`	string	否	最长 32	分类 UID
`product_type`	integer	否	`1`、`2`	商品类型
`status`	integer	否	`1`、`2`	上架状态
`page`	integer	否	≥ 1，默认 1	页码
`page_size`	integer	否	1～100，默认 20	每页数量

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "uid": "epdt8x2k4m1",
        "category_uid": "ecat8x2k4m2",
        "category_name": "手机",
        "product_type": 1,
        "spec_type": 2,
        "name": "旗舰智能手机",
        "cover": "https://cdn.example.com/uploads/ecommerce/product/cover.png",
        "images": ["https://cdn.example.com/uploads/ecommerce/product/1.png"],
        "video": "",
        "status": 1,
        "stock": 120,
        "price": "3999.00",
        "market_price": "4299.00",
        "cost_price": "3000.00",
        "code": "PHONE-2026",
        "weight": "0.220",
        "volume": "0.001",
        "intro": "新一代旗舰手机",
        "detail": "<p>商品详情</p>",
        "delivery_modes": [1, 2],
        "shipping_template_uid": "eship8x2k4m1",
        "virtual_content": "",
        "sales_count": 20,
        "virtual_sales_count": 100,
        "specs": [],
        "skus": [],
        "created_at": "2026-10-02T11:00:00+08:00",
        "updated_at": "2026-10-02T12:00:00+08:00"
      }
    ],
    "total": 1
  }
}

商品详情响应字段

商品列表、详情和保存接口共用商品结构：

字段	类型	说明
`uid`	string	商品 UID
`category_uid` / `category_name`	string	分类 UID / 分类名称
`product_type`	integer	`1` 普通，`2` 虚拟
`spec_type`	integer	`1` 单规格，`2` 多规格
`name`	string	商品名称
`cover`	string	商品封面完整地址
`images`	array<string>	轮播图完整地址数组
`video`	string	视频完整地址
`status`	integer	`1` 上架，`2` 下架
`stock`	integer	有效 SKU 汇总库存
`price`	string	有效 SKU 最低售价
`market_price` / `cost_price`	string	划线价 / 成本价
`code`	string	商品编码
`weight` / `volume`	string	重量（kg）/ 体积（m³）
`intro`	string	商品简介
`detail`	string	富文本详情
`delivery_modes`	array<integer>	配送方式
`shipping_template_uid`	string	运费模板 UID
`virtual_content`	string	虚拟交付说明
`sales_count` / `virtual_sales_count`	integer	实际销量 / 虚拟销量
`specs`	array	规格组及规格值
`skus`	array	SKU 列表
`created_at` / `updated_at`	string	创建时间 / 更新时间

规格组字段：

字段	类型	说明
`uid`	string	规格组 UID
`name`	string	规格名称
`sort`	integer	排序
`values`	array	规格值列表
`values[].uid`	string	规格值 UID
`values[].value`	string	规格值文本
`values[].image`	string	规格值图片完整地址
`values[].sort`	integer	排序

SKU 字段：

字段	类型	说明
`uid`	string	SKU UID
`spec_value_uids`	array<string>	规格值 UID 组合
`spec_text`	string	规格展示文本
`image`	string	SKU 图片完整地址
`stock`	integer	库存
`price` / `market_price` / `cost_price`	string	售价 / 划线价 / 成本价
`code`	string	SKU 编码
`weight` / `volume`	string	重量 / 体积
`status`	integer	`1` 启用，`2` 停用

查询商品详情

text

GET /admin/plugin/ecommerce/product/detail?uid=epdt8x2k4m1

权限：GET:/admin/plugin/ecommerce/product/detail

Query 参数	类型	必填	说明
`uid`	string	是	商品 UID，最长 32

成功时 data 返回完整商品结构，并包含 specs 和 skus；不存在时返回“商品不存在”。

新增或修改商品

text

POST /admin/plugin/ecommerce/product/save

权限：POST:/admin/plugin/ecommerce/product/save

商品参数：

Body 参数	类型	必填	约束	说明
`uid`	string	修改时是	最长 32	商品 UID
`category_uid`	string	是	最长 32	启用的分类 UID
`product_type`	integer	是	`1`、`2`	商品类型
`spec_type`	integer	是	`1`、`2`	规格类型
`name`	string	是	最长 200	商品名称
`cover`	string	是	最长 1024	商品封面
`images`	array<string>	是	1～10 张，每项最长 1024	轮播图
`video`	string	否	最长 1024	商品视频
`status`	integer	是	`1`、`2`	上架状态
`code`	string	否	最长 64	商品编码
`intro`	string	否	最长 500	商品简介
`detail`	string	否	富文本	商品详情
`delivery_modes`	array<integer>	是	1～2 项，值为 `1`/`2`	配送方式
`shipping_template_uid`	string	快递商品是	最长 32	运费模板 UID
`virtual_content`	string	虚拟商品建议填写	文本	虚拟交付说明
`virtual_sales_count`	integer	是	≥ 0	虚拟销量
`specs`	array	多规格时是	见下表	规格组
`skus`	array	是	至少 1 项	SKU 列表

specs[] 与 values[]：

参数	类型	必填	约束	说明
`specs[].uid`	string	修改已有规格时否	最长 32	规格 UID
`specs[].name`	string	是	最长 64	规格名称
`specs[].sort`	integer	是	≥ 0	排序
`specs[].values`	array	是	至少 1 项	规格值
`values[].uid`	string	修改已有值时否	最长 32	规格值 UID
`values[].key`	string	是	最长 64，请求内唯一	SKU 组合临时键
`values[].value`	string	是	最长 64	规格值
`values[].image`	string	否	最长 1024	规格值图片
`values[].sort`	integer	是	≥ 0	排序

skus[]：

参数	类型	必填	约束	说明
`uid`	string	修改已有 SKU 时否	最长 32	SKU UID
`spec_value_keys`	array<string>	是	每项最长 64	对应规格值 `key` 组合
`spec_text`	string	否	最长 500	展示文本
`image`	string	否	最长 1024	SKU 图片
`stock`	integer	是	≥ 0	库存
`price`	string	是	数值	售价
`market_price`	string	是	数值	划线价
`cost_price`	string	是	数值	成本价
`code`	string	否	最长 64	SKU 编码
`weight`	string	是	数值	重量（kg）
`volume`	string	是	数值	体积（m³）
`status`	integer	是	`1`、`2`	状态

多规格请求示例：

json

{
  "uid": "",
  "category_uid": "ecat8x2k4m2",
  "product_type": 1,
  "spec_type": 2,
  "name": "旗舰智能手机",
  "cover": "https://cdn.example.com/uploads/temp/cover.png",
  "images": [
    "https://cdn.example.com/uploads/temp/1.png",
    "https://cdn.example.com/uploads/temp/2.png"
  ],
  "video": "",
  "status": 1,
  "code": "PHONE-2026",
  "intro": "新一代旗舰手机",
  "detail": "<p>商品详情</p>",
  "delivery_modes": [1, 2],
  "shipping_template_uid": "eship8x2k4m1",
  "virtual_content": "",
  "virtual_sales_count": 100,
  "specs": [
    {
      "uid": "",
      "name": "颜色",
      "sort": 10,
      "values": [
        {"uid":"","key":"color_black","value":"曜石黑","image":"","sort":10},
        {"uid":"","key":"color_white","value":"陶瓷白","image":"","sort":20}
      ]
    },
    {
      "uid": "",
      "name": "容量",
      "sort": 20,
      "values": [
        {"uid":"","key":"storage_256","value":"256GB","image":"","sort":10}
      ]
    }
  ],
  "skus": [
    {
      "uid": "",
      "spec_value_keys": ["color_black", "storage_256"],
      "spec_text": "曜石黑 / 256GB",
      "image": "",
      "stock": 60,
      "price": "3999.00",
      "market_price": "4299.00",
      "cost_price": "3000.00",
      "code": "PHONE-BLACK-256",
      "weight": "0.220",
      "volume": "0.001",
      "status": 1
    }
  ]
}

成功时 data 返回完整商品详情。服务端在同一事务内保存商品、规格、规格值和 SKU，并重新计算汇总库存与最低售价。

商品上下架

text

POST /admin/plugin/ecommerce/product/status

权限：POST:/admin/plugin/ecommerce/product/status

json

{ "uid": "epdt8x2k4m1", "status": 2 }

uid 必填且最长 32；status 只允许 1 或 2。成功返回 data: null。

删除商品

text

POST /admin/plugin/ecommerce/product/delete

权限：POST:/admin/plugin/ecommerce/product/delete

json

{ "uid": "epdt8x2k4m1" }

已有订单项引用时不能删除，只能下架。

运费模板

查询运费模板

text

GET /admin/plugin/ecommerce/shipping/list?keyword=全国&status=1

权限：GET:/admin/plugin/ecommerce/shipping/list

Query 参数	类型	必填	约束	说明
`keyword`	string	否	最长 100	模板名称
`status`	integer	否	`1`、`2`	状态

data 为数组，字段如下：

字段	类型	说明
`uid`	string	模板 UID
`name`	string	模板名称
`charge_type`	integer	`1` 件数、`2` 重量、`3` 体积
`first_unit` / `first_fee`	string	首单位 / 首费
`additional_unit` / `additional_fee`	string	续单位 / 续费
`free_amount`	string	包邮金额，`0.00` 表示不包邮
`status`	integer	状态
`created_at` / `updated_at`	string	创建 / 更新时间

json

{
  "code": 0,
  "msg": "success",
  "data": [{
    "uid":"eship8x2k4m1","name":"全国按件模板","charge_type":1,
    "first_unit":"1.000","first_fee":"8.00","additional_unit":"1.000",
    "additional_fee":"2.00","free_amount":"99.00","status":1,
    "created_at":"2026-10-02T10:00:00+08:00","updated_at":"2026-10-02T10:00:00+08:00"
  }]
}

保存运费模板

text

POST /admin/plugin/ecommerce/shipping/save

权限：POST:/admin/plugin/ecommerce/shipping/save

Body 参数	类型	必填	说明
`uid`	string	修改时是	模板 UID，最长 32
`name`	string	是	模板名称，最长 100
`charge_type`	integer	是	`1` 件数、`2` 重量、`3` 体积
`first_unit`	string	是	数值，首件/首重/首体积
`first_fee`	string	是	数值，首费
`additional_unit`	string	是	数值，续单位
`additional_fee`	string	是	数值，续费
`free_amount`	string	是	数值，`0` 表示不包邮
`status`	integer	是	`1`、`2`

json

{
  "uid":"","name":"全国按件模板","charge_type":1,"first_unit":"1",
  "first_fee":"8.00","additional_unit":"1","additional_fee":"2.00",
  "free_amount":"99.00","status":1
}

成功时返回保存后的完整运费模板对象。

删除运费模板

text

POST /admin/plugin/ecommerce/shipping/delete

权限：POST:/admin/plugin/ecommerce/shipping/delete

请求：{"uid":"eship8x2k4m1"}。被商品引用时拒绝删除。

自提门店

查询门店

text

GET /admin/plugin/ecommerce/store/list?keyword=中心店&status=1

权限：GET:/admin/plugin/ecommerce/store/list

Query 参数	类型	必填	约束	说明
`keyword`	string	否	最长 100	门店名称或电话
`status`	integer	否	`1`、`2`	状态

响应门店字段：uid、name、contact_name、phone、region、address、longitude、latitude、sort、status、created_at、updated_at。

json

{
  "code":0,"msg":"success","data":[{
    "uid":"estore8x2k4m1","name":"中心店","contact_name":"张经理",
    "phone":"13800138000","region":"四川省 成都市 武侯区","address":"示例路 88 号",
    "longitude":"104.0668000","latitude":"30.5728000","sort":10,"status":1,
    "created_at":"2026-10-02T10:00:00+08:00","updated_at":"2026-10-02T10:00:00+08:00"
  }]
}

保存门店

text

POST /admin/plugin/ecommerce/store/save

权限：POST:/admin/plugin/ecommerce/store/save

Body 参数	类型	必填	约束	说明
`uid`	string	修改时是	最长 32	门店 UID
`name`	string	是	最长 100	门店名称
`contact_name`	string	是	最长 64	联系人
`phone`	string	是	最长 32	联系电话
`region`	string	是	最长 255	省市区
`address`	string	是	最长 255	详细地址
`longitude`	string	是	数值	经度
`latitude`	string	是	数值	纬度
`sort`	integer	是	≥ 0	排序
`status`	integer	是	`1`、`2`	状态

成功时返回保存后的完整门店对象。

删除门店

text

POST /admin/plugin/ecommerce/store/delete

权限：POST:/admin/plugin/ecommerce/store/delete

请求：{"uid":"estore8x2k4m1"}。已有订单引用时拒绝删除。

订单管理

查询订单列表

text

GET /admin/plugin/ecommerce/order/list

权限：GET:/admin/plugin/ecommerce/order/list

Query 参数	类型	必填	约束	说明
`status`	integer	否	1～7	订单状态
`pay_status`	integer	否	1～3	支付状态
`delivery_type`	integer	否	`1`、`2`	配送方式
`keyword`	string	否	最长 100	订单号、用户、手机号或商品名称
`start_at`	string	否	`YYYY-MM-DD HH:mm:ss`	创建开始时间
`end_at`	string	否	`YYYY-MM-DD HH:mm:ss`	创建结束时间
`page`	integer	否	≥ 1	页码
`page_size`	integer	否	1～100	每页数量

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [{
      "uid":"eord8x2k4m1","finance_order_no":"FOeord8x2k4m1","order_no":"EC202610020001",
      "member_nickname":"小明","member_avatar":"https://cdn.example.com/avatar.png",
      "member_mobile":"138****8000","order_type":1,"delivery_type":1,
      "status":2,"pay_status":2,"pay_method":"余额支付",
      "product_amount":"3999.00","shipping_amount":"0.00","discount_amount":"100.00","pay_amount":"3899.00",
      "receiver_name":"王小明","receiver_phone":"138****8000","receiver_region":"四川省 成都市 武侯区","receiver_address":"示例路 88 号",
      "store_uid":"","store_snapshot":{},"buyer_message":"尽快发货","merchant_remark":"",
      "logistics_company_uid":"","logistics_company_name":"","tracking_no":"",
      "paid_at":"2026-10-02T12:01:00+08:00","shipped_at":null,"completed_at":null,"cancelled_at":null,
      "version":1,
      "products":[{
        "uid":"eitem8x2k4m1","product_uid":"epdt8x2k4m1","sku_uid":"esku8x2k4m1",
        "product_name":"旗舰智能手机","product_cover":"https://cdn.example.com/product.png",
        "spec_text":"曜石黑 / 256GB","product_code":"PHONE-BLACK-256",
        "price":"3999.00","quantity":1,"total_amount":"3999.00"
      }],
      "logs":[],"created_at":"2026-10-02T12:00:00+08:00","updated_at":"2026-10-02T12:01:00+08:00"
    }],
    "total": 1,
    "status_counts": {"1":3,"2":1,"3":5,"4":2,"5":20,"6":1,"7":0}
  }
}

订单字段说明：

字段	类型	说明
`uid`	string	商城订单 UID
`member_nickname` / `member_avatar` / `member_mobile`	string	用户快照
`order_type` / `delivery_type`	integer	订单类型 / 配送方式
`status` / `pay_status` / `pay_method`	integer/integer/string	订单状态、支付状态、支付方式快照
`product_amount` / `shipping_amount` / `discount_amount` / `pay_amount`	string	金额快照
`receiver_*`	string	收货信息快照
`store_uid` / `store_snapshot`	string/object	自提门店 UID 与快照
`buyer_message` / `merchant_remark`	string	买家留言 / 商家备注
`logistics_company_uid` / `logistics_company_name` / `tracking_no`	string	物流信息
`paid_at` / `shipped_at` / `completed_at` / `cancelled_at`	string/null	状态时间
`version`	integer	乐观锁版本号
`products`	array	订单商品快照
`logs`	array	详情接口返回订单日志；列表通常为空
`created_at` / `updated_at`	string	创建 / 更新时间

查询订单详情

text

GET /admin/plugin/ecommerce/order/detail?uid=eord8x2k4m1

权限：GET:/admin/plugin/ecommerce/order/detail

Query 参数	类型	必填	说明
`uid`	string	是	订单 UID，最长 32

响应 data 为完整订单对象，并返回全部 products 与 logs。日志字段：

字段	类型	说明
`uid`	string	日志 UID
`operator_type`	integer	`1` 系统、`2` 管理员、`3` 用户
`operator_name`	string	操作人名称快照
`action`	string	操作标识，如 `ship`
`from_status` / `to_status`	integer	原状态 / 新状态
`remark`	string	操作说明
`created_at`	string	操作时间

查询物流选项

text

GET /admin/plugin/ecommerce/order/logistics/options

权限：GET:/admin/plugin/ecommerce/order/logistics/options

无请求参数。只返回核心系统中已启用的物流配置：

json

{
  "code":0,"msg":"success","data":[
    {"uid":"logi8x2k4m1","name":"顺丰速运","code":"SF"}
  ]
}

订单发货

text

POST /admin/plugin/ecommerce/order/ship

权限：POST:/admin/plugin/ecommerce/order/ship

Body 参数	类型	必填	约束	说明
`uid`	string	是	最长 32	订单 UID
`logistics_company_uid`	string	是	最长 32	核心物流 UID
`logistics_company_name`	string	是	最长 100	物流公司名称
`tracking_no`	string	是	最长 100	物流单号
`version`	integer	是	≥ 1	当前订单版本号

json

{
  "uid":"eord8x2k4m1","logistics_company_uid":"logi8x2k4m1",
  "logistics_company_name":"顺丰速运","tracking_no":"SF1234567890","version":1
}

仅待发货订单允许发货。服务端通过 uid + version + status 条件原子更新订单，成功后状态变为待收货并写入订单日志；并发版本不一致时拒绝操作。

保存商家备注

text

POST /admin/plugin/ecommerce/order/remark

权限：POST:/admin/plugin/ecommerce/order/remark

Body 参数	类型	必填	说明
`uid`	string	是	订单 UID，最长 32
`remark`	string	否	商家备注，最长 500
`version`	integer	是	当前订单版本号，≥ 1

请求示例：{"uid":"eord8x2k4m1","remark":"优先发货","version":2}。

修改未支付订单实付金额

text

POST /admin/plugin/ecommerce/order/pay-amount

权限：POST:/admin/plugin/ecommerce/order/pay-amount

Body 参数	类型	必填	约束	说明
`uid`	string	是	最长 32	订单 UID
`pay_amount`	string	是	`0`～`9999999999.99`，最多两位小数	修改后的实际支付金额
`version`	integer	是	≥ 1	当前订单版本号

json

{
  "uid": "eord8x2k4m1",
  "pay_amount": "3799.00",
  "version": 1
}

只有同时满足 status=1（待支付）和 pay_status=1（未支付）的订单允许修改。服务端使用 uid + status + pay_status + version 原子更新金额并递增版本号，同时写入 adjust_pay_amount 订单操作日志，记录修改前后的金额。已支付、已取消或被其他操作更新的订单会被拒绝。成功响应：

json

{ "code": 0, "msg": "success", "data": null }

订单评价

查询评价列表

text

GET /admin/plugin/ecommerce/review/list

权限：GET:/admin/plugin/ecommerce/review/list

Query 参数	类型	必填	约束	说明
`keyword`	string	否	最长 200	商品名称、评价内容或用户昵称
`rating`	integer	否	1～5	评分
`status`	integer	否	`1`、`2`	展示状态
`page`	integer	否	≥ 1	页码
`page_size`	integer	否	1～100	每页数量

json

{
  "code":0,"msg":"success","data":{
    "list":[{
      "uid":"erev8x2k4m1","order_uid":"eord8x2k4m1","order_item_uid":"eitem8x2k4m1",
      "product_uid":"epdt8x2k4m1","product_name":"旗舰智能手机",
      "product_cover":"https://cdn.example.com/product.png","spec_text":"曜石黑 / 256GB",
      "member_nickname":"小明","member_avatar":"https://cdn.example.com/avatar.png",
      "rating":5,"content":"商品很好，物流很快","images":["https://cdn.example.com/review/1.png"],
      "reply":"感谢您的支持","replied_at":"2026-10-02T15:00:00+08:00","status":1,
      "created_at":"2026-10-02T14:00:00+08:00","updated_at":"2026-10-02T15:00:00+08:00"
    }],
    "total":1
  }
}

评价响应字段即示例中的全部字段；商品、规格和用户信息均为评价创建时的展示快照，图片地址已按当前存储渠道补全。

下架或恢复评价

text

POST /admin/plugin/ecommerce/review/status

权限：POST:/admin/plugin/ecommerce/review/status

json

{ "uid": "erev8x2k4m1", "status": 2 }

status=1 恢复展示，status=2 下架。该操作不删除评价记录。

商家回复

text

POST /admin/plugin/ecommerce/review/reply

权限：POST:/admin/plugin/ecommerce/review/reply

Body 参数	类型	必填	约束	说明
`uid`	string	是	最长 32	评价 UID
`reply`	string	是	最长 1000	回复内容

json

{ "uid": "erev8x2k4m1", "reply": "感谢您的支持，我们会继续努力。" }

成功后记录回复内容和回复时间，响应 data: null。

数据报表

查询商城数据报表

text

GET /admin/plugin/ecommerce/report/overview

权限：GET:/admin/plugin/ecommerce/report/overview。无请求参数，实时聚合商城商品、订单、成交用户和近 7 天趋势，不创建模拟业务数据。

响应字段	类型	说明
`product_count` / `on_sale_product_count` / `stock_count`	integer	商品总数、上架商品数、总库存
`order_count` / `paid_order_count` / `today_order_count`	integer	订单总数、已支付订单数、今日订单数
`buyer_count`	integer	去重成交用户数
`total_pay_amount` / `today_pay_amount`	string	累计与今日已支付金额
`trend`	array	近 7 天趋势，子项含 `date`、`order_count`、`pay_amount`
`statuses`	array	状态分布，子项含 `status`、`name`、`count`
`products`	array	已支付商品销售前 10，含商品 UID、名称、销量、订单数和销售额

json

{"code":0,"msg":"success","data":{"product_count":32,"on_sale_product_count":26,"stock_count":1580,"order_count":216,"paid_order_count":188,"today_order_count":12,"buyer_count":143,"total_pay_amount":"36820.50","today_pay_amount":"1820.00","trend":[{"date":"09-26","order_count":18,"pay_amount":"2680.00"}],"statuses":[{"status":1,"name":"待支付","count":8}],"products":[{"product_uid":"epdt8x2k4m1","product_name":"旗舰智能手机","sales_count":35,"order_count":32,"sales_amount":"20965.00"}]}}

数据、安全与并发

所有业务表保留内部自增 id，同时使用 pkg/sn.Generate() 生成唯一 uid；接口与表间关系只使用 UID。
文件写入时统一转换为相对路径，查询时根据当前默认存储渠道补全地址，不使用当前请求域名拼接。
商品保存使用数据库事务同步商品、规格、规格值与 SKU，任一步失败整体回滚。
订单商品、用户、收货地址、门店、物流和价格均保存快照，历史订单不回查当前业务数据覆盖快照。
订单发货和商家备注使用 version 乐观锁防止并发覆盖。
删除分类、商品、运费模板和门店前校验业务引用；评价只允许下架，不物理删除。
当前版本没有用户端商城、购物车、结算或下单接口。订单支付统一调用核心支付中心，插件不重复注册支付路由。

安装与启用

插件业务表、菜单、菜单映射和安装记录均由安装器处理，不需要手工执行插件 SQL。安装前需确认核心框架包含“系统配置 / 渠道配置 / 物流配置”。

bash

cd go_basic_frame_plugin_ecommerce
./scripts/package.sh

cd ../server_api
go run . plugin validate \
  ../go_basic_frame_plugin_ecommerce/go_basic_frame_plugin_ecommerce-0.0.1.zip

go run . plugin install \
  ../go_basic_frame_plugin_ecommerce/go_basic_frame_plugin_ecommerce-0.0.1.zip \
  --server-root . \
  --admin-root ../admin_client \
  --user-root ../user_client \
  --apply-database \
  -c config.yaml

安装后在插件管理中启用 ecommerce，分配菜单和按钮权限，重启 API，并让管理端重新获取菜单。

商城用户端接口

公开前缀 /api/plugin/ecommerce：

方法	路径	功能
GET	/categories	启用分类
GET	/products	在售商品分页，page/page_size/keyword/category_uid
GET	/product	商品详情，uid；不返回成本和虚拟交付密文
GET	/stores	自提门店

登录前缀 /api/auth/plugin/ecommerce，会员编号仅从认证上下文取得：

方法	路径	功能
GET	/cart	购物车及实时规格库存
POST	/cart/save	sku_uid/quantity，0移除，1至99设置绝对数量
GET	/addresses	本人地址
POST	/address/save	uid可选、name、phone、region、detail
POST	/address/delete	uid
POST	/quote	试算：request_uid、items[{sku_uid,quantity}]、delivery_type、address_uid/store_uid、buyer_message
POST	/checkout	同试算；同一次下单重试必须保持request_uid和请求内容不变
GET	/orders	本人订单分页，支持status过滤
GET	/order	本人订单详情，uid
POST	/order/cancel	uid；未发起支付时取消并一次性回补库存
POST	/order/receive	uid；已支付待收货订单确认收货
POST	/review	order_item_uid、rating(1至5)、content；订单项只能评价一次

金额均以十进制字符串返回；服务端以整数分计算。快递运费按模板汇总，可按件数、SKU重量或体积计费，模板达到包邮阈值免运费。自提需选择有效门店；虚拟商品支付后展示订单快照中的交付内容。

支付使用核心 /api/auth/payment/channels、create、status。客户端支付回调不直接修改订单，必须由服务端验签回调确认。已发起支付的订单不能直接释放库存，避免迟到支付造成超卖；核心尚无主动关单流程时需商家核实处理。不提供自动退款或售后工单。

商品公开评价：GET /api/plugin/ecommerce/reviews?uid=<商品UID>&page=1&page_size=10，仅返回展示状态评价和匿名化昵称，不返回会员编号；自提订单付款后可由本人确认提货，进入待评价。

电商系统 0.0.2 接口文档 ​

通用约定 ​

商品分类 ​

查询分类树 ​

新增或修改分类 ​

删除分类 ​

商品管理 ​

查询商品列表 ​

商品详情响应字段 ​

查询商品详情 ​

新增或修改商品 ​

商品上下架 ​

删除商品 ​

运费模板 ​

查询运费模板 ​

保存运费模板 ​

删除运费模板 ​

自提门店 ​

查询门店 ​

保存门店 ​

删除门店 ​

订单管理 ​

查询订单列表 ​

查询订单详情 ​

查询物流选项 ​

订单发货 ​

保存商家备注 ​

修改未支付订单实付金额 ​

订单评价 ​

查询评价列表 ​

下架或恢复评价 ​

商家回复 ​

数据报表 ​

查询商城数据报表 ​

数据、安全与并发 ​

安装与启用 ​

商城用户端接口 ​

电商系统 0.0.2 接口文档

通用约定

商品分类

查询分类树

新增或修改分类

删除分类

商品管理

查询商品列表

商品详情响应字段

查询商品详情

新增或修改商品

商品上下架

删除商品

运费模板

查询运费模板

保存运费模板

删除运费模板

自提门店

查询门店

保存门店

删除门店

订单管理

查询订单列表

查询订单详情

查询物流选项

订单发货

保存商家备注

修改未支付订单实付金额

订单评价

查询评价列表

下架或恢复评价

商家回复

数据报表

查询商城数据报表

数据、安全与并发

安装与启用

商城用户端接口