From a4e62e31bdad390a7081887bfaa08ea11a3357e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BB=AA=E5=B1=B1=E4=B8=83=E5=AF=BB?=
 <xushanqixun@noreply.localhost>
Date: Sat, 14 Jun 2025 03:23:50 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20API3.1.2.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 API3.1.2.md | 338 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 338 insertions(+)
 create mode 100644 API3.1.2.md

diff --git a/API3.1.2.md b/API3.1.2.md
new file mode 100644
index 0000000..c4930ca
--- /dev/null
+++ b/API3.1.2.md
@@ -0,0 +1,338 @@
+## HTTP API
+
+### 1. 用户注册
+- **URL**: `/api/register`
+- **方法**: `POST`
+- **请求头**: `Content-Type: application/json`
+- **请求体**:
+```json
+{
+"username": "string",
+"password": "string",
+"avatar": "string"  // 可选，默认为'default_avatar.png'
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "register_1",
+"error": false,
+"message": "User registered successfully"
+}
+```
+
+- 用户名已存在:
+```json
+{
+"type": "register_0",
+"success": false,
+"message": "Username already exists"
+}
+```
+
+- 用户名格式错误（返回状态码400）:
+```json
+{
+"type": "register_-2",
+"success": false,
+"message": "Invalid username. Must be 2-20 characters, start with a letter or symbol, and contain only letters, numbers, or symbols: _!@#$%^&+-~?"
+}
+```
+
+- 头像格式错误（仅允许.png或.jpg）:
+```json
+{
+"type": "register_0",
+"success": False,
+"message": "Invalid avatar format. Only .png or .jpg allowed"
+}
+```
+
+- 其他错误（如数据库错误）:
+```json
+{
+"type": "register_-1",
+"error": true,
+"message": "错误详情"
+}
+```
+
+### 2. 用户登录
+- **URL**: `/api/login`
+- **方法**: `POST`
+- **请求头**: `Content-Type: application/json`
+- **请求体**:
+```json
+{
+"username": "string",
+"password": "string"
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "login_1",
+"status": "success",
+"token": "string",   // 令牌，用于后续请求
+"avatar": "string"   // 用户头像的URL
+}
+```
+
+- 账号已登录（返回状态码409）:
+```json
+{
+"type": "login",
+"status": "error_0",
+"message": "Account already logged in"
+}
+```
+
+- 凭证错误:
+```json
+{
+"type": "login_0",
+"status": "error",
+"message": "Invalid credentials"
+}
+```
+
+### 3. 发送聊天消息
+- **URL**: `/api/chat`
+- **方法**: `POST`
+- **请求头**: `Content-Type: application/json`
+- `Authorization: <token>`   // 登录时获取的令牌
+- **请求体**:
+```json
+{
+"message": "string"
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "chat",
+"status": "success"
+}
+```
+
+- 令牌无效或缺失（返回状态码401）:
+```json
+{
+"type": "chat",
+"status": "error"
+}
+```
+
+### 4. 获取头像
+- **URL**: `/avatar/<username>/<filename>`
+- **方法**: `GET`
+- **响应**:
+- 返回用户头像文件（如果存在），否则返回默认头像。
+
+
+## Socket API
+Socket服务器运行在`8889`端口。客户端连接后，可以发送JSON格式的消息。每个消息必须包含`type`字段，表示操作类型。
+
+### 消息格式
+所有消息均为JSON格式，编码为UTF-8字符串发送。
+
+### 1. 注册
+- **请求**:
+```json
+{
+"type": "register",
+"username": "string",
+"password": "string",
+"avatar": "string"   // 可选
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "register_1",
+"error": false,
+"message": "User registered successfully"
+}
+```
+
+- 用户名已存在:
+```json
+{
+"type": "register_0",
+"success": false,
+"message": "Username already exists"
+}
+```
+
+- 用户名格式错误:
+```json
+{
+"type": "register_-2",
+"success": false,
+"message": "Invalid username format"
+}
+```
+
+- 头像格式错误:
+```json
+{
+"type": "register_-3",
+"success": false,
+"message": "Invalid avatar format. Only .png or .jpg allowed"
+}
+```
+
+### 2. 登录
+- **请求**:
+```json
+{
+"type": "login",
+"username": "string",
+"password": "string"
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "login",
+"status": "success",
+"message": "Login successful",
+"token": "string",   // 用于后续操作的令牌
+"username": "string", // 登录的用户名
+"avatar": "string"    // 头像URL
+}
+```
+
+- 账号已登录:
+```json
+{
+"type": "login",
+"status": "error_-1",
+"message": "Account already logged in"
+}
+```
+
+- 凭证错误:
+```json
+{
+"type": "login",
+"status": "error_0",
+"message": "Invalid credentials"
+}
+```
+
+### 3. 发送聊天消息
+- **请求**:
+```json
+{
+"type": "chat",
+"token": "string",   // 登录时获取的令牌
+"message": "string"  // 聊天内容
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "chat",
+"status": "success"
+}
+```
+
+- 令牌无效:
+```json
+{
+"type": "chat",
+"status": "error_It",
+"message": "Invalid token"
+}
+```
+
+- 未登录:
+```json
+{
+"type": "chat",
+"status": "error_Nli",
+"message": "Not logged in"
+}
+```
+
+### 4. 心跳检测
+- **请求**:
+```json
+{
+"type": "heartbeat",
+"token": "string"
+}
+```
+
+- **响应**:
+- 成功:
+```json
+{
+"type": "heartbeat",
+"status": "success"
+}
+```
+
+- 失败:
+```json
+{
+"type": "heartbeat",
+"status": "error"
+}
+```
+
+## 错误码说明
+
+### 注册相关
+- `register_1`: 注册成功
+- `register_0`: 用户名已存在
+- `register_-1`: 数据库错误
+- `register_-2`: 用户名格式错误
+- `register_-3`: 头像格式错误（仅Socket）
+
+### 登录相关
+- `login_1`: 登录成功（HTTP）
+- `login_0`: 凭证错误（HTTP）或登录失败（Socket中为`error_0`）
+- `error_-1`（Socket）: 账号已登录
+
+### 聊天相关
+- `error_Mt`: 令牌缺失（Socket）
+- `error_It`: 令牌无效（Socket）
+- `error_Nli`: 未登录（Socket）
+
+## 用户名校验规则
+- 长度：2-20个字符
+- 只能包含字母、数字以及特定符号：`_!@#$%^&+-~?`
+- 不能以数字开头
+
+## 头像规则
+- 头像文件名必须以`.png`或`.jpg`结尾。
+- 每个用户有专属的头像目录，位于`avatar/<username>`下。
+- 默认头像为`avatar/default/default_avatar.png`。
+
+## 连接管理
+- 每个用户只能有一个活跃连接。如果尝试登录时已有活跃连接，则拒绝登录（HTTP返回409，Socket返回错误）。
+- 服务器会定期（5分钟）检查不活跃的连接并清理。
+
+- 客户端应每5分钟发送一次心跳包以保持连接活跃。
+
+## 注意事项
+
+- 令牌有效期为1小时，每次使用会刷新有效期。
+
+- 头像的获取通过HTTP GET请求，路径为`/avatar/<username>/<filename>`。
+
+请根据实际情况调整使用。
\ No newline at end of file