上传规范文档

docs/API接口文档/验证码模块接口文档.md

@@ -0,0 +1,83 @@
+# 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": "<错误信息>"}
+  ```