jacobajak/Restop_public
GitHub: jacobajak/Restop_public
基于二维码扫描的多租户餐厅数字点餐 SaaS 平台，集成了非洲移动支付和实时订单管理功能。
Stars: 0 | Forks: 0
# RESTOP - 基于二维码的多租户餐厅点餐平台
一个使用二维码的综合数字点餐平台，顾客可以扫描并从数字菜单中点餐，同时餐厅老板可以通过专用的仪表板管理运营。
## 🚀 项目概述
RESTOP 是一个处于 MVP 阶段的平台，设计为多租户系统，支持：
- **顾客界面**：通过扫描二维码访问的 Web 应用程序进行点餐
- **租户仪表板**：餐厅管理和订单处理
- **后端服务**：多租户订单、菜单和支付处理
- **实时更新**：基于 WebSocket 的实时订单通知
- **MoMo 准备就绪**：为移动支付集成准备的支付架构
## 📁 项目结构
```
RESTOP/
├── frontend/ # Next.js customer & dashboard interface
│ ├── src/
│ │ ├── app/ # Next.js app directory
│ │ ├── components/ # React components
│ │ ├── services/ # API service layer
│ │ ├── types/ # TypeScript type definitions
│ │ ├── hooks/ # Custom React hooks
│ │ ├── context/ # Context API providers
│ │ └── styles/ # Global styles
│ └── package.json
├── backend/ # NestJS API server
│ ├── src/
│ │ ├── modules/ # Feature modules
│ │ ├── common/ # Guards, middleware, decorators
│ │ ├── database/ # Database entities & migrations
│ │ └── config/ # Configuration files
│ └── package.json
├── docker/ # Docker compositions
├── docs/ # Documentation
└── README.md
```
## 🛠️ 技术栈
### 前端
- **框架**：Next.js 14
- **样式**：Tailwind CSS
- **状态管理**：Zustand
- **API 客户端**：Axios + React Query
- **实时通信**：Socket.IO
### 后端
- **框架**：NestJS
- **数据库**：PostgreSQL
- **ORM**：TypeORM
- **身份验证**：JWT + Passport
- **实时通信**：WebSockets (Socket.IO)
- **缓存**：Redis
### 基础设施与服务
- **容器化**：Docker
- **CI/CD**：GitHub Actions
- **部署**：AWS/GCP/DigitalOcean
- **支付网关**：Flutterwave (MTN/Airtel Mobile Money)
- **电子邮件**：Ethereal (测试) / SendGrid (生产)
- **监控**：内置断路器、健康检查
## 🚀 快速开始
### 前置条件
- Node.js 18+
- PostgreSQL 14+
- Redis 7+
- Docker（可选）
### 设置前端
```
cd frontend
cp .env.example .env.local
npm install
npm run dev
# 前端可通过 http://localhost:3000 访问
```
### 设置后端
```
cd backend
cp .env.example .env
npm install
npm run dev
# 后端可通过 http://localhost:3001 访问
```
## 📊 核心功能 (MVP)
### 顾客功能
- ✅ 扫描二维码
- ✅ 浏览数字菜单
- ✅ 将商品添加到购物车
- ✅ 查看包含平台费用的商品明细定价
- ✅ 下单并进行现金确认
- ✅ 实时订单状态更新
- ✅ **Mobile Money 支付**（通过 Flutterwave 的 MTN/Airtel）
- ✅ 自动扣除佣金 (10%)
- ✅ 幂等性保护的交易
### 租户（餐厅）功能
- ✅ 用于订单管理的仪表板
- ✅ 菜单管理（添加/编辑/删除商品）
- ✅ 实时订单通知
- ✅ 支持多种支付方式
- ✅ **支付账户注册**（MTN/Airtel）
- ✅ 自动支付结算（<5 分钟）
- ✅ 订单状态管理
- ✅ 销售分析
- ✅ 二维码管理
### 管理/平台功能
- ✅ 多租户隔离
- ✅ 租户入驻
- ✅ **平台佣金追踪**（实时钱包）
- ✅ **佣金分类账**（支付历史）
- ✅ 收入追踪与分析
- ✅ 系统监控
- ✅ 支付验证与对账
- ✅ 断路器与弹性模式
## 🔐 安全
- 基于 JWT 的身份验证
- 使用 tenant_id 过滤实现租户数据隔离
- Bcrypt 密码哈希
- CORS 保护
- 速率限制
- 输入验证
- HTTPS 强制执行（生产环境）
## 🔄 API 架构
基础 URL：`/api/v1`
### 支付端点（新增）
- `POST /orders/{orderId}/pay` - 发起 MTN/Airtel 支付
- `PATCH /orders/{orderId}/mark-paid` - 将现金订单标记为已支付
- `POST /webhooks/flutterwave` - Flutterwave Webhook 接收器
- `POST /tenants/{tenantId}/payment-accounts` - 注册支付账户
- `GET /admin/wallet` - 查看平台佣金钱包
- `GET /admin/ledger` - 查看佣金历史
### 菜单 API
- `GET /menu/{tenant_slug}` - 获取餐厅菜单
- `POST /menu/items` - 添加菜单项（租户）
- `PUT /menu/items/{id}` - 更新菜单项
- `PATCH /menu/items/{id}/availability` - 切换可用状态
**订单 API**
- `POST /orders` - 创建订单
- `GET /orders` - 获取订单（租户）
- `PATCH /orders/{id}/confirm` - 确认订单
- `PATCH /orders/{id}/reject` - 拒绝订单
- `PATCH /orders/{id}/status` - 更新订单状态
**分析 API**
- `GET /analytics/sales` - 销售分析
- `GET /financial-analytics/summary` - 财务概览
**完整 API 参考（91+ 个端点）请参见 [ENDPOINT_REFERENCE_GUIDE.md](ENDPOINT_REFERENCE_GUIDE.md)**
## 💳 支付集成
### Flutterwave 原生集成（2026 年 4 月）
RESTOP 现在使用 **Flutterwave 的原生支付时分账模型**：
**工作原理：**
1. 顾客发起 MTN/Airtel 支付
2. Flutterwave 自动拆分支付：
- 平台获得 10% 佣金
- 租户获得 90%（自动支付 <5 分钟）
3. 订单标记为 PAID，并启动支付
4. 佣金记录在管理员钱包中
**功能：**
- ✅ 10% 自动扣除佣金
- ✅ <5 分钟支付结算
- ✅ 带有幂等性的 Webhook 验证
- ✅ 断路器错误处理
- ✅ 每 5-10 分钟自动对账
- ✅ 网络故障时的优雅降级
**支付方式：**
- 🇷🇼 MTN Mobile Money (0788/0789)
- 🇷🇼 Airtel Money (0773/0774)
- 💰 现金（货到付款）
**完整功能清单请参见 [PAYMENT_FEATURES_AND_GAPS_ANALYSIS.md](PAYMENT_FEATURES_AND_GAPS_ANALYSIS.md)**
## 📚 文档
完整文档整理在 [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md) 中。
### 核心文档
- 📖 [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md) - 中央文档指南
- 🔧 [ENDPOINT_REFERENCE_GUIDE.md](ENDPOINT_REFERENCE_GUIDE.md) - API 端点 (91+)
- 💳 [PAYMENT_FEATURES_AND_GAPS_ANALYSIS.md](PAYMENT_FEATURES_AND_GAPS_ANALYSIS.md) - 支付功能清单
- 🧪 [FLUTTERWAVE_TESTING_GUIDE_NOW.md](FLUTTERWAVE_TESTING_GUIDE_NOW.md) - 逐步测试指南
- 🚀 [QUICK_CURL_TESTS.md](QUICK_CURL_TESTS.md) - 快速测试的 curl 命令
- 🌐 [FRONTEND_ROUTES_AND_ACCESS.md](FRONTEND_ROUTES_AND_ACCESS.md) - 前端路由指南
- 🔐 [RBAC_DEVELOPER_GUIDE.md](RBAC_DEVELOPER_GUIDE.md) - 身份验证与授权
- 📱 [OFFLINE_READINESS_ANALYSIS.md](OFFLINE_READINESS_ANALYSIS.md) - 离线能力分析
- 📊 [MVP_FEATURE_SUMMARY.md](MVP_FEATURE_SUMMARY.md) - MVP 功能概览
## 🧪 快速测试
### 测试支付端点 (CLI)
```
# 详细的测试指南请参见 QUICK_CURL_TESTS.md
# Health check
curl http://localhost:3001/api/v1/admin/health
# 创建订单
curl -X POST http://localhost:3001/api/v1/orders \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{"tenant_id": "test-tenant", "total_amount": 10000, "payment_method": "MTN"}'
# 发起支付
curl -X POST http://localhost:3001/api/v1/orders/{orderId}/pay \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{"customer_phone": "0788123456"}'
```
**综合测试指南：** 参见 [FLUTTERWAVE_TESTING_GUIDE_NOW.md](FLUTTERWAVE_TESTING_GUIDE_NOW.md)
## ⚙️ 配置
### 环境变量（后端）
```
# Database
DATABASE_URL=postgresql://restop:restop_password@localhost:5432/restop_db
# Flutterwave (Staging)
FLUTTERWAVE_CLIENT_ID=your-client-id
FLUTTERWAVE_SECRET_KEY=your-secret-key
FLUTTERWAVE_SECRET_HASH=your-webhook-hash
FLUTTERWAVE_ENV=staging
# JWT
JWT_SECRET=your-jwt-secret
# Redis (可选，graceful fallback)
REDIS_HOST=localhost
REDIS_PORT=6379
```
## 📱 离线能力状态
**当前：** ⚠️ 需要联网（Flutterwave 支付，实时数据库）
**分析：** 在 [OFFLINE_READINESS_ANALYSIS.md](OFFLINE_READINESS_ANALYSIS.md) 中的全面离线准备情况分析
**可能实现的离线功能：**
- ✅ 菜单浏览（缓存）
- ✅ 挂起的订单创建
- ✅ 重新连接时同步
**需要联网的功能：**
- ❌ Flutterwave MoMo 支付
- ❌ 实时订单更新
- ❌ 佣金结算
**建议：** 在第二阶段实现 PWA + 离线队列（需 3-4 周时间）
## 🚀 部署
### Docker
```
docker-compose up
```
### 手动部署
前端部署到 Vercel：
```
cd frontend
vercel deploy
```
后端部署（Docker）：
```
cd backend
docker build -t restop-backend .
docker run -p 3001:3001 restop-backend
```
## 📝 数据库架构
所有表都包含 `tenant_id` 用于多租户隔离。
核心表：
- `tenants` - 餐厅信息
- `users` - 餐厅员工
- `menu_categories` - 菜单分类
- `menu_items` - 单个菜单项
- `orders` - 顾客订单
- `order_items` - 订单子项
- `payments` - 支付记录
- `qr_codes` - 二维码映射
## 🔮 第二阶段及以后的增强
### 第二阶段（MVP 之后）
- 📱 带有 PWA + Service Worker 的离线模式
- 🔌 高级离线支付队列与同步
- 📧 电子邮件/短信通知（Ethereal 测试 → SendGrid 生产）
- 📊 高级分析仪表板
- 🛏️ 餐桌管理系统
- ⭐ 顾客评论与评分
- 👥 会员忠诚度计划
### 第三阶段及以后
- 🌍 多语言支持
- 📱 移动应用（iOS/Android）
- 📅 预订系统
- 💳 多币种支持
- 🔄 订阅计费
- 📈 预测性分析
## 🤝 贡献
欢迎贡献代码！请遵循现有的代码结构和提交信息规范。
## 🧹 项目维护
**上次清理：** 2026 年 4 月 21 日
- ✅ 移除了 59 个不必要的文件（测试文件、日志、旧迁移）
- ✅ 将 14 个冗余的支付文档合并 → 4 个核心文档
- ✅ 通过 DOCUMENTATION_INDEX.md 组织文档
- ✅ 验证后端编译零 TypeScript 错误
- ✅ 修复了 NestJS 依赖注入问题
**关键数据：**
- 📊 15+ 个模块中的 91+ 个 API 端点
- 🗄️ 25+ 个具有多租户隔离的数据库表
- 🔐 带有 RBAC 的 JWT + Passport 身份验证
- 🌊 具有断路器弹性的 Flutterwave 集成
- ✅ 后端已测试并在端口 3001 上运行
- ✅ 前端已在端口 3000 上准备就绪
## 📄 许可证
MIT 许可证 - 详情请参见 LICENSE 文件
## 📧 支持与贡献
如有问题或疑问，请：
1. 首先查看 [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)
2. 审阅上述列表中的相关文档
3. 在仓库中创建一个 Issue，包含：
- 对问题的清晰描述
- 重现步骤
- 相关日志/错误
欢迎贡献代码！请遵循现有的代码结构和提交信息规范。
标签：API服务, Axios, CISA项目, IP 地址批量处理, NestJS, React, React Query, SaaS平台, Syscalls, Tailwind CSS, TypeScript, WebSocket, Web应用开发, Zustand, 二维码菜单, 依赖分析, 前后端分离, 在线点餐系统, 外卖点单系统, 多租户架构, 安全插件, 实时订单通知, 扫码点餐, 搜索引擎查询, 数字化转型, 测试用例, 点单系统, 移动支付集成, 移动钱包, 自动化攻击, 请求拦截, 餐厅管理面板, 餐饮数字化