# Hertz Studio Django 验证码模块接口文档

- 基础路径: `/api/captcha/`
- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {}
  }
  ```
- 路由挂载: 项目主路由中已通过 `path('api/captcha/', include('hertz_studio_django_captcha.urls'))` 挂载（`hertz_server_django/urls.py:28`）。
- 认证说明: 接口允许匿名访问（`AllowAny`），不需要登录（`hertz_studio_django_captcha/api_views.py:18`, `hertz_studio_django_captcha/api_views.py:60`）。
- 验证接口说明: 独立的验证码验证接口已删除，验证逻辑集成到具体业务接口（`hertz_studio_django_captcha/api_views.py:54`）。


## 一、生成验证码

### 生成新的验证码
- 方法: `POST`
- 路径: `/api/captcha/generate/`
- 认证: 不需要登录
- 实现: `CaptchaGenerateAPIView.post`（`hertz_studio_django_captcha/api_views.py:38`）
- 请求示例:
  ```bash
  curl -X POST "http://localhost:8000/api/captcha/generate/"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "验证码生成成功",
    "data": {
      "captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "image_data": "data:image/png;base64,iVBORw0KGgo...",
      "expires_in": 300
    }
  }
  ```


## 二、刷新验证码

### 刷新已有验证码，生成新图像
- 方法: `POST`
- 路径: `/api/captcha/refresh/`
- 认证: 不需要登录
- 请求体: `application/json`
- 字段: `captcha_id` 旧验证码ID
- 实现: `CaptchaRefreshAPIView.post`（`hertz_studio_django_captcha/api_views.py:84`）
- 请求示例:
  ```http
  POST /api/captcha/refresh/
  Content-Type: application/json
  
  {"captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"}
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "验证码刷新成功",
    "data": {
      "captcha_id": "f2b3c4d5-e6f7-8901-bcde-0123456789ab",
      "image_data": "data:image/png;base64,iVBORw0KGgo...",
      "expires_in": 300
    }
  }
  ```


## 三、错误响应示例
- 参数不完整（刷新接口）:
  ```json
  {"success": false, "code": 400, "message": "参数不完整"}
  ```
- 生成/刷新失败（异常信息）：
  ```json
  {"success": false, "code": 500, "message": "验证码生成失败", "error": "<错误信息>"}
  ```