goalfylearning-admin/scripts/README_invite_api.md

邀请码申请 API - Python 实现

这是 /api/invite-code/apply 接口的 Python 单文件实现，与 Go 项目共用同一个 MySQL 数据库。

快速开始

1. 直接启动（默认使用 AWS RDS）

# 使用启动脚本（推荐）
./scripts/run_invite_api.sh

# 或者直接运行
uv run scripts/invite_code_api.py

💡 提示: 脚本已预配置 AWS RDS 数据库连接，无需额外配置即可运行。

2. 使用本地数据库（可选）

如需连接本地 MySQL，创建 .env 文件：

cp scripts/.env.example scripts/.env
vim scripts/.env  # 修改为本地数据库配置

服务启动后：

• API 地址: http://localhost:8000
• 交互式文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

API 使用示例

提交申请

curl -X POST http://localhost:8000/api/invite-code/apply \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "reason": "想要体验产品功能"
  }'

成功响应:

{
  "code": 0,
  "message": "申请已提交，我们将在1-2个工作日内处理您的申请",
  "data": {
    "id": 1,
    "email": "user@example.com",
    "reason": "想要体验产品功能",
    "status": "pending",
    "created_at": "2025-11-03T10:00:00Z",
    "updated_at": "2025-11-03T10:00:00Z"
  }
}

错误响应（重复申请）:

{
  "detail": "您已经提交过申请，请等待审核"
}

业务逻辑

1. 参数验证: Email 必填且格式正确
2. 重复检查:
   • 如果已有 pending 状态申请 → 提示等待审核
   • 如果已有 approved 状态申请 → 提示检查邮箱
   • 只有 rejected 或无申请时才能提交
3. 数据存储: 保存到 admin_invite_code_applications 表

技术栈

• FastAPI: 现代化 Python Web 框架
• SQLAlchemy: ORM 框架
• PyMySQL: MySQL 数据库驱动
• Pydantic: 数据验证

与 Go 项目的兼容性

• ✅ 使用相同的数据库表 admin_invite_code_applications
• ✅ 完全相同的业务逻辑
• ✅ 相同的请求/响应格式
• ✅ 相同的错误处理

开发说明

文件位置: scripts/invite_code_api.py（单文件，约 120 行代码）

支持的环境变量:

• DB_USER: 数据库用户名（默认: root）
• DB_PASSWORD: 数据库密码（默认: password）
• DB_HOST: 数据库地址（默认: localhost）
• DB_PORT: 数据库端口（默认: 3306）
• DB_NAME: 数据库名称（默认: goalfymax_prod）