# 小型超市收银系统

**Repository Path**: dnboy/shopping

## Basic Information

- **Project Name**: 小型超市收银系统
- **Description**: 包括后台管理、收银系统、自助收银、微信小程序，基于sqlite，适合小店使用，如果要做连锁，则需要改成大型数据库，欢迎大家一起维护
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 超市收银系统

基于前后端分离架构的超市收银系统，涵盖管理后台、收银POS、自助收银和微信小程序等多个终端，满足超市日常运营需求。

## 功能特性

- 商品管理：商品信息维护、分类管理、条码支持
- 库存管理：库存盘点、入库出库、库存预警
- 会员管理：会员注册、积分体系、会员等级
- 促销优惠：折扣活动、满减优惠、优惠券
- 多种支付方式：现金、微信支付、支付宝、银行卡等
- 条码支持：商品条码扫描、快捷录入
- 订单退单：整单/部分退款、管理员密码验证、历史订单退单
- 交接班：收银员交接班记录与结算（含历史退单统计）
- 广告管理：Kiosk端广告轮播配置
- 统计报表：销售统计、库存报表、会员分析
- 积分体系：可配置积分获取/抵扣规则，订单最大积分抵扣比例
- 销售报表：多维度利润分析（按日/周/月/年/平台/收银员/支付方式/分类）
- 系统设置：积分规则、门店信息等可配置化管理
- 优惠券自动发放：新人券/生日券/充值券自动发放
- 会员价：商品支持设置会员专享价，会员价与等级折扣互斥
- 促销范围扩展：支持全场/指定分类/指定厂家/指定厂家某分类/指定商品5种范围
- 精确退款：每件商品记录优惠明细和实付金额，退款精确计算
- 最大优惠比例：可配置最大总优惠比例，防止过度优惠
- 余额变动记录：充值、消费、退款、调整全记录可查
- 积分手动调整：管理员可手动增减会员积分，操作可追溯
- 数据归档：历史数据归档备份，保持主表精小，支持归档查询和导出
- 销售报表快捷日期：本日/本周/本月/本季/本年/昨日/上周/上月/上季/去年/前年快捷查询
- 付款码支付：收银员扫顾客付款码完成支付，支持微信/支付宝/银联，三种模式(模拟/沙箱/真实)
- 热敏打印：ESC/POS指令通过Web Serial API连接串口热敏打印机，支持58mm/80mm纸宽
- 客显屏同步：BroadcastChannel实时同步购物车到副屏，支持扩展窗口和串口LED两种模式
- 单品/整单折扣：收银员可对单件商品或整单设置手动折扣，支持固定金额和折扣率

## 系统界面

### 管理后台

<table>
  <tr>
    <td align="center"><b>仪表盘</b></td>
    <td align="center"><b>商品管理</b></td>
  </tr>
  <tr>
    <td><img src="docs/images/admin-dashboard.png" alt="管理后台-仪表盘" width="480" /></td>
    <td><img src="docs/images/admin-products.png" alt="管理后台-商品管理" width="480" /></td>
  </tr>
</table>

### 收银POS

<table>
  <tr>
    <td align="center"><b>收银主界面</b></td>
    <td align="center"><b>支付结算</b></td>
  </tr>
  <tr>
    <td><img src="docs/images/cashier-main.png" alt="收银POS-主界面" width="480" /></td>
    <td><img src="docs/images/cashier-payment.png" alt="收银POS-支付弹窗" width="480" /></td>
  </tr>
</table>

### 自助收银 & 小程序

<table>
  <tr>
    <td align="center"><b>自助收银 Kiosk</b></td>
    <td align="center"><b>微信小程序</b></td>
  </tr>
  <tr>
    <td><img src="docs/images/kiosk-main.png" alt="自助收银" width="320" /></td>
    <td><img src="docs/images/miniprogram.png" alt="微信小程序" width="320" /></td>
  </tr>
</table>

## 技术栈

| 模块 | 技术栈 |
|------|--------|
| server | Node.js + Express + Sequelize + SQLite |
| admin | Vue 3 + Element Plus |
| cashier | Vue 3 + Element Plus |
| kiosk | Vue 3 + Vant 4 |
| miniprogram | UniApp + Vue 3 |

## 快速开始

### 环境要求

- Node.js >= 16
- npm >= 8

### 安装依赖（首次运行）

**方式一：Windows 批处理脚本**

双击运行 `0.install.bat` 即可一键安装所有模块依赖。

**方式二：命令行**

```bash
# 后端
cd server && npm install

# 管理后台
cd ../admin && npm install

# 收银POS
cd ../cashier && npm install

# 自助收银
cd ../kiosk && npm install

# 微信小程序
cd ../miniprogram && npm install
```

### 启动服务（按顺序）

> **重要：必须先启动后端API服务，再启动前端！**

**方式一：Windows 批处理脚本**

按顺序双击以下 bat 文件：

| 步骤 | 文件 | 说明 |
|------|------|------|
| 1 | `1.start_server.bat` | 启动后端API（必须最先启动） |
| 2 | `2.start_admin.bat` | 启动管理后台 |
| 3 | `3.start_cashier.bat` | 启动收银POS |
| 4 | `4.start_kiosk.bat` | 启动自助收银 |

**方式二：命令行**

```bash
# 1. 启动后端API（端口3000）
cd server
node app.js

# 2. 新开终端，启动管理后台（端口5173）
cd admin
npm run dev

# 3. 新开终端，启动收银POS（端口5174）
cd cashier
npm run dev

# 4. 新开终端，启动自助收银（端口5176）
cd kiosk
npm run dev
```

### 服务地址

| 服务 | 端口 | 访问地址 |
|------|------|----------|
| 后端API | 3000 | http://localhost:3000 |
| 管理后台 | 5173 | http://localhost:5173 |
| 收银POS | 5174 | http://localhost:5174 |
| 自助收银 | 5176 | http://localhost:5176 |
| 小程序H5 | 5177 | http://localhost:5177 |

> 微信小程序H5模式：`cd miniprogram && npm run dev:h5`，原生模式需在微信开发者工具中打开 miniprogram/ 目录。

### 导入测试数据

启动后端服务后，可导入更丰富的测试数据：

```bash
cd server
node seed-data.js
```

## 默认账号

| 角色 | 用户名 | 密码 | 用途 |
|------|--------|------|------|
| 管理员 | admin | admin123 | 管理后台登录 |
| 收银员 | cashier | cashier123 | 收银POS登录 |
| 自助收银 | kiosk | kiosk123 | 自助收银自动登录 |
| 店长 | manager | manager123 | 管理后台登录 |

## 项目目录结构

```
shopping/
├── server/          # 后端API服务
│   ├── src/
│   │   ├── config/    # 数据库配置
│   │   ├── controllers/ # 控制器（含 statsController.js, settingController.js, archiveController）
│   │   ├── models/     # 数据模型（含 PointLog.js, SystemSetting.js, BalanceLog, archive models）
│   │   ├── routes/     # 路由定义（含 setting.js, archive.js）
│   │   ├── services/   # 业务逻辑（含 paymentGateway.js）
│   │   └── middleware/ # 中间件
│   ├── uploads/        # 上传文件目录
│   ├── app.js          # 入口文件
│   ├── seed-data.js    # 测试数据脚本
│   └── import-real-products.js # 真实商品导入脚本
├── admin/           # 管理后台 (Vue 3 + Element Plus)
│   └── views/archive/  # 归档管理页面
├── cashier/         # 收银POS系统 (Vue 3 + Element Plus)
│   ├── src/utils/escpos.js  # ESC/POS打印指令工具
│   └── views/              # 页面
│       ├── Settings.vue         # 系统设置页
│       └── CustomerDisplay.vue  # 客显屏页面
├── kiosk/           # 自助收银系统 (Vue 3 + Vant 4)
├── miniprogram/     # 微信小程序 (UniApp)
├── docs/
│   ├── design-doc.md    # 设计文档
│   └── user-manual.md   # 使用手册
├── 0.install.bat         # 一键安装依赖
├── 1~5.start_*.bat       # 各模块启动脚本
└── README.md             # 本文件
```

## 常见问题

### 端口被占用

如果启动时报端口被占用错误：
```bash
# Windows 查看端口占用
netstat -ano | findstr :3000
# 杀掉占用进程
taskkill /PID 进程号 /F
```

### 首次启动无数据

后端首次启动会自动创建数据库表和基础数据（账号、分类、示例商品）。如需更多测试数据，运行：
```bash
cd server && node seed-data.js
```

### 前端页面空白

请确认后端API服务已先启动，且各前端通过 Vite proxy 正确代理到 localhost:3000。

## 许可证

MIT