# linli-server

**Repository Path**: xrlnewman/linli-server

## Basic Information

- **Project Name**: linli-server
- **Description**: 社区团购+同城跑腿+搭子 后端 (Laravel 12 + JWT + RBAC)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# linli-server · 邻里社区服务平台 后端

> 融合 **社区团购 + 同城跑腿 + 兴趣/事务搭子** 三大核心，主打乡镇/农村 + 城区社区场景，
> 解决居民采购、代办、结伴需求；交易模式可配置，适配低识字人群。

本仓库是平台**后端 API**（纯 API，给微信小程序 `linli-mp` 和后台管理端 `linli-admin` 提供服务）。

---

## 技术栈

| 分类 | 选型 | 说明 |
|---|---|---|
| 框架 | **Laravel 12.61** | 流式 `bootstrap/app.php` 新结构 |
| 语言 | **PHP 8.3** | |
| 鉴权 | **JWT** · `php-open-source-saver/jwt-auth` | 双 guard：`api`(小程序用户) / `admin`(后台账号) |
| 权限 | **RBAC** · `spatie/laravel-permission` | 角色/权限挂 `admin` guard，支持按钮级控制 |
| 数据库 | **MySQL 5.7+**（schema 兼容 5.7，MySQL 8 亦可；本地亦可用 sqlite WAL 快速起步） | **不上外键**，关联只在 Eloquent 层维护 |
| 响应 | 统一信封 `{code,message,data}` | `App\Support\ApiResponse` + 全局异常归一 |
| 缓存/队列 | Redis(生产) | |

> 成熟方案直接复用、不重复造轮子：鉴权用 jwt-auth、权限用 laravel-permission。

---

## 功能模块

### 1. 鉴权 Auth
- 小程序：微信 `code → openid` 登录（`WechatService`，appid 从「系统设置」读，生产走 jscode2session，仅本地开发用 code 派生）、获取/更新资料、短信验证码绑定手机号、登出
- 后台：账号密码登录（返回 token + 角色 + 权限名列表，供前端按钮级控制）、改密、登出

### 2. 社区团购 GroupBuy（核心）
- **可配置三种供货**：平台自营 / 商家入驻 / 团长自供（`sellers.type`）
- **自提点**：有团长=团长制、无团长=平台直营网点（`pickup_points.leader_id`）并存
- 商品 SPU + 多 SKU；分类
- **开团**：平台开团 / 团长开团（`group_buys.launcher_type`），各 SKU 设团购价/库存/限购，开团-截单-到货时间，履约开关(自提/配送)
- **下单**：试算 → 下单(自提/送货上门) → 防超卖(事务+行锁) → 支付(余额实扣 / 微信 / 支付宝，`yansongda/pay`，密钥进系统设置) → 我的订单 → 取消(回滚库存) → 确认收货(送积分)
- **团长核销**：6 位自提码核销，佣金按成交额×自提点佣金率
- **后台运营**：发货、到货(单个/按团批量)、退款(回滚库存+退款)

### 3. 同城跑腿 Errand
- 三类：帮买(代购) / 帮送(取送件) / 帮办(代办排队)
- 发单(试算费用) → 抢单大厅 → 接单(防接自己单、行锁防重复接) → 开始 → 完成 → 互评
- 计价：起步价 + 距离 + 小费（`settings` 可调）；支付走余额 / 微信 / 支付宝

### 4. 搭子 Companion
- 六类：运动 / 饭搭 / 遛娃 / 逛街 / 拼车 / 结伴
- 发起(免费/AA/付费) → 广场 → 报名(防重复、满员并发控制) → 退出 → 留言 → 关闭/取消/结束
- 我发起的 / 我参加的

### 5. 钱包 / 积分 / 支付
- **支付**：余额（实扣 + 流水）/ 微信 / 支付宝，统一 `PaymentService`（`yansongda/pay`），密钥进系统设置，未配置优雅降级
- **钱包**：余额、收支明细（充值/消费/退款/佣金）、充值（走微信/支付宝，回调到账）
- **积分**：消费送积分 + 积分明细

### 6. 团长端 Leader
- 工作台(自提点+今日单量+待核销+累计佣金)、团长开团、本点订单、核销自提、佣金明细

### 7. 短信 / 快递（第三方，密钥进系统设置）
- **短信**：`overtrue/easy-sms`（阿里云/腾讯云），验证码 + 绑定手机号
- **快递**：快递100 / 快递鸟，按订单运单号查物流轨迹

### 8. 平台后台 Admin（RBAC 全模块）
- **系统**：角色权限(按模块分组授权)、后台账号(分配角色/重置密码)、**系统设置(微信/支付宝/短信/快递密钥 + 平台开关)**
- **业务**：卖家、商品、团购、订单(查看+发货填快递/到货/退款)、自提点(指派团长)、分类、跑腿、搭子、钱包流水、统计
- **模式开关**(`settings`)：`enable_leader/merchant/leader_goods/delivery`

---

## 目录结构（标准 Laravel 分层）

```
app/
├─ Http/Controllers/
│  ├─ Auth/        微信登录 / 后台登录
│  ├─ Api/         小程序：首页/团购/自提点/下单/跑腿/搭子/个人
│  ├─ Leader/      团长端
│  └─ Admin/       后台各模块管理
├─ Services/       业务逻辑（OrderService/GroupBuyService/ErrandService/CompanionService/LeaderService …）
├─ Models/         Eloquent（无外键，关系+casts）
├─ Enums/          ErrorCode 分段错误码
└─ Support/        ApiResponse 统一信封
routes/api.php     109 接口，按 小程序公开 / auth:api / leader / admin 分组
config/            auth(双guard) · jwt · permission · database(WAL/无外键)
database/migrations  用户/后台/卖家/自提点/分类/商品+SKU/团购+SKU/订单+明细/跑腿/搭子/配置
database/seeders     DemoSeeder + ErrandCompanionSeeder + WalletPointSeeder（DatabaseSeeder 一键串起）
```

---

## 快速开始

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan jwt:secret
php artisan migrate
php artisan db:seed          # 一键播种全部演示数据（团购/跑腿/搭子/钱包/积分/充值）
php artisan serve            # http://127.0.0.1:8000
```

生产改 `.env`：`DB_CONNECTION=mysql`、`CACHE_STORE=redis`、`APP_DEBUG=false`；微信/支付宝/短信/快递/小程序 AppID 等密钥**在后台「系统设置」页填**，无需改 `.env`。

## 演示账号

- **后台**：`admin / admin123`（super 全权限）、`operator1 / admin123`（只读）
- **小程序**：生产走微信 `uni.login` 真实登录（需在系统设置配小程序 AppID）；本地开发用任意 code 登录生成居民（如 `buyer1` 有余额订单、`leader1` 为团长）

## 接口概览（前缀 `/api`）

| 分组 | 示例 | 鉴权 |
|---|---|---|
| 小程序公开 | `home` `group-buys` `pickup-points` `errands` `companions` | 无 |
| 小程序用户 | `auth/*` `orders/*` `errands/*` `companions/*` `user/*` | `auth:api` |
| 团长端 | `leader/*` | `auth:api` + is_leader |
| 后台 | `admin/auth/login` · `admin/*` | `auth:admin` + RBAC |

---

## 生产部署

> 下文以 `Linux + Nginx + PHP-FPM + MySQL + Redis` 为例。整套是**纯 API**，前端（`linli-admin` / `linli-mp`）单独构建部署，本节只负责把后端跑起来。

### 1. 环境要求

| 组件 | 版本 | 说明 |
|---|---|---|
| PHP | **8.3**（≥8.2 即可） | 扩展：`pdo_mysql` `mbstring` `openssl` `bcmath` `ctype` `json` `tokenizer` `redis`(用 Redis 时) |
| Composer | 2.x | 拉依赖 |
| MySQL | **5.7+** | 本项目 schema 兼容 5.7，MySQL 8 亦可 |
| Redis | 5+ | 生产**强烈建议**：缓存 + 队列驱动 |
| Nginx | 稳定版 | 反代到 `public/`；HTTPS（小程序强制 https） |

### 2. 拉代码 & 装依赖

```bash
git clone https://gitee.com/xrlnewman/linli-server.git
cd linli-server
composer install --no-dev -o          # 生产不装 dev 依赖 + 优化自动加载
cp .env.example .env
```

### 3. 配置 `.env`

关键项（其余保持默认即可）：

```dotenv
APP_NAME=linli
APP_ENV=production
APP_DEBUG=false                        # 生产务必 false，否则泄漏堆栈/配置
APP_URL=https://api.your-domain.com

# 数据库 → 指向 MySQL（先建好库，字符集 utf8mb4）
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=linli
DB_USERNAME=linli
DB_PASSWORD=改成你的强密码

# 缓存 + 队列 走 Redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```

生成两个密钥（会自动写回 `.env`）：

```bash
php artisan key:generate                # 写 APP_KEY
php artisan jwt:secret                  # 写 JWT_SECRET（鉴权签名密钥，务必生成）
```

> 第三方密钥（微信/支付宝/短信/快递/小程序 AppID）**不写在这里**，在后台「系统设置」页填，见下文「第三方密钥」。

### 4. 建表 & 初始化数据

```bash
php artisan migrate --force                              # --force：生产环境免交互确认
php artisan db:seed --force                               # 首次：一键播种（团购/跑腿/搭子/钱包/积分 + 权限/角色/后台账号/模式开关）
# 仅需权限/账号、不要演示业务数据时，可单独：php artisan db:seed --class=DemoSeeder --force（再清业务表）
```

> `DemoSeeder` 中**权限/角色/后台账号/模式开关**用 `firstOrCreate`/`updateOrCreate` 幂等写入，**业务演示数据**（卖家/商品/团购/订单等）每次跑会先清空再重建。
> **正式上线**若不想要演示业务数据：可只取该 seeder 里权限/角色/后台账号那几段执行（或跑完后自行清理业务表），保留 `admin` 账号与 RBAC 即可。

### 5. 缓存优化 & 目录权限

```bash
php artisan config:cache       # 缓存配置（改 .env 后需重跑）
php artisan route:cache        # 缓存路由
# 部署/改配置后清缓存：php artisan optimize:clear

# 运行时目录给 Web 用户写权限（按你的 php-fpm 用户调整，如 www-data）
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

### 6. 队列 worker（supervisor 守护）

订单/支付/短信等异步任务走队列，生产用 [supervisor](http://supervisord.org/) 守护常驻进程。
新建 `/etc/supervisor/conf.d/linli-queue.conf`：

```ini
[program:linli-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /www/wwwroot/linli-server/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
directory=/www/wwwroot/linli-server
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/www/wwwroot/linli-server/storage/logs/queue.log
stopwaitsecs=3600
```

加载并启动：

```bash
supervisorctl reread
supervisorctl update
supervisorctl start linli-queue:*
# 每次发版后让 worker 重载新代码：
php artisan queue:restart
```

### 7. Nginx 反向代理（HTTPS + PHP-FPM）

`server` 块（站点根指向 `public/`；小程序要求 https，下面带 HTTP→HTTPS 跳转）：

```nginx
# HTTP → HTTPS 跳转
server {
    listen 80;
    server_name api.your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.your-domain.com;

    root /www/wwwroot/linli-server/public;   # 注意：指向 public 目录
    index index.php;

    ssl_certificate     /etc/nginx/ssl/api.your-domain.com.pem;
    ssl_certificate_key /etc/nginx/ssl/api.your-domain.com.key;

    client_max_body_size 20m;                # 留够给图片/上传

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass   unix:/run/php/php8.3-fpm.sock;   # 按你的 php-fpm 套接字调整
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include        fastcgi_params;
    }

    # 隐藏点文件（.env 等）
    location ~ /\.(?!well-known).* { deny all; }
}
```

### 8. 第三方密钥（全部在后台「系统设置」页填，无需改代码/重启）

所有外部服务凭据都存数据库（`settings`），登录后台 → **系统设置** 页面填写并保存即可生效，**不用动 `.env`、不用重启**。各项去哪获取：

| 配置项 | 用途 | 获取位置 |
|---|---|---|
| 小程序 **AppID / AppSecret** | 微信登录(jscode2session) | 微信公众平台 → 开发管理 → 开发设置 |
| **微信支付** 商户号/APIv3 密钥/证书 | 小程序下单支付 | 微信支付商户平台（pay.weixin.qq.com） |
| **支付宝** AppID/应用私钥/支付宝公钥 | 支付宝支付（如启用） | 支付宝开放平台（open.alipay.com） |
| **短信**（阿里云/腾讯云）AccessKey、签名、模板 | 手机号验证码 | 阿里云短信控制台 / 腾讯云 SMS 控制台 |
| **快递查询**（快递100 / 快递鸟）授权 key | 物流轨迹查询 | kuaidi100.com / kdniao.com 开放平台 |

> 设计意图：运营自助换密钥，不依赖发版。代码侧 `yansongda/pay`(支付)、`overtrue/easy-sms`(短信) 均从 `settings` 动态读取配置。

### 9. 上线安全清单

- [ ] **改默认密码**：`admin / admin123`、`operator1 / admin123` 上线后立刻改掉
- [ ] `APP_DEBUG=false`、`APP_ENV=production`（关堆栈泄漏）
- [ ] `APP_KEY`、`JWT_SECRET` 已生成且**妥善保管**（泄漏=可伪造登录态）
- [ ] **CORS** 只放行前端域名：发布 `config/cors.php`（`php artisan config:publish cors`）后，把 `allowed_origins` 收敛为后台域名，勿用 `*`
- [ ] 数据库账号最小权限、强密码；Redis 设密码或仅监听内网
- [ ] 全站 HTTPS（小程序合法域名强制 https）；`.env` 等敏感文件不可被 Web 访问（已由上面 Nginx `deny` 覆盖）
- [ ] supervisor 队列 worker 已常驻；发版后 `php artisan queue:restart`

---

配套仓库：[`linli-mp`](https://gitee.com/xrlnewman/linli-mp)（微信小程序 uniapp） · [`linli-admin`](https://gitee.com/xrlnewman/linli-admin)（后台管理端 Vue3）

---

## 功能展示

> 本仓库是后端 API，驱动 **后台管理端**（[`linli-admin`](https://gitee.com/xrlnewman/linli-admin)）与 **微信小程序**（[`linli-mp`](https://gitee.com/xrlnewman/linli-mp)）。以下为两端主模块实测截图（更多见各前端仓库 `docs/screenshots/`）。

### 后台管理端（运营）
| 工作台 | 订单发货（填快递） | 系统设置（密钥配置） |
|---|---|---|
| ![后台工作台](docs/screenshots/admin-dashboard.png) | ![订单发货](docs/screenshots/admin-order-ship.png) | ![系统设置](docs/screenshots/admin-settings.png) |

### 微信小程序（居民端 + 团长端）
| 居民首页 | 社区团购下单 | 团长工作台 |
|---|---|---|
| ![小程序首页](docs/screenshots/mp-home.png) | ![团购下单](docs/screenshots/mp-groupbuy.png) | ![团长工作台](docs/screenshots/mp-leader.png) |