{
  "name": "Drama Player Serverless Edge API",
  "status": "online",
  "version": "2.0.0",
  "description": "High-performance Serverless Edge API for Short Drama Streaming App backed by Cloudflare D1",
  "vip_policy": {
    "rule": "Non-VIP or guest users can only watch the first 5 episodes of any drama. Episodes 6 and above require an active VIP membership to unlock the video URLs.",
    "free_episodes": 5
  },
  "endpoints": [
    {
      "group": "1. 认证与用户权限 (Authentication & VIP)",
      "apis": [
        {
          "name": "用户注册 (User Register)",
          "method": "POST",
          "path": "/api/auth/register",
          "headers": {
            "Content-Type": "application/json"
          },
          "body": {
            "username": {
              "type": "string",
              "required": true,
              "desc": "账号用户名 (3~30字符)"
            },
            "password": {
              "type": "string",
              "required": true,
              "desc": "密码 (至少6位)"
            }
          },
          "body_example": {
            "username": "user_test",
            "password": "password123"
          },
          "response_example": {
            "success": true,
            "message": "User registered successfully",
            "userId": "u_abc123"
          }
        },
        {
          "name": "用户登录 (User Login)",
          "method": "POST",
          "path": "/api/auth/login",
          "headers": {
            "Content-Type": "application/json"
          },
          "body": {
            "username": {
              "type": "string",
              "required": true,
              "desc": "用户名"
            },
            "password": {
              "type": "string",
              "required": true,
              "desc": "密码"
            }
          },
          "body_example": {
            "username": "user_test",
            "password": "password123"
          },
          "response_example": {
            "success": true,
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "user": {
              "id": "u_abc123",
              "username": "user_test",
              "isVip": false,
              "vipExpireAt": null
            }
          }
        },
        {
          "name": "获取当前用户信息 (User Profile)",
          "method": "GET",
          "path": "/api/auth/me",
          "headers": {
            "Authorization": "Bearer <token>"
          },
          "response_example": {
            "success": true,
            "user": {
              "id": "u_abc123",
              "username": "user_test",
              "isVip": true,
              "vipExpireAt": "2026-10-18T12:00:00.000Z"
            }
          }
        },
        {
          "name": "开通/续费/模拟充值 VIP (Upgrade VIP)",
          "method": "POST",
          "path": "/api/auth/upgrade-vip",
          "headers": {
            "Authorization": "Bearer <token>",
            "Content-Type": "application/json"
          },
          "body": {
            "days": {
              "type": "integer",
              "required": false,
              "default": 30,
              "desc": "开通天数"
            }
          },
          "body_example": {
            "days": 30
          },
          "response_example": {
            "success": true,
            "message": "VIP upgraded successfully",
            "isVip": true,
            "vipExpireAt": "2026-10-18T12:00:00.000Z"
          }
        }
      ]
    },
    {
      "group": "2. App 首页与推荐流 (Home & Feed)",
      "apis": [
        {
          "name": "App 首页聚合推荐 (Home Composite)",
          "method": "GET",
          "path": "/api/home",
          "desc": "单接口获取首页完整数据（轮播图精选 banners、热播榜 trending、最新上线 latest、导航分类 categories、猜你喜欢 guessYouLike）",
          "headers": {},
          "response_example": {
            "success": true,
            "banners": [
              {
                "id": "...",
                "title": "...",
                "cover_url": "..."
              }
            ],
            "trending": [
              {
                "id": "...",
                "title": "...",
                "read_count": 320000
              }
            ],
            "latest": [
              {
                "id": "...",
                "title": "..."
              }
            ],
            "categories": [
              {
                "category": "Romance",
                "count": 323
              }
            ],
            "guessYouLike": [
              {
                "id": "...",
                "title": "..."
              }
            ]
          }
        },
        {
          "name": "下拉刷新 / 增量信息流 (Pull-to-Refresh Feed)",
          "method": "GET",
          "path": "/api/feed",
          "params": {
            "pageSize": {
              "type": "integer",
              "required": false,
              "default": 10,
              "desc": "刷新拉取的短剧数量"
            },
            "category": {
              "type": "string",
              "required": false,
              "desc": "按分类过滤推荐"
            }
          },
          "desc": "支持每次下拉刷新获取随机推荐或最新推荐瀑布流短剧",
          "response_example": {
            "success": true,
            "count": 10,
            "data": [
              {
                "id": "...",
                "title": "..."
              }
            ]
          }
        }
      ]
    },
    {
      "group": "3. 搜索与分别查看 (Search & Explore)",
      "apis": [
        {
          "name": "关键词智能搜索 (Search Dramas)",
          "method": "GET / POST",
          "path": "/api/search",
          "params": {
            "q": {
              "type": "string",
              "required": true,
              "desc": "搜索关键词（标题/副标题/分类/标签/简介）"
            },
            "page": {
              "type": "integer",
              "required": false,
              "default": 1
            },
            "pageSize": {
              "type": "integer",
              "required": false,
              "default": 20
            }
          },
          "desc": "支持精确与模糊模糊匹配，标题匹配加权置顶",
          "response_example": {
            "success": true,
            "query": "CEO",
            "pagination": {
              "page": 1,
              "pageSize": 20,
              "total": 138,
              "totalPages": 7,
              "hasNext": true
            },
            "data": [
              {
                "id": "...",
                "title": "Cold CEO...",
                "tags": [
                  "CEO",
                  "Romance"
                ]
              }
            ]
          }
        },
        {
          "name": "排行榜 (Rankings)",
          "method": "GET",
          "path": "/api/rankings",
          "params": {
            "type": {
              "type": "string",
              "required": false,
              "default": "hot",
              "enum": [
                "hot (热播榜)",
                "trend (飙升榜)",
                "collect (收藏榜)",
                "new (新剧榜)",
                "episodes (长剧榜)"
              ]
            },
            "limit": {
              "type": "integer",
              "required": false,
              "default": 20,
              "max": 100
            }
          }
        },
        {
          "name": "短剧列表与多维筛选 (Drama List & Filter)",
          "method": "GET",
          "path": "/api/dramas",
          "params": {
            "page": {
              "type": "integer",
              "default": 1
            },
            "pageSize": {
              "type": "integer",
              "default": 20
            },
            "category": {
              "type": "string",
              "desc": "分类，如 Romance, Urbano"
            },
            "language": {
              "type": "string",
              "desc": "语言代码，如 pt, en"
            },
            "sort": {
              "type": "string",
              "enum": [
                "popular (最热)",
                "latest (最新)",
                "random (随机)",
                "default (推荐)"
              ]
            }
          }
        },
        {
          "name": "分类全集与统计 (Categories)",
          "method": "GET",
          "path": "/api/categories",
          "desc": "返回所有短剧分类及各自短剧数"
        }
      ]
    },
    {
      "group": "4. 短剧详情与选集播放 (Drama Details & Episodes)",
      "apis": [
        {
          "name": "短剧单剧详情 (Drama Detail)",
          "method": "GET",
          "path": "/api/dramas/:id",
          "desc": "根据短剧 UUID 获取完整元数据"
        },
        {
          "name": "选集列表与视频播放直链 (Episodes & Video URLs)",
          "method": "GET",
          "path": "/api/dramas/:id/episodes",
          "headers": {
            "Authorization": "Bearer <token> (可选, 传入VIP用户的token可解锁第6集及之后所有视频)"
          },
          "params": {
            "page": {
              "type": "integer",
              "default": 1
            },
            "pageSize": {
              "type": "integer",
              "default": 100
            }
          },
          "desc": "普通用户或未登录用户仅前5集可播放（第6集起 playUrl 为 null 且 locked=true）；VIP 用户全集解锁高清播放直链",
          "response_example": {
            "success": true,
            "dramaId": "1b3c1ba7-bb52-46ae-a71d-40e85478ed3d",
            "userStatus": {
              "isVip": false,
              "note": "Non-VIP users can only view episodes 1-5"
            },
            "data": [
              {
                "episodeNo": 1,
                "locked": false,
                "needVip": false,
                "videos": [
                  {
                    "quality": "hd",
                    "format": "mp4",
                    "playUrl": "https://asserts.dramapluyf.top/.../video/hd/ep001.mp4"
                  }
                ]
              },
              {
                "episodeNo": 6,
                "locked": true,
                "needVip": true,
                "lockReason": "第6集及之后为VIP专享内容，请开通VIP后观看完整剧集",
                "videos": [
                  {
                    "quality": "hd",
                    "format": "mp4",
                    "playUrl": null
                  }
                ]
              }
            ]
          }
        }
      ]
    },
    {
      "group": "5. 用户个性化互动 (User Interaction)",
      "apis": [
        {
          "name": "获取收藏列表 (Get Favorites)",
          "method": "GET",
          "path": "/api/user/favorites",
          "headers": {
            "Authorization": "Bearer <token>"
          }
        },
        {
          "name": "添加/取消收藏 (Toggle Favorite)",
          "method": "POST",
          "path": "/api/user/favorites",
          "headers": {
            "Authorization": "Bearer <token>",
            "Content-Type": "application/json"
          },
          "body": {
            "dramaId": {
              "type": "string",
              "required": true
            }
          }
        },
        {
          "name": "获取播放历史 (Get History)",
          "method": "GET",
          "path": "/api/user/history",
          "headers": {
            "Authorization": "Bearer <token>"
          }
        },
        {
          "name": "上报播放进度 (Report Progress)",
          "method": "POST",
          "path": "/api/user/history",
          "headers": {
            "Authorization": "Bearer <token>",
            "Content-Type": "application/json"
          },
          "body": {
            "dramaId": {
              "type": "string",
              "required": true
            },
            "lastEpisodeNo": {
              "type": "integer",
              "required": true
            },
            "progressSeconds": {
              "type": "number",
              "required": false,
              "default": 0
            }
          }
        }
      ]
    }
  ]
}