内容
<div align="center">
<img src="resources/banner.png" alt="Laravel 邀请" width="100%" />
# Laravel 邀请
**适用于 Laravel 的企业邀请码、推荐、奖励、等待列表和反滥用套件。**
多租户 · 并发安全 · 幂等兑换 · GDPR 准备 · 三层表面（PHP + HTTP API + MCP）
[](https://packagist.org/packages/padosoft/laravel-invitations)
[](https://github.com/padosoft/laravel-invitations/actions)
[](https://www.php.net)
[](https://laravel.com)
[](LICENSE)
</div>
> ⚠️ **正在积极开发 `v1.0.0` 版本。** 引擎已经过生产验证（从一个正在运行的应用程序中提取），并经过了充分的测试；公共 API 可能在 `v1.0.0` 标签之前仍会发生变化。
📖 **完整文档：** **[doc.laravel-invitations.padosoft.com](https://doc.laravel-invitations.padosoft.com)**
— 深入的学术指南，涵盖原子兑换、多租户、反滥用、K因子分析、三层表面 API、GDPR 和架构决策记录。
---
## 🚀 AI 振动编码包已包含
该存储库附带一个完整的 AI 配对编程工具包：[`CLAUDE.md`](CLAUDE.md)（工程不变式 + 质量门控）、[`AGENTS.md`](AGENTS.md) 和 [`docs/`](docs) 下的设计/路线图文档。将 Claude Code、Cursor 或 Copilot 指向存储库，它们将自动继承包的规则（原子兑换、租户范围、故障开启欺诈、GRANT-never-REVOKE）。
---
## 为什么选择这个包
市场上的每个 Laravel 邀请/推荐包都停留在“生成代码，标记为已使用”。它们都没有解决生产中真正的问题：
- **它们在负载下过度兑换。** 流行的包通过检查然后写入的方式递增使用计数器，并且 **没有锁** —— 两个并发兑换都通过了“1 个座位剩余”的检查。 这是一个免费代码/容量过大的错误。
- **它们是单租户的。** 代码是全局唯一的，因此两个客户永远无法共享一个直观的代码，并且行会泄漏到租户边界。
- **它们永久存储邀请者电子邮件** ，没有删除路径 — GDPR 负债。
- **它们没有事件，没有欺诈控制，没有分析，也没有 API/MCP 接口。**
`padosoft/laravel-invitations` 是按照相反的方式构建的：优先考虑正确性、多租户、隐私和可观察性。
## ✨ 特色
- 🎟️ **邀请码** — 随机、自定义和 **加密签名** （Crockford Base32，无混淆字符），具有过期时间、最大使用次数和每用户限制。
- ⚛️ **原子、幂等、并发安全兑换** — 单个条件 `UPDATE … WHERE current_uses < max_uses` 在同一语句中翻转状态，由 `UNIQUE(code_id, redeemer_id)` 索引支持。`current_uses` 永远不会超过 `max_uses` ；重放是一个无操作，而不是双重授权 — 即使在高并发下。
- 🏢 **多租户设计** — 每个表都作用于租户范围；两个租户可以共享相同的代码。单租户应用程序具有零配置默认值。
- 🎁 **推荐图 + 双向奖励** ，具有基于数据库的幂等键（无双重授权）。
- 📨 **电子邮件邀请** — 幂等发送/接受生命周期，“谁接受 vs. 谁没有”。
- 🛡️ **故障开启反滥用** — 加权速度 / 处置电子邮件 / 蜂蜜锅 / 黑名单评分，显示一个通用 `rate_limited` （从不探测预言机），并仅存储 **HMAC 哈希** PII 。检测器故障永远不会阻止真实用户；座位安全是原子声明的工作。
- 🔑 **每个邀请的权限授予** — 邀请可以在兑换时授予角色和项目访问权限，跨一个或多个租户。 **GRANT-never-REVOKE** ：它只会提高访问权限。
- 📈 **病毒式传播分析** — K因子、接受/转换率、兑换时间百分位，与规范行（不是漂移的滚动汇总）进行核对。
- 🔔 **事件** 在每个生命周期转换上。
- 🔒 **GDPR** — 就地 PII 匿名化，**保留聚合** + 预定修剪命令。
- 🧩 **三层表面** — 相同的核心可以从 **PHP** （服务 + Artisan）、**REST API** （基于 RBAC、发布路由）和 **MCP** 工具访问。
- 🤝 **供应商中立** — 在纯 Fortify/Breeze 上运行；`spatie/laravel-permission` 、 `laravel/fortify` 和 `laravel/mcp` 是可选的、一流的集成。
## 比较
| 功能 | **laravel-invitations** | doorman | mateusjunges/invite-codes | pdazcom/referrals | taldres/waitlist |
|---|:---:|:---:|:---:|:---:|:---:|
| 邀请码（最大使用次数） | ✅ | ✅ | ✅ | — | — |
| **并发安全兑换** | ✅ | ❌ | ❌ | — | — |
| **幂等重放** | ✅ | ❌ | ❌ | ⚠️ | ⚠️ |
| **多租户范围** | ✅ | ❌ | ❌ | ❌ | ❌ |
| 自定义/签名代码 | ✅ | ❌ | ⚠️ | — | ⚠️ |
| 电子邮件邀请 | ✅ | ✅ | ⚠️ | ❌ | ⚠️ |
| 推荐图 + 双向奖励 | ✅ | ❌ | ❌ | ⚠️ 仅限推荐人 | ❌ |
| **反滥用/欺诈** | ✅ | ❌ | ❌ | ⚠️ 自我引用 | ❌ |
| 每个邀请的角色/权限授予 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 病毒式传播分析（K因子） | ✅ | ❌ | ❌ | ❌ | ❌ |
| GDPR 删除 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 事件/钩子 | ✅ | ❌ | ✅ | ✅ | ✅ |
| HTTP API + **MCP** 接口 | ✅ | ❌ | ❌ | ❌ | ❌ |
## 要求
- PHP `^8.3`
- Laravel `^12.0 | ^13.0`
## 安装
```bash
composer require padosoft/laravel-invitations
php artisan migrate
```
使您的用户模型具有邀请感知能力：
```php
use Illuminate\Foundation\Auth\User as Authenticatable;
use Padosoft\Invitations\Concerns\InteractsWithInvitations;
use Padosoft\Invitations\Contracts\InvitedAccount;
class User extends Authenticatable implements InvitedAccount
{
use InteractsWithInvitations; // 读取 `email` + 认证守护器用于引擎
}
```
发布配置（可选）：
```bash
php artisan vendor:publish --tag=invitations-config
```
## 快速开始
**生成代码** （PHP）：
```php
use Padosoft\Invitations\Services\CodeGenerator;
$code = app(CodeGenerator::class)->generateRandom(['max_uses' => 100]);
$batch = app(CodeGenerator::class)->generateBatch(500); // 500 个不同代码
```
**兑换代码** — 原子、幂等、欺诈防护：
```php
use Padosoft\Invitations\Services\RedemptionService;
$result = app(RedemptionService::class)->redeem($rawCode, $user, [
'ip' => $request->ip(),
'fingerprint' => $request->header('X-Device'),
]);
if ($result->ok) {
// $result->already === true 表示幂等重放（无二次授权）
// $result->redemption, $result->referral
} else {
// $result->error: invalid | expired | exhausted | revoked | ineligible | rate_limited
}
```
**通过 REST API** （路由自动注册；通过配置附加自己的身份验证/RBAC）：
```http
POST /api/invitations/redeem { "code": "Q7K92MNP" }
POST /api/invitations/validate { "code": "Q7K92MNP" } # 咨询，不写入任何内容
GET /api/admin/invitations/metrics
POST /api/admin/invitations/codes { "count": 50, "max_uses": 1 }
```
**通过 MCP** — 在服务器上注册捆绑工具：
```php
// app/Mcp/Servers/YourServer.php
public array $tools = [
\Padosoft\Invitations\Mcp\Tools\InviteValidateCodeTool::class,
\Padosoft\Invitations\Mcp\Tools\InviteGenerateCodesTool::class,
\Padosoft\Invitations\Mcp\Tools\InviteMetricsTool::class,
];
```
## 架构
```mermaid
flowchart LR
Caller["PHP · HTTP API · MCP · CLI"] --> RS[RedemptionService]
RS -->|validate| CV[CodeValidator]
RS -->|fail-open gate| FD[FraudDetector]
RS -->|atomic UPDATE + UNIQUE| DB[(invite_codes / invite_redemptions)]
RS -->|attribute| REF[ReferralService] --> RE[RewardEngine]
RS -->|GRANT-never-REVOKE| PROV[Provisioner*]
RS -->|fire once| EV([CodeRedeemed event])
MS[MetricsService] --> DB
```
`*` Provisioners 是可插拔的：默认情况下提供 `SpatiePermissionProvisioner` （角色授权）；主机可以添加自己的提供者，位于 `invitations.provisioners` 标签下。
## 主机集成缝隙
引擎永远不会硬编码您的应用程序。三个小的缝隙使其对供应商保持中立：
| 缝隙 | 默认值 | 覆盖条件 |
|---|---|---|
| `Contracts\TenantResolver` | 单租户（`'default'`） | 您是多租户 — 绑定自己的解析器 |
| `Contracts\Provisioner` （标签 `invitations.provisioners`） | `SpatiePermissionProvisioner` （角色） | 您在兑换时授予更多权限（例如团队/项目成员资格） |
| `Contracts\InvitedAccount` | `InteractsWithInvitations` 特性 | 您的用户模型存储电子邮件的方式不同 |
```php
// 多租户主机，在服务提供者中：
$this->app->bind(\Padosoft\Invitations\Contracts\TenantResolver::class, MyTenantResolver::class);
$this->app->tag([MyProjectMembershipProvisioner::class], 'invitations.provisioners');
```
## 事件
`CodeRedeemed` （在新声明时触发一次 — 绝不会在幂等重放时触发）、 `InvitationSent` 、 `InvitationAccepted` 。监听以授予特权、发送欢迎消息或更新您自己的投影。
## GDPR
PII（IP 地址 / 指纹 / 收件人）以哈希或可匿名化的形式存储。计划的清理程序会就地匿名化保留期过后的行 — `current_uses` 、漏斗计数和 K因子不受影响：
```bash
php artisan invite:prune-pii --days=90
```
## 配置
所有配置项都位于 `config/invitations.php` 中，可以通过环境变量覆盖 — 代码字母表/长度、签名密钥、PII 保留时间、反滥用阈值/速度/黑名单，以及路由前缀 + 每个表面中间件（将您的 RBAC 门控附加到 `invitations.routes.admin_middleware` ）。
## Web 管理面板
[`padosoft/laravel-invitations-admin`](https://github.com/padosoft/laravel-invitations-admin) 提供了基于此包 API 的精美 **React + Tailwind** 管理单页应用 — 病毒式传播仪表盘 + 活动、代码、邀请（谁接受 vs. 谁没有）、推荐图、奖励账本、等待列表和反滥用审查。默认关闭，主机门控，预构建资产（无需安装 JS 工具链）。对于已经运行自己的 React 单页应用的应用程序，可以在本机适配屏幕，而不是跨挂载。
<p align="center">
<img src="resources/laravel-invitations-admin-dashboard-dark.png" alt="邀请 & 生长管理 — 病毒式传播仪表盘" width="100%" />
</p>
## 测试
```bash
composer test # PHPUnit (Testbench)
composer analyse # PHPStan
composer check # 格式化 + 分析 + 测试
```
## 许可证
MIT © [Padosoft](https://www.padosoft.com)。查看 [LICENSE](LICENSE)。
