yl-frontend/api-docs/activity-api.txt

老年活动模块接口文档
=================

基础信息
-------
- 基础路径: /api/v1/activities
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

Activity 活动对象:
{
  id: number,          // 活动ID
  title: string,       // 活动标题
  description: string, // 活动描述
  time: string,        // 活动时间
  location: string,    // 活动地点
  category: string,    // 活动分类
  capacity: number,    // 活动容量
  participants: number,// 参与人数
  status: string,      // 活动状态(upcoming/ongoing/ended)
  organizer: {         // 组织者信息
    id: number,
    name: string,
    avatar: string,
    phone: string
  },
  cover: string,       // 封面图片
  tags: string[],      // 活动标签
  price: number,       // 活动费用
  requirements?: string[] // 参与要求
}

API 接口
-------

1. 获取活动列表
GET /api/v1/activities

请求参数：
| 参数名    | 类型   | 必填 | 说明 |
| category | string | 否   | 活动分类 |
| status   | string | 否   | 活动状态 |
| page     | number | 否   | 页码，默认1 |
| size     | number | 否   | 每页数量，默认10 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "records": [
      {
        "id": 1,
        "title": "太极拳晨练班",
        "description": "由专业老师指导的太极拳晨练活动",
        "time": "2024-03-21 07:30:00",
        "location": "社区活动中心",
        "category": "sports",
        "capacity": 30,
        "participants": 18,
        "status": "upcoming",
        "organizer": {
          "id": 1,
          "name": "王教练",
          "avatar": "https://example.com/avatar1.jpg",
          "phone": "13800138000"
        },
        "cover": "https://example.com/taichi.jpg",
        "tags": ["运动", "太极拳", "健康"],
        "price": 0
      }
    ]
  }
}

2. 获取活动详情
GET /api/v1/activities/{id}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    // 活动详细信息
  }
}

3. 活动报名
POST /api/v1/activities/{id}/register

请求参数：
{
  "notes": "需要准备运动服装" // 可选备注
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "activityId": 1,
    "userId": 10001,
    "status": "confirmed",
    "registrationTime": "2024-03-19 10:00:00",
    "notes": "需要准备运动服装"
  }
}

4. 取消报名
POST /api/v1/activities/registrations/{id}/cancel

响应示例：
{
  "code": 200,
  "message": "success"
}

5. 获取活动评论
GET /api/v1/activities/{id}/comments

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "activityId": 1,
      "userId": 10001,
      "userName": "张三",
      "userAvatar": "https://example.com/user1.jpg",
      "content": "活动很有意思",
      "createTime": "2024-03-19 15:00:00",
      "likes": 5,
      "images": ["https://example.com/photo1.jpg"]
    }
  ]
}

6. 发表评论
POST /api/v1/activities/{id}/comments

请求参数：
{
  "content": "活动很有意思",
  "images": ["base64图片数据"]
}

7. 获取推荐活动
GET /api/v1/activities/recommended

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    // 推荐活动列表
  ]
}

8. 获取用户参与的活动
GET /api/v1/activities/user/{userId}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    // 用户参与的活动列表
  ]
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 资源不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 活动报名需要检查：
   - 活动是否已满
   - 用户是否已报名
   - 活动是否已开始
   - 用户是否满足参与要求

2. 图片上传要求：
   - 支持格式：jpg、png、gif
   - 单张大小限制：5MB
   - 最多上传9张

3. 活动状态自动更新：
   - 到达开始时间自动变更为进行中
   - 结束时间后自动变更为已结束

4. 缓存策略：
   - 活动列表缓存：5分钟
   - 活动详情缓存：10分钟
   - 评论列表缓存：1分钟