二哥项目资料
首页/派聪明 RAG 星球/正文

✅派聪明用户管理模块设计方案

正文 28,792 字 #10 原文

星球：Java进阶之路&二哥编程星球 ｜ 专栏：派聪明RAG知识库 ｜ 作者：沉默王二 ｜ 发布：2025-09-29

✅派聪明用户管理模块设计方案

✅派聪明用户管理模块设计方案

用户管理模块 负责处理用户的 注册、登录和权限控制 功能。该模块的核心目标是：

确保用户身份的安全性。

提供灵活的权限管理机制，支持基于角色的访问控制，通过 RBAC 实现对不同角色（如普通用户和管理员）的功能权限区分，通过组织标签实现数据访问权限隔离。

为其他模块提供用户信息支持。

一、功能需求

图片.png

二、技术选型

图片.png

三、关键流程

01、用户注册流程

接收用户注册请求，验证用户名和密码；

检查用户名是否已存在；

使用 BCrypt 加密密码；

创建用户记录，设置默认角色为USER;

创建用户私人组织标签（PRIVATE_username）；

将私人组织标签设置为用户的主组织标签；返回注册成功响应。

图片.png

02、用户登录流程

接收用户登录请求，获取用户名和密码；

查询用户记录并验证密码；加载用户组织标签信息；

生成包含用户信息和组织标签的 JWT Token；

返回登录成功响应和 Token。

图片.png

03、组织标签管理流程

管理员创建组织标签，设置标签名称和描述；

可选择设置父级组织标签（支持简单层级）；

管理员为用户分配组织标签；

系统自动保留用户的私人组织标签，确保其不被移除；

用户查看自己的组织标签。

04、权限验证流程

解析请求头中的 JWT Token，验证有效性；

提取用户 ID、角色和组织标签信息；

对功能权限请求，根据用户角色判断是否允许访问；

对数据权限请求，根据用户组织标签判断是否可以访问特定资源；

允许或拒绝请求访问；权限验证流程具体讲解见： ✅如何基于Spring Security实现RBAC？

图片.png

四、接口设计 01、用户注册接口

URL: /api/v1/users/register

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",   // 用户名，唯一
  "password": "string"    // 密码（明文传输，后端加密存储）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "User registered successfully"
}

{
  "code": 400, // 失败
  "message": "Username already exists"
}

02、用户登录接口

URL: /api/v1/users/login

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",
  "password": "string"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Login successful",
  "data": {
    "token": "JWT_TOKEN_STRING"
  }
}

{
  "code": 401, // 失败
  "message": "Invalid username or password"
}

03、获取用户信息接口

URL: /api/v1/users/me

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "id": 1,
    "username": "example_user",
    "role": "USER",
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user"
  }
}

{
  "code": 401, // 失败
  "message": "Unauthorized"
}

04、用户列表查询接口

URL: /api/v1/admin/users/list

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Query Parameters:

page: 页码（从1开始，默认1）

size: 每页条数（默认20）

keyword: 搜索关键词（可选）

orgTag: 按组织标签筛选（可选）

status: 用户状态（可选，0=禁用，1=启用

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get users successful",
  "data": {
    "content": [
      {
        "userId": "user1",
        "username": "用户1",
        "email": "user1@example.com",
        "status": 1,
        "orgTags": ["dept1", "team2"],
        "primaryOrg": "dept1",
        "createTime": "2023-01-01T12:00:00Z",
        "lastLoginTime": "2023-06-15T08:30:00Z"
      },
      // 更多用户...
    ],
    "totalElements": 150,
    "totalPages": 8,
    "size": 20,
    "number": 0
  }
}

05、组织标签管理接口

5.1 创建组织标签（管理员）

URL: /api/v1/admin/org-tags

Method: POST

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "tagId": "string",     // 标签ID，唯一
  "name": "string",      // 标签名称
  "description": "string", // 标签描述
  "parentTag": "string"  // 父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag created successfully"
}

5.2 为用户分配组织标签（admin）

URL: /api/v1/admin/users/{userId}/org-tags

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "orgTags": ["tag1", "tag2"]
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, //   成功：
  "message": "Organization tags assigned successfully"
}

5.3 设置用户主组织

URL: /api/v1/users/primary-org

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "primaryOrg": "tag1",
  "userId":"xxx"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Primary organization set successfully"
}

5.4 获取用户组织标签详情

URL: /api/v1/users/org-tags

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get user organization tags successful",
  "data": {
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user",
    "orgTagDetails": [
      {
        "tagId": "PRIVATE_example_user",
        "name": "example_user的私人空间",
        "description": "用户的私人组织标签，仅用户本人可访问"
      },
      {
        "tagId": "dept1",
        "name": "部门1",
        "description": "部门1的组织标签"
      },
      {
        "tagId": "team2",
        "name": "团队2",
        "description": "团队2的组织标签"
      }
    ]
  }
}

5.5 组织标签树查询接口 (admin)

URL: /api/v1/admin/org-tags/tree

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get organization tag tree successful",
  "data": [
    {
      "tagId": "dept1",
      "name": "部门1",
      "description": "部门1描述",
      "children": [
        {
          "tagId": "team1",
          "name": "团队1",
          "description": "团队1描述",
          "children": []
        },
        {
          "tagId": "team2",
          "name": "团队2",
          "description": "团队2描述",
          "children": []
        }
      ]
    },
    {
      "tagId": "dept2",
      "name": "部门2",
      "description": "部门2描述",
      "children": []
    }
  ]
}

5.6 更新组织标签接口(admin)

URL: /api/v1/admin/org-tags/{tagId}

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "name": "string",       // 新标签名称
  "description": "string", // 新标签描述
  "parentTag": "string"    // 新父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Organization tag updated successfully"
}

5.7 删除组织标签接口

URL: /api/v1/admin/org-tags/{tagId}

Method: DELETE

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag deleted successfully"
}
{
  "code": 409, // 错误（标签已被使用）：
  "message": "Cannot delete tag as it is associated with users or documents"
}

五、库表设计 01、用户表 (users)

字段名

数据类型

是否主键

描述

id

BIGINT

是

用户唯一标识

username

VARCHAR(255)

否

用户名，唯一

password

VARCHAR(255)

否

加密后的密码

role

ENUM('USER', 'ADMIN')

否

用户角色

org_tags

VARCHAR(255)

否

用户所属组织标签，多个用逗号分隔

primary_org

VARCHAR(50)

否

用户主组织标签

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '用户唯一标识',
    username VARCHAR(255) NOT NULL UNIQUE COMMENT '用户名，唯一',
    password VARCHAR(255) NOT NULL COMMENT '加密后的密码',
    role ENUM('USER', 'ADMIN') NOT NULL DEFAULT 'USER' COMMENT '用户角色',
    org_tags VARCHAR(255) DEFAULT NULL COMMENT '用户所属组织标签，多个用逗号分隔',
    primary_org VARCHAR(50) DEFAULT NULL COMMENT '用户主组织标签',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    INDEX idx_username (username) COMMENT '用户名索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

02、组织标签表

字段名

数据类型

是否主键

描述

tag_id

VARCHAR(50)

是

标签唯一标识

name

VARCHAR(100)

否

标签名称

description

TEXT

否

描述

parent_tag

VARCHAR(50)

否

父标签ID

created_by

BIGINT

否

创建者ID

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE organization_tags (
    tag_id VARCHAR(50) PRIMARY KEY COMMENT '标签唯一标识',
    name VARCHAR(100) NOT NULL COMMENT '标签名称',
    description TEXT COMMENT '描述',
    parent_tag VARCHAR(50) DEFAULT NULL COMMENT '父标签ID',
    created_by BIGINT NOT NULL COMMENT '创建者ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (parent_tag) REFERENCES organization_tags(tag_id) ON DELETE SET NULL,
    FOREIGN KEY (created_by) REFERENCES users(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织标签表';

用户管理模块 负责处理用户的 注册、登录和权限控制 功能。该模块的核心目标是：

确保用户身份的安全性。

提供灵活的权限管理机制，支持基于角色的访问控制，通过 RBAC 实现对不同角色（如普通用户和管理员）的功能权限区分，通过组织标签实现数据访问权限隔离。

为其他模块提供用户信息支持。

一、功能需求

图片.png

二、技术选型

图片.png

三、关键流程

01、用户注册流程

接收用户注册请求，验证用户名和密码；

检查用户名是否已存在；

使用 BCrypt 加密密码；

创建用户记录，设置默认角色为USER;

创建用户私人组织标签（PRIVATE_username）；

将私人组织标签设置为用户的主组织标签；返回注册成功响应。

图片.png

02、用户登录流程

接收用户登录请求，获取用户名和密码；

查询用户记录并验证密码；加载用户组织标签信息；

生成包含用户信息和组织标签的 JWT Token；

返回登录成功响应和 Token。

图片.png

03、组织标签管理流程

管理员创建组织标签，设置标签名称和描述；

可选择设置父级组织标签（支持简单层级）；

管理员为用户分配组织标签；

系统自动保留用户的私人组织标签，确保其不被移除；

用户查看自己的组织标签。

04、权限验证流程

解析请求头中的 JWT Token，验证有效性；

提取用户 ID、角色和组织标签信息；

对功能权限请求，根据用户角色判断是否允许访问；

对数据权限请求，根据用户组织标签判断是否可以访问特定资源；

允许或拒绝请求访问；权限验证流程具体讲解见： ✅如何基于Spring Security实现RBAC？

图片.png

四、接口设计 01、用户注册接口

URL: /api/v1/users/register

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",   // 用户名，唯一
  "password": "string"    // 密码（明文传输，后端加密存储）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "User registered successfully"
}

{
  "code": 400, // 失败
  "message": "Username already exists"
}

02、用户登录接口

URL: /api/v1/users/login

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",
  "password": "string"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Login successful",
  "data": {
    "token": "JWT_TOKEN_STRING"
  }
}

{
  "code": 401, // 失败
  "message": "Invalid username or password"
}

03、获取用户信息接口

URL: /api/v1/users/me

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "id": 1,
    "username": "example_user",
    "role": "USER",
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user"
  }
}

{
  "code": 401, // 失败
  "message": "Unauthorized"
}

04、用户列表查询接口

URL: /api/v1/admin/users/list

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Query Parameters:

page: 页码（从1开始，默认1）

size: 每页条数（默认20）

keyword: 搜索关键词（可选）

orgTag: 按组织标签筛选（可选）

status: 用户状态（可选，0=禁用，1=启用

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get users successful",
  "data": {
    "content": [
      {
        "userId": "user1",
        "username": "用户1",
        "email": "user1@example.com",
        "status": 1,
        "orgTags": ["dept1", "team2"],
        "primaryOrg": "dept1",
        "createTime": "2023-01-01T12:00:00Z",
        "lastLoginTime": "2023-06-15T08:30:00Z"
      },
      // 更多用户...
    ],
    "totalElements": 150,
    "totalPages": 8,
    "size": 20,
    "number": 0
  }
}

05、组织标签管理接口

5.1 创建组织标签（管理员）

URL: /api/v1/admin/org-tags

Method: POST

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "tagId": "string",     // 标签ID，唯一
  "name": "string",      // 标签名称
  "description": "string", // 标签描述
  "parentTag": "string"  // 父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag created successfully"
}

5.2 为用户分配组织标签（admin）

URL: /api/v1/admin/users/{userId}/org-tags

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "orgTags": ["tag1", "tag2"]
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, //   成功：
  "message": "Organization tags assigned successfully"
}

5.3 设置用户主组织

URL: /api/v1/users/primary-org

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "primaryOrg": "tag1",
  "userId":"xxx"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Primary organization set successfully"
}

5.4 获取用户组织标签详情

URL: /api/v1/users/org-tags

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get user organization tags successful",
  "data": {
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user",
    "orgTagDetails": [
      {
        "tagId": "PRIVATE_example_user",
        "name": "example_user的私人空间",
        "description": "用户的私人组织标签，仅用户本人可访问"
      },
      {
        "tagId": "dept1",
        "name": "部门1",
        "description": "部门1的组织标签"
      },
      {
        "tagId": "team2",
        "name": "团队2",
        "description": "团队2的组织标签"
      }
    ]
  }
}

5.5 组织标签树查询接口 (admin)

URL: /api/v1/admin/org-tags/tree

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get organization tag tree successful",
  "data": [
    {
      "tagId": "dept1",
      "name": "部门1",
      "description": "部门1描述",
      "children": [
        {
          "tagId": "team1",
          "name": "团队1",
          "description": "团队1描述",
          "children": []
        },
        {
          "tagId": "team2",
          "name": "团队2",
          "description": "团队2描述",
          "children": []
        }
      ]
    },
    {
      "tagId": "dept2",
      "name": "部门2",
      "description": "部门2描述",
      "children": []
    }
  ]
}

5.6 更新组织标签接口(admin)

URL: /api/v1/admin/org-tags/{tagId}

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "name": "string",       // 新标签名称
  "description": "string", // 新标签描述
  "parentTag": "string"    // 新父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Organization tag updated successfully"
}

5.7 删除组织标签接口

URL: /api/v1/admin/org-tags/{tagId}

Method: DELETE

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag deleted successfully"
}
{
  "code": 409, // 错误（标签已被使用）：
  "message": "Cannot delete tag as it is associated with users or documents"
}

五、库表设计 01、用户表 (users)

字段名

数据类型

是否主键

描述

id

BIGINT

是

用户唯一标识

username

VARCHAR(255)

否

用户名，唯一

password

VARCHAR(255)

否

加密后的密码

role

ENUM('USER', 'ADMIN')

否

用户角色

org_tags

VARCHAR(255)

否

用户所属组织标签，多个用逗号分隔

primary_org

VARCHAR(50)

否

用户主组织标签

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '用户唯一标识',
    username VARCHAR(255) NOT NULL UNIQUE COMMENT '用户名，唯一',
    password VARCHAR(255) NOT NULL COMMENT '加密后的密码',
    role ENUM('USER', 'ADMIN') NOT NULL DEFAULT 'USER' COMMENT '用户角色',
    org_tags VARCHAR(255) DEFAULT NULL COMMENT '用户所属组织标签，多个用逗号分隔',
    primary_org VARCHAR(50) DEFAULT NULL COMMENT '用户主组织标签',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    INDEX idx_username (username) COMMENT '用户名索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

02、组织标签表

字段名

数据类型

是否主键

描述

tag_id

VARCHAR(50)

是

标签唯一标识

name

VARCHAR(100)

否

标签名称

description

TEXT

否

描述

parent_tag

VARCHAR(50)

否

父标签ID

created_by

BIGINT

否

创建者ID

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE organization_tags (
    tag_id VARCHAR(50) PRIMARY KEY COMMENT '标签唯一标识',
    name VARCHAR(100) NOT NULL COMMENT '标签名称',
    description TEXT COMMENT '描述',
    parent_tag VARCHAR(50) DEFAULT NULL COMMENT '父标签ID',
    created_by BIGINT NOT NULL COMMENT '创建者ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (parent_tag) REFERENCES organization_tags(tag_id) ON DELETE SET NULL,
    FOREIGN KEY (created_by) REFERENCES users(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织标签表';

用户管理模块 负责处理用户的 注册、登录和权限控制 功能。该模块的核心目标是：

确保用户身份的安全性。

提供灵活的权限管理机制，支持基于角色的访问控制，通过 RBAC 实现对不同角色（如普通用户和管理员）的功能权限区分，通过组织标签实现数据访问权限隔离。

为其他模块提供用户信息支持。

一、功能需求

图片.png

二、技术选型

图片.png

三、关键流程

01、用户注册流程

接收用户注册请求，验证用户名和密码；

检查用户名是否已存在；

使用 BCrypt 加密密码；

创建用户记录，设置默认角色为USER;

创建用户私人组织标签（PRIVATE_username）；

将私人组织标签设置为用户的主组织标签；返回注册成功响应。

图片.png

02、用户登录流程

接收用户登录请求，获取用户名和密码；

查询用户记录并验证密码；加载用户组织标签信息；

生成包含用户信息和组织标签的 JWT Token；

返回登录成功响应和 Token。

图片.png

03、组织标签管理流程

管理员创建组织标签，设置标签名称和描述；

可选择设置父级组织标签（支持简单层级）；

管理员为用户分配组织标签；

系统自动保留用户的私人组织标签，确保其不被移除；

用户查看自己的组织标签。

04、权限验证流程

解析请求头中的 JWT Token，验证有效性；

提取用户 ID、角色和组织标签信息；

对功能权限请求，根据用户角色判断是否允许访问；

对数据权限请求，根据用户组织标签判断是否可以访问特定资源；

允许或拒绝请求访问；权限验证流程具体讲解见： ✅如何基于Spring Security实现RBAC？

图片.png

四、接口设计 01、用户注册接口

URL: /api/v1/users/register

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",   // 用户名，唯一
  "password": "string"    // 密码（明文传输，后端加密存储）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "User registered successfully"
}

{
  "code": 400, // 失败
  "message": "Username already exists"
}

02、用户登录接口

URL: /api/v1/users/login

Method: POST

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "username": "string",
  "password": "string"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Login successful",
  "data": {
    "token": "JWT_TOKEN_STRING"
  }
}

{
  "code": 401, // 失败
  "message": "Invalid username or password"
}

03、获取用户信息接口

URL: /api/v1/users/me

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "id": 1,
    "username": "example_user",
    "role": "USER",
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user"
  }
}

{
  "code": 401, // 失败
  "message": "Unauthorized"
}

04、用户列表查询接口

URL: /api/v1/admin/users/list

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Query Parameters:

page: 页码（从1开始，默认1）

size: 每页条数（默认20）

keyword: 搜索关键词（可选）

orgTag: 按组织标签筛选（可选）

status: 用户状态（可选，0=禁用，1=启用

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get users successful",
  "data": {
    "content": [
      {
        "userId": "user1",
        "username": "用户1",
        "email": "user1@example.com",
        "status": 1,
        "orgTags": ["dept1", "team2"],
        "primaryOrg": "dept1",
        "createTime": "2023-01-01T12:00:00Z",
        "lastLoginTime": "2023-06-15T08:30:00Z"
      },
      // 更多用户...
    ],
    "totalElements": 150,
    "totalPages": 8,
    "size": 20,
    "number": 0
  }
}

05、组织标签管理接口

5.1 创建组织标签（管理员）

URL: /api/v1/admin/org-tags

Method: POST

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "tagId": "string",     // 标签ID，唯一
  "name": "string",      // 标签名称
  "description": "string", // 标签描述
  "parentTag": "string"  // 父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag created successfully"
}

5.2 为用户分配组织标签（admin）

URL: /api/v1/admin/users/{userId}/org-tags

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "orgTags": ["tag1", "tag2"]
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, //   成功：
  "message": "Organization tags assigned successfully"
}

5.3 设置用户主组织

URL: /api/v1/users/primary-org

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "primaryOrg": "tag1",
  "userId":"xxx"
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Primary organization set successfully"
}

5.4 获取用户组织标签详情

URL: /api/v1/users/org-tags

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get user organization tags successful",
  "data": {
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user",
    "orgTagDetails": [
      {
        "tagId": "PRIVATE_example_user",
        "name": "example_user的私人空间",
        "description": "用户的私人组织标签，仅用户本人可访问"
      },
      {
        "tagId": "dept1",
        "name": "部门1",
        "description": "部门1的组织标签"
      },
      {
        "tagId": "team2",
        "name": "团队2",
        "description": "团队2的组织标签"
      }
    ]
  }
}

5.5 组织标签树查询接口 (admin)

URL: /api/v1/admin/org-tags/tree

Method: GET

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Get organization tag tree successful",
  "data": [
    {
      "tagId": "dept1",
      "name": "部门1",
      "description": "部门1描述",
      "children": [
        {
          "tagId": "team1",
          "name": "团队1",
          "description": "团队1描述",
          "children": []
        },
        {
          "tagId": "team2",
          "name": "团队2",
          "description": "团队2描述",
          "children": []
        }
      ]
    },
    {
      "tagId": "dept2",
      "name": "部门2",
      "description": "部门2描述",
      "children": []
    }
  ]
}

5.6 更新组织标签接口(admin)

URL: /api/v1/admin/org-tags/{tagId}

Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Request Body:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "name": "string",       // 新标签名称
  "description": "string", // 新标签描述
  "parentTag": "string"    // 新父标签ID（可选）
}

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200,
  "message": "Organization tag updated successfully"
}

5.7 删除组织标签接口

URL: /api/v1/admin/org-tags/{tagId}

Method: DELETE

Headers:

Authorization: Bearer JWT_TOKEN_STRING

Response:

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

{
  "code": 200, // 成功
  "message": "Organization tag deleted successfully"
}
{
  "code": 409, // 错误（标签已被使用）：
  "message": "Cannot delete tag as it is associated with users or documents"
}

五、库表设计 01、用户表 (users)

字段名

数据类型

是否主键

描述

id

BIGINT

是

用户唯一标识

username

VARCHAR(255)

否

用户名，唯一

password

VARCHAR(255)

否

加密后的密码

role

ENUM('USER', 'ADMIN')

否

用户角色

org_tags

VARCHAR(255)

否

用户所属组织标签，多个用逗号分隔

primary_org

VARCHAR(50)

否

用户主组织标签

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '用户唯一标识',
    username VARCHAR(255) NOT NULL UNIQUE COMMENT '用户名，唯一',
    password VARCHAR(255) NOT NULL COMMENT '加密后的密码',
    role ENUM('USER', 'ADMIN') NOT NULL DEFAULT 'USER' COMMENT '用户角色',
    org_tags VARCHAR(255) DEFAULT NULL COMMENT '用户所属组织标签，多个用逗号分隔',
    primary_org VARCHAR(50) DEFAULT NULL COMMENT '用户主组织标签',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    INDEX idx_username (username) COMMENT '用户名索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

02、组织标签表

字段名

数据类型

是否主键

描述

tag_id

VARCHAR(50)

是

标签唯一标识

name

VARCHAR(100)

否

标签名称

description

TEXT

否

描述

parent_tag

VARCHAR(50)

否

父标签ID

created_by

BIGINT

否

创建者ID

created_at

TIMESTAMP

否

创建时间

updated_at

TIMESTAMP

否

更新时间

建表语句：

textjavascripttypescriptcsshtmlbashjsonmarkdownpythonjavaccpprubygorustphpsqlyaml Copy

CREATE TABLE organization_tags (
    tag_id VARCHAR(50) PRIMARY KEY COMMENT '标签唯一标识',
    name VARCHAR(100) NOT NULL COMMENT '标签名称',
    description TEXT COMMENT '描述',
    parent_tag VARCHAR(50) DEFAULT NULL COMMENT '父标签ID',
    created_by BIGINT NOT NULL COMMENT '创建者ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (parent_tag) REFERENCES organization_tags(tag_id) ON DELETE SET NULL,
    FOREIGN KEY (created_by) REFERENCES users(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织标签表';