chatserver/API3.1.3.md

## 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>`。

请根据实际情况调整使用。