Skip to Content
🚀 Drubase One v1.1 - 基于 Drupal 11 的多租户后端即服务平台
Docs前端应用Groups - 智能团队运动平台核心功能

核心功能

Groups 应用提供了完整的团队运动管理功能,从用户注册到活动组织,再到智能分组。

🔐 用户认证系统

注册和登录

功能特性:

  • 邮箱 + 密码注册
  • JWT Token 认证
  • 自动 Token 刷新
  • 记住登录状态

API 端点:

# 用户注册
POST /api/user/register
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "password123",
  "name": "张三"
}
 
# 用户登录
POST /api/user/login
Content-Type: application/json
 
{
  "username": "user@example.com",
  "password": "password123"
}
 
# Token 刷新
POST /api/user/token/refresh
Authorization: Bearer OLD_TOKEN

响应示例:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "uid": 123,
      "name": "张三",
      "email": "user@example.com",
      "avatar": "http://YOUR_HOST/files/avatars/123.jpg"
    }
  }
}

个人资料管理

  • 修改昵称
  • 上传头像
  • 更新密码
  • 设置偏好

🏟️ 活动管理

创建活动

功能特性:

  • 活动名称和描述
  • 活动时间设置
  • 地点选择
  • 活动类型 (足球/篮球/羽毛球等)
  • 人数限制

创建活动 API:

POST /api/baas/activities
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "name": "周末足球赛",
  "description": "欢迎所有水平的球友参加!",
  "activity_type": "football",
  "location": "XX体育场",
  "start_time": "2025-01-25 14:00:00",
  "max_participants": 20,
  "status": "open"
}

活动列表

筛选功能:

  • 按状态筛选 (进行中/已结束/已取消)
  • 按时间范围筛选
  • 按活动类型筛选
  • 搜索活动名称

获取活动列表:

GET /api/baas/activities?status=open&type=football&limit=10
Authorization: Bearer YOUR_TOKEN

响应示例:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "周末足球赛",
      "description": "欢迎所有水平的球友参加!",
      "activity_type": "football",
      "location": "XX体育场",
      "start_time": "2025-01-25 14:00:00",
      "max_participants": 20,
      "current_participants": 15,
      "status": "open",
      "created_by": {
        "uid": 123,
        "name": "张三",
        "avatar": "http://YOUR_HOST/files/avatars/123.jpg"
      }
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10
  }
}

参加活动

POST /api/baas/user_activities
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "activity_id": 1,
  "user_id": 123,
  "status": "confirmed"
}

🧩 智能分组功能

分组算法

Groups 的核心功能之一是智能分组算法,能够自动将参与者分配到不同队伍。

算法特点:

  • 动态平衡: 确保各队人数均衡
  • 概率分配: 使用加权随机算法
  • 可配置性: 支持自定义占用率因子
  • 实时更新: 分组结果即时推送

分组流程:

1. 用户发起分组请求
   ↓
2. 获取活动的所有队伍和参与者
   ↓
3. 计算每个队伍的概率权重
   概率 = (1 - 占用率^factor) × (可用座位/总座位)^(1/factor)
   ↓
4. 轮盘赌算法分配用户到队伍
   ↓
5. 更新数据库并通过 WebSocket 推送
   ↓
6. 前端实时显示分组结果

触发分组 API:

POST /api/groups/allocate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "activity_id": 1,
  "occupancy_factor": 2.0
}

分组结果响应:

{
  "success": true,
  "data": {
    "activity_id": 1,
    "allocations": [
      {
        "team_id": 1,
        "team_name": "红队",
        "members": [
          { "uid": 123, "name": "张三" },
          { "uid": 124, "name": "李四" },
          { "uid": 125, "name": "王五" }
        ]
      },
      {
        "team_id": 2,
        "team_name": "蓝队",
        "members": [
          { "uid": 126, "name": "赵六" },
          { "uid": 127, "name": "孙七" },
          { "uid": 128, "name": "周八" }
        ]
      }
    ],
    "timestamp": "2025-01-22T10:30:00Z"
  }
}

👥 队伍管理

创建队伍

活动创建后,可以添加多个队伍:

POST /api/baas/teams
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "activity_id": 1,
  "name": "红队",
  "max_members": 5,
  "logo": 123  // 文件 ID
}

队伍统计

  • 当前人数
  • 最大人数
  • 占用率
  • 可用座位数

📍 位置管理

每个队伍中的成员可以占据具体位置 (例如球场位置):

POST /api/baas/positions
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "team_id": 1,
  "user_id": 123,
  "position_name": "前锋",
  "x": 100,
  "y": 200
}

位置数据结构:

  • position_name: 位置名称 (前锋/后卫/守门员等)
  • x, y: 场地坐标
  • status: 位置状态 (占用/空闲)

🖼️ 活动海报生成

自动生成海报

Groups 支持自动生成活动分享海报,方便用户分享到社交媒体。

生成海报 API:

POST /api/poster/generate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "activity_id": 1,
  "template": "default"
}

海报内容包括:

  • 活动名称和描述
  • 时间和地点
  • 参与人数
  • 队伍分组结果
  • 二维码 (可选)

返回海报 URL:

{
  "success": true,
  "data": {
    "poster_url": "http://YOUR_HOST/files/posters/activity_1.jpg",
    "width": 1080,
    "height": 1920
  }
}

🔄 实时同步

WebSocket 实时推送

Groups 使用 WebSocket 实现数据的实时同步:

连接 WebSocket:

const ws = new WebSocket('ws://YOUR_HOST:3001');
 
ws.onopen = () => {
  // 订阅活动频道
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'activity_1'
  }));
};
 
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
 
  if (message.type === 'entity_change') {
    // 处理实体变更
    updateLocalState(message.data);
  }
};

实时推送的事件:

  • 新用户加入活动
  • 用户退出活动
  • 分组结果更新
  • 队伍信息变更
  • 活动状态变化

📁 文件上传

头像上传

POST /api/files/upload
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data
 
file: (binary data)
project_id: tenant_7375b0cd_project_6888d012be80c

支持的文件类型:

  • 图片: jpg, png, gif, webp
  • 最大文件大小: 10 MB
  • 自动生成缩略图

更新头像

PUT /api/baas/users/123
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
 
{
  "avatar": 456  // 上传后返回的文件 ID
}

🔔 通知系统 (计划中)

消息类型

  • 活动通知: 新活动创建、活动取消
  • 参与通知: 用户加入/退出活动
  • 分组通知: 分组完成通知
  • 提醒通知: 活动开始前提醒

推送渠道

  • 站内消息
  • 邮件通知 (可选)
  • 微信模板消息 (计划中)
  • App 推送 (计划中)

📊 数据统计 (计划中)

用户统计

  • 参与活动次数
  • 胜率统计
  • 活跃度分析

活动统计

  • 活动参与率
  • 热门时间段
  • 热门地点

📖 相关文档

Last updated on
技术架构部署指南