一、用户管理模块

01、用户注册接口

• URL: /api/v1/users/register
• Method: POST
• Request Body:

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

• Response:

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

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

02、用户登录接口

• URL: /api/v1/users/login
• Method: POST
• Request Body:

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

• Response:

{
  "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:

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

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

04、组织标签管理接口

①、创建组织标签（管理员）

• URL: /api/v1/admin/org-tags
• Method: POST
• Headers:
  • Authorization: Bearer JWT_TOKEN_STRING
• Request Body:

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

• Response:

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

②、为用户分配组织标签

• URL: /api/v1/admin/users/{userId}/org-tags
• Method: PUT
• Headers:
  • Authorization: Bearer JWT_TOKEN_STRING
• Request Body:

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

• Response:

{
  "code": 200,
  "message": "Organization tags assigned successfully"
}

③、设置用户组织

• URL: /api/v1/users/primary-org
• Method: PUT
• Headers:
  • Authorization: Bearer JWT_TOKEN_STRING
• Request Body:

{
  "primaryOrg": "tag1"
}

• Response:
  • 成功：

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

④、获取用户组织标签详情

• URL: /api/v1/users/org-tags
• Method: GET
• Headers:
• Authorization: Bearer JWT_TOKEN_STRING
• Response:

{
  "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的组织标签"
      }
    ]
  }
}

二、文件上传与处理模块

01、分片上传接口

• URL: /api/v1/upload/chunk
• Method: POST
• Headers:
  • X-File-MD5: d41d8cd98f00b204e9800998ecf8427e
  • X-Chunk-Index: 3
  • Authorization: Bearer
• Body: multipart/form-data (分片二进制数据)
• Response:

{
  "code": 200,// 成功
  "message": "Chunk uploaded successfully",
  "data": {
    "uploaded": [0, 1, 2, 3],
    "progress": 75.0
  }
}

{
  "code": 400,//失败
  "message": "Invalid chunk data"
}

02、查询上传状态接口

• URL: /api/v1/upload/status
• Method: GET
• Query Parameters:
  • file_md5: d41d8cd98f00b204e9800998ecf8427e
• Headers:
  • Authorization: Bearer
• Response:

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "uploaded": [0, 1, 2],
    "progress": 60.0,
    "total_chunks": 5
  }
}

{
  "code": 404,//失败
  "message": "Upload record not found"
}

03、文件合并接口

• URL: /api/v1/upload/merge
• Method: POST
• Headers:
  • Authorization: Bearer
• Request Body:

{
  "file_md5": "d41d8cd98f00b204e9800998ecf8427e",
  "file_name": "paismart.pdf"
}

• Response:

{
  "code": 200, // 成功
  "message": "File merged successfully",
  "data": {
    "object_url": "https://minio.example.com/reports/paismart.pdf",
    "file_size": 15728640
  }
}

{
  "code": 400, // 失败
  "message": "Not all chunks have been uploaded"
}

04、文件删除接口

• URL: /api/v1/documents/{file_md5}
• Method: DELETE
• Path Parameters:
  • file_md5: 要删除的文件唯一标识（MD5值）
• Headers:
  • Authorization: Bearer {token} （用于身份验证）
• Response:

{
  "status": "success",
  "message": "文档删除成功"
}

{
  "status": "error",
  "message": "文档不存在"
}

{
  "status": "error",
  "message": "没有权限删除此文档"
}

{
  "status": "error",
  "message": "删除文档失败: 详细错误信息"
}

三、知识库检索模块

01、混合搜索接口

• URL: /api/search/hybrid
• Method: POST
• Request Body:

{
  "query": "沉默王二是条狗？",
  "topK": 10
}

• Response:

[
  {
    "file_md5": "abc123...",
    "chunk_id": 1,
    "text_content": "哦不，沉默王二帅的像个人。",
    "score": 0.92,
    "file_name": "itwanger.pdf"
  },
  // ...更多结果
]

02、文档删除接口

• URL: /api/documents/{file_md5}
• Method: DELETE
• Path Parameters:
  • file_md5: 要删除的文件唯一标识（MD5值）
• Headers:
  • Authorization: Bearer {token} （用于身份验证）
• Response:

{
  "status": "success",
  "message": "文档删除成功"
}

{
  "status": "error",
  "message": "文档不存在"
}

{
  "status": "error",
  "message": "没有权限删除此文档"
}

{
  "status": "error",
  "message": "删除文档失败: 详细错误信息"
}

四、聊天助手模块

01、WebSocket 接口

• URL: /ws/chat
• 协议: WebSocket
• 功能: 用户通过WebSocket发送消息，服务端逐段返回回答内容
• 客户端发送消息格式:

{
  "message": "派聪明是什么？",
  "conversationId": "abcdef123456"  // 可选，不提供则使用当前会话
}

• 服务端返回格式:

{"chunk": "派聪明是"}
{"chunk": "一个 RAG"}
{"chunk": " 的私有知识库。"}

02、创建聊天接口

• URL: /api/conversation/create
• Method: POST
• Request Body:

{
  "userId": "12345"
}

• Response:

{
  "conversationId": "abcdef123456" //为用户生成一个新的conversationId，并将其与用户关联
}

03、获取聊天历史

• URL: /api/conversation/history
• Method: GET
• Query Parameters:userId: 用户ID
• Response:

{ // 根据用户的userId获取其当前会话的对话历史
  "messages": [
    {"role": "user", "content": "派聪明是什么？"},
    {"role": "assistant", "content": "派聪明是一个 RAG 的私有知识库。"}
  ]
}