ApiServer-Web-admin_dashboard_pc/拼团API对接说明.md

拼团 API 对接说明

API 文件位置

• 管理端接口：src/api/admin/activity.js
• 用户端接口：src/api/groupBuy.js

管理端 API 接口（已更新）

1. 获取拼团列表 ✅ 已更新

import { getGroupBuyList } from '@/api/admin/activity.js'

// 调用示例
const resp = await getGroupBuyList()

// 接口路径：GET /api/v1/users/activity/group_buy/list

// 实际返回数据结构：
{
  code: 200,
  message: "Success",
  data: {
    group_buy_list: ["17670726110-5", "17670733070-5"],      // 所有队伍ID
    lack_group_buy_list: ["17670726110-5"],                   // 未满员队伍ID
    success_group_buy_list: []                                // 已满员队伍ID
  }
}

2. 获取拼团队伍详情 ✅ 新增

import { getGroupBuyDetail } from '@/api/admin/activity.js'

// 调用示例
const resp = await getGroupBuyDetail('17670733070-5')

// 接口路径：GET /api/v1/users/activity/group_buy/detail/:id

// 实际返回数据结构：
{
  code: 200,
  message: "Success",
  data: {
    group_buy_id: "17670733070-5",
    name: "发士大夫",
    maxPerson: 5,
    createTime: "2025-12-30T13:41:47.216888773+08:00",
    users: [{
      user_id: 0,
      user_name: "",
      team_leader: true,
      cover: "https://...",
      idc_phone: "",
      idc_uid: ""
    }]
  }
}

3. 创建随机伪人队伍 ✅ 已验证

import { addRandomGroup } from '@/api/admin/activity.js'

// 调用示例
const resp = await addRandomGroup('队伍名称', 0) // 0=5人队, 1=10人队

// 实际返回数据结构：
{
  code: 200,
  message: "Success",
  data: {
    group_buy_id: "17670733070-5",
    name: "发士大夫",
    maxPerson: 5,
    createTime: "2025-12-30T13:41:47.216888773+08:00",
    users: [{
      user_id: 0,
      user_name: "",
      team_leader: true,
      cover: "https://...",
      idc_phone: "",
      idc_uid: ""
    }]
  }
}

4. 为队伍添加随机伪人

import { addRandomUser } from '@/api/admin/activity.js'

const resp = await addRandomUser(groupBuyId)

5. 为指定队伍下发订单

import { setOrder } from '@/api/admin/activity.js'

const resp = await setOrder(groupBuyId)

6. 导出成功队伍信息

import { exportIdcInfo } from '@/api/admin/activity.js'

const resp = await exportIdcInfo()
// 返回 Excel 文件流

用户端 API 接口

1. 创建拼团

import { createGroupBuy } from '@/api/groupBuy.js'

// 调用示例
const data = {
  name: '地擦拭大',
  maxPerson: 5,
  cover: 'https://example.com/cover.jpg'
}

const resp = await createGroupBuy(data)

// 响应数据结构
{
  code: 200,
  message: "Success",
  data: {
    group_buy_id: "17670726110-5",
    name: "地擦拭大",
    maxPerson: 5,
    createTime: "2025-12-30T13:30:11.918394294+08:00",
    users: [{
      user_id: 0,
      user_name: "",
      team_leader: true,
      cover: "https://...",
      idc_phone: "",
      idc_uid: ""
    }]
  }
}

2. 检查拼团

import { checkGroupBuy } from '@/api/groupBuy.js'

// 调用示例
const groupBuyId = "17670726110-5"
const resp = await checkGroupBuy(groupBuyId)

// 响应数据结构
{
  code: 200,
  message: "Success",
  data: "ok"
}

3. 获取拼团详情

import { getGroupBuyDetail } from '@/api/groupBuy.js'

const resp = await getGroupBuyDetail(groupBuyId)

4. 获取拼团列表（用户端）

import { getGroupBuyList } from '@/api/groupBuy.js'

const resp = await getGroupBuyList({ page: 1, pageSize: 20 })

// 接口路径：GET /api/v1/users/activity/group_buy/list

5. 加入拼团

import { joinGroupBuy } from '@/api/groupBuy.js'

const resp = await joinGroupBuy(groupBuyId, {
  user_id: 123,
  user_name: "张三"
})

6. 删除拼团

import { deleteGroupBuy } from '@/api/groupBuy.js'

const resp = await deleteGroupBuy(groupBuyId)

完整示例页面

• 管理端页面：src/views/activity/GroupBuyActivity.vue ✅ 已存在
• 用户端示例：src/views/marketing/GroupBuyManage.vue

管理端页面包含：

• ✅ 拼团列表展示（使用正确的接口路径）
• ✅ 创建随机伪人队伍
• ✅ 添加随机伪人
• ✅ 下发订单功能
• ✅ 导出成功队伍
• ✅ 查看队伍成员

接口路径总结

管理端接口

• GET /api/v1/users/activity/group_buy/list - 获取拼团列表 ✅ 返回队伍ID数组
• GET /api/v1/users/activity/group_buy/detail/:id - 获取队伍详情 ✅ 新增
• POST /api/v1/admin/activity/group_buy/add_random_group - 创建随机队伍 ✅ 已验证
• POST /api/v1/admin/activity/group_buy/add_random_user - 添加随机伪人
• POST /api/v1/admin/activity/group_buy/set_order - 下发订单
• GET /api/v1/admin/activity/group_buy/export_idc_info - 导出信息

用户端接口（根据需要调整）

• POST /api/v1/group-buy/create - 创建拼团
• GET /api/v1/group-buy/check/:id - 检查拼团
• GET /api/v1/group-buy/:id - 获取拼团详情
• GET /api/v1/users/activity/group_buy/list - 获取拼团列表 ✅
• POST /api/v1/group-buy/:id/join - 加入拼团
• DELETE /api/v1/group-buy/:id - 删除拼团

使用方法

在管理端页面使用

<script setup>
import { getGroupBuyList, addRandomUser } from '@/api/admin/activity.js'
import { ElMessage } from 'element-plus'

// 获取列表
const fetchList = async () => {
  try {
    const resp = await getGroupBuyList()
    if (resp && resp.code === 200) {
      console.log('拼团列表:', resp.data)
    }
  } catch (error) {
    console.error('获取失败:', error)
    ElMessage.error('获取失败')
  }
}

// 添加伪人
const addUser = async (groupBuyId) => {
  try {
    const resp = await addRandomUser(groupBuyId)
    if (resp && resp.code === 200) {
      ElMessage.success('添加成功')
    }
  } catch (error) {
    console.error('添加失败:', error)
    ElMessage.error('添加失败')
  }
}
</script>

注意事项

1. 接口路径已更新：获取拼团列表接口已更新为 /api/v1/users/activity/group_buy/list
2. 错误处理：所有 API 调用都应该包含 try-catch 错误处理
3. 响应检查：始终检查 resp.code === 200 来判断请求是否成功
4. 空值处理：使用可选链 ?. 和空值合并 || 来处理可能为空的数据
5. 用户提示：使用 ElMessage 给用户友好的提示信息