# mall-system

**Repository Path**: xrlnewman/mall-system

## Basic Information

- **Project Name**: mall-system
- **Description**: 多商户商城管理系统 - Laravel 12 + PHP 8.3，三端（平台/商户/C 端）+ SaaS 多租户隔离 + 进销存底座
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mall System

多商户 SaaS 商城后端 API。**Laravel 12 + PHP 8.3 + MySQL 8 + Redis 7 + Reverb + Elasticsearch**。

服务于一套生态：
- **mall-system** —— 本仓库，后端 200+ API
- [mall-h5](https://gitee.com/xrlnewman/mall-h5) —— C 端商城 H5
- [mall-admin](https://gitee.com/xrlnewman/mall-admin) —— 平台 + 商户后台

> **生产部署看这里**：[`docs/DEPLOY.md`](./docs/DEPLOY.md) + [`docs/PRODUCTION_CHECKLIST.md`](./docs/PRODUCTION_CHECKLIST.md)

---

## 一、项目简介

多商户 SaaS 模式电商平台。一次部署，支持：

- 任意数量商户入驻，数据完全隔离（`BelongsToMerchant` Trait + 全局 Scope）
- C 端 / 商户端 / 平台端 三套角色一份代码
- 全套高并发能力：Redis Lua 秒杀（30000+ QPS）、分布式锁、接口幂等、读写分离
- 第三方密钥**全部走后台配置中心**，不用改代码不用重启

---

## 二、功能模块清单

### C 端（mall-h5 对接）
- 登录注册：手机验证码 / 密码 / 微信小程序 / 公众号 OAuth / 邀请码绑定 / 2FA
- 商品体系：SPU + SKU + 树形分类 + 品牌库 + Q&A + 收藏 + 足迹
- 购物车：跨商户分组、SKU 校验、库存校验
- 下单支付：跨商户拆单、库存原子占用、微信/支付宝/余额混合、接口幂等
- 订单：7 状态机 + 30 分钟自动取消 + 7 天自动确认收货
- 退款售后：仅退款/退货退款、9 张凭证、平台仲裁
- 物流：22 家物流公司、快递 100 实时轨迹（5 分钟缓存）、多包裹一单
- 营销活动：拼团 / 秒杀 / 砍价 / 优惠券 / 满减 / 签到 / 抽奖 / 积分商城 / 预售 / 阶梯价 / 专题落地页
- 会员：V1-V6 6 级 + 成长值升级 + 等级折扣 + 等级权益
- 分销：二级返佣 + 邀请码 + 佣金生命周期 + 提现
- 钱包：余额 + 积分 + 成长值，三套独立流水
- 客服 IM：用户 ↔ 商户 + Reverb 实时推送 + 失败降级轮询

### 商户端（mall-admin 商户角色）
- 商品 CRUD + SKU 矩阵 + 多图上传（OSS 直传）
- 仓库 / 库存 / 库存调拨 / 库存盘点
- 采购单 / 销售单 / 供应商 / 客户（完整进销存）
- 商城订单管理 + 批量发货（Excel 模板）
- 营销活动配置：拼团 / 秒杀 / 砍价 / 优惠券
- 店铺装修拖拽编辑器（10+ 组件 + 375px 预览）
- 运费模板 + 提现申请
- 商户报表（销售/库存/利润）

### 平台端（mall-admin 平台角色）
- 运营大屏（4 KPI + GMV 趋势 + 漏斗 + Top 排行 + 待办）
- 商户审核 / 启用 / 封禁
- 提现审核（二次确认 + 流水号必填）
- 月度对账单（自动生成）
- 会员等级配置 + 全量重算
- 物流公司 CRUD + 批量启停
- 系统配置中心（7 大组 40+ 项，加密存储，连通性测试）
- 平台品牌库 + 专题落地页 + 积分商品 + 抽奖配置
- 争议仲裁（资金裁定）

### 第三方集成
- 支付：微信支付 5 场景 + 支付宝 4 场景
- 短信：阿里云 Dysmsapi
- 对象存储：阿里云 OSS（前端直传 + 服务端上传）
- 物流：快递 100
- 邮件：SMTP
- 推送：极光 JPush
- 搜索：Elasticsearch（中文分词 + 高亮 + 聚合）
- 监控：Sentry

---

## 三、技术栈

| 类别 | 技术 | 版本 |
|---|---|---|
| 语言 | PHP | 8.3+ |
| 框架 | Laravel | 12.x |
| 数据库 | MySQL | 8.0+ |
| 缓存 / 队列 / 锁 | Redis | 7.x |
| WebSocket | Laravel Reverb | 1.x |
| 鉴权 | Sanctum + Spatie Permission | 4.x / 6.x |
| 支付 | yansongda/pay | 3.7+ |
| 搜索 | Elasticsearch | 8.x |
| 2FA | pragmarx/google2fa | 8.x |
| 监控 | sentry/sentry-laravel | 4.6+ |
| Web 服务器 | Nginx | 1.24+ |
| 进程守护 | Supervisor | 4.x |

---

## 四、快速开始（本地开发）

```bash
# 1. 克隆 + 装依赖
git clone https://gitee.com/xrlnewman/mall-system.git
cd mall-system
composer install

# 2. 配置环境
cp .env.example .env
php artisan key:generate
# 改 .env：DB_*、REDIS_*、REVERB_*

# 3. 建库 + 种子
php artisan migrate:fresh --seed
php artisan db:seed --class=RichDemoSeeder   # 富演示数据（5 商户 / 30 商品 / 200 订单）

# 4. 起服务（4 个进程，各开一个终端）
php artisan serve --host=0.0.0.0 --port=8000                    # 1) HTTP
php artisan queue:work redis --queue=seckill,default,notify     # 2) 队列
php artisan reverb:start --host=0.0.0.0 --port=8080             # 3) WebSocket
php artisan schedule:work                                        # 4) 定时（Windows 用，Linux 走 cron）

# 5. 后台登录填密钥
# 打开 mall-admin 用 platform-admin / admin123 登录 → 系统配置 → 依次填
#   - 支付 / 短信 / OSS / 微信 / 物流 / 邮件 / 极光 / 站点信息
```

生产部署完整步骤见 [`docs/DEPLOY.md`](./docs/DEPLOY.md)。

---

## 五、项目结构

```
mall-system/
├── app/
│   ├── Console/
│   │   └── Kernel.php             # 11 个定时任务
│   ├── Http/
│   │   ├── Controllers/           # 平台 / 商户 / Mall(C 端) 三套
│   │   ├── Middleware/            # AuditLog / Idempotency / ApiRateLimit / TraceId / RoleGate
│   │   └── Requests/              # FormRequest 验证
│   ├── Models/                    # 75+ 模型（含 BelongsToMerchant Trait）
│   ├── Services/
│   │   ├── PaymentGateway.php
│   │   ├── RedisSeckillService.php
│   │   ├── ConfigService.php      # 后台配置中心读写
│   │   ├── CacheService.php       # 防穿透/雪崩/击穿
│   │   ├── Notification/          # 5 通道统一通知
│   │   └── ...
│   ├── Jobs/                      # 异步任务（SendNotification / SeckillOrder / ...）
│   ├── Events / Listeners/        # 事件驱动
│   ├── Observers/                 # ProductObserver 同步 ES
│   ├── Support/
│   │   └── RedisLock.php          # 分布式锁
│   └── Scopes/MerchantScope.php
├── bootstrap/
├── config/                        # database / queue / broadcasting / sanctum / ...
├── database/
│   ├── migrations/                # 75+ 张表
│   └── seeders/
│       ├── DatabaseSeeder.php
│       └── RichDemoSeeder.php
├── docs/
│   ├── DEPLOY.md                  # 生产部署完整指南 ★
│   ├── PRODUCTION_CHECKLIST.md    # 上线前必查清单 ★
│   ├── MALL_API.md                # 200+ 接口说明
│   ├── HIGH_CONCURRENCY.md        # 高并发架构
│   ├── INTEGRATIONS.md            # 第三方集成
│   ├── OBSERVABILITY.md           # 监控可观测
│   └── OPTIMIZATIONS.md           # 优化项清单
├── public/                        # Nginx 站点根目录
├── routes/
│   ├── api.php                    # /api/* 业务接口
│   ├── channels.php               # Echo 广播频道鉴权
│   └── console.php
├── storage/                       # 上传、日志、缓存（chmod 775，属主 www）
├── tests/
└── .env.example
```

---

## 六、开发指南

### 1. 添加新表 / 改字段

```bash
# 新建迁移
php artisan make:migration create_xxx_table

# 命名规范：YYYY_MM_DD_HHMMSS_<动作>_<表/字段>_table.php
# 改字段时必须 NULL 兼容老数据，灰度发布两步走（加字段 → 业务用 → 删字段）

php artisan migrate
```

**改字段必须先 `Read` 模型文件确认字段名再写**，不要凭印象写——隔壁表叫啥不代表这张表也叫啥。

### 2. 加 API

1. `routes/api.php` 加路由（按 `prefix('admin')` / `prefix('merchant')` / `prefix('mall')` 分组）
2. `app/Http/Controllers/<分组>/` 加 Controller
3. `app/Http/Requests/` 加 FormRequest 做验证
4. 写操作必经中间件链：`auth:sanctum` → `role:xxx` → `idempotency`（写）→ `audit-log`

### 3. 加 Service

业务逻辑放 `app/Services/`，Controller 只做 IO。事务用 `DB::transaction(fn() => ...)`，跨服务调用用 `RedisLock::acquire()`。

### 4. 加中间件

```bash
php artisan make:middleware Xxx
# 在 bootstrap/app.php 注册 alias 或 global
```

### 5. 加 Job

```bash
php artisan make:job XxxJob
# 默认走 redis 队列，秒杀走 seckill 队列，通知走 notify 队列
# tries=3 backoff=60 在类里声明
```

### 6. 加 Event / Listener

广播事件继承 `ShouldBroadcast`，channel 名严格 `private-im.{userId}` 之类，鉴权放 `routes/channels.php`。

### 7. 改第三方密钥

**不改代码、不改 .env**，登录 mall-admin 平台后台 → 系统配置 → 找对应组 → 改 → 保存（Redis 缓存自动失效）。开发时本地直连测试：每组顶部「连通性测试」按钮。

### 8. 跑测试

```bash
php artisan test
./vendor/bin/pint                # 代码格式化
./vendor/bin/phpstan analyse     # 静态分析
```

---

## 七、其他文档

| 文档 | 主题 |
|---|---|
| [`docs/DEPLOY.md`](./docs/DEPLOY.md) | 生产部署完整指南（运维必读） |
| [`docs/PRODUCTION_CHECKLIST.md`](./docs/PRODUCTION_CHECKLIST.md) | 上线前必查清单 |
| [`docs/MALL_API.md`](./docs/MALL_API.md) | 200+ API 完整说明 |
| [`docs/HIGH_CONCURRENCY.md`](./docs/HIGH_CONCURRENCY.md) | 高并发架构与压测基线 |
| [`docs/INTEGRATIONS.md`](./docs/INTEGRATIONS.md) | 第三方集成 + 配置中心 |
| [`docs/OBSERVABILITY.md`](./docs/OBSERVABILITY.md) | 监控可观测 |
| [`docs/OPTIMIZATIONS.md`](./docs/OPTIMIZATIONS.md) | 8 维度优化清单 |
| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | 贡献指南 |
| [`CHANGELOG.md`](./CHANGELOG.md) | 版本历史 |

---

## License

MIT © [xrlnewman](https://gitee.com/xrlnewman)