# 邀请码申请管理功能 - 部署和测试指南

## 部署状态

### ✅ 已完成的部署步骤

1. **后端服务**
   - 已构建成功：`admin-server`
   - 数据库迁移已完成：`admin_invite_code_applications` 表已创建
   - 服务已启动：监听端口 `8087`
   - 路由已注册：所有API端点正常

2. **配置文件**
   - 邮件配置已添加到 `etc/config.yaml`
   - 配置项：
     - SMTP服务器：smtp.mxhichina.com:465
     - 发件人：goalfymax@goalfyai.com
     - 注册链接前缀：https://goalfy.com/register?code=

3. **数据库表结构**
   ```sql
   admin_invite_code_applications
   - 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
   ```

## 已验证的功能

### ✅ 公开API测试（官网提交）

**1. 成功提交申请**
```bash
curl -X POST http://localhost:8087/api/public/invite-code/apply \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "reason": "想体验AI编程助手"}'
```
返回：
```json
{
  "code": 0,
  "message": "申请已提交，我们将在1-2个工作日内处理您的申请",
  "data": {
    "id": 1,
    "email": "test@example.com",
    "status": "pending",
    ...
  }
}
```

**2. 重复提交拦截**
```bash
curl -X POST http://localhost:8087/api/public/invite-code/apply \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "reason": "第二次申请"}'
```
返回：
```json
{
  "error": "您已经提交过申请，请等待审核"
}
```

## 后台管理功能测试

### 需要认证的API端点

所有管理接口都需要通过SSO认证，访问路径为：`/api/admin/invite-applications/*`

**可用的管理接口：**

1. `GET /api/admin/invite-applications` - 获取申请列表
2. `GET /api/admin/invite-applications/statistics` - 获取统计信息
3. `GET /api/admin/invite-applications/pending-count` - 获取待处理数量
4. `POST /api/admin/invite-applications/approve` - 审批通过
5. `POST /api/admin/invite-applications/reject` - 审批拒绝
6. `POST /api/admin/invite-applications/batch-approve` - 批量审批通过
7. `POST /api/admin/invite-applications/batch-reject` - 批量审批拒绝

### 前端测试步骤

1. **启动前端应用**
   ```bash
   cd /path/to/goalfymax-admin-web
   npm run dev
   ```

2. **登录管理后台**
   - 访问：http://localhost:5173
   - 使用SSO登录

3. **访问邀请码管理页面**
   - 导航到邀请码管理
   - 查看页面顶部的"待处理申请"按钮
   - 按钮上应该显示待处理数量徽章

4. **处理申请**
   - 点击"待处理申请"按钮
   - 查看申请列表
   - 测试以下操作：
     - ✓ 单个申请审批通过
     - ✓ 单个申请拒绝（可填写拒绝理由）
     - ✓ 批量选择申请
     - ✓ 批量审批通过
     - ✓ 批量拒绝

## 邮件发送测试

### 审批通过邮件

**触发条件**：管理员点击"同意"按钮

**邮件内容**：
- 主题：Goalfy 邀请码已发放
- 包含邀请码（自动生成）
- 包含有效期（默认7天）
- 包含注册链接：https://goalfy.com/register?code=XXXXXXXX

### 审批拒绝邮件

**触发条件**：管理员点击"拒绝"按钮并填写原因

**邮件内容**：
- 主题：关于您的 Goalfy 申请
- 包含拒绝理由
- 包含支持邮箱：support@goalfy.com

## 当前测试数据

已创建的测试申请：
1. test@example.com - 状态：pending
2. another@example.com - 状态：pending

## 下一步操作建议

### 1. 前端功能测试
```bash
cd /Users/youziba/goalfyagent/goalfymax-admin-web
npm run dev
```
然后登录后台，访问邀请码管理页面测试完整流程。

### 2. 邮件发送测试
在前端进行审批操作后：
- 检查申请人邮箱是否收到邮件
- 验证邮件内容是否正确
- 验证邀请码链接是否有效

### 3. 官网集成
将 `docs/invite_apply_example.html` 中的表单集成到官网：
- 修改 API_BASE_URL 为实际的后端地址
- 调整样式以匹配官网设计
- 添加必要的验证逻辑

## 注意事项

### ⚠️ 生产环境配置
1. 修改 `etc/config.yaml` 中的 `invite_url_prefix`
2. 确保SMTP服务器能够正常发送邮件
3. 配置CORS允许官网域名访问API

### ⚠️ 安全建议
1. 公开API `/api/public/invite-code/apply` 建议添加：
   - 频率限制（防止恶意申请）
   - 图形验证码
   - IP白名单

2. 邮箱验证：
   - 确保邮箱格式正确
   - 可考虑添加邮箱域名白名单

## 服务管理命令

```bash
# 启动服务
./scripts/start.sh

# 停止服务
./scripts/stop.sh

# 查看日志
tail -f logs/admin-server.log

# 测试API
./scripts/test_api.sh
```

## 故障排查

### 服务无法启动
- 检查端口8087是否被占用：`lsof -i:8087`
- 查看日志文件：`tail -100 logs/admin-server.log`

### 邮件发送失败
- 检查 `etc/config.yaml` 中的邮件配置
- 确认SMTP服务器可访问
- 查看服务日志中的邮件发送错误信息

### 数据库连接失败
- 检查 `etc/config.yaml` 中的数据库连接字符串
- 确认数据库服务可访问
- 检查数据库用户权限