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

# 拼团 API 对接说明

## API 文件位置
- 管理端接口：`src/api/admin/activity.js`
- 用户端接口：`src/api/groupBuy.js`

## 管理端 API 接口（已更新）

### 1. 获取拼团列表 ✅ 已更新
```javascript
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. 获取拼团队伍详情 ✅ 新增
```javascript
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. 创建随机伪人队伍 ✅ 已验证
```javascript
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. 为队伍添加随机伪人
```javascript
import { addRandomUser } from '@/api/admin/activity.js'

const resp = await addRandomUser(groupBuyId)
```

### 5. 为指定队伍下发订单
```javascript
import { setOrder } from '@/api/admin/activity.js'

const resp = await setOrder(groupBuyId)
```

### 6. 导出成功队伍信息
```javascript
import { exportIdcInfo } from '@/api/admin/activity.js'

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

## 用户端 API 接口

### 1. 创建拼团
```javascript
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. 检查拼团
```javascript
import { checkGroupBuy } from '@/api/groupBuy.js'

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

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

### 3. 获取拼团详情
```javascript
import { getGroupBuyDetail } from '@/api/groupBuy.js'

const resp = await getGroupBuyDetail(groupBuyId)
```

### 4. 获取拼团列表（用户端）
```javascript
import { getGroupBuyList } from '@/api/groupBuy.js'

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

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

### 5. 加入拼团
```javascript
import { joinGroupBuy } from '@/api/groupBuy.js'

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

### 6. 删除拼团
```javascript
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` - 删除拼团

## 使用方法

### 在管理端页面使用
```vue
<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` 给用户友好的提示信息