cf_Ghbf

Appearance

电商系统插件（ecommerce） ​

当前版本为 0.0.1。插件业务接口统一前缀为 /admin/plugin/ecommerce，注册在 Permission 路由组；订单支付复用核心用户端统一支付接口。

通用约定 ​

请求头：

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

统一响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
字段类型说明
codeinteger0 成功；参数或业务错误返回非 0
msgstring成功提示或错误原因
dataobject/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 参数类型必填约束说明
keywordstring否最长 64分类名称关键词
statusinteger否1、2状态

响应 data 为分类树数组：

字段类型说明
uidstring分类 UID
parent_uidstring父分类 UID，顶级为空字符串
namestring分类名称
imagestring按当前存储渠道补全的图片地址
sortinteger排序值
statusinteger1 启用，2 停用
created_atstring创建时间
updated_atstring更新时间
childrenarray子分类，字段结构相同
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 参数类型必填约束说明
uidstring修改时是最长 32分类 UID；新增为空
parent_uidstring否最长 32父分类 UID；空为顶级
namestring是最长 64分类名称
imagestring否最长 1024上传接口返回的图片地址
sortinteger是≥ 0排序值
statusinteger是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 参数类型必填说明
uidstring是分类 UID，最长 32

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

商品管理 ​

查询商品列表 ​

text
GET /admin/plugin/ecommerce/product/list

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

Query 参数类型必填约束说明
keywordstring否最长 200商品名称或编码
category_uidstring否最长 32分类 UID
product_typeinteger否1、2商品类型
statusinteger否1、2上架状态
pageinteger否≥ 1，默认 1页码
page_sizeinteger否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
  }
}

商品详情响应字段 ​

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

字段类型说明
uidstring商品 UID
category_uid / category_namestring分类 UID / 分类名称
product_typeinteger1 普通，2 虚拟
spec_typeinteger1 单规格，2 多规格
namestring商品名称
coverstring商品封面完整地址
imagesarray<string>轮播图完整地址数组
videostring视频完整地址
statusinteger1 上架，2 下架
stockinteger有效 SKU 汇总库存
pricestring有效 SKU 最低售价
market_price / cost_pricestring划线价 / 成本价
codestring商品编码
weight / volumestring重量（kg）/ 体积（m³）
introstring商品简介
detailstring富文本详情
delivery_modesarray<integer>配送方式
shipping_template_uidstring运费模板 UID
virtual_contentstring虚拟交付说明
sales_count / virtual_sales_countinteger实际销量 / 虚拟销量
specsarray规格组及规格值
skusarraySKU 列表
created_at / updated_atstring创建时间 / 更新时间

规格组字段：

字段类型说明
uidstring规格组 UID
namestring规格名称
sortinteger排序
valuesarray规格值列表
values[].uidstring规格值 UID
values[].valuestring规格值文本
values[].imagestring规格值图片完整地址
values[].sortinteger排序

SKU 字段：

字段类型说明
uidstringSKU UID
spec_value_uidsarray<string>规格值 UID 组合
spec_textstring规格展示文本
imagestringSKU 图片完整地址
stockinteger库存
price / market_price / cost_pricestring售价 / 划线价 / 成本价
codestringSKU 编码
weight / volumestring重量 / 体积
statusinteger1 启用，2 停用

查询商品详情 ​

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

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

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

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

新增或修改商品 ​

text
POST /admin/plugin/ecommerce/product/save

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

商品参数：

Body 参数类型必填约束说明
uidstring修改时是最长 32商品 UID
category_uidstring是最长 32启用的分类 UID
product_typeinteger是1、2商品类型
spec_typeinteger是1、2规格类型
namestring是最长 200商品名称
coverstring是最长 1024商品封面
imagesarray<string>是1～10 张，每项最长 1024轮播图
videostring否最长 1024商品视频
statusinteger是1、2上架状态
codestring否最长 64商品编码
introstring否最长 500商品简介
detailstring否富文本商品详情
delivery_modesarray<integer>是1～2 项，值为 1/2配送方式
shipping_template_uidstring快递商品是最长 32运费模板 UID
virtual_contentstring虚拟商品建议填写文本虚拟交付说明
virtual_sales_countinteger是≥ 0虚拟销量
specsarray多规格时是见下表规格组
skusarray是至少 1 项SKU 列表

specs[] 与 values[]：

参数类型必填约束说明
specs[].uidstring修改已有规格时否最长 32规格 UID
specs[].namestring是最长 64规格名称
specs[].sortinteger是≥ 0排序
specs[].valuesarray是至少 1 项规格值
values[].uidstring修改已有值时否最长 32规格值 UID
values[].keystring是最长 64，请求内唯一SKU 组合临时键
values[].valuestring是最长 64规格值
values[].imagestring否最长 1024规格值图片
values[].sortinteger是≥ 0排序

skus[]：

参数类型必填约束说明
uidstring修改已有 SKU 时否最长 32SKU UID
spec_value_keysarray<string>是每项最长 64对应规格值 key 组合
spec_textstring否最长 500展示文本
imagestring否最长 1024SKU 图片
stockinteger是≥ 0库存
pricestring是数值售价
market_pricestring是数值划线价
cost_pricestring是数值成本价
codestring否最长 64SKU 编码
weightstring是数值重量（kg）
volumestring是数值体积（m³）
statusinteger是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 参数类型必填约束说明
keywordstring否最长 100模板名称
statusinteger否1、2状态

data 为数组，字段如下：

字段类型说明
uidstring模板 UID
namestring模板名称
charge_typeinteger1 件数、2 重量、3 体积
first_unit / first_feestring首单位 / 首费
additional_unit / additional_feestring续单位 / 续费
free_amountstring包邮金额，0.00 表示不包邮
statusinteger状态
created_at / updated_atstring创建 / 更新时间
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 参数类型必填说明
uidstring修改时是模板 UID，最长 32
namestring是模板名称，最长 100
charge_typeinteger是1 件数、2 重量、3 体积
first_unitstring是数值，首件/首重/首体积
first_feestring是数值，首费
additional_unitstring是数值，续单位
additional_feestring是数值，续费
free_amountstring是数值，0 表示不包邮
statusinteger是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 参数类型必填约束说明
keywordstring否最长 100门店名称或电话
statusinteger否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 参数类型必填约束说明
uidstring修改时是最长 32门店 UID
namestring是最长 100门店名称
contact_namestring是最长 64联系人
phonestring是最长 32联系电话
regionstring是最长 255省市区
addressstring是最长 255详细地址
longitudestring是数值经度
latitudestring是数值纬度
sortinteger是≥ 0排序
statusinteger是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 参数类型必填约束说明
statusinteger否1～7订单状态
pay_statusinteger否1～3支付状态
delivery_typeinteger否1、2配送方式
keywordstring否最长 100订单号、用户、手机号或商品名称
start_atstring否YYYY-MM-DD HH:mm:ss创建开始时间
end_atstring否YYYY-MM-DD HH:mm:ss创建结束时间
pageinteger否≥ 1页码
page_sizeinteger否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":"微信支付","payment_channel":1,"payment_scene":1,
      "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}
  }
}

订单字段说明：

字段类型说明
uidstring商城订单 UID
finance_order_nostring核心基座订单号
order_nostring商城业务订单号
member_nickname / member_avatar / member_mobilestring用户快照
order_type / delivery_typeinteger订单类型 / 配送方式
status / pay_status / pay_methodinteger/integer/string订单状态、支付状态、支付方式快照
payment_channelinteger支付渠道：0未支付，1微信，2支付宝
payment_sceneinteger支付场景，与核心统一支付枚举一致
product_amount / shipping_amount / discount_amount / pay_amountstring金额快照
receiver_*string收货信息快照
store_uid / store_snapshotstring/object自提门店 UID 与快照
buyer_message / merchant_remarkstring买家留言 / 商家备注
logistics_company_uid / logistics_company_name / tracking_nostring物流信息
paid_at / shipped_at / completed_at / cancelled_atstring/null状态时间
versioninteger乐观锁版本号
productsarray订单商品快照
logsarray详情接口返回订单日志；列表通常为空
created_at / updated_atstring创建 / 更新时间

查询订单详情 ​

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

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

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

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

字段类型说明
uidstring日志 UID
operator_typeinteger1 系统、2 管理员、3 用户
operator_namestring操作人名称快照
actionstring操作标识，如 ship
from_status / to_statusinteger原状态 / 新状态
remarkstring操作说明
created_atstring操作时间

查询物流选项 ​

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 参数类型必填约束说明
uidstring是最长 32订单 UID
logistics_company_uidstring是最长 32核心物流 UID
logistics_company_namestring是最长 100物流公司名称
tracking_nostring是最长 100物流单号
versioninteger是≥ 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 参数类型必填说明
uidstring是订单 UID，最长 32
remarkstring否商家备注，最长 500
versioninteger是当前订单版本号，≥ 1

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

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

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

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

Body 参数类型必填约束说明
uidstring是最长 32订单 UID
pay_amountstring是0～9999999999.99，最多两位小数修改后的实际支付金额
versioninteger是≥ 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 参数类型必填约束说明
keywordstring否最长 200商品名称、评价内容或用户昵称
ratinginteger否1～5评分
statusinteger否1、2展示状态
pageinteger否≥ 1页码
page_sizeinteger否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 参数类型必填约束说明
uidstring是最长 32评价 UID
replystring是最长 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_countinteger商品总数、上架商品数、总库存
order_count / paid_order_count / today_order_countinteger订单总数、已支付订单数、今日订单数
buyer_countinteger去重成交用户数
total_pay_amount / today_pay_amountstring累计与今日已支付金额
trendarray近 7 天趋势，子项含 date、order_count、pay_amount
statusesarray状态分布，子项含 status、name、count
productsarray已支付商品销售前 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 乐观锁防止并发覆盖。
  • 删除分类、商品、运费模板和门店前校验业务引用；评价只允许下架，不物理删除。
  • 当前版本没有用户端商城、购物车、结算或下单接口。
  • 电商插件实现 PaymentOrderProvider，支付接口、回调验签、幂等和渠道选择统一由核心支付中心提供，详见用户端统一支付。

安装与启用 ​

插件业务表、菜单、菜单映射和安装记录均由安装器处理，不需要手工执行插件 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，并让管理端重新获取菜单。

小程序商城（0.0.2） ​

商城入口为 /plugins/ecommerce/pages/index/index，独立子包提供首页、分类、购物车、我的四个自定义底部菜单。用户端复用基座认证与核心支付，不配置原生TabBar。

公开接口前缀 /api/plugin/ecommerce：GET categories、products、product、stores。

认证接口前缀 /api/auth/plugin/ecommerce：GET cart、addresses、orders、order；POST cart/save、address/save、address/delete、quote、checkout、order/cancel、order/receive、review。

结算参数为 request_uid、items:[{sku_uid,quantity}]、delivery_type（1快递、2自提）、address_uid/store_uid、buyer_message。商品金额和运费由服务端计算，金额以十进制字符串交付。幂等标识按会员隔离，同一标识的重复请求返回同一订单，内容变化则拒绝。下单在事务中锁定商品与SKU并扣减库存，最多30种规格、每种99件，每个会员最多10笔待支付订单。

订单状态沿用管理端：1待支付、2待发货、3待收货、4待评价、5已完成、6已取消、7已退款。确认收货只允许本人已支付待收货订单；每个订单项只能评价一次。虚拟商品在验签支付回调后交付，未支付时不返回交付内容。

支付复用核心 payment/channels、payment/create、payment/status，客户端SDK成功不是到账依据。核心创建支付时新增事务内订单重验，避免取消与创建支付竞争。已发起支付的订单暂不支持直接取消释放库存，需商家核实处理；主动关单、自动退款和售后工单仍需核心支付后续能力。

基座首页入口配置 ​

安装电商插件并重建用户端后，在后台内容菜单新增“商城”：位置为首页，平台为微信小程序，展示形式为图标（store），跳转类型为应用内页面，地址 /plugins/ecommerce/pages/index/index，启用。无需修改基座首页布局和TabBar，也不向插件SQL写入核心菜单表。演示菜单仅在已安装且启用该插件时提供默认商城入口。

数据库与部署 ​

电商 database/0.0.2 同时交付全量和增量，新增购物车、收货地址和下单幂等记录表。旧数据升级只执行增量，新装执行全量。部署前停用插件并备份数据库，按标准升级流程执行，随后重建后端和用户端。真实微信支付需要配置小程序、商户及公网通知地址，并绑定会员平台身份。

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