Add user_id for third-party system to record sessions. (#4206)

### What problem does this PR solve?


### Type of change

- [x] New Feature (non-breaking change which adds functionality)
- [x] Documentation Update

---------

Co-authored-by: writinwaters <93570324+writinwaters@users.noreply.github.com>

api/apps/sdk/session.py

         "id": get_uuid(),
         "dialog_id": req["dialog_id"],
         "name": req.get("name", "New session"),
-        "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}]
+        "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}],
+        "user_id": req.get("user_id", "")
     }
     if not conv.get("name"):
         return get_error_data_result(message="`name` can not be empty.")
         return get_error_data_result("Agent not found.")
 
     if not UserCanvasService.query(user_id=tenant_id,id=agent_id):
-        return  get_error_data_result("You cannot access the agent.")
+        return get_error_data_result("You cannot access the agent.")
 
     if not isinstance(cvs.dsl, str):
         cvs.dsl = json.dumps(cvs.dsl, ensure_ascii=False)
     page_number = int(request.args.get("page", 1))
     items_per_page = int(request.args.get("page_size", 30))
     orderby = request.args.get("orderby", "create_time")
+    user_id = request.args.get("user_id")
     if request.args.get("desc") == "False" or request.args.get("desc") == "false":
         desc = False
     else:
         desc = True
-    convs = ConversationService.get_list(chat_id, page_number, items_per_page, orderby, desc, id, name)
+    convs = ConversationService.get_list(chat_id, page_number, items_per_page, orderby, desc, id, name, user_id)
     if not convs:
         return get_result(data=[])
     for conv in convs:

api/db/db_models.py

 )
 from playhouse.pool import PooledMySQLDatabase, PooledPostgresqlDatabase
 
-
 from api.db import SerializedType, ParserType
 from api import settings
 from api import utils
     name = CharField(max_length=255, null=True, help_text="converastion name", index=True)
     message = JSONField(null=True)
     reference = JSONField(null=True, default=[])
+    user_id = CharField(max_length=255, null=True, help_text="user_id", index=True)
 
     class Meta:
         db_table = "conversation"
             pass
         try:
             migrate(
-                migrator.add_column("tenant_llm","max_tokens",IntegerField(default=8192,index=True))
+                migrator.add_column("tenant_llm", "max_tokens", IntegerField(default=8192, index=True))
             )
         except Exception:
             pass
         try:
             migrate(
-                migrator.add_column("api_4_conversation","dsl",JSONField(null=True, default={}))
+                migrator.add_column("api_4_conversation", "dsl", JSONField(null=True, default={}))
             )
         except Exception:
             pass
             )
         except Exception:
             pass
+        try:
+            migrate(
+                migrator.add_column("conversation", "user_id",
+                                    CharField(max_length=255, null=True, help_text="user_id", index=True))
+            )
+        except Exception:
+            pass

api/db/services/api_service.py

 
     @classmethod
     @DB.connection_context()
-    def get_list(cls,dialog_id, tenant_id,
-                 page_number, items_per_page, orderby, desc, id):
-        sessions = cls.model.select().where(cls.model.dialog_id ==dialog_id)
+    def get_list(cls, dialog_id, tenant_id,
+                 page_number, items_per_page,
+                 orderby, desc, id, user_id=None):
+        sessions = cls.model.select().where(cls.model.dialog_id == dialog_id)
         if id:
             sessions = sessions.where(cls.model.id == id)
+        if user_id:
+            sessions = sessions.where(cls.model.user_id == user_id)
         if desc:
             sessions = sessions.order_by(cls.model.getter_by(orderby).desc())
         else:

api/db/services/conversation_service.py

 
     @classmethod
     @DB.connection_context()
-    def get_list(cls,dialog_id,page_number, items_per_page, orderby, desc, id , name):
-        sessions = cls.model.select().where(cls.model.dialog_id ==dialog_id)
+    def get_list(cls, dialog_id, page_number, items_per_page, orderby, desc, id, name, user_id=None):
+        sessions = cls.model.select().where(cls.model.dialog_id == dialog_id)
         if id:
             sessions = sessions.where(cls.model.id == id)
         if name:
             sessions = sessions.where(cls.model.name == name)
+        if user_id:
+            sessions = sessions.where(cls.model.user_id == user_id)
         if desc:
             sessions = sessions.order_by(cls.model.getter_by(orderby).desc())
         else:
 
     def get_value(d, k1, k2):
         return d.get(k1, d.get(k2))
+
     chunk_list = [{
-            "id": get_value(chunk, "chunk_id", "id"),
-            "content": get_value(chunk, "content", "content_with_weight"),
-            "document_id": get_value(chunk, "doc_id", "document_id"),
-            "document_name": get_value(chunk, "docnm_kwd", "document_name"),
-            "dataset_id": get_value(chunk, "kb_id", "dataset_id"),
-            "image_id": get_value(chunk, "image_id", "img_id"),
-            "positions": get_value(chunk, "positions", "position_int"),
-        } for chunk in reference.get("chunks", [])]
+        "id": get_value(chunk, "chunk_id", "id"),
+        "content": get_value(chunk, "content", "content_with_weight"),
+        "document_id": get_value(chunk, "doc_id", "document_id"),
+        "document_name": get_value(chunk, "docnm_kwd", "document_name"),
+        "dataset_id": get_value(chunk, "kb_id", "dataset_id"),
+        "image_id": get_value(chunk, "image_id", "img_id"),
+        "positions": get_value(chunk, "positions", "position_int"),
+    } for chunk in reference.get("chunks", [])]
 
     reference["chunks"] = chunk_list
     ans["id"] = message_id
     if not session_id:
         session_id = get_uuid()
         conv = {
-            "id":session_id ,
+            "id": session_id,
             "dialog_id": chat_id,
             "name": name,
-            "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}]
+            "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}],
+            "user_id": kwargs.get("user_id", "")
         }
         ConversationService.save(**conv)
         yield "data:" + json.dumps({"code": 0, "message": "",
             API4ConversationService.append_message(conv.id, conv.to_dict())
             break
         yield answer
-

docs/references/http_api_reference.md

   - `'Authorization: Bearer <YOUR_API_KEY>'`
 - Body:
   - `"name"`: `string`
+  - `"user_id"`: `string`(optional)
 
 ##### Request example
 
   The ID of the associated chat assistant.
 - `"name"`: (*Body parameter*), `string`  
   The name of the chat session to create.
+- `"user_id"`: (*Body parameter*), `string`  
+  Optional user-defined ID.
 
 #### Response
 
   - `'Authorization: Bearer <YOUR_API_KEY>'`
 - Body:
   - `"name`: `string`
+  - `"user_id`: `string`(optional)
 
 ##### Request example
 
   The ID of the session to update.
 - `"name"`: (*Body Parameter*), `string`  
   The revised name of the session.
+- `"user_id"`: (*Body parameter*), `string`  
+  Optional user-defined ID.
 
 #### Response
 
 #### Request
 
 - Method: GET
-- URL: `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}`
+- URL: `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}&user_id={user_id}`
 - Headers:
   - `'Authorization: Bearer <YOUR_API_KEY>'`
 
   The name of the chat session to retrieve.
 - `id`: (*Filter parameter*), `string`  
   The ID of the chat session to retrieve.
+- `user_id`: (*Filter parameter*), `string`  
+  The optional user-defined ID passed in when creating session.
 
 #### Response
 
 - Body:
   - `"question"`: `string`
   - `"stream"`: `boolean`
-  - `"session_id"`: `string`
+  - `"session_id"`: `string`(optional)
+  - `"user_id`: `string`(optional)
 
 ##### Request example
 
   - `false`: Disable streaming.
 - `"session_id"`: (*Body Parameter*)  
   The ID of session. If it is not provided, a new session will be generated.
+- `"user_id"`: (*Body parameter*), `string`  
+  The optional user-defined ID. Valid *only* when no `session_id` is provided.
 
 #### Response
 
 - Body:
   - the required parameters:`str`
   - the optional parameters:`str`
+    - `"user_id"`: `string`  
+      The optional user-defined ID.
 
 ##### Request example
 If `begin` component in the agent doesn't have required parameters:
   - `"question"`: `string`
   - `"stream"`: `boolean`
   - `"session_id"`: `string`
+  - `"user_id"`: `string`(optional)
   - other parameters: `string`
 ##### Request example
 If the `begin` component doesn't have parameters, the following code will create a session.
   - `false`: Disable streaming.
 - `"session_id"`: (*Body Parameter*)  
   The ID of the session. If it is not provided, a new session will be generated.
+- `"user_id"`: (*Body parameter*), `string`  
+  The optional user-defined ID. Valid *only* when no `session_id` is provided.
 - Other parameters: (*Body Parameter*)  
   The parameters in the begin component.
 #### Response
 
 ### List agent sessions
 
-**GET** `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}`
+**GET** `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id}`
 
 Lists sessions associated with a specified agent.
 
 
 ```bash
 curl --request GET \
-     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id} \
+     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id} \
      --header 'Authorization: Bearer <YOUR_API_KEY>'
 ```
 
   Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `true`.
 - `id`: (*Filter parameter*), `string`  
   The ID of the agent session to retrieve.
-
+- `user_id`: (*Filter parameter*), `string`  
+  The optional user-defined ID passed in when creating session.
+  
 #### Response
 
 Success: