goalfylearning-admin/docs/invite_code_application_feature.md

邀请码申请管理功能

功能概述

本功能为 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）

# 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. 数据库迁移

执行数据库迁移脚本：

cd /path/to/goalfymax-admin
./scripts/migrate.sh

2. 后端部署

# 构建后端
go build -o admin-server cmd/server/main.go

# 运行服务
./admin-server

3. 前端部署

cd /path/to/goalfymax-admin-web
npm install
npm run build

测试方法

1. API 测试

使用提供的测试脚本：

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