HigoShop 产品说明文档

1产品简介

HigoShop 是运行在 NiuCloud 多站点 SaaS 框架之上的一套完整电商业务应用，面向「平台—商家—会员」三层角色， 把 多商户经营（B2B2C）、内容电商（直播 / 短视频 / 种草社区）、社交裂变（阶梯拼团 / 分销）、 线下门店收银（专业收银台） 四件事整合在同一套系统里。

1.1 典型使用场景

1.2 一句话能力清单

多商户入驻 · 商品 SPU/SKU 全链路 · 拼团（含阶梯拼团）· 秒杀 · 限时折扣 · 满减 · 优惠券 · 新人专享 · 积分商城 · 卡密购物额度 · 直播带货 · 短视频 · 种草社区 · 分销三级分佣 · 店铺装修 DIY · 电子面单 · 同城/门店配送 · 专业收银台（POS + 交接班）· 平台结算抽佣 · 全站数据看板。

2系统架构

2.1 四端四端口

HigoShop 采用「四个前端 + 四个后端端口」架构，每个端口拥有独立的路由文件、中间件与鉴权体系。

┌──────────────────────────────────────────────────────────────────┐
│                        NiuCloud 框架内核                          │
│        站点 / 会员 / 支付 / 上传 / 消息 / 权限 / 多语言 / 计划任务    │
└──────────────────────────────────────────────────────────────────┘
        ↑               ↑               ↑              ↑
   /adminapi       /sellerapi        /api         /cashierapi
        │               │               │              │
   平台管理后台      商家工作台       移动端商城       门店收银台
   Vue3 + Vite    Nuxt3 + Vue3      uni-app      Vue3 + Electron
   258 页面        197 路由         142 页面        47 路由

2.2 后端分层

2.3 双目录同步

插件源码存在双目录（真源码 + 框架镜像），两边必须同步修改：

3角色与权限模型

权限点示例（收银台）：order.create / order.refund / shift.start / shift.end / member.view / goods.stock 等；店长（主账号或 role=1）恒拥有全部权限。

4平台管理后台

后台菜单树（源：app/dict/menu/site.php）：

5商家工作台

6移动端商城

6.1 商品与交易

• 商品：列表 / 详情 / SKU / 分类树 / 推荐 / 收藏 / 取消收藏 / 浏览记录 / 评价 / 组件数据（装修用）
• 购物车：列表 / 数量 / 加购 / 改数量 / 删除 / 清空
• 下单：order_create/calculate 结算试算 → 优惠券 / 自提点 / 同城配送选择 → order_create/create 创建订单
• 订单：列表 / 详情 / 状态 / 数量 / 取消 / 确认收货 / 删除 / 物流 / 交易配置
• 售后：申请 / 列表 / 详情 / 取消 / 退款原因 / 退货发货 / 编辑 / 关闭 / 统计
• 发票：配置 / 列表 / 详情 / 申请开票
• 评价：发表、我的评价、商品公开评价

6.2 营销玩法

6.3 内容与社交

6.4 会员中心与分销

信息 / 资料更新 / 收藏 / 足迹 / 关注（店铺与用户）/ 粉丝 / 统计 / 账户 / 地址 / 银行卡 / 钱包（充值、明细、历史提现记录）/ 积分 / 签到（配置、签到、记录、排行）/ 评价 / 投诉 / 反馈 / 通知（系统、物流、聊天、未读、已读、清空）。

分销：配置 / 等级 / 我的分销信息 / 申请成为分销商 / 邀请码绑定上级 / 团队 / 分销订单 / 佣金明细 / 提现（走框架 member_cash_out，账户类型 commission）/ 提现记录。

6.5 移动端商家管理

以会员 token 鉴权的轻量商家入口：工作台概览 / 商家入口判定 / 店铺信息与编辑 / 商品管理（列表、详情、上下架、改库存、删除、新增、编辑）/ 订单（列表、详情、发货、批量发货、改物流、取消、状态计数、物流公司）/ 售后处理 / 财务钱包与提现 / 佣金与结算 / 营销优惠券全套。

7收银台（v2.3.0）

专业门店收银，分为 Web 版与 Electron 桌面版双形态。

7.1 标准作业流程

1. 确认身份：门店 / 终端 / 收银员 / 权限（POS 机心跳上报在线状态）
2. 上一班交接：GET cashier/shift/handover 一次拉全 —— 当前班次、上一班班次号与交班人、应有金额、收款构成、上一班未结挂单数
3. 备用金清点：按面额数张数（100/50/20/10/5/1/0.5/0.1），系统自动合计
4. 开店自检：打印机 / 钱箱 / 扫码枪 / 支付方式，可实测（每一步都可以跳过，不阻断收银）
5. 确认开班：POST cashier/shift/start；已有未交班班次则走「接管」模式，不重复开班
6. 收银：扫码或商品墙选品 → 多规格必须弹选择器（三入口：商品墙点击、扫码命中多 SKU、购物车行改规格）→ 会员绑定 → 开单（is_hold=1 挂单）/ 收款 → 支付结果轮询或确认
7. 交班：POST cashier/shift/end，按面额清点实交现金，系统计算长款 / 短款 / 账实相符，需双人复核

7.2 关键能力

8核心业务流程

8.1 商家入驻

8.2 下单与支付

8.3 售后退款

• 平台可介入退款、审核、批量处理；
• 退款会同步失效分销佣金（已入账的从会员账户扣回，余额不足按余额扣并记日志，不阻断退款）；
• 本地通道退款不得在 refund() 里提前把 refund_status 置为 DONE（会导致 refund_money 恒为 0），应只写 refund_no 交给 confirmRefund()。

8.4 结算与分佣

9数据模型

148 张表，按业务域分组（前缀 higo_ / higo_shop_）：

10技术栈与环境

11安装与部署

11.1 安装

1. 将插件目录放入 niucloud/addon/higo_shop/；
2. 后台「应用管理」安装 HigoShop，自动执行 sql/install.sql（148 张表）；
3. 执行菜单同步：php think menu:refresh -a higo_shop（菜单源 app/dict/menu/site.php）；
4. 按需配置：平台配置（入驻、抽佣、结算、直营）、直播配置（推流 / 播放域名、鉴权密钥，保存入库，前端通过 /api/higo_shop/getLiveConfigInfo 动态读取）、IM 配置、消息通知模板。

11.2 构建前端端口

# 管理后台
cd admin && npm run build

# 商家端（必须用构建脚本，内部会处理 index.html entry 替换）
cd seller && bash build.sh --publish

# 收银台 Web 版
cd cashier && npm run build

# 收银台 Electron 桌面版
cd cashier && npm run electron:build

# 移动端（微信小程序）
cd mp-higo-shop && ./node_modules/.bin/uni build -p mp-weixin

11.3 升级

• 升级脚本目录：app/upgrade/v<去点版本>/（如 v220）；
• upgrade.sql 里表名写裸表名（框架自动补前缀），禁止写 CREATE TABLE IF NOT EXISTS（框架的正则会把 IF 当成表名）；
• 新增字段放 Upgrade.php，执行前先 SHOW COLUMNS 判断；
• install.sql 必须覆盖所有升级脚本产生的变更，保证全新安装与升级后结构一致。

11.4 测试数据

管理端「系统工具 → 测试数据」可一键导入 / 清空全站演示数据（生成器 .workbuddy/scripts/gen_testdata.php，数据文件 sql/testdata-fullsite-v220.sql）。

12版本记录（节选）

13开发者约定（速查）

14附录：主要文件路径