# 自定义挑战 API 接口文档

**版本**: v1.0  
**更新日期**: 2025-01-25  
**基础URL**: `https://your-domain.com/api`

## 目录

- [概述](#概述)
- [认证](#认证)
- [数据模型](#数据模型)
- [API 接口](#api-接口)
  - [创建自定义挑战](#1-创建自定义挑战)
  - [通过分享码加入挑战](#2-通过分享码加入挑战)
  - [获取分享码对应的挑战信息](#3-获取分享码对应的挑战信息)
  - [获取我创建的挑战列表](#4-获取我创建的挑战列表)
  - [更新自定义挑战](#5-更新自定义挑战)
  - [归档自定义挑战](#6-归档自定义挑战)
  - [重新生成分享码](#7-重新生成分享码)
- [错误码说明](#错误码说明)
- [客户端集成示例](#客户端集成示例)

---

## 概述

自定义挑战功能允许用户创建自己的挑战，并通过分享码邀请其他用户参与。该功能完全兼容现有的系统挑战。

### 核心特性

- ✅ 用户可以自由创建挑战
- ✅ 自动生成6位唯一分享码
- ✅ 支持公开和私密两种模式
- ✅ 可设置参与人数限制
- ✅ 完全兼容现有的打卡、排行榜系统

---

## 认证

大部分接口需要用户认证。在请求头中添加 JWT Token：

```http
Authorization: Bearer {your_jwt_token}
```

**公开接口**（无需认证）：

- 获取分享码对应的挑战信息

---

## 数据模型

### ChallengeType（挑战类型）

```typescript
enum ChallengeType {
  WATER = "water", // 喝水
  EXERCISE = "exercise", // 运动
  DIET = "diet", // 饮食
  MOOD = "mood", // 心情
  SLEEP = "sleep", // 睡眠
  WEIGHT = "weight", // 体重
}
```

### ChallengeSource（挑战来源）

```typescript
enum ChallengeSource {
  SYSTEM = "system", // 系统预设挑战
  CUSTOM = "custom", // 用户自定义挑战
}
```

### ChallengeState（挑战状态）

```typescript
enum ChallengeState {
  DRAFT = "draft", // 草稿（预留）
  ACTIVE = "active", // 活跃
  ARCHIVED = "archived", // 已归档
}
```

### CustomChallengeResponse（自定义挑战响应）

```typescript
interface CustomChallengeResponse {
  id: string; // 挑战ID
  title: string; // 挑战标题
  type: ChallengeType; // 挑战类型
  source: ChallengeSource; // 挑战来源
  creatorId: string | null; // 创建者ID
  shareCode: string | null; // 分享码（6位大写字母和数字）
  image: string | null; // 封面图URL
  startAt: number; // 开始时间戳（毫秒）
  endAt: number; // 结束时间戳（毫秒）
  periodLabel: string | null; // 周期标签，如"21天挑战"
  durationLabel: string; // 持续时间标签，如"持续21天"
  requirementLabel: string; // 要求标签，如"每日喝水8杯"
  summary: string | null; // 挑战说明
  targetValue: number; // 每日目标值
  progressUnit: string; // 进度单位，默认"天"
  minimumCheckInDays: number; // 最少打卡天数
  rankingDescription: string | null; // 排行榜描述
  highlightTitle: string; // 高亮标题
  highlightSubtitle: string; // 高亮副标题
  ctaLabel: string; // CTA按钮文字
  isPublic: boolean; // 是否公开
  maxParticipants: number | null; // 最大参与人数（null=无限制）
  challengeState: ChallengeState; // 挑战状态
  participantsCount: number; // 当前参与人数
  progress?: {
    // 用户进度（仅加入后有值）
    completed: number; // 已完成天数
    target: number; // 目标天数
    remaining: number; // 剩余天数
    checkedInToday: boolean; // 今日是否已打卡
  };
  isJoined: boolean; // 当前用户是否已加入
  isCreator: boolean; // 当前用户是否为创建者
  createdAt: Date; // 创建时间
  updatedAt: Date; // 更新时间
}
```

---

## API 接口

### 1. 创建自定义挑战

创建一个新的自定义挑战，系统会自动生成唯一的分享码。

**接口地址**: `POST /challenges/custom`

**是否需要认证**: ✅ 是

**请求头**:

```http
Content-Type: application/json
Authorization: Bearer {token}
```

**请求体**:

```json
{
  "title": "21天喝水挑战",
  "type": "water",
  "image": "https://example.com/image.jpg",
  "startAt": 1704067200000,
  "endAt": 1705881600000,
  "targetValue": 8,
  "minimumCheckInDays": 21,
  "durationLabel": "持续21天",
  "requirementLabel": "每日喝水8杯",
  "summary": "坚持每天喝足8杯水，养成健康好习惯",
  "progressUnit": "天",
  "periodLabel": "21天挑战",
  "rankingDescription": "连续打卡榜",
  "highlightTitle": "坚持21天",
  "highlightSubtitle": "养成喝水好习惯",
  "ctaLabel": "立即加入",
  "isPublic": true,
  "maxParticipants": 100
}
```

**参数说明**:

| 参数               | 类型          | 必填 | 说明                                  |
| ------------------ | ------------- | ---- | ------------------------------------- |
| title              | string        | ✅   | 挑战标题，最长100字符                 |
| type               | ChallengeType | ✅   | 挑战类型                              |
| startAt            | number        | ✅   | 开始时间戳（毫秒），必须是未来时间    |
| endAt              | number        | ✅   | 结束时间戳（毫秒），必须晚于开始时间  |
| targetValue        | number        | ✅   | 每日目标值，1-1000                    |
| minimumCheckInDays | number        | ✅   | 最少打卡天数，1-365                   |
| durationLabel      | string        | ✅   | 持续时间标签，最长128字符             |
| requirementLabel   | string        | ✅   | 要求标签，最长255字符                 |
| image              | string        | ❌   | 封面图URL，最长512字符                |
| summary            | string        | ❌   | 挑战说明                              |
| progressUnit       | string        | ❌   | 进度单位，默认"天"，最长64字符        |
| periodLabel        | string        | ❌   | 周期标签，最长128字符                 |
| rankingDescription | string        | ❌   | 排行榜描述，最长255字符               |
| highlightTitle     | string        | ❌   | 高亮标题，最长255字符                 |
| highlightSubtitle  | string        | ❌   | 高亮副标题，最长255字符               |
| ctaLabel           | string        | ❌   | CTA按钮文字，最长128字符              |
| isPublic           | boolean       | ❌   | 是否公开，默认true                    |
| maxParticipants    | number        | ❌   | 最大参与人数，2-10000，null表示无限制 |

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "创建挑战成功",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "shareCode": "A3K9P2",
    "title": "21天喝水挑战",
    "type": "water",
    "source": "custom",
    "creatorId": "user_123",
    "isPublic": true,
    "maxParticipants": 100,
    "participantsCount": 0,
    "isJoined": false,
    "isCreator": true,
    ...
  }
}
```

**错误响应**:

```json
{
  "code": 1,
  "message": "每天最多创建 5 个挑战，请明天再试",
  "data": null
}
```

---

### 2. 通过分享码加入挑战

使用分享码加入他人创建的挑战。

**接口地址**: `POST /challenges/join-by-code`

**是否需要认证**: ✅ 是

**请求头**:

```http
Content-Type: application/json
Authorization: Bearer {token}
```

**请求体**:

```json
{
  "shareCode": "A3K9P2"
}
```

**参数说明**:

| 参数      | 类型   | 必填 | 说明                                 |
| --------- | ------ | ---- | ------------------------------------ |
| shareCode | string | ✅   | 6-12位分享码，只能包含大写字母和数字 |

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "加入挑战成功",
  "data": {
    "completed": 0,
    "target": 21,
    "remaining": 21,
    "checkedInToday": false
  }
}
```

**错误响应**:

```json
{
  "code": 1,
  "message": "分享码无效或挑战不存在",
  "data": null
}
```

```json
{
  "code": 1,
  "message": "挑战人数已满",
  "data": null
}
```

---

### 3. 获取分享码对应的挑战信息

通过分享码查看挑战详情（公开接口，无需登录）。

**接口地址**: `GET /challenges/share/{shareCode}`

**是否需要认证**: ❌ 否（但提供token可获取更多信息）

**路径参数**:

- `shareCode`: 分享码，如 `A3K9P2`

**请求示例**:

```http
GET /challenges/share/A3K9P2
```

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "获取挑战信息成功",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "21天喝水挑战",
    "image": "https://example.com/image.jpg",
    "periodLabel": "21天挑战",
    "durationLabel": "持续21天",
    "requirementLabel": "每日喝水8杯",
    "summary": "坚持每天喝足8杯水",
    "rankingDescription": "连续打卡榜",
    "highlightTitle": "坚持21天",
    "highlightSubtitle": "养成喝水好习惯",
    "ctaLabel": "立即加入",
    "minimumCheckInDays": 21,
    "participantsCount": 15,
    "progress": null,
    "rankings": [...],
    "userRank": null,
    "unit": "天",
    "type": "water"
  }
}
```

**错误响应**:

```json
{
  "code": 1,
  "message": "分享码无效或挑战不存在",
  "data": null
}
```

---

### 4. 获取我创建的挑战列表

获取当前用户创建的所有挑战。

**接口地址**: `GET /challenges/my/created`

**是否需要认证**: ✅ 是

**请求头**:

```http
Authorization: Bearer {token}
```

**查询参数**:

| 参数     | 类型           | 必填 | 说明                      |
| -------- | -------------- | ---- | ------------------------- |
| page     | number         | ❌   | 页码，默认1               |
| pageSize | number         | ❌   | 每页数量，默认20，最大100 |
| state    | ChallengeState | ❌   | 挑战状态筛选              |

**请求示例**:

```http
GET /challenges/my/created?page=1&pageSize=20&state=active
```

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "获取我创建的挑战列表成功",
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "shareCode": "A3K9P2",
        "title": "21天喝水挑战",
        "type": "water",
        "source": "custom",
        "participantsCount": 15,
        "challengeState": "active",
        "isCreator": true,
        ...
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}
```

---

### 5. 更新自定义挑战

更新自定义挑战信息（仅创建者可操作）。

**接口地址**: `PUT /challenges/custom/{id}`

**是否需要认证**: ✅ 是（仅创建者）

**路径参数**:

- `id`: 挑战ID

**请求头**:

```http
Content-Type: application/json
Authorization: Bearer {token}
```

**请求体**:

```json
{
  "title": "新的挑战标题",
  "image": "https://example.com/new-image.jpg",
  "summary": "更新的挑战说明",
  "isPublic": false,
  "maxParticipants": 50,
  "highlightTitle": "新的高亮标题",
  "highlightSubtitle": "新的高亮副标题",
  "ctaLabel": "快来加入"
}
```

**参数说明**:

| 参数              | 类型    | 必填 | 说明         |
| ----------------- | ------- | ---- | ------------ |
| title             | string  | ❌   | 挑战标题     |
| image             | string  | ❌   | 封面图URL    |
| summary           | string  | ❌   | 挑战说明     |
| isPublic          | boolean | ❌   | 是否公开     |
| maxParticipants   | number  | ❌   | 最大参与人数 |
| highlightTitle    | string  | ❌   | 高亮标题     |
| highlightSubtitle | string  | ❌   | 高亮副标题   |
| ctaLabel          | string  | ❌   | CTA按钮文字  |

**⚠️ 重要**: 挑战开始后，只能编辑以下字段：

- summary（挑战说明）
- isPublic（公开性）
- highlightTitle（高亮标题）
- highlightSubtitle（高亮副标题）
- ctaLabel（CTA文字）

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "更新挑战成功",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "新的挑战标题",
    ...
  }
}
```

**错误响应**:

```json
{
  "code": 1,
  "message": "只有创建者才能编辑挑战",
  "data": null
}
```

```json
{
  "code": 1,
  "message": "挑战已开始，只能编辑概要、公开性和展示文案",
  "data": null
}
```

---

### 6. 归档自定义挑战

归档（软删除）自定义挑战（仅创建者可操作）。

**接口地址**: `DELETE /challenges/custom/{id}`

**是否需要认证**: ✅ 是（仅创建者）

**路径参数**:

- `id`: 挑战ID

**请求头**:

```http
Authorization: Bearer {token}
```

**请求示例**:

```http
DELETE /challenges/custom/550e8400-e29b-41d4-a716-446655440000
```

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "归档挑战成功",
  "data": true
}
```

**错误响应**:

```json
{
  "code": 1,
  "message": "只有创建者才能归档挑战",
  "data": null
}
```

---

### 7. 重新生成分享码

为挑战重新生成一个新的分享码（仅创建者可操作）。

**接口地址**: `POST /challenges/custom/{id}/regenerate-code`

**是否需要认证**: ✅ 是（仅创建者）

**路径参数**:

- `id`: 挑战ID

**请求头**:

```http
Authorization: Bearer {token}
```

**请求示例**:

```http
POST /challenges/custom/550e8400-e29b-41d4-a716-446655440000/regenerate-code
```

**成功响应**: `200 OK`

```json
{
  "code": 0,
  "message": "重新生成分享码成功",
  "data": {
    "shareCode": "B7M4N9"
  }
}
```

**使用场景**:

- 分享码泄露，需要更换
- 想要限制旧分享码的传播
- 重新组织挑战参与者

---

## 错误码说明

### 通用错误码

| code | message | 说明                            |
| ---- | ------- | ------------------------------- |
| 0    | Success | 请求成功                        |
| 1    | Error   | 业务错误（message中有具体说明） |

### 常见业务错误

| 错误信息                                     | 说明                   | 解决方案             |
| -------------------------------------------- | ---------------------- | -------------------- |
| "每天最多创建 5 个挑战，请明天再试"          | 创建频率限制           | 提示用户明天再试     |
| "分享码无效或挑战不存在"                     | 分享码错误或挑战已归档 | 提示用户检查分享码   |
| "挑战人数已满"                               | 达到最大参与人数       | 提示用户挑战已满     |
| "挑战已过期，无法加入"                       | 挑战已结束             | 提示挑战已结束       |
| "只有创建者才能编辑挑战"                     | 权限不足               | 提示只有创建者可操作 |
| "挑战已开始，只能编辑概要、公开性和展示文案" | 限制编辑               | 提示可编辑字段       |
| "已加入该挑战"                               | 重复加入               | 跳转到挑战详情页     |

### HTTP 状态码

| 状态码 | 说明                 |
| ------ | -------------------- |
| 200    | 请求成功             |
| 400    | 请求参数错误         |
| 401    | 未授权（需要登录）   |
| 403    | 禁止访问（权限不足） |
| 404    | 资源不存在           |
| 500    | 服务器内部错误       |

---

## 客户端集成示例

### Swift (iOS)

#### 1. 创建挑战

```swift
struct CreateChallengeRequest: Codable {
    let title: String
    let type: String
    let startAt: Int64
    let endAt: Int64
    let targetValue: Int
    let minimumCheckInDays: Int
    let durationLabel: String
    let requirementLabel: String
    let isPublic: Bool
}

func createChallenge(request: CreateChallengeRequest) async throws -> CustomChallengeResponse {
    guard let url = URL(string: "\(baseURL)/challenges/custom") else {
        throw NetworkError.invalidURL
    }

    var urlRequest = URLRequest(url: url)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    urlRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
    urlRequest.httpBody = try JSONEncoder().encode(request)

    let (data, response) = try await URLSession.shared.data(for: urlRequest)

    guard let httpResponse = response as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw NetworkError.requestFailed
    }

    let result = try JSONDecoder().decode(APIResponse<CustomChallengeResponse>.self, from: data)
    return result.data
}
```

#### 2. 通过分享码加入

```swift
func joinByShareCode(_ shareCode: String) async throws {
    guard let url = URL(string: "\(baseURL)/challenges/join-by-code") else {
        throw NetworkError.invalidURL
    }

    var urlRequest = URLRequest(url: url)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    urlRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")

    let body = ["shareCode": shareCode]
    urlRequest.httpBody = try JSONEncoder().encode(body)

    let (data, response) = try await URLSession.shared.data(for: urlRequest)

    guard let httpResponse = response as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw NetworkError.requestFailed
    }

    let result = try JSONDecoder().decode(APIResponse<ChallengeProgress>.self, from: data)
    // Handle success
}
```

#### 3. 分享功能

```swift
func shareChallengeCode(_ shareCode: String, title: String) {
    let message = "邀请你加入挑战：\(title)\n分享码：\(shareCode)"

    let activityVC = UIActivityViewController(
        activityItems: [message],
        applicationActivities: nil
    )

    present(activityVC, animated: true)
}
```

### Kotlin (Android)

#### 1. 创建挑战

```kotlin
data class CreateChallengeRequest(
    val title: String,
    val type: String,
    val startAt: Long,
    val endAt: Long,
    val targetValue: Int,
    val minimumCheckInDays: Int,
    val durationLabel: String,
    val requirementLabel: String,
    val isPublic: Boolean = true
)

suspend fun createChallenge(request: CreateChallengeRequest): CustomChallengeResponse {
    return withContext(Dispatchers.IO) {
        val response = apiService.createChallenge(request)
        if (response.code == 0) {
            response.data
        } else {
            throw Exception(response.message)
        }
    }
}
```

#### 2. 通过分享码加入

```kotlin
suspend fun joinByShareCode(shareCode: String): ChallengeProgress {
    return withContext(Dispatchers.IO) {
        val request = JoinByCodeRequest(shareCode)
        val response = apiService.joinByShareCode(request)
        if (response.code == 0) {
            response.data
        } else {
            throw Exception(response.message)
        }
    }
}
```

#### 3. 分享功能

```kotlin
fun shareChallenge(context: Context, shareCode: String, title: String) {
    val message = "邀请你加入挑战：$title\n分享码：$shareCode"

    val shareIntent = Intent().apply {
        action = Intent.ACTION_SEND
        putExtra(Intent.EXTRA_TEXT, message)
        type = "text/plain"
    }

    context.startActivity(Intent.createChooser(shareIntent, "分享挑战"))
}
```

### TypeScript/JavaScript

#### 1. API 客户端封装

```typescript
class ChallengesAPI {
  private baseURL: string;
  private token: string;

  constructor(baseURL: string, token: string) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async createChallenge(
    data: CreateChallengeRequest
  ): Promise<CustomChallengeResponse> {
    const response = await fetch(`${this.baseURL}/challenges/custom`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.token}`,
      },
      body: JSON.stringify(data),
    });

    const result = await response.json();
    if (result.code !== 0) {
      throw new Error(result.message);
    }
    return result.data;
  }

  async joinByShareCode(shareCode: string): Promise<ChallengeProgress> {
    const response = await fetch(`${this.baseURL}/challenges/join-by-code`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.token}`,
      },
      body: JSON.stringify({ shareCode }),
    });

    const result = await response.json();
    if (result.code !== 0) {
      throw new Error(result.message);
    }
    return result.data;
  }

  async getChallengeByShareCode(shareCode: string): Promise<ChallengeDetail> {
    const response = await fetch(
      `${this.baseURL}/challenges/share/${shareCode}`
    );
    const result = await response.json();
    if (result.code !== 0) {
      throw new Error(result.message);
    }
    return result.data;
  }
}
```

#### 2. 使用示例

```typescript
const api = new ChallengesAPI("https://api.example.com/api", userToken);

// 创建挑战
try {
  const challenge = await api.createChallenge({
    title: "21天喝水挑战",
    type: "water",
    startAt: Date.now(),
    endAt: Date.now() + 21 * 24 * 60 * 60 * 1000,
    targetValue: 8,
    minimumCheckInDays: 21,
    durationLabel: "持续21天",
    requirementLabel: "每日喝水8杯",
    isPublic: true,
  });

  console.log("分享码:", challenge.shareCode);
} catch (error) {
  console.error("创建失败:", error.message);
}
```

---

## 注意事项

### 1. 时间戳格式

- 所有时间戳均为**毫秒级**（JavaScript: `Date.now()`）
- 示例: `1704067200000`（2024-01-01 00:00:00）

### 2. 分享码规则

- 长度: 6-12位字符
- 字符集: 大写字母和数字（A-Z, 2-9）
- 排除易混淆字符: 0/O, 1/I/l
- 示例: `A3K9P2`, `B7M4N9`

### 3. 创建频率限制

- 每个用户每天最多创建 **5 个挑战**
- 超出限制会返回错误，建议提示用户

### 4. 人数限制

- `maxParticipants` 为 `null` 表示无限制
- 最小值: 2 人
- 最大值: 10000 人

### 5. 编辑限制

-