docs: Refresh deployment and API documentation

- Align deployment guidance with the current three-node Compose topology - Document the current frontend architecture and development workflow - Replace the stale API list with a controller-based route index
2026-08-18 23:37:49 +08:00
parent 23c2912ea8
commit 30c17f01e9
12 changed files with 286 additions and 4126 deletions
@@ -1,751 +1,20 @@
-# video-user模块目录架构、功能及接口文档
+# video-user 模块

-## 一、目录架构
+用户服务端口为 `9002`，负责平台用户域，不负责登录凭据签发。

-```
-video-user/
-├── src/
-│   ├── main/
-│   │   ├── java/
-│   │   │   └── com/nuaa/video/user/
-│   │   │       ├── config/              # 配置类
-│   │   │       │   ├── FeignConfig.java		# Feign配置类
-│   │   │       │   ├── MinioConfig.java        # Minio配置类
-│   │   │       │   └── SecurityConfig.java     # 安全配置类 
-│   │   │       ├── controller/          # 控制器
-│   │   │       │   ├── UserProfileController.java    # 用户资料控制器
-│   │   │       │   ├── UserFollowController.java     # 用户关注控制器
-│   │   │       │   ├── UserMessageController.java    # 用户私信控制器
-│   │   │       │   ├── UserNotificationController.java # 用户通知控制器
-│   │   │       │   └── UserSettingController.java    # 用户设置控制器
-│   │   │       ├── dto/                 # 数据传输对象
-│   │   │       │   ├── UserProfileDTO.java      # 用户资料DTO
-│   │   │       │   ├── UserMessageDTO.java      # 用户私信DTO
-│   │   │       │   └── UserSettingDTO.java      # 用户设置DTO
-│   │   │       ├── entity/              # 实体类
-│   │   │       │   ├── UserInfo.java           # 用户信息实体
-│   │   │       │   ├── UserFollow.java         # 用户关注实体
-│   │   │       │   ├── UserStatDaily.java      # 用户每日统计实体
-│   │   │       │   ├── UserMessage.java        # 用户私信实体
-│   │   │       │   ├── UserNotification.java   # 用户通知实体
-│   │   │       │   └── UserSetting.java        # 用户设置实体
-│   │   │       ├── feign/               # Feign客户端
-│   │   │       │   └── AuthFeignClient.java    # 认证服务Feign客户端
-│   │   │       ├── filter/              # 过滤器
-│   │   │       │   └── JwtAuthenticationFilter.java # JWT认证过滤器
-│   │   │       ├── mapper/              # MyBatis映射接口
-│   │   │       │   ├── UserInfoMapper.java       # 用户信息Mapper
-│   │   │       │   ├── UserFollowMapper.java     # 用户关注Mapper
-│   │   │       │   ├── UserStatDailyMapper.java  # 用户每日统计Mapper
-│   │   │       │   ├── UserMessageMapper.java    # 用户私信Mapper
-│   │   │       │   ├── UserNotificationMapper.java # 用户通知Mapper
-│   │   │       │   └── UserSettingMapper.java    # 用户设置Mapper
-│   │   │       ├── service/             # 服务层
-│   │   │       │   ├── UserInfoService.java      # 用户信息服务接口
-│   │   │       │   ├── UserFollowService.java    # 用户关注服务接口
-│   │   │       │   ├── UserMessageService.java   # 用户私信服务接口
-│   │   │       │   ├── UserNotificationService.java # 用户通知服务接口
-│   │   │       │   ├── UserSettingService.java   # 用户设置服务接口
-│   │   │       │   └── impl/                     # 实现类
-│   │   │       │       ├── UserInfoServiceImpl.java
-│   │   │       │       ├── UserFollowServiceImpl.java
-│   │   │       │       ├── UserMessageServiceImpl.java
-│   │   │       │       ├── UserNotificationServiceImpl.java
-│   │   │       │       └── UserSettingServiceImpl.java
-│   │   │       ├── vo/                  # 视图对象
-│   │   │       │   ├── UserProfileVO.java       # 用户资料VO
-│   │   │       │   ├── UserMessageVO.java       # 用户私信VO
-│   │   │       │   └── UserNotificationVO.java  # 用户通知VO
-│   │   │       └── UserApplication.java   # 启动类
-│   │   └── resources/
-│   │       ├── mapper/                  # MyBatis XML映射文件
-│   │       │   ├── UserInfoMapper.xml
-│   │       │   ├── UserFollowMapper.xml
-│   │       │   ├── UserMessageMapper.xml
-│   │       │   └── UserNotificationMapper.xml
-│   │       ├── application.yml          # 主配置文件
-│   │       └── application-dev.yml      # 开发环境配置
-└── pom.xml
-```
+## 当前功能与 Controller

-## 二、功能概述
+| Controller | 前缀 | 功能 |
+| --- | --- | --- |
+| `UserProfileController` | `/user/profile` | 用户资料、头像上传、公开主页、用户搜索、计数维护 |
+| `UserFollowController` | `/user/follow` | 关注、取消关注、关注/粉丝列表与状态查询 |
+| `UserMessageController` | `/user/message` | 私信会话、明细、已读和未读数 |
+| `UserNotificationController` | `/user/notification` | 站内通知与已读状态 |
+| `UserSettingController` | `/user/setting` | 个人设置 |
+| `AdminUserController` | `/user/profile/admin` | 管理端用户查询、状态和统计 |

-### 1. 核心功能
+## 实现要点

- **用户资料管理**：创建、查询、更新用户资料，上传头像
- **用户关系管理**：关注/取消关注用户，查看关注列表和粉丝列表
- **私信系统**：发送和接收私信，管理会话和消息状态
- **通知系统**：管理用户收到的系统通知和用户互动通知
- **用户设置**：管理用户隐私和通知偏好设置
- **用户数据统计**：收集和查询用户活动统计信息
-
-### 2. 业务流程
-
-1. **用户资料流程**：
-   - 用户注册时，auth服务创建基本认证信息
-   - auth服务通过Feign调用user服务创建用户资料
-   - 用户可随时更新个人资料信息
-
-2. **用户关系流程**：
-   - 用户关注他人，增加自己的关注数和对方的粉丝数
-   - 系统为被关注用户创建通知
-   - 用户可查看关注列表和粉丝列表
-
-3. **私信流程**：
-   - 用户发送私信给其他用户
-   - 接收用户收到未读消息通知
-   - 用户可查看会话列表和详细私信记录
-
-4. **通知流程**：
-   - 系统根据用户互动(点赞、评论、关注)创建通知
-   - 用户可查看不同类型的通知
-   - 用户可标记通知为已读
-
-## 三、接口文档
-
-### 1. 用户资料接口
-
-#### 1.1 初始化用户资料
-
- **URI**: `/user/profile/init`
- **方法**: POST
- **描述**: 服务内部接口，初始化用户资料(由auth服务在用户注册时调用)
- **请求参数**:
-  - `userId`: 用户ID
-  - `username`: 用户名
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
- **错误码**:
-  - `400`: 参数错误
-  - `500`: 服务器内部错误
-
-#### 1.2 获取当前用户资料
-
- **URI**: `/user/profile/current`
- **方法**: GET
- **描述**: 获取当前登录用户的资料
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "id": 1,
-      "nickname": "用户昵称",
-      "avatar": "头像URL",
-      "gender": 1,
-      "birthday": "1990-01-01",
-      "signature": "个性签名",
-      "region": "地区",
-      "followerCount": 10,
-      "followingCount": 20,
-      "videoCount": 5,
-      "likeCount": 100,
-      "level": 3,
-      "vipLevel": 0,
-      "vipExpireTime": null,
-      "isFollowed": false,
-      "createTime": "2023-01-01T12:00:00"
-    }
-  }
-  ```
-
-#### 1.3 获取指定用户资料
-
- **URI**: `/user/profile/public/{userId}`
- **方法**: GET
- **描述**: 获取指定用户的资料
- **路径参数**:
-  - `userId`: 用户ID
- **响应**: 与获取当前用户资料相同
-
-#### 1.4 更新用户资料
-
- **URI**: `/user/profile`
- **方法**: PUT
- **描述**: 更新当前用户资料
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **请求Body**:
-  ```json
-  {
-    "nickname": "新昵称",
-    "gender": 1,
-    "birthday": "1990-01-01",
-    "signature": "新的个性签名",
-    "region": "新的地区"
-  }
-  ```
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 1.5 上传头像
-
- **URI**: `/user/profile/avatar`
- **方法**: POST
- **描述**: 上传用户头像
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
-  - `Content-Type`: multipart/form-data
- **请求参数**:
-  - `file`: 图片文件
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": "头像URL"
-  }
-  ```
-
-#### 1.6 搜索用户
-
- **URI**: `/user/profile/search`
- **方法**: GET
- **描述**: 按关键词搜索用户
- **请求参数**:
-  - `keyword`: 搜索关键词
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认10)
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "records": [
-        {
-          "id": 1,
-          "nickname": "用户昵称",
-          "avatar": "头像URL",
-          "signature": "个性签名",
-          "followerCount": 10,
-          "followingCount": 20
-        }
-      ],
-      "total": 100,
-      "size": 10,
-      "current": 1,
-      "pages": 10
-    }
-  }
-  ```
-
-### 2. 用户关注接口
-
-#### 2.1 关注用户
-
- **URI**: `/user/follow/{followId}`
- **方法**: POST
- **描述**: 关注指定用户
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `followId`: 要关注的用户ID
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
- **错误码**:
-  - `400`: 参数错误(如已关注)
-  - `404`: 用户不存在
-
-#### 2.2 取消关注
-
- **URI**: `/user/follow/{followId}`
- **方法**: DELETE
- **描述**: 取消关注指定用户
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `followId`: 要取消关注的用户ID
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 2.3 获取关注列表
-
- **URI**: `/user/follow/following/{userId}`
- **方法**: GET
- **描述**: 获取指定用户的关注列表
- **路径参数**:
-  - `userId`: 用户ID
- **请求参数**:
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认10)
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "records": [
-        {
-          "id": 2,
-          "nickname": "被关注用户",
-          "avatar": "头像URL",
-          "signature": "个性签名",
-          "followerCount": 100,
-          "followingCount": 50,
-          "isFollowed": true
-        }
-      ],
-      "total": 20,
-      "size": 10,
-      "current": 1,
-      "pages": 2
-    }
-  }
-  ```
-
-#### 2.4 获取粉丝列表
-
- **URI**: `/user/follow/followers/{userId}`
- **方法**: GET
- **描述**: 获取指定用户的粉丝列表
- **路径参数**:
-  - `userId`: 用户ID
- **请求参数**:
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认10)
- **响应**: 与关注列表格式相同
-
-#### 2.5 检查是否已关注
-
- **URI**: `/user/follow/check/{followId}`
- **方法**: GET
- **描述**: 检查当前用户是否已关注指定用户
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `followId`: 被检查的用户ID
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": true  // 或 false
-  }
-  ```
-
-### 3. 用户私信接口
-
-#### 3.1 发送私信
-
- **URI**: `/user/message`
- **方法**: POST
- **描述**: 发送私信给指定用户
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **请求Body**:
-  ```json
-  {
-    "receiverId": 2,
-    "content": "私信内容"
-  }
-  ```
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 3.2 获取私信会话列表
-
- **URI**: `/user/message/list`
- **方法**: GET
- **描述**: 获取当前用户的私信会话列表
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **请求参数**:
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认10)
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "records": [
-        {
-          "id": 100,
-          "senderId": 2,
-          "senderNickname": "发送者昵称",
-          "senderAvatar": "发送者头像URL",
-          "receiverId": 1,
-          "receiverNickname": "接收者昵称",
-          "receiverAvatar": "接收者头像URL",
-          "content": "最新消息内容",
-          "isRead": 0,
-          "createTime": "2023-05-20T14:30:00"
-        }
-      ],
-      "total": 5,
-      "size": 10,
-      "current": 1,
-      "pages": 1
-    }
-  }
-  ```
-
-#### 3.3 获取私信详情
-
- **URI**: `/user/message/detail/{targetId}`
- **方法**: GET
- **描述**: 获取与指定用户的私信记录
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `targetId`: 目标用户ID
- **请求参数**:
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认20)
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "records": [
-        {
-          "id": 100,
-          "senderId": 1,
-          "senderNickname": "当前用户",
-          "senderAvatar": "头像URL",
-          "receiverId": 2,
-          "receiverNickname": "目标用户",
-          "receiverAvatar": "头像URL",
-          "content": "你好",
-          "isRead": 1,
-          "createTime": "2023-05-20T14:28:00"
-        },
-        {
-          "id": 101,
-          "senderId": 2,
-          "senderNickname": "目标用户",
-          "senderAvatar": "头像URL",
-          "receiverId": 1,
-          "receiverNickname": "当前用户",
-          "receiverAvatar": "头像URL",
-          "content": "你好，很高兴认识你",
-          "isRead": 1,
-          "createTime": "2023-05-20T14:30:00"
-        }
-      ],
-      "total": 2,
-      "size": 20,
-      "current": 1,
-      "pages": 1
-    }
-  }
-  ```
-
-#### 3.4 标记私信为已读
-
- **URI**: `/user/message/read/{senderId}`
- **方法**: PUT
- **描述**: 标记来自指定发送者的所有私信为已读
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `senderId`: 发送者用户ID
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 3.5 获取未读私信数量
-
- **URI**: `/user/message/unread/count`
- **方法**: GET
- **描述**: 获取当前用户的未读私信数量
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": 5
-  }
-  ```
-
-### 4. 用户通知接口
-
-#### 4.1 获取通知列表
-
- **URI**: `/user/notification/list`
- **方法**: GET
- **描述**: 获取用户通知列表
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **请求参数**:
-  - `type`: 通知类型(1:点赞,2:评论,3:关注,4:系统通知，可选)
-  - `page`: 页码(默认1)
-  - `size`: 每页数量(默认10)
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "records": [
-        {
-          "id": 1,
-          "type": 3,
-          "content": "用户小明关注了你",
-          "relatedId": 123,
-          "isRead": 0,
-          "createTime": "2023-05-20T10:00:00"
-        }
-      ],
-      "total": 50,
-      "size": 10,
-      "current": 1,
-      "pages": 5
-    }
-  }
-  ```
-
-#### 4.2 标记所有通知为已读
-
- **URI**: `/user/notification/read`
- **方法**: PUT
- **描述**: 标记当前用户的所有通知为已读
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 4.3 标记指定通知为已读
-
- **URI**: `/user/notification/read/{notificationId}`
- **方法**: PUT
- **描述**: 标记指定通知为已读
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **路径参数**:
-  - `notificationId`: 通知ID
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-#### 4.4 获取未读通知数量
-
- **URI**: `/user/notification/unread/count`
- **方法**: GET
- **描述**: 获取当前用户的未读通知数量
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": 10
-  }
-  ```
-
-### 5. 用户设置接口
-
-#### 5.1 获取用户设置
-
- **URI**: `/user/setting`
- **方法**: GET
- **描述**: 获取当前用户的设置
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": {
-      "privacyLevel": 1,
-      "commentNotify": 1,
-      "likeNotify": 1,
-      "followNotify": 1,
-      "systemNotify": 1
-    }
-  }
-  ```
-
-#### 5.2 更新用户设置
-
- **URI**: `/user/setting`
- **方法**: PUT
- **描述**: 更新当前用户的设置
- **请求头**:
-  - `Authorization`: Bearer {accessToken}
- **请求Body**:
-  ```json
-  {
-    "privacyLevel": 2,
-    "commentNotify": 1,
-    "likeNotify": 0,
-    "followNotify": 1,
-    "systemNotify": 1
-  }
-  ```
- **响应**:
-  ```json
-  {
-    "code": 200,
-    "message": "操作成功",
-    "data": null
-  }
-  ```
-
-## 四、数据库表结构
-
-### 1. user_info (用户信息表)
- `id`: bigint - 用户ID (主键)
- `nickname`: varchar(64) - 昵称
- `avatar`: varchar(256) - 头像URL
- `gender`: tinyint - 性别(0:未知,1:男,2:女)
- `birthday`: date - 生日
- `signature`: varchar(256) - 个性签名
- `region`: varchar(128) - 地区
- `follower_count`: int - 粉丝数
- `following_count`: int - 关注数
- `video_count`: int - 视频数
- `like_count`: int - 获赞数
- `coin_count`: int - 硬币数
- `favorite_count`: int - 收藏数
- `view_count`: bigint - 播放数
- `level`: tinyint - 等级
- `vip_level`: tinyint - VIP等级
- `vip_expire_time`: datetime - VIP到期时间
- `created_by`: varchar(64) - 创建人
- `updated_by`: varchar(64) - 更新人
- `create_time`: datetime - 创建时间
- `update_time`: datetime - 更新时间
-
-### 2. user_follow (用户关注表)
- `id`: bigint - 主键ID
- `user_id`: bigint - 用户ID
- `follow_id`: bigint - 关注用户ID
- `create_time`: datetime - 创建时间
-
-### 3. user_stat_daily (用户每日统计表)
- `id`: bigint - 主键ID
- `user_id`: bigint - 用户ID
- `stat_date`: date - 统计日期
- `follower_increment`: int - 新增粉丝数
- `following_increment`: int - 新增关注数
- `video_increment`: int - 新增视频数
- `like_increment`: int - 新增获赞数
- `coin_increment`: int - 新增硬币数
- `favorite_increment`: int - 新增收藏数
- `view_increment`: bigint - 新增播放数
- `create_time`: datetime - 创建时间
-
-### 4. user_message (用户私信表)
- `id`: bigint - 主键ID
- `sender_id`: bigint - 发送者ID
- `receiver_id`: bigint - 接收者ID
- `content`: text - 消息内容
- `is_read`: tinyint - 是否已读(0:未读,1:已读)
- `create_time`: datetime - 创建时间
-
-### 5. user_notification (用户通知表)
- `id`: bigint - 主键ID
- `user_id`: bigint - 用户ID
- `type`: tinyint - 通知类型(1:点赞,2:评论,3:关注,4:系统通知)
- `content`: text - 通知内容
- `related_id`: bigint - 相关ID
- `is_read`: tinyint - 是否已读(0:未读,1:已读)
- `create_time`: datetime - 创建时间
-
-### 6. user_setting (用户设置表)
- `id`: bigint - 主键ID
- `user_id`: bigint - 用户ID
- `privacy_level`: tinyint - 隐私等级(1:公开,2:仅关注,3:私密)
- `comment_notify`: tinyint - 评论通知(0:关闭,1:开启)
- `like_notify`: tinyint - 点赞通知(0:关闭,1:开启)
- `follow_notify`: tinyint - 关注通知(0:关闭,1:开启)
- `system_notify`: tinyint - 系统通知(0:关闭,1:开启)
- `created_by`: varchar(64) - 创建人
- `updated_by`: varchar(64) - 更新人
- `create_time`: datetime - 创建时间
- `update_time`: datetime - 更新时间
-
-## 五、调用示例
-
-### 1. 获取用户资料
-
-```bash
-# 使用cURL
-curl -X GET http://localhost:9002/user/profile/current \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
-
-# 使用JavaScript
-fetch('http://localhost:9002/user/profile/current', {
-  headers: {
-    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...'
-  }
-})
-.then(response => response.json())
-.then(data => console.log(data));
-```
-
-### 2. 关注用户
-
-```bash
-# 使用cURL
-curl -X POST http://localhost:9002/user/follow/2 \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
-
-# 使用JavaScript
-fetch('http://localhost:9002/user/follow/2', {
-  method: 'POST',
-  headers: {
-    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...'
-  }
-})
-.then(response => response.json())
-.then(data => console.log(data));
-```
-
-video-user模块是整个视频平台的核心组成部分，它提供了完整的用户信息管理、社交互动和消息通知功能，为用户提供良好的社交体验。
+- 使用 MyBatis-Plus、MySQL 与 Redis；头像通过共享 MinIO 工具上传。
+- 头像请求限制定义在 `application.yml`：默认单文件/请求 10 MB，业务头像大小默认 5 MB，可由环境变量覆盖。
+- 服务通过 Feign 与认证、内容等服务协作。前端经网关访问，不使用文档中的旧 `localhost:9002` 直连示例。