199 lines
5.3 KiB
Markdown
199 lines
5.3 KiB
Markdown
# 邀请码申请管理功能
|
||
|
||
## 功能概述
|
||
|
||
本功能为 Goalfy 管理后台新增了邀请码申请管理功能，支持官网用户提交邀请码申请、后台管理员审批、自动发送邮件通知等完整流程。
|
||
|
||
## 功能架构
|
||
|
||
### 1. 数据库设计
|
||
|
||
新增邀请码申请表 `admin_invite_code_applications`：
|
||
|
||
- `id` - 主键ID
|
||
- `email` - 申请邮箱（必填）
|
||
- `reason` - 申请理由（选填）
|
||
- `status` - 申请状态（pending/approved/rejected）
|
||
- `invite_code_id` - 关联的邀请码ID
|
||
- `reject_reason` - 拒绝理由
|
||
- `approved_at` - 审批时间
|
||
- `approved_by` - 审批人
|
||
- `email_sent_at` - 邮件发送时间
|
||
- `created_at` - 创建时间
|
||
- `updated_at` - 更新时间
|
||
- `deleted_at` - 软删除时间
|
||
|
||
### 2. 后端功能
|
||
|
||
#### API 接口
|
||
|
||
**公开接口（官网使用）：**
|
||
- `POST /api/public/invite-code/apply` - 提交邀请码申请
|
||
|
||
**管理后台接口（需认证）：**
|
||
- `GET /api/admin/invite-applications` - 获取申请列表
|
||
- `GET /api/admin/invite-applications/statistics` - 获取统计信息
|
||
- `GET /api/admin/invite-applications/pending-count` - 获取待处理数量
|
||
- `POST /api/admin/invite-applications/approve` - 审批通过
|
||
- `POST /api/admin/invite-applications/reject` - 审批拒绝
|
||
- `POST /api/admin/invite-applications/batch-approve` - 批量审批通过
|
||
- `POST /api/admin/invite-applications/batch-reject` - 批量审批拒绝
|
||
|
||
#### 邮件服务
|
||
|
||
实现了基于 SMTP 的邮件发送服务，支持：
|
||
- 审批通过邮件（包含邀请码和注册链接）
|
||
- 审批拒绝邮件（包含拒绝理由）
|
||
- 批量发送邮件
|
||
|
||
### 3. 前端功能
|
||
|
||
#### 管理后台界面
|
||
|
||
在邀请码管理页面新增：
|
||
- **待处理申请按钮** - 显示待处理数量，点击打开申请列表
|
||
- **申请列表弹窗** - 显示所有待处理申请，支持：
|
||
- 单个申请审批（同意/拒绝）
|
||
- 批量审批操作
|
||
- 拒绝原因填写
|
||
- 实时更新待处理数量
|
||
|
||
## 使用流程
|
||
|
||
### 1. 官网用户申请流程
|
||
|
||
1. 用户访问官网申请页面
|
||
2. 填写邮箱（必填）和申请理由（选填）
|
||
3. 提交申请
|
||
4. 系统提示"申请已提交，将在1-2个工作日内处理"
|
||
|
||
### 2. 管理员审批流程
|
||
|
||
1. 管理员登录后台
|
||
2. 进入邀请码管理页面
|
||
3. 点击"待处理申请"按钮
|
||
4. 查看申请列表
|
||
5. 审批操作：
|
||
- **同意**：自动创建邀请码（默认7天有效期），发送邮件通知
|
||
- **拒绝**：可填写拒绝原因，发送邮件通知
|
||
6. 支持批量操作
|
||
|
||
### 3. 邮件通知流程
|
||
|
||
**审批通过邮件内容：**
|
||
- 主题：Goalfy 邀请码已发放
|
||
- 内容：邀请码、有效期、注册链接
|
||
- 注意事项：邀请码仅限使用一次
|
||
|
||
**审批拒绝邮件内容：**
|
||
- 主题：关于您的 Goalfy 申请
|
||
- 内容：拒绝原因（如未填写则使用默认文案）
|
||
- 联系方式：support@goalfy.com
|
||
|
||
## 环境配置
|
||
|
||
### 邮件服务配置（.env）
|
||
|
||
```env
|
||
# Email SMTP Configuration
|
||
EMAIL_SENDER=goalfymax@goalfyai.com
|
||
EMAIL_HOST=smtp.mxhichina.com
|
||
EMAIL_PORT=465
|
||
EMAIL_USERNAME=goalfymax@goalfyai.com
|
||
EMAIL_PASSWORD=efRuPRpGKS6gZpuw
|
||
```
|
||
|
||
## 部署说明
|
||
|
||
### 1. 数据库迁移
|
||
|
||
执行数据库迁移脚本：
|
||
|
||
```bash
|
||
cd /path/to/goalfymax-admin
|
||
./scripts/migrate.sh
|
||
```
|
||
|
||
### 2. 后端部署
|
||
|
||
```bash
|
||
# 构建后端
|
||
go build -o admin-server cmd/server/main.go
|
||
|
||
# 运行服务
|
||
./admin-server
|
||
```
|
||
|
||
### 3. 前端部署
|
||
|
||
```bash
|
||
cd /path/to/goalfymax-admin-web
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
## 测试方法
|
||
|
||
### 1. API 测试
|
||
|
||
使用提供的测试脚本：
|
||
|
||
```bash
|
||
./scripts/test_api.sh
|
||
```
|
||
|
||
### 2. 官网申请页面测试
|
||
|
||
打开 `docs/invite_apply_example.html` 文件，可测试申请提交功能。
|
||
|
||
### 3. 手动测试流程
|
||
|
||
1. 通过官网页面提交申请
|
||
2. 登录管理后台
|
||
3. 查看待处理申请数量
|
||
4. 点击查看申请列表
|
||
5. 执行审批操作
|
||
6. 检查邮件是否发送成功
|
||
|
||
## 文件清单
|
||
|
||
### 后端文件
|
||
|
||
- `internal/models/invite_code_application.go` - 申请数据模型
|
||
- `internal/services/invite_code_application_service.go` - 申请业务逻辑
|
||
- `internal/services/email_service.go` - 邮件发送服务
|
||
- `internal/api/handlers/invite_code_application_handler.go` - API处理器
|
||
- `internal/api/routes/routes.go` - 路由配置（已更新）
|
||
- `migrations/20250131_add_invite_code_applications_table.sql` - 数据库迁移
|
||
|
||
### 前端文件
|
||
|
||
- `src/types/inviteCodeApplication.ts` - 申请类型定义
|
||
- `src/services/inviteCodeApplicationApi.ts` - API服务
|
||
- `src/pages/InviteCodes.tsx` - 邀请码管理页面（已更新）
|
||
|
||
### 脚本文件
|
||
|
||
- `scripts/migrate.sh` - 数据库迁移脚本
|
||
- `scripts/test_api.sh` - API测试脚本
|
||
|
||
### 文档文件
|
||
|
||
- `docs/invite_apply_example.html` - 官网申请页面示例
|
||
- `docs/invite_code_application_feature.md` - 功能说明文档（本文件）
|
||
|
||
## 注意事项
|
||
|
||
1. **邮件发送失败不会影响审批流程** - 邮件发送采用异步方式，失败不会导致事务回滚
|
||
2. **重复申请限制** - 同一邮箱如有待处理或已通过的申请，不能重复提交
|
||
3. **默认有效期** - 审批通过时如未指定有效期，默认为7天
|
||
4. **批量操作** - 批量审批时如某个申请处理失败，不会影响其他申请的处理
|
||
|
||
## 后续优化建议
|
||
|
||
1. 增加申请统计报表功能
|
||
2. 支持自定义邮件模板
|
||
3. 增加申请历史记录查询
|
||
4. 支持导出申请数据
|
||
5. 增加申请频率限制（防止恶意申请）
|
||
6. 优化邮件发送队列，支持重试机制 |