# 邀请码申请管理功能

## 功能概述

本功能为 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. 优化邮件发送队列，支持重试机制