# sweet-circle

**Repository Path**: ErGeAnan/sweet-circle

## Basic Information

- **Project Name**: sweet-circle
- **Description**: java springboot 聊天工具
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-12
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sweet-Circle 项目详细文档

## 📋 目录

- [一、项目概述](#一项目概述)
- [二、技术架构](#二技术架构)
- [三、模块详解](#三模块详解)
- [四、数据库设计](#四数据库设计)
- [五、核心功能](#五核心功能)
- [六、API接口文档](#六api接口文档)
- [七、环境部署](#七环境部署)
- [八、开发指南](#八开发指南)
- [九、常见问题](#九常见问题)

---

## 一、项目概述

### 1.1 项目简介

**Sweet-Circle（甜圈）** 是一个基于 Java Spring Boot 3.x 和 Spring Cloud 微服务架构的即时通讯系统。该项目源自 ruoyi-cloud 框架的二次开发，旨在提供一个稳定、高效、可扩展的即时通讯解决方案。

**项目定位**：
- 支持单聊、群聊等核心即时通讯功能
- 提供完整的用户认证与授权体系
- 支持多种文件存储方式（本地/MinIO/阿里云OSS）
- 基于 WebSocket 实现实时消息推送
- 采用微服务架构，易于扩展和维护

### 1.2 版本信息

| 项目 | 值 |
|-----|---|
| 项目名称 | Sweet-Circle（甜圈） |
| 项目版本 | 1.0.0 |
| GroupId | com.anan |
| ArtifactId | sweet-circle |
| JDK 版本 | 21+ |
| 许可证 | 详见 LICENSE 文件 |

### 1.3 项目特色

✅ **微服务架构**：基于 Spring Cloud Alibaba，服务独立部署，易于扩展  
✅ **实时通讯**：Netty + WebSocket 实现低延迟消息推送  
✅ **多端支持**：支持 Web、Mobile、Desktop 等多平台客户端  
✅ **安全认证**：JWT Token + Spring Security 双重保障  
✅ **灵活存储**：支持本地、MinIO、阿里云 OSS 多种文件存储方案  
✅ **高可用性**：集成 Sentinel 实现限流熔断，保障系统稳定性

---

## 二、技术架构

### 2.1 核心技术栈

#### 后端技术

| 技术组件 | 版本 | 说明 |
|---------|------|------|
| **Java** | 21+ | 开发语言 |
| **Spring Boot** | 3.3.5 | 基础框架 |
| **Spring Cloud** | 2023.0.3 | 微服务框架 |
| **Spring Cloud Alibaba** | 2023.0.1.2 | 阿里巴巴微服务组件 |
| **MyBatis-Plus** | 3.5.5 | ORM 框架，简化数据库操作 |
| **Nacos** | 2.x | 配置中心 & 服务发现 |
| **Redis** | 3.2+ | 缓存、会话管理、分布式锁 |
| **MySQL** | 8.0+ | 主数据库 |
| **Netty** | 4.1.92.Final | WebSocket 服务端 |
| **Sentinel** | - | 流量控制、熔断降级 |
| **SpringDoc** | 2.6.0 | API 文档（OpenAPI 3） |
| **JWT** | 0.9.1 | Token 认证 |
| **MinIO** | 8.2.2 | 对象存储 |
| **Aliyun OSS** | 3.17.1 | 阿里云对象存储 |
| **FastJSON2** | 2.0.57 | JSON 解析 |
| **Lombok** | - | 简化代码 |

#### 前端技术（待补充）

> 注：本项目为后端服务，前端客户端需单独开发

### 2.2 系统架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                            客户端层                                  │
│                     (Web / Mobile / Desktop)                        │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      anan-gateway (API网关)                          │
│                    端口: 待配置                                       │
│         路由转发 | 认证校验 | 限流熔断 | 负载均衡                         │
└─────────────────────────────────────────────────────────────────────┘
                                    │
            ┌───────────────────────┼───────────────────────┐
            ▼                       ▼                       ▼
    ┌───────────────┐     ┌───────────────┐     ┌───────────────┐
    │  anan-auth    │     │ anan-system   │     │  anan-file    │
    │  认证服务      │     │  系统服务       │     │  文件服务       │
    │  端口: 9205    │     │  端口: 待配置   │     │  端口: 待配置   │
    └───────────────┘     └───────────────┘     └───────────────┘
            │                       │                       │
            └───────────────────────┼───────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          中间件层                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │  Nacos   │  │  Redis   │  │  MySQL   │  │  MinIO   │             │
│  │配置/发现  │  │  缓存    │  │  数据库   │  │文件存储   │              │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘             │
└─────────────────────────────────────────────────────────────────────┘
```

### 2.3 数据流向

#### 用户登录流程
```
客户端 → Gateway(路由) → Auth服务(认证) → Redis(存储Token) → 返回Token
```

#### 消息发送流程
```
客户端A → Gateway → System服务 → WebSocket(Netty) → 客户端B
                                ↓
                          MySQL(持久化)
                                ↓
                          Redis(离线消息)
```

#### 文件上传流程
```
客户端 → Gateway → File服务 → 存储引擎(Local/MinIO/OSS) → 返回URL
                              ↓
                        MySQL(记录元数据)
```

---

## 三、模块详解

### 3.1 模块总览

```
sweet-circle/
├── anan-gateway              # API网关模块
├── anan-auth                 # 认证授权中心
├── anan-api/                 # API接口定义
│   └── anan-api-system       # 系统服务API
├── anan-modules/             # 业务模块
│   ├── anan-system           # 系统服务（用户、社交、消息）
│   ├── anan-file             # 文件服务
│   └── anan-config           # 配置服务
└── anan-common/              # 公共模块
    ├── anan-common-core      # 核心工具类
    ├── anan-common-redis     # Redis服务
    ├── anan-common-security  # 安全认证
    ├── anan-common-sensitive # 数据脱敏
    ├── anan-common-swagger   # API文档
    └── anan-common-netty     # WebSocket服务
```

### 3.2 anan-gateway（网关模块）

**职责**：统一入口、路由转发、认证鉴权、限流熔断

**技术栈**：
- Spring Cloud Gateway
- Spring Cloud Alibaba Nacos
- Spring Cloud Alibaba Sentinel
- Spring Cloud LoadBalancer

**核心功能**：
1. **路由转发**：根据请求路径转发到对应微服务
2. **认证校验**：验证 JWT Token 合法性
3. **限流熔断**：基于 Sentinel 实现流量控制
4. **负载均衡**：集成 LoadBalancer 实现服务负载均衡
5. **跨域处理**：统一处理 CORS 跨域请求

**配置文件**：
- `bootstrap.yml`：Nacos 配置中心连接
- `application.yml`：网关路由规则

### 3.3 anan-auth（认证模块）

**端口**：9205

**职责**：用户注册、登录、验证码、Token 管理

**技术栈**：
- Spring Boot Web
- Spring Mail（邮件发送）
- EasyCaptcha（图形验证码）
- JWT（Token 生成与验证）
- BCrypt（密码加密）

**核心功能**：

#### 3.3.1 用户注册
- 接口：`POST /auth/register`
- 支持邮箱注册
- 密码 BCrypt 加密存储
- 自动生成甜蜜账号

#### 3.3.2 用户登录
- 接口：`POST /auth/login`
- 支持账号/邮箱/手机号登录
- 图形验证码校验
- 生成 JWT Token

#### 3.3.3 验证码服务
- 图形验证码：`GET /auth/captcha`
- 邮箱验证码：`POST /auth/email/code`

**核心类**：
- `TokenController`：登录注册控制器
- `EmailController`：邮箱验证码控制器
- `SysLoginService`：登录业务逻辑
- `SysRegisterService`：注册业务逻辑

### 3.4 anan-modules/anan-system（系统模块）

**职责**：用户管理、社交关系、消息管理

**核心功能**：

#### 3.4.1 用户管理
- 获取用户信息
- 更新用户资料
- 查询用户列表

#### 3.4.2 社交关系管理
- 发起好友申请：`POST /contact/apply`
- 查看申请列表：`GET /contact/apply/list`
- 同意好友申请：`POST /contactApply/accept`
- 拒绝好友申请：`POST /contactApply/refuse`
- 删除好友申请：`POST /contactApply/delete`
- 联系人列表查询
- 黑名单管理

#### 3.4.3 消息管理
- 单聊消息发送
- 群聊消息发送
- 消息历史记录查询
- 消息状态同步（已读/未读）
- 离线消息推送

#### 3.4.4 群聊管理
- 创建群聊
- 邀请成员
- 移除成员
- 设置管理员
- 解散群聊

**核心类**：
- `SysUserController`：用户管理控制器
- `ContactController`：联系人管理控制器
- `ChatMessageService`：消息服务
- `GroupChatService`：群聊服务

### 3.5 anan-modules/anan-file（文件模块）

**职责**：文件上传、下载、管理

**支持的存储方式**：
1. **本地存储**：文件存储在服务器本地磁盘
2. **MinIO存储**：私有化对象存储
3. **阿里云OSS**：公有云对象存储

**核心功能**：

#### 3.5.1 本地存储
- 接口：`POST /file/local/upload`
- 适用场景：开发环境、小规模应用

#### 3.5.2 MinIO存储
- 接口：`POST /file/minio/upload`
- 适用场景：私有化部署、企业内网

#### 3.5.3 阿里云OSS存储
- 接口：`POST /file/oss/upload`
- 适用场景：生产环境、大规模应用

**文件类型支持**：
- 图片：jpg, png, gif, webp
- 视频：mp4, avi, mov
- 音频：mp3, wav, aac
- 文档：pdf, doc, docx, xls, xlsx
- 其他：zip, rar, txt

**核心类**：
- `LocalSysFileController`：本地存储控制器
- `MinioSysFileController`：MinIO 存储控制器
- `OssSysFileController`：阿里云 OSS 控制器
- `SysFileService`：文件服务接口

### 3.6 anan-modules/anan-config（配置模块）

**职责**：动态配置管理

**核心功能**：
- 配置项动态加载
- 配置热更新
- 配置版本管理

### 3.7 anan-common（公共模块）

#### 3.7.1 anan-common-core（核心模块）

**功能**：
- 统一响应封装（R<T>）
- 全局异常处理
- 通用工具类
- 常量定义
- 枚举类
- 自定义注解

**核心类**：
- `R<T>`：统一响应结果
- `ResponseCodeEnum`：响应码枚举
- `GlobalExceptionHandler`：全局异常处理器
- `StringUtils`：字符串工具类
- `DateUtils`：日期工具类

#### 3.7.2 anan-common-redis（Redis模块）

**功能**：
- Redis Template 封装
- 分布式锁实现
- 缓存工具类
- Session 管理

**核心类**：
- `RedisService`：Redis 服务
- `RedisLock`：分布式锁

#### 3.7.3 anan-common-security（安全模块）

**功能**：
- Spring Security 配置
- JWT Token 生成与验证
- 权限校验
- 用户上下文管理

**核心类**：
- `SecurityConfig`：安全配置
- `TokenService`：Token 服务
- `AuthUtil`：认证工具类

#### 3.7.4 anan-common-sensitive（脱敏模块）

**功能**：
- 手机号脱敏
- 邮箱脱敏
- 身份证脱敏
- 自定义脱敏策略

#### 3.7.5 anan-common-swagger（文档模块）

**功能**：
- OpenAPI 3 文档配置
- Swagger UI 界面
- API 分组管理

**访问地址**：
- Swagger UI: `http://{host}:{port}/swagger-ui.html`
- OpenAPI JSON: `http://{host}:{port}/v3/api-docs`

#### 3.7.6 anan-common-netty（WebSocket模块）

**功能**：
- Netty WebSocket 服务端
- 心跳检测
- 连接管理
- 消息编解码

**核心类**：
- `NettyWebSocketStarter`：Netty 启动器
- `HandlerWebSocket`：WebSocket 处理器
- `HandlerHeartBeat`：心跳处理器
- `ChannelContextUtils`：通道上下文工具

---

## 四、数据库设计

### 4.1 数据表概览

| 表名 | 中文名 | 说明 |
|-----|--------|------|
| sys_user | 用户表 | 存储用户基本信息 |
| user_contact | 好友关系表 | 存储用户好友关系 |
| contact_apply | 好友申请表 | 存储好友申请记录 |
| chat_session | 聊天会话表 | 存储聊天会话信息 |
| group_chat | 群聊表 | 存储群聊基本信息 |
| group_member | 群成员表 | 存储群成员信息 |
| chat_message | 消息表 | 存储聊天消息 |
| offline_message | 离线消息表 | 存储离线消息 |
| file_storage | 文件存储表 | 存储文件元数据 |

### 4.2 核心表结构详解

#### 4.2.1 用户表 (sys_user)

**用途**：存储系统用户的基本信息和认证信息

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 用户ID（主键，UUID） |
| account | varchar(50) | ✓ | - | 甜蜜账号（唯一标识） |
| username | varchar(32) | ✓ | - | 昵称 |
| avatar | varchar(255) | - | '' | 头像URL |
| phone | varchar(16) | - | NULL | 手机号（唯一） |
| email | varchar(50) | - | NULL | 邮箱（唯一） |
| password | varchar(128) | ✓ | - | 加密密码（BCrypt） |
| gender | tinyint | - | 1 | 性别：1-男 2-女 |
| signature | varchar(255) | - | '' | 个性签名 |
| locality | varchar(50) | - | NULL | 地区 |
| join_type | tinyint | - | 1 | 加入方式：1-需验证 2-免验证 |
| status | tinyint | - | 0 | 状态：0-正常 1-禁用 |
| create_time | BIGINT | ✓ | - | 创建时间（时间戳） |
| login_time | BIGINT | ✓ | - | 最后登录时间 |
| login_ip | varchar(50) | ✓ | - | 最后登录IP |

**索引**：
- 主键索引：`id`
- 唯一索引：`account`, `phone`, `email`
- 普通索引：`status`, `create_time`
- 复合索引：`(id, status)`, `(phone, status)`, `(email, status)`, `(account, status)`

#### 4.2.2 好友关系表 (user_contact)

**用途**：存储用户之间的好友关系状态

| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| user_id | varchar(50) | ✓ | 用户ID |
| contact_user_id | varchar(50) | ✓ | 联系人ID |
| contact_account | varchar(50) | ✓ | 联系人甜蜜账号 |
| contact_phone | varchar(50) | ✓ | 联系人手机号 |
| friends_code | tinyint(1) | ✓ | 好友状态码（见下方说明） |
| avatar | varchar(255) | ✓ | 联系人头像 |
| username | varchar(15) | ✓ | 联系人昵称 |
| join_type | tinyint(1) | ✓ | 加入方式：0-直接加入 1-同意后加好友 |
| gender | tinyint(1) | ✓ | 性别：0-女 1-男 |
| signature | varchar(255) | - | 个性签名 |
| add_time | BIGINT | ✓ | 添加时间 |
| locality | varchar(50) | ✓ | 地区 |
| note_name | varchar(30) | - | 备注名 |
| donut_auth | tinyint(1) | - | 甜甜圈权限：1-聊天+甜甜圈 2-仅聊天 |
| donut_status_a | tinyint(1) | - | 不让他看她：0-否 1-是 |
| donut_status_b | tinyint(1) | - | 不看她：0-否 1-是 |
| status | tinyint(1) | - | 逻辑删除：0-未删 1-已删 |

**friends_code 状态说明**：
- `0`: 非好友
- `1`: 好友
- `2`: 已删除好友（我删除对方）
- `3`: 被好友删除（对方删除我）
- `4`: 已拉黑好友（我拉黑对方）
- `5`: 被好友拉黑（对方拉黑我）

**索引**：
- 复合索引：`(user_id, contact_user_id, status)`
- 普通索引：`contact_user_id`, `user_id`, `friends_code`

#### 4.2.3 好友申请表 (contact_apply)

**用途**：存储好友申请记录

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 主键ID（UUID） |
| from_user_id | varchar(64) | ✓ | - | 申请人ID |
| to_user_id | varchar(64) | ✓ | - | 接收人ID |
| verify_msg | text | - | NULL | 验证消息 |
| apply_status | tinyint | - | 0 | 申请状态：0-待处理 1-已同意 2-已拒绝 3-已过期 |
| create_time | BIGINT | ✓ | - | 申请时间 |
| update_time | BIGINT | ✓ | - | 更新时间 |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |

**索引**：
- 主键：`id`
- 唯一索引：`(from_user_id, to_user_id)` - 防止重复申请
- 普通索引：`from_user_id`, `to_user_id`, `apply_status`, `status`, `create_time`

#### 4.2.4 聊天会话表 (chat_session)

**用途**：存储用户的聊天会话列表

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 主键ID |
| session_id | varchar(64) | ✓ | - | 会话唯一标识 |
| owner_id | varchar(64) | ✓ | - | 会话所属用户ID |
| session_type | tinyint | ✓ | - | 会话类型：1-单聊 2-群聊 |
| note_name | varchar(64) | - | '' | 会话名称（备注） |
| avatar | varchar(255) | - | '' | 会话头像 |
| last_msg_id | varchar(64) | - | NULL | 最后一条消息ID |
| last_msg_time | BIGINT | ✓ | - | 最后一条消息时间 |
| is_top | tinyint | - | 0 | 是否置顶：0-否 1-是 |
| is_mute | tinyint | - | 0 | 是否静音：0-否 1-是 |
| create_time | BIGINT | ✓ | - | 创建时间 |
| update_time | BIGINT | ✓ | - | 更新时间 |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |

**说明**：
- 单聊：双方各存一条记录
- 群聊：每个群成员各存一条记录

**索引**：
- 主键：`id`
- 唯一索引：`id`
- 普通索引：`owner_id`, `session_type`, `last_msg_time`, `status`
- 复合索引：`(session_type, last_msg_time)`

#### 4.2.5 群聊表 (group_chat)

**用途**：存储群聊基本信息

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 群ID（如：group_123456） |
| group_name | varchar(64) | ✓ | - | 群名称 |
| avatar | varchar(255) | - | '' | 群头像URL |
| owner_id | varchar(64) | ✓ | - | 群主ID |
| desc | varchar(255) | - | '' | 群描述 |
| max_member | int | - | 200 | 最大成员数 |
| group_status | tinyint | - | 1 | 群状态：0-解散 1-正常 |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |
| create_time | BIGINT | ✓ | - | 创建时间 |
| update_time | BIGINT | ✓ | - | 更新时间 |

**索引**：
- 主键：`id`
- 唯一索引：`id`
- 普通索引：`owner_id`, `group_status`, `status`

#### 4.2.6 群成员表 (group_member)

**用途**：存储群成员信息及角色

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 主键ID |
| user_id | varchar(64) | ✓ | - | 成员ID |
| role | tinyint | ✓ | - | 角色：1-群主 2-管理员 3-普通成员 |
| nickname | varchar(32) | - | '' | 群昵称 |
| join_time | BIGINT | ✓ | - | 加入时间 |
| quit_time | BIGINT | ✓ | - | 退出时间 |
| is_mute | tinyint | - | 0 | 是否禁言：0-否 1-是 |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |

**索引**：
- 主键：`id`
- 唯一索引：`user_id` - 避免重复加入
- 普通索引：`user_id`, `role`, `is_mute`, `status`

#### 4.2.7 消息表 (chat_message)

**用途**：存储所有聊天消息

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 消息全局唯一标识 |
| session_id | varchar(64) | ✓ | - | 所属会话ID |
| sender_id | varchar(64) | ✓ | - | 发送者ID |
| receiver_id | varchar(64) | ✓ | - | 接收者ID（单聊=好友ID，群聊=群ID） |
| msg_type | tinyint | ✓ | - | 消息类型（见下方说明） |
| content | text | - | NULL | 消息内容 |
| file_size | bigint | - | 0 | 文件大小（字节） |
| file_name | varchar(128) | - | '' | 文件名 |
| send_time | BIGINT | ✓ | - | 发送时间 |
| msg_status | tinyint | - | 0 | 消息状态（见下方说明） |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |
| create_time | BIGINT | ✓ | - | 创建时间 |
| update_time | BIGINT | ✓ | - | 更新时间 |

**msg_type 消息类型**：
- `1`: 文字
- `2`: 图片
- `3`: 语音
- `4`: 视频
- `5`: 文件
- `6`: 表情
- `7`: 撤回
- `8`: 系统通知

**msg_status 消息状态**：
- `0`: 发送中
- `1`: 已发送
- `2`: 已送达
- `3`: 已读
- `4`: 已撤回
- `5`: 发送失败

**索引**：
- 主键：`id`
- 唯一索引：`id`
- 普通索引：`session_id`, `sender_id`, `receiver_id`, `send_time`, `msg_status`, `msg_type`, `status`
- 复合索引：`(send_time, status)`, `(msg_type, send_time)`

#### 4.2.8 离线消息表 (offline_message)

**用途**：存储用户离线期间的消息

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|--------|------|
| id | varchar(64) | ✓ | - | 主键ID |
| user_id | varchar(64) | ✓ | - | 接收者ID（离线用户） |
| msg_id | varchar(64) | ✓ | - | 消息ID |
| session_id | varchar(64) | ✓ | - | 会话ID |
| is_pulled | tinyint | - | 0 | 是否已拉取：0-未拉取 1-已拉取 |
| create_time | BIGINT | ✓ | - | 创建时间 |
| update_time | BIGINT | ✓ | - | 更新时间 |
| status | tinyint | - | 0 | 逻辑删除：0-未删 1-已删 |

**索引**：
- 主键：`id`
- 普通索引：`user_id`, `is_pulled`, `session_id`

#### 4.2.9 文件存储表 (file_storage)

**用途**：存储文件元数据信息

> 注：完整表结构请参考 SQL 文件

---

## 五、核心功能

### 5.1 用户认证

#### 5.1.1 注册流程

```mermaid
graph TB
    A[用户提交注册信息] --> B{参数校验}
    B -->|失败| C[返回错误信息]
    B -->|成功| D{邮箱是否已注册}
    D -->|是| C
    D -->|否| E{手机号是否已注册}
    E -->|是| C
    E -->|否| F[BCrypt加密密码]
    F --> G[生成甜蜜账号]
    G --> H[保存用户信息到数据库]
    H --> I[返回注册成功]
```

#### 5.1.2 登录流程

```mermaid
graph TB
    A[用户提交登录信息] --> B{参数校验}
    B -->|失败| C[返回错误信息]
    B -->|成功| D{图形验证码校验}
    D -->|失败| C
    D -->|成功| E[查询用户信息]
    E --> F{用户是否存在}
    F -->|否| C
    F -->|是| G{密码是否正确}
    G -->|否| C
    G -->|是| H[生成JWT Token]
    H --> I[保存Token到Redis]
    I --> J[返回Token和用户信息]
```

### 5.2 社交关系管理

#### 5.2.1 好友申请流程

```mermaid
graph TB
    A[用户A发起好友申请] --> B{用户B是否存在}
    B -->|否| C[返回错误]
    B -->|是| D{是否已是好友}
    D -->|是| E[返回提示]
    D -->|否| F{是否有待处理申请}
    F -->|是| E
    F -->|否| G[创建申请记录]
    G --> H[推送通知给用户B]
    H --> I[返回申请成功]
```

#### 5.2.2 好友状态流转

```
非好友(0) --申请--> 待处理
待处理 --同意--> 好友(1)
待处理 --拒绝--> 非好友(0)
好友(1) --我删除--> 已删除好友(2)
好友(1) --对方删除--> 被好友删除(3)
好友(1) --我拉黑--> 已拉黑好友(4)
好友(1) --对方拉黑--> 被好友拉黑(5)
```

### 5.3 实时消息

#### 5.3.1 单聊消息流程

```mermaid
graph TB
    A[用户A发送消息] --> B[Gateway路由]
    B --> C[System服务接收]
    C --> D[保存消息到数据库]
    D --> E{用户B是否在线}
    E -->|是| F[通过WebSocket推送]
    E -->|否| G[保存到离线消息表]
    F --> H[更新消息状态为已送达]
    G --> H
    H --> I[返回发送成功]
```

#### 5.3.2 群聊消息流程

```mermaid
graph TB
    A[用户发送群消息] --> B[保存到数据库]
    B --> C[查询群成员列表]
    C --> D[遍历在线成员]
    D --> E[通过WebSocket推送]
    D --> F[离线成员存入离线表]
    E --> G[更新消息状态]
    F --> G
    G --> H[返回发送成功]
```

### 5.4 文件管理

#### 5.4.1 文件上传流程

```mermaid
graph TB
    A[客户端选择文件] --> B[上传到File服务]
    B --> C{选择存储方式}
    C -->|本地| D[保存到本地磁盘]
    C -->|MinIO| E[上传到MinIO]
    C -->|OSS| F[上传到阿里云OSS]
    D --> G[生成访问URL]
    E --> G
    F --> G
    G --> H[保存文件元数据到数据库]
    H --> I[返回文件URL]
```

---

## 六、API接口文档

### 6.1 认证接口 (/auth)

| 接口路径 | 方法 | 说明 | 是否需要认证 |
|---------|------|------|------------|
| `/auth/register` | POST | 用户注册 | ❌ |
| `/auth/login` | POST | 用户登录 | ❌ |
| `/auth/captcha` | GET | 获取图形验证码 | ❌ |
| `/auth/email/code` | POST | 发送邮箱验证码 | ❌ |

#### 6.1.1 用户注册

**请求示例**：
```json
POST /auth/register
Content-Type: application/json

{
  "username": "测试用户",
  "email": "test@example.com",
  "password": "123456",
  "confirmPassword": "123456"
}
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "注册成功",
  "data": {
    "userId": "uuid-xxx",
    "account": "100001"
  }
}
```

#### 6.1.2 用户登录

**请求示例**：
```json
POST /auth/login
Content-Type: application/json

{
  "username": "100001",
  "password": "123456",
  "captchaCode": "abcd",
  "captchaKey": "captcha-key-xxx"
}
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "userInfo": {
      "userId": "uuid-xxx",
      "username": "测试用户",
      "avatar": "http://..."
    }
  }
}
```

### 6.2 用户接口 (/user)

| 接口路径 | 方法 | 说明 | 是否需要认证 |
|---------|------|------|------------|
| `/user/info` | GET | 获取用户信息 | ✅ |
| `/user/update` | PUT | 更新用户信息 | ✅ |

### 6.3 联系人接口 (/contact)

| 接口路径 | 方法 | 说明 | 是否需要认证 |
|---------|------|------|------------|
| `/contact/apply` | POST | 发起好友申请 | ✅ |
| `/contact/apply/list` | GET | 获取好友申请列表 | ✅ |
| `/contactApply/accept` | POST | 同意好友申请 | ✅ |
| `/contactApply/refuse` | POST | 拒绝好友申请 | ✅ |
| `/contactApply/delete` | POST | 删除好友申请 | ✅ |
| `/contact/list` | GET | 获取联系人列表 | ✅ |

### 6.4 文件接口 (/file)

| 接口路径 | 方法 | 说明 | 是否需要认证 |
|---------|------|------|------------|
| `/file/local/upload` | POST | 本地文件上传 | ✅ |
| `/file/minio/upload` | POST | MinIO文件上传 | ✅ |
| `/file/oss/upload` | POST | OSS文件上传 | ✅ |

#### 6.4.1 文件上传

**请求示例**：
```
POST /file/local/upload
Content-Type: multipart/form-data

file: [二进制文件]
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "url": "http://localhost:9300/files/xxx.jpg",
    "fileName": "xxx.jpg",
    "fileSize": 102400
  }
}
```

### 6.5 WebSocket 消息协议

#### 6.5.1 连接建立

```
ws://{host}:{port}/ws?token={jwt_token}
```

#### 6.5.2 消息格式

**发送消息**：
```json
{
  "type": "CHAT",
  "sessionId": "session-xxx",
  "receiverId": "user-xxx",
  "msgType": 1,
  "content": "你好"
}
```

**接收消息**：
```json
{
  "type": "CHAT",
  "msgId": "msg-xxx",
  "senderId": "user-xxx",
  "senderName": "张三",
  "senderAvatar": "http://...",
  "msgType": 1,
  "content": "你好",
  "sendTime": 1234567890,
  "msgStatus": 1
}
```

**消息类型**：
- `CHAT`: 聊天消息
- `ACK`: 消息确认
- `READ`: 已读回执
- `ONLINE`: 在线状态
- `OFFLINE`: 离线通知
- `SYSTEM`: 系统通知

---

## 七、环境部署

### 7.1 环境要求

| 组件 | 版本要求 | 说明 |
|-----|---------|------|
| JDK | 21+ | 推荐使用 Oracle JDK 21 或 OpenJDK 21 |
| Maven | 3.9+ | 构建工具 |
| MySQL | 8.0+ | 主数据库 |
| Redis | 3.2+ | 缓存服务 |
| Nacos | 2.x | 配置中心和服务发现 |
| MinIO | 最新版（可选） | 对象存储（可选） |

### 7.2 部署步骤

#### 步骤1：安装基础环境

1. **安装 JDK 21**
   ```bash
   # 下载并安装 JDK 21
   # 配置 JAVA_HOME 环境变量
   java -version  # 验证安装
   ```

2. **安装 Maven 3.9+**
   ```bash
   # 下载并安装 Maven
   mvn -version  # 验证安装
   ```

3. **安装 MySQL 8.0+**
   ```bash
   # 安装 MySQL
   # 创建数据库
   mysql -u root -p
   CREATE DATABASE `sweet-circle` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

4. **安装 Redis**
   ```bash
   # Linux
   sudo apt-get install redis-server
   
   # Windows
   # 下载 Redis for Windows
   
   # 验证
   redis-cli ping  # 应返回 PONG
   ```

5. **安装 Nacos**
   ```bash
   # 下载 Nacos
   wget https://github.com/alibaba/nacos/releases/download/2.x.x/nacos-server-2.x.x.tar.gz
   
   # 解压并启动
   tar -xzf nacos-server-2.x.x.tar.gz
   cd nacos/bin
   sh startup.sh -m standalone  # 单机模式
   ```

#### 步骤2：初始化数据库

```bash
# 导入 SQL 脚本
mysql -u root -p sweet-circle < sql/sweet-circle.sql
```

#### 步骤3：配置 Nacos

1. 访问 Nacos 控制台：`http://localhost:8848/nacos`
  - 默认用户名：`nacos`
  - 默认密码：`nacos`

2. 导入配置文件
  - 解压 `nacos_config.zip`
  - 在 Nacos 控制台创建配置
  - 或手动创建以下配置文件：
    - `application-dev.yml`（公共配置）
    - `anan-auth-dev.yml`（认证服务配置）
    - `anan-system-dev.yml`（系统服务配置）
    - `anan-file-dev.yml`（文件服务配置）

3. 修改配置项
   ```yaml
   # 数据库配置
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/sweet-circle?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
       username: root
       password: your_password
   
   # Redis配置
   spring:
     data:
       redis:
         host: localhost
         port: 6379
         password: your_redis_password
   
   # Nacos配置
   spring:
     cloud:
       nacos:
         discovery:
           server-addr: 127.0.0.1:8848
         config:
           server-addr: 127.0.0.1:8848
   ```

#### 步骤4：编译项目

```bash
# 进入项目根目录
cd sweet-circle

# 编译打包（跳过测试）
mvn clean package -DskipTests

# 或只编译不打包
mvn clean install -DskipTests
```

#### 步骤5：启动服务

**启动顺序**（重要）：

1. **启动 Nacos**（如果尚未启动）
   ```bash
   cd nacos/bin
   sh startup.sh -m standalone
   ```

2. **启动 Redis**（如果尚未启动）
   ```bash
   redis-server
   ```

3. **启动 anan-gateway（网关）**
   ```bash
   cd anan-gateway/target
   java -jar anan-gateway.jar
   ```

4. **启动 anan-auth（认证服务）**
   ```bash
   cd anan-auth/target
   java -jar anan-auth.jar
   ```

5. **启动 anan-system（系统服务）**
   ```bash
   cd anan-modules/anan-system/target
   java -jar anan-system.jar
   ```

6. **启动 anan-file（文件服务）**
   ```bash
   cd anan-modules/anan-file/target
   java -jar anan-file.jar
   ```

#### 步骤6：验证服务

1. **检查 Nacos 服务列表**
  - 访问：`http://localhost:8848/nacos`
  - 查看服务列表中是否有以下服务：
    - anan-gateway
    - anan-auth
    - anan-system
    - anan-file

2. **测试登录接口**
   ```bash
   curl -X POST http://localhost:9205/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "username": "100000",
       "password": "your_password",
       "captchaCode": "xxxx",
       "captchaKey": "xxxx"
     }'
   ```

3. **访问 Swagger 文档**
  - 认证服务：`http://localhost:9205/swagger-ui.html`
  - 系统服务：`http://localhost:{port}/swagger-ui.html`
  - 文件服务：`http://localhost:{port}/swagger-ui.html`

### 7.3 Docker 部署（可选）

#### 7.3.1 创建 Dockerfile

以 anan-auth 为例：

```dockerfile
FROM openjdk:21-jdk-slim

WORKDIR /app

COPY target/anan-auth.jar app.jar

EXPOSE 9205

ENTRYPOINT ["java", "-jar", "app.jar"]
```

#### 7.3.2 构建镜像

```bash
docker build -t anan-auth:1.0.0 .
```

#### 7.3.3 运行容器

```bash
docker run -d \
  --name anan-auth \
  -p 9205:9205 \
  -e SPRING_PROFILES_ACTIVE=dev \
  anan-auth:1.0.0
```

### 7.4 生产环境建议

1. **数据库优化**
  - 启用慢查询日志
  - 定期备份数据库
  - 配置主从复制

2. **Redis 优化**
  - 配置持久化（RDB + AOF）
  - 设置内存淘汰策略
  - 启用集群模式（高可用）

3. **Nacos 优化**
  - 使用集群模式部署
  - 配置 Derby 或 MySQL 持久化

4. **JVM 调优**
   ```bash
   java -jar \
     -Xms2g \
     -Xmx2g \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     app.jar
   ```

5. **日志管理**
  - 配置日志滚动策略
  - 集成 ELK 日志系统
  - 定期清理旧日志

6. **监控告警**
  - 集成 Spring Boot Actuator
  - 使用 Prometheus + Grafana 监控
  - 配置告警规则

---

## 八、开发指南

### 8.1 项目结构

```
sweet-circle/
├── anan-gateway/              # 网关模块
│   ├── src/main/java/
│   │   └── com/anan/gateway/
│   │       ├── AnanGatewayApplication.java  # 启动类
│   │       ├── config/          # 配置类
│   │       ├── filter/          # 过滤器
│   │       └── handler/         # 处理器
│   └── src/main/resources/
│       ├── bootstrap.yml        # Nacos配置
│       └── application.yml      # 应用配置
│
├── anan-auth/                   # 认证模块
│   ├── src/main/java/
│   │   └── com/anan/auth/
│   │       ├── AnanAuthApplication.java
│   │       ├── controller/      # 控制器
│   │       ├── service/         # 服务层
│   │       ├── domain/          # 领域模型
│   │       └── utils/           # 工具类
│   └── src/main/resources/
│
├── anan-modules/                # 业务模块
│   ├── anan-system/             # 系统服务
│   │   ├── controller/
│   │   ├── service/
│   │   ├── mapper/              # MyBatis Mapper
│   │   └── domain/
│   ├── anan-file/               # 文件服务
│   │   ├── controller/
│   │   ├── service/
│   │   └── config/
│   └── anan-config/             # 配置服务
│
├── anan-common/                 # 公共模块
│   ├── anan-common-core/        # 核心工具
│   ├── anan-common-redis/       # Redis服务
│   ├── anan-common-security/    # 安全认证
│   ├── anan-common-sensitive/   # 数据脱敏
│   ├── anan-common-swagger/     # API文档
│   └── anan-common-netty/       # WebSocket
│
└── sql/                         # 数据库脚本
    └── sweet-circle.sql
```

### 8.2 代码规范

#### 8.2.1 包命名规范

```
com.anan.{模块名}.{层级}
例如：
com.anan.auth.controller
com.anan.system.service
com.anan.file.config
```

#### 8.2.2 类命名规范

- **Controller**：`XxxController`
- **Service**：`XxxService`（接口）、`XxxServiceImpl`（实现）
- **Mapper**：`XxxMapper`
- **Entity**：`Xxx`（与表名对应）
- **DTO**：`XxxDTO`
- **VO**：`XxxVO`
- **Config**：`XxxConfig`
- **Utils**：`XxxUtils`

#### 8.2.3 方法命名规范

- **查询单个**：`getById`, `getByXxx`
- **查询列表**：`list`, `listByXxx`
- **分页查询**：`page`, `pageByXxx`
- **新增**：`add`, `insert`, `save`
- **修改**：`update`, `edit`
- **删除**：`delete`, `remove`
- **统计**：`count`, `countByXxx`

#### 8.2.4 注释规范

**类注释**：
```java
/**
 * 用户服务实现类
 * 
 * @author YourName
 * @since 2024-01-01
 */
public class SysUserServiceImpl implements SysUserService {
}
```

**方法注释**：
```java
/**
 * 根据用户ID查询用户信息
 * 
 * @param userId 用户ID
 * @return 用户信息
 */
public SysUser getById(String userId) {
    // ...
}
```

### 8.3 开发流程

#### 8.3.1 新增功能模块

1. **数据库设计**
  - 在 `sql/sweet-circle.sql` 中添加建表语句
  - 执行 SQL 创建表

2. **创建 Entity**
   ```java
   @Data
   @TableName("table_name")
   public class Xxx {
       @TableId
       private String id;
       // 其他字段
   }
   ```

3. **创建 Mapper**
   ```java
   @Mapper
   public interface XxxMapper extends BaseMapper<Xxx> {
       // 自定义查询方法
   }
   ```

4. **创建 Service**
   ```java
   public interface XxxService {
       // 业务方法
   }
   
   @Service
   public class XxxServiceImpl implements XxxService {
       @Autowired
       private XxxMapper xxxMapper;
       
       // 实现业务方法
   }
   ```

5. **创建 Controller**
   ```java
   @RestController
   @RequestMapping("/xxx")
   public class XxxController {
       @Autowired
       private XxxService xxxService;
       
       @GetMapping("/{id}")
       public R<Xxx> getById(@PathVariable String id) {
           return R.success(xxxService.getById(id));
       }
   }
   ```

6. **编写单元测试**
   ```java
   @SpringBootTest
   public class XxxServiceTest {
       @Autowired
       private XxxService xxxService;
       
       @Test
       public void testGetById() {
           // 测试代码
       }
   }
   ```

#### 8.3.2 统一响应格式

**成功响应**：
```java
return R.success(data);
return R.success("操作成功", data);
```

**失败响应**：
```java
return R.fail(ResponseCodeEnum.PARAM_ERROR);
return R.fail("错误信息");
```

#### 8.3.3 参数校验

**使用注解校验**：
```java
@PostMapping("/add")
public R<Void> add(@Validated @RequestBody XxxDTO dto) {
    // DTO中使用校验注解
    // @NotBlank, @NotNull, @Email, @Pattern 等
}
```

**自定义校验注解**：
```java
@CheckValue
@FieldNote("参数说明")
@RequestParam("param") String param
```

#### 8.3.4 异常处理

**抛出业务异常**：
```java
if (user == null) {
    throw new ServiceException("用户不存在");
}
```

**全局异常捕获**：
由 `GlobalExceptionHandler` 统一处理，无需手动捕获

### 8.4 常用工具类

#### 8.4.1 字符串工具 (StringUtils)

```java
// 判断是否为空
StringUtils.isEmpty(str);
StringUtils.isNotEmpty(str);

// 截取字符串
StringUtils.substring(str, 0, 10);

// 格式化
StringUtils.format("Hello {}", "World");
```

#### 8.4.2 日期工具 (DateUtils)

```java
// 获取当前时间戳
long timestamp = DateUtils.getCurrentTimestamp();

// 时间戳转日期
Date date = DateUtils.timestampToDate(timestamp);

// 日期格式化
String dateStr = DateUtils.format(date, "yyyy-MM-dd HH:mm:ss");
```

#### 8.4.3 Redis 工具 (RedisService)

```java
@Autowired
private RedisService redisService;

// 设置缓存
redisService.setCacheObject("key", value, 10, TimeUnit.MINUTES);

// 获取缓存
Object value = redisService.getCacheObject("key");

// 删除缓存
redisService.deleteObject("key");

// 分布式锁
RedisLock lock = new RedisLock(redisService, "lock_key");
lock.lock();
try {
    // 业务逻辑
} finally {
    lock.unlock();
}
```

#### 8.4.4 Token 工具 (TokenService)

```java
@Autowired
private TokenService tokenService;

// 从请求中获取用户ID
String userId = tokenService.getUserId(request);

// 验证 Token
LoginUser loginUser = tokenService.getLoginUser(request);
```

### 8.5 调试技巧

#### 8.5.1 日志级别配置

```yaml
# application.yml
logging:
  level:
    com.anan: DEBUG
    org.springframework: INFO
```

#### 8.5.2 远程调试

```bash
java -jar -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 app.jar
```

在 IDEA 中配置 Remote JVM Debug，连接到 5005 端口

#### 8.5.3 性能分析

- 使用 Arthas 进行线上诊断
- 使用 JProfiler 进行性能分析
- 使用 VisualVM 监控 JVM

### 8.6 Git 工作流

```bash
# 1. 创建功能分支
git checkout -b feature/xxx

# 2. 开发并提交
git add .
git commit -m "feat: 添加xxx功能"

# 3. 推送到远程
git push origin feature/xxx

# 4. 创建 Pull Request

# 5. 合并后删除分支
git branch -d feature/xxx
```

**Commit 规范**：
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档变更
- `style`: 代码格式（不影响功能）
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具变动

---

## 九、常见问题

### 9.1 启动问题

#### Q1: 服务启动失败，提示无法连接 Nacos

**解决方案**：
1. 检查 Nacos 是否启动：`http://localhost:8848/nacos`
2. 检查 `bootstrap.yml` 中的 Nacos 地址配置
3. 检查防火墙是否阻止了 8848 端口

#### Q2: 服务启动失败，提示无法连接 MySQL

**解决方案**：
1. 检查 MySQL 是否启动
2. 检查数据库连接配置（URL、用户名、密码）
3. 确认数据库 `sweet-circle` 已创建
4. 检查 MySQL 驱动版本是否兼容

#### Q3: 服务启动失败，提示无法连接 Redis

**解决方案**：
1. 检查 Redis 是否启动：`redis-cli ping`
2. 检查 Redis 连接配置（host、port、password）
3. 检查 Redis 版本是否 >= 3.2

### 9.2 运行时问题

#### Q4: 登录时提示验证码错误

**解决方案**：
1. 检查 Redis 是否正常（验证码存储在 Redis 中）
2. 检查验证码是否过期（默认 5 分钟）
3. 清除浏览器缓存后重试

#### Q5: WebSocket 连接失败

**解决方案**：
1. 检查 Token 是否有效
2. 检查 WebSocket 端口是否开放
3. 检查防火墙和安全组配置
4. 查看服务端日志排查具体错误

#### Q6: 文件上传失败

**解决方案**：
1. 检查文件大小是否超过限制
2. 检查文件类型是否允许
3. 检查存储空间是否充足
4. 检查存储配置（本地路径/MinIO/OSS）

### 9.3 性能问题

#### Q7: 消息发送延迟高

**解决方案**：
1. 检查网络状况
2. 检查数据库性能（添加索引、优化查询）
3. 检查 Redis 性能
4. 增加 WebSocket 连接池大小
5. 考虑使用消息队列（RabbitMQ/Kafka）异步处理

#### Q8: 内存占用过高

**解决方案**：
1. 调整 JVM 参数（-Xms, -Xmx）
2. 检查是否有内存泄漏
3. 优化代码，减少对象创建
4. 定期清理离线消息
5. 使用 GC 日志分析工具

### 9.4 其他问题

#### Q9: 如何修改默认端口？

**解决方案**：
在对应的 `bootstrap.yml` 或 `application.yml` 中修改：
```yaml
server:
  port: 新端口号
```

#### Q10: 如何切换文件存储方式？

**解决方案**：
在 Nacos 配置中心修改文件服务配置：
```yaml
file:
  storage-type: local  # local/minio/oss
```

#### Q11: 如何添加新的微服务？

**解决方案**：
1. 在父 POM 的 `<modules>` 中添加新模块
2. 创建新模块，继承父 POM
3. 添加必要的依赖
4. 创建启动类和配置文件
5. 在 Nacos 中注册服务

---

## 十、附录

### 10.1 测试账号

| 账号 | 密码 | 说明 |
|-----|------|------|
| 100000 | (加密存储) | 开发员 |
| 100001 | (加密存储) | 测试 |
| 100002 | (加密存储) | 晚风叙旧 |

> 注意：密码经过 BCrypt 加密，实际使用时需要通过注册接口创建新用户

### 10.2 相关资源

- **项目地址**：[Gitee Repository](https://gitee.com/your-repo/sweet-circle)
- **Nacos 官网**：https://nacos.io/
- **Spring Cloud Alibaba**：https://spring-cloud-alibaba-group.github.io/
- **MyBatis-Plus**：https://baomidou.com/
- **Netty**：https://netty.io/

### 10.3 版本历史

#### v1.0.0 (2024-XX-XX)
- ✨ 初始版本发布
- ✅ 实现用户注册登录
- ✅ 实现好友管理
- ✅ 实现单聊功能
- ✅ 实现文件上传
- ✅ 集成 WebSocket 实时通讯

### 10.4 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 10.5 联系方式

- **Issues**: [Gitee Issues](https://gitee.com/your-repo/sweet-circle/issues)
- **Email**: your-email@example.com

### 10.6 许可证

本项目遵循相应的开源许可证，详见 [LICENSE](LICENSE) 文件。

---

**文档版本**: v1.0.0  
**最后更新**: 2024-XX-XX  
**维护者**: Sweet-Circle Team