From f2d3feca6682c41c4f048b35b77f64a7b642dd64 Mon Sep 17 00:00:00 2001
From: yyh <92089059+lyzno1@users.noreply.github.com>
Date: Mon, 9 Mar 2026 13:38:11 +0800
Subject: [PATCH 01/12] fix(web): fix tool item text not vertically centered in
 block selector (#33148)

---
 .../components/workflow/block-selector/tool/action-item.tsx | 4 ++--
 .../workflow/block-selector/trigger-plugin/action-item.tsx  | 4 ++--
 web/eslint-suppressions.json                                | 6 ------
 3 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/web/app/components/workflow/block-selector/tool/action-item.tsx b/web/app/components/workflow/block-selector/tool/action-item.tsx
index 4ffa99b05d..359cd5360d 100644
--- a/web/app/components/workflow/block-selector/tool/action-item.tsx
+++ b/web/app/components/workflow/block-selector/tool/action-item.tsx
@@ -111,11 +111,11 @@ const ToolItem: FC<Props> = ({
           })
         }}
       >
-        <div className={cn('system-sm-medium h-8 truncate border-l-2 border-divider-subtle pl-4 leading-8 text-text-secondary')}>
+        <div className={cn('truncate border-l-2 border-divider-subtle py-2 pl-4 text-text-secondary system-sm-medium')}>
           <span className={cn(disabled && 'opacity-30')}>{payload.label[language]}</span>
         </div>
         {isAdded && (
-          <div className="system-xs-regular mr-4 text-text-tertiary">{t('addToolModal.added', { ns: 'tools' })}</div>
+          <div className="mr-4 text-text-tertiary system-xs-regular">{t('addToolModal.added', { ns: 'tools' })}</div>
         )}
       </div>
     </Tooltip>
diff --git a/web/app/components/workflow/block-selector/trigger-plugin/action-item.tsx b/web/app/components/workflow/block-selector/trigger-plugin/action-item.tsx
index 5d47534da5..38ad4951ea 100644
--- a/web/app/components/workflow/block-selector/trigger-plugin/action-item.tsx
+++ b/web/app/components/workflow/block-selector/trigger-plugin/action-item.tsx
@@ -77,11 +77,11 @@ const TriggerPluginActionItem: FC<Props> = ({
           })
         }}
       >
-        <div className={cn('system-sm-medium h-8 truncate border-l-2 border-divider-subtle pl-4 leading-8 text-text-secondary')}>
+        <div className={cn('truncate border-l-2 border-divider-subtle py-2 pl-4 text-text-secondary system-sm-medium')}>
           <span className={cn(disabled && 'opacity-30')}>{payload.label[language]}</span>
         </div>
         {isAdded && (
-          <div className="system-xs-regular mr-4 text-text-tertiary">{t('addToolModal.added', { ns: 'tools' })}</div>
+          <div className="mr-4 text-text-tertiary system-xs-regular">{t('addToolModal.added', { ns: 'tools' })}</div>
         )}
       </div>
     </Tooltip>
diff --git a/web/eslint-suppressions.json b/web/eslint-suppressions.json
index 3aec0ae56f..1bfa47577d 100644
--- a/web/eslint-suppressions.json
+++ b/web/eslint-suppressions.json
@@ -6554,9 +6554,6 @@
   "app/components/workflow/block-selector/tool/action-item.tsx": {
     "no-restricted-imports": {
       "count": 1
-    },
-    "tailwindcss/enforce-consistent-class-order": {
-      "count": 2
     }
   },
   "app/components/workflow/block-selector/tool/tool-list-flat-view/list.tsx": {
@@ -6576,9 +6573,6 @@
     "no-restricted-imports": {
       "count": 1
     },
-    "tailwindcss/enforce-consistent-class-order": {
-      "count": 2
-    },
     "ts/no-explicit-any": {
       "count": 1
     }

From 8b1ea3a8f537083a4d00869264b7e71b6de2cbee Mon Sep 17 00:00:00 2001
From: Olexandr88 <radole1203@gmail.com>
Date: Mon, 9 Mar 2026 08:43:06 +0300
Subject: [PATCH 02/12] refactor: deduplicate legacy section mapping in
 ConfigHelper (#32715)

---
 scripts/stress-test/common/config_helper.py | 30 ++++++++++-----------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/scripts/stress-test/common/config_helper.py b/scripts/stress-test/common/config_helper.py
index 75fcbffa6f..fb34b43e26 100644
--- a/scripts/stress-test/common/config_helper.py
+++ b/scripts/stress-test/common/config_helper.py
@@ -6,6 +6,13 @@ from typing import Any
 
 
 class ConfigHelper:
+    _LEGACY_SECTION_MAP = {
+        "admin_config": "admin",
+        "token_config": "auth",
+        "app_config": "app",
+        "api_key_config": "api_key",
+    }
+
     """Helper class for reading and writing configuration files."""
 
     def __init__(self, base_dir: Path | None = None):
@@ -50,14 +57,8 @@ class ConfigHelper:
             Dictionary containing config data, or None if file doesn't exist
         """
         # Provide backward compatibility for old config names
-        if filename in ["admin_config", "token_config", "app_config", "api_key_config"]:
-            section_map = {
-                "admin_config": "admin",
-                "token_config": "auth",
-                "app_config": "app",
-                "api_key_config": "api_key",
-            }
-            return self.get_state_section(section_map[filename])
+        if filename in self._LEGACY_SECTION_MAP:
+            return self.get_state_section(self._LEGACY_SECTION_MAP[filename])
 
         config_path = self.get_config_path(filename)
 
@@ -85,14 +86,11 @@ class ConfigHelper:
             True if successful, False otherwise
         """
         # Provide backward compatibility for old config names
-        if filename in ["admin_config", "token_config", "app_config", "api_key_config"]:
-            section_map = {
-                "admin_config": "admin",
-                "token_config": "auth",
-                "app_config": "app",
-                "api_key_config": "api_key",
-            }
-            return self.update_state_section(section_map[filename], data)
+        if filename in self._LEGACY_SECTION_MAP:
+            return self.update_state_section(
+                self._LEGACY_SECTION_MAP[filename],
+                data,
+            )
 
         self.ensure_config_dir()
         config_path = self.get_config_path(filename)

From ec5409756eb242ddf05cad71df6174940bdc65ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9D=9E=E6=B3=95=E6=93=8D=E4=BD=9C?= <hjlarry@163.com>
Date: Mon, 9 Mar 2026 13:54:10 +0800
Subject: [PATCH 03/12] feat: keep connections when change node (#31982)

---
 .../workflow/hooks/use-nodes-interactions.ts  | 175 +++++++++++++++---
 1 file changed, 152 insertions(+), 23 deletions(-)

diff --git a/web/app/components/workflow/hooks/use-nodes-interactions.ts b/web/app/components/workflow/hooks/use-nodes-interactions.ts
index 4635baa787..1a3a8f74a7 100644
--- a/web/app/components/workflow/hooks/use-nodes-interactions.ts
+++ b/web/app/components/workflow/hooks/use-nodes-interactions.ts
@@ -1422,21 +1422,136 @@ export const useNodesInteractions = () => {
         extent: currentNode.extent,
         zIndex: currentNode.zIndex,
       })
-      const nodesConnectedSourceOrTargetHandleIdsMap
-        = getNodesConnectedSourceOrTargetHandleIdsMap(
-          connectedEdges.map(edge => ({ type: 'remove', edge })),
-          nodes,
-        )
-      const newNodes = produce(nodes, (draft) => {
+      const parentNode = nodes.find(node => node.id === currentNode.parentId)
+      const newNodeIsInIteration
+        = !!parentNode && parentNode.data.type === BlockEnum.Iteration
+      const newNodeIsInLoop
+        = !!parentNode && parentNode.data.type === BlockEnum.Loop
+      const outgoingEdges = connectedEdges.filter(
+        edge => edge.source === currentNodeId,
+      )
+      const normalizedSourceHandle = sourceHandle || 'source'
+      const outgoingHandles = new Set(
+        outgoingEdges.map(edge => edge.sourceHandle || 'source'),
+      )
+      const branchSourceHandle = currentNode.data._targetBranches?.[0]?.id
+      let outgoingHandleToPreserve = normalizedSourceHandle
+      if (!outgoingHandles.has(outgoingHandleToPreserve)) {
+        if (branchSourceHandle && outgoingHandles.has(branchSourceHandle))
+          outgoingHandleToPreserve = branchSourceHandle
+        else if (outgoingHandles.has('source'))
+          outgoingHandleToPreserve = 'source'
+        else
+          outgoingHandleToPreserve = outgoingEdges[0]?.sourceHandle || 'source'
+      }
+      const outgoingEdgesToPreserve = outgoingEdges.filter(
+        edge => (edge.sourceHandle || 'source') === outgoingHandleToPreserve,
+      )
+      const outgoingEdgeIds = new Set(
+        outgoingEdgesToPreserve.map(edge => edge.id),
+      )
+      const newNodeSourceHandle = newCurrentNode.data._targetBranches?.[0]?.id || 'source'
+      const reconnectedEdges = connectedEdges.reduce<Edge[]>(
+        (acc, edge) => {
+          if (outgoingEdgeIds.has(edge.id)) {
+            const originalTargetNode = nodes.find(
+              node => node.id === edge.target,
+            )
+            const targetNodeForEdge
+              = originalTargetNode && originalTargetNode.id !== currentNodeId
+                ? originalTargetNode
+                : newCurrentNode
+            if (!targetNodeForEdge)
+              return acc
+
+            const targetHandle = edge.targetHandle || 'target'
+            const targetParentNode
+              = targetNodeForEdge.id === newCurrentNode.id
+                ? parentNode || null
+                : nodes.find(node => node.id === targetNodeForEdge.parentId)
+                  || null
+            const isInIteration
+              = !!targetParentNode
+                && targetParentNode.data.type === BlockEnum.Iteration
+            const isInLoop
+              = !!targetParentNode
+                && targetParentNode.data.type === BlockEnum.Loop
+
+            acc.push({
+              ...edge,
+              id: `${newCurrentNode.id}-${newNodeSourceHandle}-${targetNodeForEdge.id}-${targetHandle}`,
+              source: newCurrentNode.id,
+              sourceHandle: newNodeSourceHandle,
+              target: targetNodeForEdge.id,
+              targetHandle,
+              type: CUSTOM_EDGE,
+              data: {
+                ...(edge.data || {}),
+                sourceType: newCurrentNode.data.type,
+                targetType: targetNodeForEdge.data.type,
+                isInIteration,
+                iteration_id: isInIteration
+                  ? targetNodeForEdge.parentId
+                  : undefined,
+                isInLoop,
+                loop_id: isInLoop ? targetNodeForEdge.parentId : undefined,
+                _connectedNodeIsSelected: false,
+              },
+              zIndex: targetNodeForEdge.parentId
+                ? isInIteration
+                  ? ITERATION_CHILDREN_Z_INDEX
+                  : LOOP_CHILDREN_Z_INDEX
+                : 0,
+            })
+          }
+
+          if (
+            edge.target === currentNodeId
+            && edge.source !== currentNodeId
+            && !outgoingEdgeIds.has(edge.id)
+          ) {
+            const sourceNode = nodes.find(node => node.id === edge.source)
+            if (!sourceNode)
+              return acc
+
+            const targetHandle = edge.targetHandle || 'target'
+            const sourceHandle = edge.sourceHandle || 'source'
+
+            acc.push({
+              ...edge,
+              id: `${sourceNode.id}-${sourceHandle}-${newCurrentNode.id}-${targetHandle}`,
+              source: sourceNode.id,
+              sourceHandle,
+              target: newCurrentNode.id,
+              targetHandle,
+              type: CUSTOM_EDGE,
+              data: {
+                ...(edge.data || {}),
+                sourceType: sourceNode.data.type,
+                targetType: newCurrentNode.data.type,
+                isInIteration: newNodeIsInIteration,
+                iteration_id: newNodeIsInIteration
+                  ? newCurrentNode.parentId
+                  : undefined,
+                isInLoop: newNodeIsInLoop,
+                loop_id: newNodeIsInLoop ? newCurrentNode.parentId : undefined,
+                _connectedNodeIsSelected: false,
+              },
+              zIndex: newCurrentNode.parentId
+                ? newNodeIsInIteration
+                  ? ITERATION_CHILDREN_Z_INDEX
+                  : LOOP_CHILDREN_Z_INDEX
+                : 0,
+            })
+          }
+
+          return acc
+        },
+        [],
+      )
+      const nodesWithNewNode = produce(nodes, (draft) => {
         draft.forEach((node) => {
           node.data.selected = false
-
-          if (nodesConnectedSourceOrTargetHandleIdsMap[node.id]) {
-            node.data = {
-              ...node.data,
-              ...nodesConnectedSourceOrTargetHandleIdsMap[node.id],
-            }
-          }
         })
         const index = draft.findIndex(node => node.id === currentNodeId)
 
@@ -1446,18 +1561,32 @@ export const useNodesInteractions = () => {
         if (newLoopStartNode)
           draft.push(newLoopStartNode)
       })
-      setNodes(newNodes)
-      const newEdges = produce(edges, (draft) => {
-        const filtered = draft.filter(
-          edge =>
-            !connectedEdges.find(
-              connectedEdge => connectedEdge.id === edge.id,
-            ),
+      const nodesConnectedSourceOrTargetHandleIdsMap
+        = getNodesConnectedSourceOrTargetHandleIdsMap(
+          [
+            ...connectedEdges.map(edge => ({ type: 'remove', edge })),
+            ...reconnectedEdges.map(edge => ({ type: 'add', edge })),
+          ],
+          nodesWithNewNode,
         )
-
-        return filtered
+      const newNodes = produce(nodesWithNewNode, (draft) => {
+        draft.forEach((node) => {
+          if (nodesConnectedSourceOrTargetHandleIdsMap[node.id]) {
+            node.data = {
+              ...node.data,
+              ...nodesConnectedSourceOrTargetHandleIdsMap[node.id],
+            }
+          }
+        })
       })
-      setEdges(newEdges)
+      setNodes(newNodes)
+      const remainingEdges = edges.filter(
+        edge =>
+          !connectedEdges.find(
+            connectedEdge => connectedEdge.id === edge.id,
+          ),
+      )
+      setEdges([...remainingEdges, ...reconnectedEdges])
       if (nodeType === BlockEnum.TriggerWebhook) {
         handleSyncWorkflowDraft(true, true, {
           onSuccess: () => autoGenerateWebhookUrl(newCurrentNode.id),

From 654e41d47fddedced2ff5e3a569d3d0af9ed9c8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9D=9E=E6=B3=95=E6=93=8D=E4=BD=9C?= <hjlarry@163.com>
Date: Mon, 9 Mar 2026 13:54:54 +0800
Subject: [PATCH 04/12] fix: workflow_as_tool not work with json input (#32554)

---
 api/core/tools/workflow_as_tool/provider.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/api/core/tools/workflow_as_tool/provider.py b/api/core/tools/workflow_as_tool/provider.py
index d73012375d..aef8b3f779 100644
--- a/api/core/tools/workflow_as_tool/provider.py
+++ b/api/core/tools/workflow_as_tool/provider.py
@@ -37,6 +37,7 @@ VARIABLE_TO_PARAMETER_TYPE_MAPPING = {
     VariableEntityType.CHECKBOX: ToolParameter.ToolParameterType.BOOLEAN,
     VariableEntityType.FILE: ToolParameter.ToolParameterType.FILE,
     VariableEntityType.FILE_LIST: ToolParameter.ToolParameterType.FILES,
+    VariableEntityType.JSON_OBJECT: ToolParameter.ToolParameterType.OBJECT,
 }
 
 

From 4a2ba058bbb1a12e72ecbefff9d4d90135a44596 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9D=9E=E6=B3=95=E6=93=8D=E4=BD=9C?= <hjlarry@163.com>
Date: Mon, 9 Mar 2026 13:55:12 +0800
Subject: [PATCH 05/12] feat: when copy/paste multi nodes not require reconnect
 them (#32631)

---
 .../workflow/hooks/use-nodes-interactions.ts  | 45 +++++++++++++++++--
 .../workflow/nodes/loop/use-interactions.ts   | 11 ++++-
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/web/app/components/workflow/hooks/use-nodes-interactions.ts b/web/app/components/workflow/hooks/use-nodes-interactions.ts
index 1a3a8f74a7..e18405b196 100644
--- a/web/app/components/workflow/hooks/use-nodes-interactions.ts
+++ b/web/app/components/workflow/hooks/use-nodes-interactions.ts
@@ -1735,6 +1735,7 @@ export const useNodesInteractions = () => {
       const offsetX = currentPosition.x - x
       const offsetY = currentPosition.y - y
       let idMapping: Record<string, string> = {}
+      const pastedNodesMap: Record<string, Node> = {}
       const parentChildrenToAppend: { parentId: string, childId: string, childType: BlockEnum }[] = []
       clipboardElements.forEach((nodeToPaste, index) => {
         const nodeType = nodeToPaste.data.type
@@ -1794,7 +1795,21 @@ export const useNodesInteractions = () => {
           newLoopStartNode!.parentId = newNode.id;
           (newNode.data as LoopNodeType).start_node_id = newLoopStartNode!.id
 
-          newChildren = handleNodeLoopChildrenCopy(nodeToPaste.id, newNode.id)
+          const oldLoopStartNode = nodes.find(
+            n =>
+              n.parentId === nodeToPaste.id
+              && n.type === CUSTOM_LOOP_START_NODE,
+          )
+          idMapping[oldLoopStartNode!.id] = newLoopStartNode!.id
+
+          const { copyChildren, newIdMapping }
+            = handleNodeLoopChildrenCopy(
+              nodeToPaste.id,
+              newNode.id,
+              idMapping,
+            )
+          newChildren = copyChildren
+          idMapping = newIdMapping
           newChildren.forEach((child) => {
             newNode.data._children?.push({
               nodeId: child.id,
@@ -1839,18 +1854,31 @@ export const useNodesInteractions = () => {
           }
         }
 
+        idMapping[nodeToPaste.id] = newNode.id
         nodesToPaste.push(newNode)
+        pastedNodesMap[newNode.id] = newNode
 
-        if (newChildren.length)
+        if (newChildren.length) {
+          newChildren.forEach((child) => {
+            pastedNodesMap[child.id] = child
+          })
           nodesToPaste.push(...newChildren)
+        }
       })
 
-      // only handle edge when paste nested block
+      // Rebuild edges where both endpoints are part of the pasted set.
       edges.forEach((edge) => {
         const sourceId = idMapping[edge.source]
         const targetId = idMapping[edge.target]
 
         if (sourceId && targetId) {
+          const sourceNode = pastedNodesMap[sourceId]
+          const targetNode = pastedNodesMap[targetId]
+          const parentNode = sourceNode?.parentId && sourceNode.parentId === targetNode?.parentId
+            ? pastedNodesMap[sourceNode.parentId] ?? nodes.find(n => n.id === sourceNode.parentId)
+            : null
+          const isInIteration = parentNode?.data.type === BlockEnum.Iteration
+          const isInLoop = parentNode?.data.type === BlockEnum.Loop
           const newEdge: Edge = {
             ...edge,
             id: `${sourceId}-${edge.sourceHandle}-${targetId}-${edge.targetHandle}`,
@@ -1858,8 +1886,19 @@ export const useNodesInteractions = () => {
             target: targetId,
             data: {
               ...edge.data,
+              isInIteration,
+              iteration_id: isInIteration ? parentNode?.id : undefined,
+              isInLoop,
+              loop_id: isInLoop ? parentNode?.id : undefined,
               _connectedNodeIsSelected: false,
             },
+            zIndex: parentNode
+              ? isInIteration
+                ? ITERATION_CHILDREN_Z_INDEX
+                : isInLoop
+                  ? LOOP_CHILDREN_Z_INDEX
+                  : 0
+              : 0,
           }
           edgesToPaste.push(newEdge)
         }
diff --git a/web/app/components/workflow/nodes/loop/use-interactions.ts b/web/app/components/workflow/nodes/loop/use-interactions.ts
index 5e8f6ae36c..e9c4e31e30 100644
--- a/web/app/components/workflow/nodes/loop/use-interactions.ts
+++ b/web/app/components/workflow/nodes/loop/use-interactions.ts
@@ -108,12 +108,13 @@ export const useNodeLoopInteractions = () => {
       handleNodeLoopRerender(parentId)
   }, [store, handleNodeLoopRerender])
 
-  const handleNodeLoopChildrenCopy = useCallback((nodeId: string, newNodeId: string) => {
+  const handleNodeLoopChildrenCopy = useCallback((nodeId: string, newNodeId: string, idMapping: Record<string, string>) => {
     const { getNodes } = store.getState()
     const nodes = getNodes()
     const childrenNodes = nodes.filter(n => n.parentId === nodeId && n.type !== CUSTOM_LOOP_START_NODE)
+    const newIdMapping = { ...idMapping }
 
-    return childrenNodes.map((child, index) => {
+    const copyChildren = childrenNodes.map((child, index) => {
       const childNodeType = child.data.type as BlockEnum
       const { defaultValue } = nodesMetaDataMap![childNodeType]
       const nodesWithSameType = nodes.filter(node => node.data.type === childNodeType)
@@ -139,8 +140,14 @@ export const useNodeLoopInteractions = () => {
         zIndex: LOOP_CHILDREN_Z_INDEX,
       })
       newNode.id = `${newNodeId}${newNode.id + index}`
+      newIdMapping[child.id] = newNode.id
       return newNode
     })
+
+    return {
+      copyChildren,
+      newIdMapping,
+    }
   }, [store, nodesMetaDataMap])
 
   return {

From d2208ad43e3dc9bc3043df10ce63d38a8c3dac1b Mon Sep 17 00:00:00 2001
From: wangxiaolei <fatelei@gmail.com>
Date: Mon, 9 Mar 2026 14:20:44 +0800
Subject: [PATCH 06/12] fix: fix allow handle value is none (#33031)

---
 .../nodes/document_extractor/node.py          | 11 +++++++
 .../nodes/test_document_extractor_node.py     | 32 +++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/api/dify_graph/nodes/document_extractor/node.py b/api/dify_graph/nodes/document_extractor/node.py
index e1ae6f0199..c26b18aac9 100644
--- a/api/dify_graph/nodes/document_extractor/node.py
+++ b/api/dify_graph/nodes/document_extractor/node.py
@@ -83,8 +83,18 @@ class DocumentExtractorNode(Node[DocumentExtractorNodeData]):
 
         value = variable.value
         inputs = {"variable_selector": variable_selector}
+        if isinstance(value, list):
+            value = list(filter(lambda x: x, value))
         process_data = {"documents": value if isinstance(value, list) else [value]}
 
+        if not value:
+            return NodeRunResult(
+                status=WorkflowNodeExecutionStatus.SUCCEEDED,
+                inputs=inputs,
+                process_data=process_data,
+                outputs={"text": ArrayStringSegment(value=[])},
+            )
+
         try:
             if isinstance(value, list):
                 extracted_text_list = [
@@ -112,6 +122,7 @@ class DocumentExtractorNode(Node[DocumentExtractorNodeData]):
             else:
                 raise DocumentExtractorError(f"Unsupported variable type: {type(value)}")
         except DocumentExtractorError as e:
+            logger.warning(e, exc_info=True)
             return NodeRunResult(
                 status=WorkflowNodeExecutionStatus.FAILED,
                 error=str(e),
diff --git a/api/tests/unit_tests/core/workflow/nodes/test_document_extractor_node.py b/api/tests/unit_tests/core/workflow/nodes/test_document_extractor_node.py
index abdf0954c4..13275d4be6 100644
--- a/api/tests/unit_tests/core/workflow/nodes/test_document_extractor_node.py
+++ b/api/tests/unit_tests/core/workflow/nodes/test_document_extractor_node.py
@@ -87,6 +87,38 @@ def test_run_invalid_variable_type(document_extractor_node, mock_graph_runtime_s
     assert "is not an ArrayFileSegment" in result.error
 
 
+def test_run_empty_file_list_returns_succeeded(document_extractor_node, mock_graph_runtime_state):
+    """Empty file list should return SUCCEEDED with empty documents and ArrayStringSegment([])."""
+    document_extractor_node.graph_runtime_state = mock_graph_runtime_state
+
+    # Provide an actual ArrayFileSegment with an empty list
+    mock_graph_runtime_state.variable_pool.get.return_value = ArrayFileSegment(value=[])
+
+    result = document_extractor_node._run()
+
+    assert isinstance(result, NodeRunResult)
+    assert result.status == WorkflowNodeExecutionStatus.SUCCEEDED, result.error
+    assert result.process_data.get("documents") == []
+    assert result.outputs["text"] == ArrayStringSegment(value=[])
+
+
+def test_run_none_only_file_list_returns_succeeded(document_extractor_node, mock_graph_runtime_state):
+    """A file list containing only None (e.g., [None]) should be filtered to [] and succeed."""
+    document_extractor_node.graph_runtime_state = mock_graph_runtime_state
+
+    # Use a Mock to bypass type validation for None entries in the list
+    afs = Mock(spec=ArrayFileSegment)
+    afs.value = [None]
+    mock_graph_runtime_state.variable_pool.get.return_value = afs
+
+    result = document_extractor_node._run()
+
+    assert isinstance(result, NodeRunResult)
+    assert result.status == WorkflowNodeExecutionStatus.SUCCEEDED, result.error
+    assert result.process_data.get("documents") == []
+    assert result.outputs["text"] == ArrayStringSegment(value=[])
+
+
 @pytest.mark.parametrize(
     ("mime_type", "file_content", "expected_text", "transfer_method", "extension"),
     [

From 0aef09d630b5696284c7441ef7cfa80fc6fd3fdd Mon Sep 17 00:00:00 2001
From: hj24 <mambahj24@gmail.com>
Date: Mon, 9 Mar 2026 14:32:35 +0800
Subject: [PATCH 07/12] feat: support relative mode for message clean command
 (#32834)

---
 api/commands.py                               |  91 +++++++--
 .../conversation/messages_clean_service.py    |   3 +-
 .../commands/test_clean_expired_messages.py   | 181 ++++++++++++++++++
 .../services/test_messages_clean_service.py   |  18 +-
 4 files changed, 269 insertions(+), 24 deletions(-)
 create mode 100644 api/tests/unit_tests/commands/test_clean_expired_messages.py

diff --git a/api/commands.py b/api/commands.py
index 0a3b808950..53ec65f54a 100644
--- a/api/commands.py
+++ b/api/commands.py
@@ -30,6 +30,7 @@ from extensions.ext_redis import redis_client
 from extensions.ext_storage import storage
 from extensions.storage.opendal_storage import OpenDALStorage
 from extensions.storage.storage_type import StorageType
+from libs.datetime_utils import naive_utc_now
 from libs.db_migration_lock import DbMigrationAutoRenewLock
 from libs.helper import email as email_validate
 from libs.password import hash_password, password_pattern, valid_password
@@ -2598,15 +2599,29 @@ def migrate_oss(
 @click.option(
     "--start-from",
     type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
-    required=True,
+    required=False,
+    default=None,
     help="Lower bound (inclusive) for created_at.",
 )
 @click.option(
     "--end-before",
     type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
-    required=True,
+    required=False,
+    default=None,
     help="Upper bound (exclusive) for created_at.",
 )
+@click.option(
+    "--from-days-ago",
+    type=int,
+    default=None,
+    help="Relative lower bound in days ago (inclusive). Must be used with --before-days.",
+)
+@click.option(
+    "--before-days",
+    type=int,
+    default=None,
+    help="Relative upper bound in days ago (exclusive). Required for relative mode.",
+)
 @click.option("--batch-size", default=1000, show_default=True, help="Batch size for selecting messages.")
 @click.option(
     "--graceful-period",
@@ -2618,8 +2633,10 @@ def migrate_oss(
 def clean_expired_messages(
     batch_size: int,
     graceful_period: int,
-    start_from: datetime.datetime,
-    end_before: datetime.datetime,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime | None,
+    from_days_ago: int | None,
+    before_days: int | None,
     dry_run: bool,
 ):
     """
@@ -2630,18 +2647,70 @@ def clean_expired_messages(
     start_at = time.perf_counter()
 
     try:
+        abs_mode = start_from is not None and end_before is not None
+        rel_mode = before_days is not None
+
+        if abs_mode and rel_mode:
+            raise click.UsageError(
+                "Options are mutually exclusive: use either (--start-from,--end-before) "
+                "or (--from-days-ago,--before-days)."
+            )
+
+        if from_days_ago is not None and before_days is None:
+            raise click.UsageError("--from-days-ago must be used together with --before-days.")
+
+        if (start_from is None) ^ (end_before is None):
+            raise click.UsageError("Both --start-from and --end-before are required when using absolute time range.")
+
+        if not abs_mode and not rel_mode:
+            raise click.UsageError(
+                "You must provide either (--start-from,--end-before) or (--before-days [--from-days-ago])."
+            )
+
+        if rel_mode:
+            assert before_days is not None
+            if before_days < 0:
+                raise click.UsageError("--before-days must be >= 0.")
+            if from_days_ago is not None:
+                if from_days_ago < 0:
+                    raise click.UsageError("--from-days-ago must be >= 0.")
+                if from_days_ago <= before_days:
+                    raise click.UsageError("--from-days-ago must be greater than --before-days.")
+
         # Create policy based on billing configuration
         # NOTE: graceful_period will be ignored when billing is disabled.
         policy = create_message_clean_policy(graceful_period_days=graceful_period)
 
         # Create and run the cleanup service
-        service = MessagesCleanService.from_time_range(
-            policy=policy,
-            start_from=start_from,
-            end_before=end_before,
-            batch_size=batch_size,
-            dry_run=dry_run,
-        )
+        if abs_mode:
+            assert start_from is not None
+            assert end_before is not None
+            service = MessagesCleanService.from_time_range(
+                policy=policy,
+                start_from=start_from,
+                end_before=end_before,
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
+        elif from_days_ago is None:
+            assert before_days is not None
+            service = MessagesCleanService.from_days(
+                policy=policy,
+                days=before_days,
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
+        else:
+            assert before_days is not None
+            assert from_days_ago is not None
+            now = naive_utc_now()
+            service = MessagesCleanService.from_time_range(
+                policy=policy,
+                start_from=now - datetime.timedelta(days=from_days_ago),
+                end_before=now - datetime.timedelta(days=before_days),
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
         stats = service.run()
 
         end_at = time.perf_counter()
diff --git a/api/services/retention/conversation/messages_clean_service.py b/api/services/retention/conversation/messages_clean_service.py
index f7836a2b14..04265817d7 100644
--- a/api/services/retention/conversation/messages_clean_service.py
+++ b/api/services/retention/conversation/messages_clean_service.py
@@ -12,6 +12,7 @@ from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
 from extensions.ext_database import db
+from libs.datetime_utils import naive_utc_now
 from models.model import (
     App,
     AppAnnotationHitHistory,
@@ -142,7 +143,7 @@ class MessagesCleanService:
         if batch_size <= 0:
             raise ValueError(f"batch_size ({batch_size}) must be greater than 0")
 
-        end_before = datetime.datetime.now() - datetime.timedelta(days=days)
+        end_before = naive_utc_now() - datetime.timedelta(days=days)
 
         logger.info(
             "clean_messages: days=%s, end_before=%s, batch_size=%s, policy=%s",
diff --git a/api/tests/unit_tests/commands/test_clean_expired_messages.py b/api/tests/unit_tests/commands/test_clean_expired_messages.py
new file mode 100644
index 0000000000..2e55f17981
--- /dev/null
+++ b/api/tests/unit_tests/commands/test_clean_expired_messages.py
@@ -0,0 +1,181 @@
+import datetime
+import re
+from unittest.mock import MagicMock, patch
+
+import click
+import pytest
+
+from commands import clean_expired_messages
+
+
+def _mock_service() -> MagicMock:
+    service = MagicMock()
+    service.run.return_value = {
+        "batches": 1,
+        "total_messages": 10,
+        "filtered_messages": 5,
+        "total_deleted": 5,
+    }
+    return service
+
+
+def test_absolute_mode_calls_from_time_range():
+    policy = object()
+    service = _mock_service()
+    start_from = datetime.datetime(2024, 1, 1, 0, 0, 0)
+    end_before = datetime.datetime(2024, 2, 1, 0, 0, 0)
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_time_range", return_value=service) as mock_from_time_range,
+        patch("commands.MessagesCleanService.from_days") as mock_from_days,
+    ):
+        clean_expired_messages.callback(
+            batch_size=200,
+            graceful_period=21,
+            start_from=start_from,
+            end_before=end_before,
+            from_days_ago=None,
+            before_days=None,
+            dry_run=True,
+        )
+
+    mock_from_time_range.assert_called_once_with(
+        policy=policy,
+        start_from=start_from,
+        end_before=end_before,
+        batch_size=200,
+        dry_run=True,
+    )
+    mock_from_days.assert_not_called()
+
+
+def test_relative_mode_before_days_only_calls_from_days():
+    policy = object()
+    service = _mock_service()
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_days", return_value=service) as mock_from_days,
+        patch("commands.MessagesCleanService.from_time_range") as mock_from_time_range,
+    ):
+        clean_expired_messages.callback(
+            batch_size=500,
+            graceful_period=14,
+            start_from=None,
+            end_before=None,
+            from_days_ago=None,
+            before_days=30,
+            dry_run=False,
+        )
+
+    mock_from_days.assert_called_once_with(
+        policy=policy,
+        days=30,
+        batch_size=500,
+        dry_run=False,
+    )
+    mock_from_time_range.assert_not_called()
+
+
+def test_relative_mode_with_from_days_ago_calls_from_time_range():
+    policy = object()
+    service = _mock_service()
+    fixed_now = datetime.datetime(2024, 8, 20, 12, 0, 0)
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_time_range", return_value=service) as mock_from_time_range,
+        patch("commands.MessagesCleanService.from_days") as mock_from_days,
+        patch("commands.naive_utc_now", return_value=fixed_now),
+    ):
+        clean_expired_messages.callback(
+            batch_size=1000,
+            graceful_period=21,
+            start_from=None,
+            end_before=None,
+            from_days_ago=60,
+            before_days=30,
+            dry_run=False,
+        )
+
+    mock_from_time_range.assert_called_once_with(
+        policy=policy,
+        start_from=fixed_now - datetime.timedelta(days=60),
+        end_before=fixed_now - datetime.timedelta(days=30),
+        batch_size=1000,
+        dry_run=False,
+    )
+    mock_from_days.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        (
+            {
+                "start_from": datetime.datetime(2024, 1, 1),
+                "end_before": datetime.datetime(2024, 2, 1),
+                "from_days_ago": None,
+                "before_days": 30,
+            },
+            "mutually exclusive",
+        ),
+        (
+            {
+                "start_from": datetime.datetime(2024, 1, 1),
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": None,
+            },
+            "Both --start-from and --end-before are required",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": 10,
+                "before_days": None,
+            },
+            "--from-days-ago must be used together with --before-days",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": -1,
+            },
+            "--before-days must be >= 0",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": 30,
+                "before_days": 30,
+            },
+            "--from-days-ago must be greater than --before-days",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": None,
+            },
+            "You must provide either (--start-from,--end-before) or (--before-days [--from-days-ago])",
+        ),
+    ],
+)
+def test_invalid_inputs_raise_usage_error(kwargs: dict, message: str):
+    with pytest.raises(click.UsageError, match=re.escape(message)):
+        clean_expired_messages.callback(
+            batch_size=1000,
+            graceful_period=21,
+            start_from=kwargs["start_from"],
+            end_before=kwargs["end_before"],
+            from_days_ago=kwargs["from_days_ago"],
+            before_days=kwargs["before_days"],
+            dry_run=False,
+        )
diff --git a/api/tests/unit_tests/services/test_messages_clean_service.py b/api/tests/unit_tests/services/test_messages_clean_service.py
index 67ae2c9142..4449b442d6 100644
--- a/api/tests/unit_tests/services/test_messages_clean_service.py
+++ b/api/tests/unit_tests/services/test_messages_clean_service.py
@@ -554,11 +554,9 @@ class TestMessagesCleanServiceFromDays:
             MessagesCleanService.from_days(policy=policy, days=-1)
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 14, 0, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(policy=policy, days=0)
 
         # Assert
@@ -586,11 +584,9 @@ class TestMessagesCleanServiceFromDays:
         dry_run = True
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 10, 30, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(
                 policy=policy,
                 days=days,
@@ -613,11 +609,9 @@ class TestMessagesCleanServiceFromDays:
         policy = BillingDisabledPolicy()
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 10, 30, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(policy=policy)
 
         # Assert

From cbb19cce39843340ff65152954e47e8e08c70f6f Mon Sep 17 00:00:00 2001
From: Sense_wang <167664334+haosenwang1018@users.noreply.github.com>
Date: Mon, 9 Mar 2026 15:02:30 +0800
Subject: [PATCH 08/12] docs: use docker compose command consistently in README
 (#33077)

Co-authored-by: Contributor <contributor@example.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 90961a5346..42ea06cbea 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,7 @@ Star Dify on GitHub and be instantly notified of new releases.
 
 ### Custom configurations
 
-If you need to customize the configuration, please refer to the comments in our [.env.example](docker/.env.example) file and update the corresponding values in your `.env` file. Additionally, you might need to make adjustments to the `docker-compose.yaml` file itself, such as changing image versions, port mappings, or volume mounts, based on your specific deployment environment and requirements. After making any changes, please re-run `docker-compose up -d`. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
+If you need to customize the configuration, please refer to the comments in our [.env.example](docker/.env.example) file and update the corresponding values in your `.env` file. Additionally, you might need to make adjustments to the `docker-compose.yaml` file itself, such as changing image versions, port mappings, or volume mounts, based on your specific deployment environment and requirements. After making any changes, please re-run `docker compose up -d`. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
 
 #### Customizing Suggested Questions
 

From 9970f4449a93acd670a27cda1301c41ee17aec67 Mon Sep 17 00:00:00 2001
From: wangxiaolei <fatelei@gmail.com>
Date: Mon, 9 Mar 2026 15:53:21 +0800
Subject: [PATCH 09/12] refactor: reuse redis connection instead of create new
 one (#32678)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
---
 api/schedule/queue_monitor_task.py            |    4 +
 api/schedule/trigger_provider_refresh_task.py |   20 +-
 api/schedule/workflow_schedule_task.py        |   34 +-
 api/tasks/document_indexing_task.py           |   39 +-
 .../rag_pipeline/rag_pipeline_run_task.py     |   38 +-
 .../tasks/test_dataset_indexing_task.py       |   24 +-
 .../tasks/test_document_indexing_task.py      |   27 +-
 .../tasks/test_rag_pipeline_run_tasks.py      |   91 +-
 .../trigger/conftest.py                       |   12 +-
 .../tasks/test_dataset_indexing_task.py       | 1183 ++++++++++++++++-
 10 files changed, 1360 insertions(+), 112 deletions(-)

diff --git a/api/schedule/queue_monitor_task.py b/api/schedule/queue_monitor_task.py
index 77d6b5a138..01642e397e 100644
--- a/api/schedule/queue_monitor_task.py
+++ b/api/schedule/queue_monitor_task.py
@@ -21,6 +21,10 @@ celery_redis = Redis(
     ssl_cert_reqs=getattr(dify_config, "REDIS_SSL_CERT_REQS", None) if dify_config.BROKER_USE_SSL else None,
     ssl_certfile=getattr(dify_config, "REDIS_SSL_CERTFILE", None) if dify_config.BROKER_USE_SSL else None,
     ssl_keyfile=getattr(dify_config, "REDIS_SSL_KEYFILE", None) if dify_config.BROKER_USE_SSL else None,
+    # Add conservative socket timeouts and health checks to avoid long-lived half-open sockets
+    socket_timeout=5,
+    socket_connect_timeout=5,
+    health_check_interval=30,
 )
 
 logger = logging.getLogger(__name__)
diff --git a/api/schedule/trigger_provider_refresh_task.py b/api/schedule/trigger_provider_refresh_task.py
index 3b3e478793..df5058d70a 100644
--- a/api/schedule/trigger_provider_refresh_task.py
+++ b/api/schedule/trigger_provider_refresh_task.py
@@ -3,6 +3,7 @@ import math
 import time
 from collections.abc import Iterable, Sequence
 
+from celery import group
 from sqlalchemy import ColumnElement, and_, func, or_, select
 from sqlalchemy.engine.row import Row
 from sqlalchemy.orm import Session
@@ -85,20 +86,25 @@ def trigger_provider_refresh() -> None:
             lock_keys: list[str] = build_trigger_refresh_lock_keys(subscriptions)
             acquired: list[bool] = _acquire_locks(keys=lock_keys, ttl_seconds=lock_ttl)
 
-            enqueued: int = 0
-            for (tenant_id, subscription_id), is_locked in zip(subscriptions, acquired):
-                if not is_locked:
-                    continue
-                trigger_subscription_refresh.delay(tenant_id=tenant_id, subscription_id=subscription_id)
-                enqueued += 1
+            if not any(acquired):
+                continue
+
+            jobs = [
+                trigger_subscription_refresh.s(tenant_id=tenant_id, subscription_id=subscription_id)
+                for (tenant_id, subscription_id), is_locked in zip(subscriptions, acquired)
+                if is_locked
+            ]
+            result = group(jobs).apply_async()
+            enqueued = len(jobs)
 
             logger.info(
-                "Trigger refresh page %d/%d: scanned=%d locks_acquired=%d enqueued=%d",
+                "Trigger refresh page %d/%d: scanned=%d locks_acquired=%d enqueued=%d result=%s",
                 page + 1,
                 pages,
                 len(subscriptions),
                 sum(1 for x in acquired if x),
                 enqueued,
+                result,
             )
 
     logger.info("Trigger refresh scan done: due=%d", total_due)
diff --git a/api/schedule/workflow_schedule_task.py b/api/schedule/workflow_schedule_task.py
index d68b9565ec..2fee9e467d 100644
--- a/api/schedule/workflow_schedule_task.py
+++ b/api/schedule/workflow_schedule_task.py
@@ -1,6 +1,6 @@
 import logging
 
-from celery import group, shared_task
+from celery import current_app, group, shared_task
 from sqlalchemy import and_, select
 from sqlalchemy.orm import Session, sessionmaker
 
@@ -29,31 +29,27 @@ def poll_workflow_schedules() -> None:
     with session_factory() as session:
         total_dispatched = 0
 
-        # Process in batches until we've handled all due schedules or hit the limit
         while True:
             due_schedules = _fetch_due_schedules(session)
 
             if not due_schedules:
                 break
 
-            dispatched_count = _process_schedules(session, due_schedules)
-            total_dispatched += dispatched_count
+            with current_app.producer_or_acquire() as producer:  # type: ignore
+                dispatched_count = _process_schedules(session, due_schedules, producer)
+                total_dispatched += dispatched_count
 
-            logger.debug("Batch processed: %d dispatched", dispatched_count)
-
-            # Circuit breaker: check if we've hit the per-tick limit (if enabled)
-            if (
-                dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK > 0
-                and total_dispatched >= dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK
-            ):
-                logger.warning(
-                    "Circuit breaker activated: reached dispatch limit (%d), will continue next tick",
-                    dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK,
-                )
-                break
+                logger.debug("Batch processed: %d dispatched", dispatched_count)
 
+                # Circuit breaker: check if we've hit the per-tick limit (if enabled)
+                if 0 < dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK <= total_dispatched:
+                    logger.warning(
+                        "Circuit breaker activated: reached dispatch limit (%d), will continue next tick",
+                        dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK,
+                    )
+                    break
         if total_dispatched > 0:
-            logger.info("Total processed: %d dispatched", total_dispatched)
+            logger.info("Total processed: %d workflow schedule(s) dispatched", total_dispatched)
 
 
 def _fetch_due_schedules(session: Session) -> list[WorkflowSchedulePlan]:
@@ -90,7 +86,7 @@ def _fetch_due_schedules(session: Session) -> list[WorkflowSchedulePlan]:
     return list(due_schedules)
 
 
-def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan]) -> int:
+def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan], producer=None) -> int:
     """Process schedules: check quota, update next run time and dispatch to Celery in parallel."""
     if not schedules:
         return 0
@@ -107,7 +103,7 @@ def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan])
 
     if tasks_to_dispatch:
         job = group(run_schedule_trigger.s(schedule_id) for schedule_id in tasks_to_dispatch)
-        job.apply_async()
+        job.apply_async(producer=producer)
 
         logger.debug("Dispatched %d tasks in parallel", len(tasks_to_dispatch))
 
diff --git a/api/tasks/document_indexing_task.py b/api/tasks/document_indexing_task.py
index 11edcf151f..b3f36d8f44 100644
--- a/api/tasks/document_indexing_task.py
+++ b/api/tasks/document_indexing_task.py
@@ -1,9 +1,10 @@
 import logging
 import time
-from collections.abc import Callable, Sequence
+from collections.abc import Sequence
+from typing import Any, Protocol
 
 import click
-from celery import shared_task
+from celery import current_app, shared_task
 
 from configs import dify_config
 from core.db.session_factory import session_factory
@@ -19,6 +20,12 @@ from tasks.generate_summary_index_task import generate_summary_index_task
 logger = logging.getLogger(__name__)
 
 
+class CeleryTaskLike(Protocol):
+    def delay(self, *args: Any, **kwargs: Any) -> Any: ...
+
+    def apply_async(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
 @shared_task(queue="dataset")
 def document_indexing_task(dataset_id: str, document_ids: list):
     """
@@ -179,8 +186,8 @@ def _document_indexing(dataset_id: str, document_ids: Sequence[str]):
 
 
 def _document_indexing_with_tenant_queue(
-    tenant_id: str, dataset_id: str, document_ids: Sequence[str], task_func: Callable[[str, str, Sequence[str]], None]
-):
+    tenant_id: str, dataset_id: str, document_ids: Sequence[str], task_func: CeleryTaskLike
+) -> None:
     try:
         _document_indexing(dataset_id, document_ids)
     except Exception:
@@ -201,16 +208,20 @@ def _document_indexing_with_tenant_queue(
         logger.info("document indexing tenant isolation queue %s next tasks: %s", tenant_id, next_tasks)
 
         if next_tasks:
-            for next_task in next_tasks:
-                document_task = DocumentTask(**next_task)
-                # Process the next waiting task
-                # Keep the flag set to indicate a task is running
-                tenant_isolated_task_queue.set_task_waiting_time()
-                task_func.delay(  # type: ignore
-                    tenant_id=document_task.tenant_id,
-                    dataset_id=document_task.dataset_id,
-                    document_ids=document_task.document_ids,
-                )
+            with current_app.producer_or_acquire() as producer:  # type: ignore
+                for next_task in next_tasks:
+                    document_task = DocumentTask(**next_task)
+                    # Keep the flag set to indicate a task is running
+                    tenant_isolated_task_queue.set_task_waiting_time()
+                    task_func.apply_async(
+                        kwargs={
+                            "tenant_id": document_task.tenant_id,
+                            "dataset_id": document_task.dataset_id,
+                            "document_ids": document_task.document_ids,
+                        },
+                        producer=producer,
+                    )
+
         else:
             # No more waiting tasks, clear the flag
             tenant_isolated_task_queue.delete_task_key()
diff --git a/api/tasks/rag_pipeline/rag_pipeline_run_task.py b/api/tasks/rag_pipeline/rag_pipeline_run_task.py
index 093342d1a3..52f66dddb8 100644
--- a/api/tasks/rag_pipeline/rag_pipeline_run_task.py
+++ b/api/tasks/rag_pipeline/rag_pipeline_run_task.py
@@ -3,12 +3,13 @@ import json
 import logging
 import time
 import uuid
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from concurrent.futures import ThreadPoolExecutor
+from itertools import islice
 from typing import Any
 
 import click
-from celery import shared_task  # type: ignore
+from celery import group, shared_task
 from flask import current_app, g
 from sqlalchemy.orm import Session, sessionmaker
 
@@ -27,6 +28,11 @@ from services.file_service import FileService
 logger = logging.getLogger(__name__)
 
 
+def chunked(iterable: Sequence, size: int):
+    it = iter(iterable)
+    return iter(lambda: list(islice(it, size)), [])
+
+
 @shared_task(queue="pipeline")
 def rag_pipeline_run_task(
     rag_pipeline_invoke_entities_file_id: str,
@@ -83,16 +89,24 @@ def rag_pipeline_run_task(
         logger.info("rag pipeline tenant isolation queue %s next files: %s", tenant_id, next_file_ids)
 
         if next_file_ids:
-            for next_file_id in next_file_ids:
-                # Process the next waiting task
-                # Keep the flag set to indicate a task is running
-                tenant_isolated_task_queue.set_task_waiting_time()
-                rag_pipeline_run_task.delay(  # type: ignore
-                    rag_pipeline_invoke_entities_file_id=next_file_id.decode("utf-8")
-                    if isinstance(next_file_id, bytes)
-                    else next_file_id,
-                    tenant_id=tenant_id,
-                )
+            for batch in chunked(next_file_ids, 100):
+                jobs = []
+                for next_file_id in batch:
+                    tenant_isolated_task_queue.set_task_waiting_time()
+
+                    file_id = (
+                        next_file_id.decode("utf-8") if isinstance(next_file_id, (bytes, bytearray)) else next_file_id
+                    )
+
+                    jobs.append(
+                        rag_pipeline_run_task.s(
+                            rag_pipeline_invoke_entities_file_id=file_id,
+                            tenant_id=tenant_id,
+                        )
+                    )
+
+                if jobs:
+                    group(jobs).apply_async()
         else:
             # No more waiting tasks, clear the flag
             tenant_isolated_task_queue.delete_task_key()
diff --git a/api/tests/test_containers_integration_tests/tasks/test_dataset_indexing_task.py b/api/tests/test_containers_integration_tests/tasks/test_dataset_indexing_task.py
index 207bdad751..4a62383590 100644
--- a/api/tests/test_containers_integration_tests/tasks/test_dataset_indexing_task.py
+++ b/api/tests/test_containers_integration_tests/tasks/test_dataset_indexing_task.py
@@ -322,11 +322,14 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_called_once_with(
-            tenant_id=next_task["tenant_id"],
-            dataset_id=next_task["dataset_id"],
-            document_ids=next_task["document_ids"],
-        )
+        # apply_async is used by implementation; assert it was called once with expected kwargs
+        assert task_dispatch_spy.apply_async.call_count == 1
+        call_kwargs = task_dispatch_spy.apply_async.call_args.kwargs.get("kwargs", {})
+        assert call_kwargs == {
+            "tenant_id": next_task["tenant_id"],
+            "dataset_id": next_task["dataset_id"],
+            "document_ids": next_task["document_ids"],
+        }
         set_waiting_spy.assert_called_once()
         delete_key_spy.assert_not_called()
 
@@ -352,7 +355,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_not_called()
+        task_dispatch_spy.apply_async.assert_not_called()
         delete_key_spy.assert_called_once()
 
     def test_validation_failure_sets_error_status_when_vector_space_at_limit(
@@ -447,7 +450,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_called_once()
+        task_dispatch_spy.apply_async.assert_called_once()
 
     def test_sessions_close_on_successful_indexing(
         self,
@@ -534,7 +537,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        assert task_dispatch_spy.delay.call_count == concurrency_limit
+        assert task_dispatch_spy.apply_async.call_count == concurrency_limit
         assert set_waiting_spy.call_count == concurrency_limit
 
     def test_task_queue_fifo_ordering(self, db_session_with_containers, patched_external_dependencies):
@@ -565,9 +568,10 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        assert task_dispatch_spy.delay.call_count == 3
+        assert task_dispatch_spy.apply_async.call_count == 3
         for index, expected_task in enumerate(ordered_tasks):
-            assert task_dispatch_spy.delay.call_args_list[index].kwargs["document_ids"] == expected_task["document_ids"]
+            call_kwargs = task_dispatch_spy.apply_async.call_args_list[index].kwargs.get("kwargs", {})
+            assert call_kwargs.get("document_ids") == expected_task["document_ids"]
 
     def test_billing_disabled_skips_limit_checks(self, db_session_with_containers, patched_external_dependencies):
         """Skip limit checks when billing feature is disabled."""
diff --git a/api/tests/test_containers_integration_tests/tasks/test_document_indexing_task.py b/api/tests/test_containers_integration_tests/tasks/test_document_indexing_task.py
index 4be1180c73..5dc1f6bee0 100644
--- a/api/tests/test_containers_integration_tests/tasks/test_document_indexing_task.py
+++ b/api/tests/test_containers_integration_tests/tasks/test_document_indexing_task.py
@@ -762,11 +762,12 @@ class TestDocumentIndexingTasks:
         mock_external_service_dependencies["indexing_runner_instance"].run.assert_called_once()
 
         # Verify task function was called for each waiting task
-        assert mock_task_func.delay.call_count == 1
+        assert mock_task_func.apply_async.call_count == 1
 
         # Verify correct parameters for each call
-        calls = mock_task_func.delay.call_args_list
-        assert calls[0][1] == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
+        calls = mock_task_func.apply_async.call_args_list
+        sent_kwargs = calls[0][1]["kwargs"]
+        assert sent_kwargs == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
 
         # Verify queue is empty after processing (tasks were pulled)
         remaining_tasks = queue.pull_tasks(count=10)  # Pull more than we added
@@ -830,11 +831,15 @@ class TestDocumentIndexingTasks:
             assert updated_document.processing_started_at is not None
 
         # Verify waiting task was still processed despite core processing error
-        mock_task_func.delay.assert_called_once()
+        mock_task_func.apply_async.assert_called_once()
 
         # Verify correct parameters for the call
-        call = mock_task_func.delay.call_args
-        assert call[1] == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
+        call = mock_task_func.apply_async.call_args
+        assert call[1]["kwargs"] == {
+            "tenant_id": tenant_id,
+            "dataset_id": dataset_id,
+            "document_ids": ["waiting-doc-1"],
+        }
 
         # Verify queue is empty after processing (task was pulled)
         remaining_tasks = queue.pull_tasks(count=10)
@@ -896,9 +901,13 @@ class TestDocumentIndexingTasks:
         mock_external_service_dependencies["indexing_runner_instance"].run.assert_called_once()
 
         # Verify only tenant1's waiting task was processed
-        mock_task_func.delay.assert_called_once()
-        call = mock_task_func.delay.call_args
-        assert call[1] == {"tenant_id": tenant1_id, "dataset_id": dataset1_id, "document_ids": ["tenant1-doc-1"]}
+        mock_task_func.apply_async.assert_called_once()
+        call = mock_task_func.apply_async.call_args
+        assert call[1]["kwargs"] == {
+            "tenant_id": tenant1_id,
+            "dataset_id": dataset1_id,
+            "document_ids": ["tenant1-doc-1"],
+        }
 
         # Verify tenant1's queue is empty
         remaining_tasks1 = queue1.pull_tasks(count=10)
diff --git a/api/tests/test_containers_integration_tests/tasks/test_rag_pipeline_run_tasks.py b/api/tests/test_containers_integration_tests/tasks/test_rag_pipeline_run_tasks.py
index ef7191299a..f01fcc1742 100644
--- a/api/tests/test_containers_integration_tests/tasks/test_rag_pipeline_run_tasks.py
+++ b/api/tests/test_containers_integration_tests/tasks/test_rag_pipeline_run_tasks.py
@@ -1,6 +1,6 @@
 import json
 import uuid
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 from faker import Faker
@@ -388,8 +388,10 @@ class TestRagPipelineRunTasks:
         # Set the task key to indicate there are waiting tasks (legacy behavior)
         redis_client.set(legacy_task_key, 1, ex=60 * 60)
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the priority task with new code but legacy queue data
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -398,13 +400,14 @@ class TestRagPipelineRunTasks:
             mock_file_service["delete_file"].assert_called_once_with(file_id)
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify waiting tasks were processed, pull 1 task a time by default
-            assert mock_delay.call_count == 1
+            # Verify waiting tasks were processed via group, pull 1 task a time by default
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == legacy_file_ids[0]
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == legacy_file_ids[0]
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify that new code can process legacy queue entries
             # The new TenantIsolatedTaskQueue should be able to read from the legacy format
@@ -446,8 +449,10 @@ class TestRagPipelineRunTasks:
         waiting_file_ids = [str(uuid.uuid4()) for _ in range(3)]
         queue.push_tasks(waiting_file_ids)
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -456,13 +461,14 @@ class TestRagPipelineRunTasks:
             mock_file_service["delete_file"].assert_called_once_with(file_id)
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify waiting tasks were processed, pull 1 task a time by default
-            assert mock_delay.call_count == 1
+            # Verify waiting tasks were processed via group.apply_async
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_ids[0]
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_ids[0]
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue still has remaining tasks (only 1 was pulled)
             remaining_tasks = queue.pull_tasks(count=10)
@@ -557,8 +563,10 @@ class TestRagPipelineRunTasks:
         waiting_file_id = str(uuid.uuid4())
         queue.push_tasks([waiting_file_id])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task (should not raise exception)
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -569,12 +577,13 @@ class TestRagPipelineRunTasks:
             assert mock_pipeline_generator.call_count == 1
 
             # Verify waiting task was still processed despite core processing error
-            mock_delay.assert_called_once()
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue is empty after processing (task was pulled)
             remaining_tasks = queue.pull_tasks(count=10)
@@ -684,8 +693,10 @@ class TestRagPipelineRunTasks:
         queue1.push_tasks([waiting_file_id1])
         queue2.push_tasks([waiting_file_id2])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task for tenant1 only
             rag_pipeline_run_task(file_id1, tenant1.id)
 
@@ -694,11 +705,12 @@ class TestRagPipelineRunTasks:
             assert mock_file_service["delete_file"].call_count == 1
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify only tenant1's waiting task was processed
-            mock_delay.assert_called_once()
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id1
-            assert call_kwargs.get("tenant_id") == tenant1.id
+            # Verify only tenant1's waiting task was processed (via group)
+            assert mock_group.return_value.apply_async.called
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id1
+            assert first_kwargs.get("tenant_id") == tenant1.id
 
             # Verify tenant1's queue is empty
             remaining_tasks1 = queue1.pull_tasks(count=10)
@@ -913,8 +925,10 @@ class TestRagPipelineRunTasks:
         waiting_file_id = str(uuid.uuid4())
         queue.push_tasks([waiting_file_id])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act & Assert: Execute the regular task (should raise Exception)
             with pytest.raises(Exception, match="File not found"):
                 rag_pipeline_run_task(file_id, tenant.id)
@@ -924,12 +938,13 @@ class TestRagPipelineRunTasks:
             mock_pipeline_generator.assert_not_called()
 
             # Verify waiting task was still processed despite file error
-            mock_delay.assert_called_once()
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue is empty after processing (task was pulled)
             remaining_tasks = queue.pull_tasks(count=10)
diff --git a/api/tests/test_containers_integration_tests/trigger/conftest.py b/api/tests/test_containers_integration_tests/trigger/conftest.py
index 9c1fd5e0ec..e3832fb2ef 100644
--- a/api/tests/test_containers_integration_tests/trigger/conftest.py
+++ b/api/tests/test_containers_integration_tests/trigger/conftest.py
@@ -105,18 +105,26 @@ def app_model(
 
 
 class MockCeleryGroup:
-    """Mock for celery group() function that collects dispatched tasks."""
+    """Mock for celery group() function that collects dispatched tasks.
+
+    Matches the Celery group API loosely, accepting arbitrary kwargs on apply_async
+    (e.g. producer) so production code can pass broker-related options without
+    breaking tests.
+    """
 
     def __init__(self) -> None:
         self.collected: list[dict[str, Any]] = []
         self._applied = False
+        self.last_apply_async_kwargs: dict[str, Any] | None = None
 
     def __call__(self, items: Any) -> MockCeleryGroup:
         self.collected = list(items)
         return self
 
-    def apply_async(self) -> None:
+    def apply_async(self, **kwargs: Any) -> None:
+        # Accept arbitrary kwargs like producer to be compatible with Celery
         self._applied = True
+        self.last_apply_async_kwargs = kwargs
 
     @property
     def applied(self) -> bool:
diff --git a/api/tests/unit_tests/tasks/test_dataset_indexing_task.py b/api/tests/unit_tests/tasks/test_dataset_indexing_task.py
index 11b4663187..67e0a8efaf 100644
--- a/api/tests/unit_tests/tasks/test_dataset_indexing_task.py
+++ b/api/tests/unit_tests/tasks/test_dataset_indexing_task.py
@@ -10,14 +10,23 @@ This module tests the document indexing task functionality including:
 """
 
 import uuid
-from unittest.mock import Mock, patch
+from unittest.mock import MagicMock, Mock, patch
 
 import pytest
 
+from core.indexing_runner import DocumentIsPausedError
 from core.rag.pipeline.queue import TenantIsolatedTaskQueue
 from enums.cloud_plan import CloudPlan
 from extensions.ext_redis import redis_client
+from models.dataset import Dataset, Document
 from services.document_indexing_proxy.document_indexing_task_proxy import DocumentIndexingTaskProxy
+from tasks.document_indexing_task import (
+    _document_indexing,
+    _document_indexing_with_tenant_queue,
+    document_indexing_task,
+    normal_document_indexing_task,
+    priority_document_indexing_task,
+)
 
 # ============================================================================
 # Fixtures
@@ -56,6 +65,190 @@ def mock_redis():
     return redis_client
 
 
+# Additional fixtures required by tests in this module
+
+
+@pytest.fixture
+def mock_db_session():
+    """Mock session_factory.create_session() to return a session whose queries use shared test data.
+
+    Tests set session._shared_data = {"dataset": <Dataset>, "documents": [<Document>, ...]}
+    This fixture makes session.query(Dataset).first() return the shared dataset,
+    and session.query(Document).all()/first() return from the shared documents.
+    """
+    with patch("tasks.document_indexing_task.session_factory") as mock_sf:
+        session = MagicMock()
+        session._shared_data = {"dataset": None, "documents": []}
+
+        # Keep a pointer so repeated Document.first() calls iterate across provided docs
+        session._doc_first_idx = 0
+
+        def _query_side_effect(model):
+            q = MagicMock()
+
+            # Capture filters passed via where(...) so first()/all() can honor them.
+            q._filters = {}
+
+            def _extract_filters(*conds, **kw):
+                # Support both SQLAlchemy expressions (BinaryExpression) and kwargs
+                # We only need the simple fields used by production code: id, dataset_id, and id.in_(...)
+                for cond in conds:
+                    left = getattr(cond, "left", None)
+                    right = getattr(cond, "right", None)
+                    key = None
+                    if left is not None:
+                        key = getattr(left, "key", None) or getattr(left, "name", None)
+                    if not key:
+                        continue
+                    # Right side might be a BindParameter with .value, or a raw value/sequence
+                    val = getattr(right, "value", right)
+                    q._filters[key] = val
+                # Also accept kwargs (e.g., where(id=...)) just in case
+                for k, v in kw.items():
+                    q._filters[k] = v
+
+            def _where_side_effect(*conds, **kw):
+                _extract_filters(*conds, **kw)
+                return q
+
+            q.where.side_effect = _where_side_effect
+
+            # Dataset queries
+            if model.__name__ == "Dataset":
+
+                def _dataset_first():
+                    ds = session._shared_data.get("dataset")
+                    if not ds:
+                        return None
+                    if "id" in q._filters:
+                        val = q._filters["id"]
+                        if isinstance(val, (list, tuple, set)):
+                            return ds if ds.id in val else None
+                        return ds if ds.id == val else None
+                    return ds
+
+                def _dataset_all():
+                    ds = session._shared_data.get("dataset")
+                    if not ds:
+                        return []
+                    first = _dataset_first()
+                    return [first] if first else []
+
+                q.first.side_effect = _dataset_first
+                q.all.side_effect = _dataset_all
+                return q
+
+            # Document queries
+            if model.__name__ == "Document":
+
+                def _apply_doc_filters(docs):
+                    result = list(docs)
+                    for key in ("id", "dataset_id"):
+                        if key in q._filters:
+                            val = q._filters[key]
+                            if isinstance(val, (list, tuple, set)):
+                                result = [d for d in result if getattr(d, key, None) in val]
+                            else:
+                                result = [d for d in result if getattr(d, key, None) == val]
+                    return result
+
+                def _docs_all():
+                    docs = session._shared_data.get("documents", [])
+                    return _apply_doc_filters(docs)
+
+                def _docs_first():
+                    docs = _docs_all()
+                    return docs[0] if docs else None
+
+                q.all.side_effect = _docs_all
+                q.first.side_effect = _docs_first
+                return q
+
+            # Default fallback
+            q.first.return_value = None
+            q.all.return_value = []
+            return q
+
+        session.query.side_effect = _query_side_effect
+
+        # Implement session.begin() context manager that commits on exit
+        session.commit = MagicMock()
+        bm = MagicMock()
+        bm.__enter__.return_value = session
+
+        def _bm_exit_side_effect(*args, **kwargs):
+            session.commit()
+
+        bm.__exit__.side_effect = _bm_exit_side_effect
+        session.begin.return_value = bm
+
+        # Context manager behavior for create_session(): ensure close() is called on exit
+        session.close = MagicMock()
+        cm = MagicMock()
+        cm.__enter__.return_value = session
+
+        def _exit_side_effect(*args, **kwargs):
+            session.close()
+
+        cm.__exit__.side_effect = _exit_side_effect
+        mock_sf.create_session.return_value = cm
+
+        yield session
+
+
+@pytest.fixture
+def mock_dataset(dataset_id, tenant_id):
+    """Create a mock Dataset object."""
+    dataset = Mock(spec=Dataset)
+    dataset.id = dataset_id
+    dataset.tenant_id = tenant_id
+    dataset.indexing_technique = "high_quality"
+    dataset.embedding_model_provider = "openai"
+    dataset.embedding_model = "text-embedding-ada-002"
+    return dataset
+
+
+@pytest.fixture
+def mock_documents(document_ids, dataset_id):
+    """Create mock Document objects."""
+    documents = []
+    for doc_id in document_ids:
+        doc = Mock(spec=Document)
+        doc.id = doc_id
+        doc.dataset_id = dataset_id
+        doc.indexing_status = "waiting"
+        doc.error = None
+        doc.stopped_at = None
+        doc.processing_started_at = None
+        # optional attribute used in some code paths
+        doc.doc_form = "text_model"
+        documents.append(doc)
+    return documents
+
+
+@pytest.fixture
+def mock_indexing_runner():
+    """Mock IndexingRunner for document_indexing_task module."""
+    with patch("tasks.document_indexing_task.IndexingRunner") as mock_runner_class:
+        mock_runner = MagicMock()
+        mock_runner_class.return_value = mock_runner
+        yield mock_runner
+
+
+@pytest.fixture
+def mock_feature_service():
+    """Mock FeatureService for document_indexing_task module."""
+    with patch("tasks.document_indexing_task.FeatureService") as mock_service:
+        mock_features = Mock()
+        mock_features.billing = Mock()
+        mock_features.billing.enabled = False
+        mock_features.vector_space = Mock()
+        mock_features.vector_space.size = 0
+        mock_features.vector_space.limit = 1000
+        mock_service.get_features.return_value = mock_features
+        yield mock_service
+
+
 # ============================================================================
 # Test Task Enqueuing
 # ============================================================================
@@ -166,6 +359,492 @@ class TestTaskEnqueuing:
                 assert mock_redis.lpush.called
                 mock_task.delay.assert_not_called()
 
+    def test_legacy_document_indexing_task_still_works(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_documents, mock_indexing_runner
+    ):
+        """
+        Test that the legacy document_indexing_task function still works.
+
+        This ensures backward compatibility for existing code that may still
+        use the deprecated function.
+        """
+        # Arrange
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            document_indexing_task(dataset_id, document_ids)
+
+            # Assert
+            mock_indexing_runner.run.assert_called_once()
+
+
+# ============================================================================
+# Test Batch Processing
+# ============================================================================
+
+
+class TestBatchProcessing:
+    """Test cases for batch processing of multiple documents."""
+
+    def test_batch_processing_multiple_documents(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test batch processing of multiple documents.
+
+        All documents in the batch should be processed together and their
+        status should be updated to 'parsing'.
+        """
+        # Arrange - Create actual document objects that can be modified
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.error = None
+            doc.stopped_at = None
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - All documents should be set to 'parsing' status
+            for doc in mock_documents:
+                assert doc.indexing_status == "parsing"
+                assert doc.processing_started_at is not None
+
+            # IndexingRunner should be called with all documents
+            mock_indexing_runner.run.assert_called_once()
+            call_args = mock_indexing_runner.run.call_args[0][0]
+            assert len(call_args) == len(document_ids)
+
+    def test_batch_processing_with_limit_check(self, dataset_id, mock_db_session, mock_dataset, mock_feature_service):
+        """
+        Test batch processing respects upload limits.
+
+        When the number of documents exceeds the batch upload limit,
+        an error should be raised and all documents should be marked as error.
+        """
+        # Arrange
+        batch_limit = 10
+        document_ids = [str(uuid.uuid4()) for _ in range(batch_limit + 1)]
+
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.error = None
+            doc.stopped_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        mock_feature_service.get_features.return_value.billing.enabled = True
+        mock_feature_service.get_features.return_value.billing.subscription.plan = CloudPlan.PROFESSIONAL
+        mock_feature_service.get_features.return_value.vector_space.limit = 1000
+        mock_feature_service.get_features.return_value.vector_space.size = 0
+
+        with patch("tasks.document_indexing_task.dify_config.BATCH_UPLOAD_LIMIT", str(batch_limit)):
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - All documents should have error status
+            for doc in mock_documents:
+                assert doc.indexing_status == "error"
+                assert doc.error is not None
+                assert "batch upload limit" in doc.error
+
+    def test_batch_processing_sandbox_plan_single_document_only(
+        self, dataset_id, mock_db_session, mock_dataset, mock_feature_service
+    ):
+        """
+        Test that sandbox plan only allows single document upload.
+
+        Sandbox plan should reject batch uploads (more than 1 document).
+        """
+        # Arrange
+        document_ids = [str(uuid.uuid4()) for _ in range(2)]
+
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.error = None
+            doc.stopped_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        mock_feature_service.get_features.return_value.billing.enabled = True
+        mock_feature_service.get_features.return_value.billing.subscription.plan = CloudPlan.SANDBOX
+        mock_feature_service.get_features.return_value.vector_space.limit = 1000
+        mock_feature_service.get_features.return_value.vector_space.size = 0
+
+        # Act
+        _document_indexing(dataset_id, document_ids)
+
+        # Assert - All documents should have error status
+        for doc in mock_documents:
+            assert doc.indexing_status == "error"
+            assert "does not support batch upload" in doc.error
+
+    def test_batch_processing_empty_document_list(
+        self, dataset_id, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test batch processing with empty document list.
+
+        Should handle empty list gracefully without errors.
+        """
+        # Arrange
+        document_ids = []
+
+        # Set shared mock data with empty documents list
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = []
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - IndexingRunner should still be called with empty list
+            mock_indexing_runner.run.assert_called_once_with([])
+
+
+# ============================================================================
+# Test Progress Tracking
+# ============================================================================
+
+
+class TestProgressTracking:
+    """Test cases for progress tracking through task lifecycle."""
+
+    def test_document_status_progression(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test document status progresses correctly through lifecycle.
+
+        Documents should transition from 'waiting' -> 'parsing' -> processed.
+        """
+        # Arrange - Create actual document objects
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - Status should be 'parsing'
+            for doc in mock_documents:
+                assert doc.indexing_status == "parsing"
+                assert doc.processing_started_at is not None
+
+            # Verify commit was called to persist status
+            assert mock_db_session.commit.called
+
+    def test_processing_started_timestamp_set(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test that processing_started_at timestamp is set correctly.
+
+        When documents start processing, the timestamp should be recorded.
+        """
+        # Arrange - Create actual document objects
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert
+            for doc in mock_documents:
+                assert doc.processing_started_at is not None
+
+    def test_tenant_queue_processes_next_task_after_completion(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test that tenant queue processes next waiting task after completion.
+
+        After a task completes, the system should check for waiting tasks
+        and process the next one.
+        """
+        # Arrange
+        next_task_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["next_doc_id"]}
+
+        # Simulate next task in queue
+        from core.rag.pipeline.queue import TaskWrapper
+
+        wrapper = TaskWrapper(data=next_task_data)
+        mock_redis.rpop.return_value = wrapper.serialize()
+
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert - Next task should be enqueued
+                mock_task.apply_async.assert_called()
+                # Task key should be set for next task
+                assert mock_redis.setex.called
+
+    def test_tenant_queue_clears_flag_when_no_more_tasks(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test that tenant queue clears flag when no more tasks are waiting.
+
+        When there are no more tasks in the queue, the task key should be deleted.
+        """
+        # Arrange
+        mock_redis.rpop.return_value = None  # No more tasks
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert - Task key should be deleted
+                assert mock_redis.delete.called
+
+
+# ============================================================================
+# Test Error Handling and Retries
+# ============================================================================
+
+
+class TestErrorHandling:
+    """Test cases for error handling and retry mechanisms."""
+
+    def test_error_handling_sets_document_error_status(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_feature_service
+    ):
+        """
+        Test that errors during validation set document error status.
+
+        When validation fails (e.g., limit exceeded), documents should be
+        marked with error status and error message.
+        """
+        # Arrange - Create actual document objects
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.error = None
+            doc.stopped_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Set up to trigger vector space limit error
+        mock_feature_service.get_features.return_value.billing.enabled = True
+        mock_feature_service.get_features.return_value.billing.subscription.plan = CloudPlan.PROFESSIONAL
+        mock_feature_service.get_features.return_value.vector_space.limit = 100
+        mock_feature_service.get_features.return_value.vector_space.size = 100  # At limit
+
+        # Act
+        _document_indexing(dataset_id, document_ids)
+
+        # Assert
+        for doc in mock_documents:
+            assert doc.indexing_status == "error"
+            assert doc.error is not None
+            assert "over the limit" in doc.error
+            assert doc.stopped_at is not None
+
+    def test_error_handling_during_indexing_runner(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_documents, mock_indexing_runner
+    ):
+        """
+        Test error handling when IndexingRunner raises an exception.
+
+        Errors during indexing should be caught and logged, but not crash the task.
+        """
+        # Arrange
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Make IndexingRunner raise an exception
+        mock_indexing_runner.run.side_effect = Exception("Indexing failed")
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act - Should not raise exception
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - Session should be closed even after error
+            assert mock_db_session.close.called
+
+    def test_document_paused_error_handling(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_documents, mock_indexing_runner
+    ):
+        """
+        Test handling of DocumentIsPausedError.
+
+        When a document is paused, the error should be caught and logged
+        but not treated as a failure.
+        """
+        # Arrange
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Make IndexingRunner raise DocumentIsPausedError
+        mock_indexing_runner.run.side_effect = DocumentIsPausedError("Document is paused")
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act - Should not raise exception
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - Session should be closed
+            assert mock_db_session.close.called
+
+    def test_dataset_not_found_error_handling(self, dataset_id, document_ids, mock_db_session):
+        """
+        Test handling when dataset is not found.
+
+        If the dataset doesn't exist, the task should exit gracefully.
+        """
+        # Arrange
+        mock_db_session.query.return_value.where.return_value.first.return_value = None
+
+        # Act
+        _document_indexing(dataset_id, document_ids)
+
+        # Assert - Session should be closed
+        assert mock_db_session.close.called
+
+    def test_tenant_queue_error_handling_still_processes_next_task(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test that errors don't prevent processing next task in tenant queue.
+
+        Even if the current task fails, the next task should still be processed.
+        """
+        # Arrange
+        next_task_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["next_doc_id"]}
+
+        from core.rag.pipeline.queue import TaskWrapper
+
+        wrapper = TaskWrapper(data=next_task_data)
+        # Set up rpop to return task once for concurrency check
+        mock_redis.rpop.side_effect = [wrapper.serialize(), None]
+
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        # Make _document_indexing raise an error
+        with patch("tasks.document_indexing_task._document_indexing") as mock_indexing:
+            mock_indexing.side_effect = Exception("Processing failed")
+
+            # Patch logger to avoid format string issue in actual code
+            with patch("tasks.document_indexing_task.logger"):
+                with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                    # Act
+                    _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                    # Assert - Next task should still be enqueued despite error
+                    mock_task.apply_async.assert_called()
+
+    def test_concurrent_task_limit_respected(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset
+    ):
+        """
+        Test that tenant isolated task concurrency limit is respected.
+
+        Should pull only TENANT_ISOLATED_TASK_CONCURRENCY tasks at a time.
+        """
+        # Arrange
+        concurrency_limit = 2
+
+        # Create multiple tasks in queue
+        tasks = []
+        for i in range(5):
+            task_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": [f"doc_{i}"]}
+            from core.rag.pipeline.queue import TaskWrapper
+
+            wrapper = TaskWrapper(data=task_data)
+            tasks.append(wrapper.serialize())
+
+        # Mock rpop to return tasks one by one
+        mock_redis.rpop.side_effect = tasks[:concurrency_limit] + [None]
+
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.dify_config.TENANT_ISOLATED_TASK_CONCURRENCY", concurrency_limit):
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert - Should enqueue exactly concurrency_limit tasks
+                assert mock_task.apply_async.call_count == concurrency_limit
+
 
 # ============================================================================
 # Test Task Cancellation
@@ -198,6 +877,407 @@ class TestTaskCancellation:
         assert tenant_2 in queue_2._queue
 
 
+# ============================================================================
+# Integration Tests
+# ============================================================================
+
+
+class TestAdvancedScenarios:
+    """Advanced test scenarios for edge cases and complex workflows."""
+
+    def test_multiple_documents_with_mixed_success_and_failure(
+        self, dataset_id, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test handling of mixed success and failure scenarios in batch processing.
+
+        When processing multiple documents, some may succeed while others fail.
+        This tests that the system handles partial failures gracefully.
+
+        Scenario:
+        - Process 3 documents in a batch
+        - First document succeeds
+        - Second document is not found (skipped)
+        - Third document succeeds
+
+        Expected behavior:
+        - Only found documents are processed
+        - Missing documents are skipped without crashing
+        - IndexingRunner receives only valid documents
+        """
+        # Arrange - Create document IDs with one missing
+        document_ids = [str(uuid.uuid4()) for _ in range(3)]
+
+        # Create only 2 documents (simulate one missing)
+        # The new code uses .all() which will only return existing documents
+        mock_documents = []
+        for i, doc_id in enumerate([document_ids[0], document_ids[2]]):  # Skip middle one
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data - .all() will only return existing documents
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert - Only 2 documents should be processed (missing one skipped)
+            mock_indexing_runner.run.assert_called_once()
+            call_args = mock_indexing_runner.run.call_args[0][0]
+            assert len(call_args) == 2  # Only found documents
+
+    def test_tenant_queue_with_multiple_concurrent_tasks(
+        self, tenant_id, dataset_id, mock_redis, mock_db_session, mock_dataset
+    ):
+        """
+        Test concurrent task processing with tenant isolation.
+
+        This tests the scenario where multiple tasks are queued for the same tenant
+        and need to be processed respecting the concurrency limit.
+
+        Scenario:
+        - 5 tasks are waiting in the queue
+        - Concurrency limit is 2
+        - After current task completes, pull and enqueue next 2 tasks
+
+        Expected behavior:
+        - Exactly 2 tasks are pulled from queue (respecting concurrency)
+        - Each task is enqueued with correct parameters
+        - Task waiting time is set for each new task
+        """
+        # Arrange
+        concurrency_limit = 2
+        document_ids = [str(uuid.uuid4())]
+
+        # Create multiple waiting tasks
+        waiting_tasks = []
+        for i in range(5):
+            task_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": [f"doc_{i}"]}
+            from core.rag.pipeline.queue import TaskWrapper
+
+            wrapper = TaskWrapper(data=task_data)
+            waiting_tasks.append(wrapper.serialize())
+
+        # Mock rpop to return tasks up to concurrency limit
+        mock_redis.rpop.side_effect = waiting_tasks[:concurrency_limit] + [None]
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.dify_config.TENANT_ISOLATED_TASK_CONCURRENCY", concurrency_limit):
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert
+                # Should enqueue exactly concurrency_limit tasks
+                assert mock_task.apply_async.call_count == concurrency_limit
+
+                # Verify task waiting time was set for each task
+                assert mock_redis.setex.call_count >= concurrency_limit
+
+    def test_vector_space_limit_edge_case_at_exact_limit(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_feature_service
+    ):
+        """
+        Test vector space limit validation at exact boundary.
+
+        Edge case: When vector space is exactly at the limit (not over),
+        the upload should still be rejected.
+
+        Scenario:
+        - Vector space limit: 100
+        - Current size: 100 (exactly at limit)
+        - Try to upload 3 documents
+
+        Expected behavior:
+        - Upload is rejected with appropriate error message
+        - All documents are marked with error status
+        """
+        # Arrange
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.error = None
+            doc.stopped_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Set vector space exactly at limit
+        mock_feature_service.get_features.return_value.billing.enabled = True
+        mock_feature_service.get_features.return_value.billing.subscription.plan = CloudPlan.PROFESSIONAL
+        mock_feature_service.get_features.return_value.vector_space.limit = 100
+        mock_feature_service.get_features.return_value.vector_space.size = 100  # Exactly at limit
+
+        # Act
+        _document_indexing(dataset_id, document_ids)
+
+        # Assert - All documents should have error status
+        for doc in mock_documents:
+            assert doc.indexing_status == "error"
+            assert "over the limit" in doc.error
+
+    def test_task_queue_fifo_ordering(self, tenant_id, dataset_id, mock_redis, mock_db_session, mock_dataset):
+        """
+        Test that tasks are processed in FIFO (First-In-First-Out) order.
+
+        The tenant isolated queue should maintain task order, ensuring
+        that tasks are processed in the sequence they were added.
+
+        Scenario:
+        - Task A added first
+        - Task B added second
+        - Task C added third
+        - When pulling tasks, should get A, then B, then C
+
+        Expected behavior:
+        - Tasks are retrieved in the order they were added
+        - FIFO ordering is maintained throughout processing
+        """
+        # Arrange
+        document_ids = [str(uuid.uuid4())]
+
+        # Create tasks with identifiable document IDs to track order
+        task_order = ["task_A", "task_B", "task_C"]
+        tasks = []
+        for task_name in task_order:
+            task_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": [task_name]}
+            from core.rag.pipeline.queue import TaskWrapper
+
+            wrapper = TaskWrapper(data=task_data)
+            tasks.append(wrapper.serialize())
+
+        # Mock rpop to return tasks in FIFO order
+        mock_redis.rpop.side_effect = tasks + [None]
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.dify_config.TENANT_ISOLATED_TASK_CONCURRENCY", 3):
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert - Verify tasks were enqueued in correct order
+                assert mock_task.apply_async.call_count == 3
+
+                # Check that document_ids in calls match expected order
+                for i, call_obj in enumerate(mock_task.apply_async.call_args_list):
+                    called_doc_ids = call_obj[1]["kwargs"]["document_ids"]
+                    assert called_doc_ids == [task_order[i]]
+
+    def test_empty_queue_after_task_completion_cleans_up(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset
+    ):
+        """
+        Test cleanup behavior when queue becomes empty after task completion.
+
+        After processing the last task in the queue, the system should:
+        1. Detect that no more tasks are waiting
+        2. Delete the task key to indicate tenant is idle
+        3. Allow new tasks to start fresh processing
+
+        Scenario:
+        - Process a task
+        - Check queue for next tasks
+        - Queue is empty
+        - Task key should be deleted
+
+        Expected behavior:
+        - Task key is deleted when queue is empty
+        - Tenant is marked as idle (no active tasks)
+        """
+        # Arrange
+        mock_redis.rpop.return_value = None  # Empty queue
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+            # Act
+            _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+            # Assert
+            # Verify delete was called to clean up task key
+            mock_redis.delete.assert_called_once()
+
+            # Verify the correct key was deleted (contains tenant_id and "document_indexing")
+            delete_call_args = mock_redis.delete.call_args[0][0]
+            assert tenant_id in delete_call_args
+            assert "document_indexing" in delete_call_args
+
+    def test_billing_disabled_skips_limit_checks(
+        self, dataset_id, document_ids, mock_db_session, mock_dataset, mock_indexing_runner, mock_feature_service
+    ):
+        """
+        Test that billing limit checks are skipped when billing is disabled.
+
+        For self-hosted or enterprise deployments where billing is disabled,
+        the system should not enforce vector space or batch upload limits.
+
+        Scenario:
+        - Billing is disabled
+        - Upload 100 documents (would normally exceed limits)
+        - No limit checks should be performed
+
+        Expected behavior:
+        - Documents are processed without limit validation
+        - No errors related to limits
+        - All documents proceed to indexing
+        """
+        # Arrange - Create many documents
+        large_batch_ids = [str(uuid.uuid4()) for _ in range(100)]
+
+        mock_documents = []
+        for doc_id in large_batch_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Billing disabled - limits should not be checked
+        mock_feature_service.get_features.return_value.billing.enabled = False
+
+        # Act
+        _document_indexing(dataset_id, large_batch_ids)
+
+        # Assert
+        # All documents should be set to parsing (no limit errors)
+        for doc in mock_documents:
+            assert doc.indexing_status == "parsing"
+
+        # IndexingRunner should be called with all documents
+        mock_indexing_runner.run.assert_called_once()
+        call_args = mock_indexing_runner.run.call_args[0][0]
+        assert len(call_args) == 100
+
+
+class TestIntegration:
+    """Integration tests for complete task workflows."""
+
+    def test_complete_workflow_normal_task(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test complete workflow for normal document indexing task.
+
+        This tests the full flow from task receipt to completion.
+        """
+        # Arrange - Create actual document objects
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set up rpop to return None for concurrency check (no more tasks)
+        mock_redis.rpop.side_effect = [None]
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            normal_document_indexing_task(tenant_id, dataset_id, document_ids)
+
+            # Assert
+            # Documents should be processed
+            mock_indexing_runner.run.assert_called_once()
+            # Session should be closed
+            assert mock_db_session.close.called
+            # Task key should be deleted (no more tasks)
+            assert mock_redis.delete.called
+
+    def test_complete_workflow_priority_task(
+        self, tenant_id, dataset_id, document_ids, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test complete workflow for priority document indexing task.
+
+        Priority tasks should follow the same flow as normal tasks.
+        """
+        # Arrange - Create actual document objects
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set up rpop to return None for concurrency check (no more tasks)
+        mock_redis.rpop.side_effect = [None]
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            # Act
+            priority_document_indexing_task(tenant_id, dataset_id, document_ids)
+
+            # Assert
+            mock_indexing_runner.run.assert_called_once()
+            assert mock_db_session.close.called
+            assert mock_redis.delete.called
+
+    def test_queue_chain_processing(
+        self, tenant_id, dataset_id, mock_redis, mock_db_session, mock_dataset, mock_indexing_runner
+    ):
+        """
+        Test that multiple tasks in queue are processed in sequence.
+
+        When tasks are queued, they should be processed one after another.
+        """
+        # Arrange
+        task_1_docs = [str(uuid.uuid4())]
+        task_2_docs = [str(uuid.uuid4())]
+
+        task_2_data = {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": task_2_docs}
+
+        from core.rag.pipeline.queue import TaskWrapper
+
+        wrapper = TaskWrapper(data=task_2_data)
+
+        # First call returns task 2, second call returns None
+        mock_redis.rpop.side_effect = [wrapper.serialize(), None]
+
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.FeatureService.get_features") as mock_features:
+            mock_features.return_value.billing.enabled = False
+
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act - Process first task
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, task_1_docs, mock_task)
+
+                # Assert - Second task should be enqueued
+                assert mock_task.apply_async.called
+                call_args = mock_task.apply_async.call_args
+                assert call_args[1]["kwargs"]["document_ids"] == task_2_docs
+
+
 # ============================================================================
 # Additional Edge Case Tests
 # ============================================================================
@@ -249,6 +1329,107 @@ class TestEdgeCases:
 class TestPerformanceScenarios:
     """Test performance-related scenarios and optimizations."""
 
+    def test_large_document_batch_processing(
+        self, dataset_id, mock_db_session, mock_dataset, mock_indexing_runner, mock_feature_service
+    ):
+        """
+        Test processing a large batch of documents at batch limit.
+
+        When processing the maximum allowed batch size, the system
+        should handle it efficiently without errors.
+
+        Scenario:
+        - Process exactly batch_upload_limit documents (e.g., 50)
+        - All documents are valid
+        - Billing is enabled
+
+        Expected behavior:
+        - All documents are processed successfully
+        - No timeout or memory issues
+        - Batch limit is not exceeded
+        """
+        # Arrange
+        batch_limit = 50
+        document_ids = [str(uuid.uuid4()) for _ in range(batch_limit)]
+
+        mock_documents = []
+        for doc_id in document_ids:
+            doc = MagicMock(spec=Document)
+            doc.id = doc_id
+            doc.dataset_id = dataset_id
+            doc.indexing_status = "waiting"
+            doc.processing_started_at = None
+            mock_documents.append(doc)
+
+        # Set shared mock data so all sessions can access it
+        mock_db_session._shared_data["dataset"] = mock_dataset
+        mock_db_session._shared_data["documents"] = mock_documents
+
+        # Configure billing with sufficient limits
+        mock_feature_service.get_features.return_value.billing.enabled = True
+        mock_feature_service.get_features.return_value.billing.subscription.plan = CloudPlan.PROFESSIONAL
+        mock_feature_service.get_features.return_value.vector_space.limit = 10000
+        mock_feature_service.get_features.return_value.vector_space.size = 0
+
+        with patch("tasks.document_indexing_task.dify_config.BATCH_UPLOAD_LIMIT", str(batch_limit)):
+            # Act
+            _document_indexing(dataset_id, document_ids)
+
+            # Assert
+            for doc in mock_documents:
+                assert doc.indexing_status == "parsing"
+
+            mock_indexing_runner.run.assert_called_once()
+            call_args = mock_indexing_runner.run.call_args[0][0]
+            assert len(call_args) == batch_limit
+
+    def test_tenant_queue_handles_burst_traffic(self, tenant_id, dataset_id, mock_redis, mock_db_session, mock_dataset):
+        """
+        Test tenant queue handling burst traffic scenarios.
+
+        When many tasks arrive in a burst for the same tenant,
+        the queue should handle them efficiently without dropping tasks.
+
+        Scenario:
+        - 20 tasks arrive rapidly
+        - Concurrency limit is 3
+        - Tasks should be queued and processed in batches
+
+        Expected behavior:
+        - First 3 tasks are processed immediately
+        - Remaining tasks wait in queue
+        - No tasks are lost
+        """
+        # Arrange
+        num_tasks = 20
+        concurrency_limit = 3
+        document_ids = [str(uuid.uuid4())]
+
+        # Create waiting tasks
+        waiting_tasks = []
+        for i in range(num_tasks):
+            task_data = {
+                "tenant_id": tenant_id,
+                "dataset_id": dataset_id,
+                "document_ids": [f"doc_{i}"],
+            }
+            from core.rag.pipeline.queue import TaskWrapper
+
+            wrapper = TaskWrapper(data=task_data)
+            waiting_tasks.append(wrapper.serialize())
+
+        # Mock rpop to return tasks up to concurrency limit
+        mock_redis.rpop.side_effect = waiting_tasks[:concurrency_limit] + [None]
+        mock_db_session.query.return_value.where.return_value.first.return_value = mock_dataset
+
+        with patch("tasks.document_indexing_task.dify_config.TENANT_ISOLATED_TASK_CONCURRENCY", concurrency_limit):
+            with patch("tasks.document_indexing_task.normal_document_indexing_task") as mock_task:
+                # Act
+                _document_indexing_with_tenant_queue(tenant_id, dataset_id, document_ids, mock_task)
+
+                # Assert - Should process exactly concurrency_limit tasks
+                assert mock_task.apply_async.call_count == concurrency_limit
+
     def test_multiple_tenants_isolated_processing(self, mock_redis):
         """
         Test that multiple tenants process tasks in isolation.

From 6c19e759691b5b94029975853badd22545c9204c Mon Sep 17 00:00:00 2001
From: Dev Sharma <50591491+cryptus-neoxys@users.noreply.github.com>
Date: Mon, 9 Mar 2026 13:28:34 +0530
Subject: [PATCH 10/12] test: improve unit tests for controllers.web (#32150)

Co-authored-by: Rajat Agarwal <rajat.agarwal@infocusp.com>
---
 api/controllers/web/message.py                |   2 +-
 .../unit_tests/controllers/web/__init__.py    |   0
 .../unit_tests/controllers/web/conftest.py    |  85 ++++
 .../unit_tests/controllers/web/test_app.py    | 165 +++++++
 .../unit_tests/controllers/web/test_audio.py  | 135 ++++++
 .../controllers/web/test_completion.py        | 161 +++++++
 .../controllers/web/test_conversation.py      | 183 ++++++++
 .../unit_tests/controllers/web/test_error.py  |  75 ++++
 .../controllers/web/test_feature.py           |  38 ++
 .../unit_tests/controllers/web/test_files.py  |  89 ++++
 .../controllers/web/test_message_endpoints.py | 156 +++++++
 .../controllers/web/test_passport.py          | 103 +++++
 .../controllers/web/test_pydantic_models.py   | 423 ++++++++++++++++++
 .../controllers/web/test_remote_files.py      | 147 ++++++
 .../controllers/web/test_saved_message.py     |  97 ++++
 .../unit_tests/controllers/web/test_site.py   | 126 ++++++
 .../controllers/web/test_web_login.py         | 114 ++++-
 .../controllers/web/test_web_passport.py      | 192 ++++++++
 .../controllers/web/test_workflow.py          |  95 ++++
 .../controllers/web/test_workflow_events.py   | 127 ++++++
 .../unit_tests/controllers/web/test_wraps.py  | 393 ++++++++++++++++
 21 files changed, 2904 insertions(+), 2 deletions(-)
 create mode 100644 api/tests/unit_tests/controllers/web/__init__.py
 create mode 100644 api/tests/unit_tests/controllers/web/conftest.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_app.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_audio.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_completion.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_conversation.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_error.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_feature.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_files.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_message_endpoints.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_passport.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_pydantic_models.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_remote_files.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_saved_message.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_site.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_web_passport.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_workflow.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_workflow_events.py
 create mode 100644 api/tests/unit_tests/controllers/web/test_wraps.py

diff --git a/api/controllers/web/message.py b/api/controllers/web/message.py
index bbae1ce266..2b60691949 100644
--- a/api/controllers/web/message.py
+++ b/api/controllers/web/message.py
@@ -239,7 +239,7 @@ class MessageSuggestedQuestionApi(WebApiResource):
     def get(self, app_model, end_user, message_id):
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
-            raise NotCompletionAppError()
+            raise NotChatAppError()
 
         message_id = str(message_id)
 
diff --git a/api/tests/unit_tests/controllers/web/__init__.py b/api/tests/unit_tests/controllers/web/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/api/tests/unit_tests/controllers/web/conftest.py b/api/tests/unit_tests/controllers/web/conftest.py
new file mode 100644
index 0000000000..274d78c9cf
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/conftest.py
@@ -0,0 +1,85 @@
+"""Shared fixtures for controllers.web unit tests."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from flask import Flask
+
+
+@pytest.fixture
+def app() -> Flask:
+    """Minimal Flask app for request contexts."""
+    flask_app = Flask(__name__)
+    flask_app.config["TESTING"] = True
+    return flask_app
+
+
+class FakeSession:
+    """Stand-in for db.session that returns pre-seeded objects by model class name."""
+
+    def __init__(self, mapping: dict[str, Any] | None = None):
+        self._mapping: dict[str, Any] = mapping or {}
+        self._model_name: str | None = None
+
+    def query(self, model: type) -> FakeSession:
+        self._model_name = model.__name__
+        return self
+
+    def where(self, *_args: object, **_kwargs: object) -> FakeSession:
+        return self
+
+    def first(self) -> Any:
+        assert self._model_name is not None
+        return self._mapping.get(self._model_name)
+
+
+class FakeDB:
+    """Minimal db stub exposing engine and session."""
+
+    def __init__(self, session: FakeSession | None = None):
+        self.session = session or FakeSession()
+        self.engine = object()
+
+
+def make_app_model(
+    *,
+    app_id: str = "app-1",
+    tenant_id: str = "tenant-1",
+    mode: str = "chat",
+    enable_site: bool = True,
+    status: str = "normal",
+) -> SimpleNamespace:
+    """Build a fake App model with common defaults."""
+    tenant = SimpleNamespace(
+        id=tenant_id,
+        status="normal",
+        plan="basic",
+        custom_config_dict={},
+    )
+    return SimpleNamespace(
+        id=app_id,
+        tenant_id=tenant_id,
+        tenant=tenant,
+        mode=mode,
+        enable_site=enable_site,
+        status=status,
+        workflow=None,
+        app_model_config=None,
+    )
+
+
+def make_end_user(
+    *,
+    user_id: str = "end-user-1",
+    session_id: str = "session-1",
+    external_user_id: str = "ext-user-1",
+) -> SimpleNamespace:
+    """Build a fake EndUser model with common defaults."""
+    return SimpleNamespace(
+        id=user_id,
+        session_id=session_id,
+        external_user_id=external_user_id,
+    )
diff --git a/api/tests/unit_tests/controllers/web/test_app.py b/api/tests/unit_tests/controllers/web/test_app.py
new file mode 100644
index 0000000000..ce7ae27188
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_app.py
@@ -0,0 +1,165 @@
+"""Unit tests for controllers.web.app endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.app import AppAccessMode, AppMeta, AppParameterApi, AppWebAuthPermission
+from controllers.web.error import AppUnavailableError
+
+
+# ---------------------------------------------------------------------------
+# AppParameterApi
+# ---------------------------------------------------------------------------
+class TestAppParameterApi:
+    def test_advanced_chat_mode_uses_workflow(self, app: Flask) -> None:
+        features_dict = {"opening_statement": "Hello"}
+        workflow = SimpleNamespace(
+            features_dict=features_dict,
+            user_input_form=lambda to_old_structure=False: [],
+        )
+        app_model = SimpleNamespace(mode="advanced-chat", workflow=workflow)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {"result": "ok"}
+            result = AppParameterApi().get(app_model, SimpleNamespace())
+
+        mock_params.assert_called_once_with(features_dict=features_dict, user_input_form=[])
+        assert result == {"result": "ok"}
+
+    def test_workflow_mode_uses_workflow(self, app: Flask) -> None:
+        features_dict = {}
+        workflow = SimpleNamespace(
+            features_dict=features_dict,
+            user_input_form=lambda to_old_structure=False: [{"var": "x"}],
+        )
+        app_model = SimpleNamespace(mode="workflow", workflow=workflow)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {}
+            AppParameterApi().get(app_model, SimpleNamespace())
+
+        mock_params.assert_called_once_with(features_dict=features_dict, user_input_form=[{"var": "x"}])
+
+    def test_advanced_chat_mode_no_workflow_raises(self, app: Flask) -> None:
+        app_model = SimpleNamespace(mode="advanced-chat", workflow=None)
+        with app.test_request_context("/parameters"):
+            with pytest.raises(AppUnavailableError):
+                AppParameterApi().get(app_model, SimpleNamespace())
+
+    def test_standard_mode_uses_app_model_config(self, app: Flask) -> None:
+        config = SimpleNamespace(to_dict=lambda: {"user_input_form": [{"var": "y"}], "key": "val"})
+        app_model = SimpleNamespace(mode="chat", app_model_config=config)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {}
+            AppParameterApi().get(app_model, SimpleNamespace())
+
+        call_kwargs = mock_params.call_args
+        assert call_kwargs.kwargs["user_input_form"] == [{"var": "y"}]
+
+    def test_standard_mode_no_config_raises(self, app: Flask) -> None:
+        app_model = SimpleNamespace(mode="chat", app_model_config=None)
+        with app.test_request_context("/parameters"):
+            with pytest.raises(AppUnavailableError):
+                AppParameterApi().get(app_model, SimpleNamespace())
+
+
+# ---------------------------------------------------------------------------
+# AppMeta
+# ---------------------------------------------------------------------------
+class TestAppMeta:
+    @patch("controllers.web.app.AppService")
+    def test_get_returns_meta(self, mock_service_cls: MagicMock, app: Flask) -> None:
+        mock_service_cls.return_value.get_app_meta.return_value = {"tool_icons": {}}
+        app_model = SimpleNamespace(id="app-1")
+
+        with app.test_request_context("/meta"):
+            result = AppMeta().get(app_model, SimpleNamespace())
+
+        assert result == {"tool_icons": {}}
+
+
+# ---------------------------------------------------------------------------
+# AppAccessMode
+# ---------------------------------------------------------------------------
+class TestAppAccessMode:
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_returns_public_when_webapp_auth_disabled(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        with app.test_request_context("/webapp/access-mode?appId=app-1"):
+            result = AppAccessMode().get()
+
+        assert result == {"accessMode": "public"}
+
+    @patch("controllers.web.app.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_returns_access_mode_with_app_id(
+        self, mock_features: MagicMock, mock_access: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+        mock_access.return_value = SimpleNamespace(access_mode="internal")
+
+        with app.test_request_context("/webapp/access-mode?appId=app-1"):
+            result = AppAccessMode().get()
+
+        assert result == {"accessMode": "internal"}
+        mock_access.assert_called_once_with("app-1")
+
+    @patch("controllers.web.app.AppService.get_app_id_by_code", return_value="resolved-id")
+    @patch("controllers.web.app.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_resolves_app_code_to_id(
+        self, mock_features: MagicMock, mock_access: MagicMock, mock_resolve: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+        mock_access.return_value = SimpleNamespace(access_mode="external")
+
+        with app.test_request_context("/webapp/access-mode?appCode=code1"):
+            result = AppAccessMode().get()
+
+        mock_resolve.assert_called_once_with("code1")
+        mock_access.assert_called_once_with("resolved-id")
+        assert result == {"accessMode": "external"}
+
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_raises_when_no_app_id_or_code(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+
+        with app.test_request_context("/webapp/access-mode"):
+            with pytest.raises(ValueError, match="appId or appCode"):
+                AppAccessMode().get()
+
+
+# ---------------------------------------------------------------------------
+# AppWebAuthPermission
+# ---------------------------------------------------------------------------
+class TestAppWebAuthPermission:
+    @patch("controllers.web.app.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_returns_true_when_no_permission_check_required(self, mock_check: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/webapp/permission?appId=app-1", headers={"X-App-Code": "code1"}):
+            result = AppWebAuthPermission().get()
+
+        assert result == {"result": True}
+
+    def test_raises_when_missing_app_id(self, app: Flask) -> None:
+        with app.test_request_context("/webapp/permission", headers={"X-App-Code": "code1"}):
+            with pytest.raises(ValueError, match="appId"):
+                AppWebAuthPermission().get()
diff --git a/api/tests/unit_tests/controllers/web/test_audio.py b/api/tests/unit_tests/controllers/web/test_audio.py
new file mode 100644
index 0000000000..01f34345aa
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_audio.py
@@ -0,0 +1,135 @@
+"""Unit tests for controllers.web.audio endpoints."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.audio import AudioApi, TextApi
+from controllers.web.error import (
+    AudioTooLargeError,
+    CompletionRequestError,
+    NoAudioUploadedError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderNotSupportSpeechToTextError,
+    ProviderQuotaExceededError,
+    UnsupportedAudioTypeError,
+)
+from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from dify_graph.model_runtime.errors.invoke import InvokeError
+from services.errors.audio import (
+    AudioTooLargeServiceError,
+    NoAudioUploadedServiceError,
+    ProviderNotSupportSpeechToTextServiceError,
+    UnsupportedAudioTypeServiceError,
+)
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1", external_user_id="ext-1")
+
+
+# ---------------------------------------------------------------------------
+# AudioApi (audio-to-text)
+# ---------------------------------------------------------------------------
+class TestAudioApi:
+    @patch("controllers.web.audio.AudioService.transcript_asr", return_value={"text": "hello"})
+    def test_happy_path(self, mock_asr: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        data = {"file": (BytesIO(b"fake-audio"), "test.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            result = AudioApi().post(_app_model(), _end_user())
+
+        assert result == {"text": "hello"}
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=NoAudioUploadedServiceError())
+    def test_no_audio_uploaded(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b""), "empty.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(NoAudioUploadedError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=AudioTooLargeServiceError("too big"))
+    def test_audio_too_large(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"big"), "big.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(AudioTooLargeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=UnsupportedAudioTypeServiceError())
+    def test_unsupported_type(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"bad"), "bad.xyz")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(UnsupportedAudioTypeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_asr",
+        side_effect=ProviderNotSupportSpeechToTextServiceError(),
+    )
+    def test_provider_not_support(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderNotSupportSpeechToTextError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_asr",
+        side_effect=ProviderTokenNotInitError(description="no token"),
+    )
+    def test_provider_not_init(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderNotInitializeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=QuotaExceededError())
+    def test_quota_exceeded(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderQuotaExceededError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=ModelCurrentlyNotSupportError())
+    def test_model_not_support(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderModelCurrentlyNotSupportError):
+                AudioApi().post(_app_model(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# TextApi (text-to-audio)
+# ---------------------------------------------------------------------------
+class TestTextApi:
+    @patch("controllers.web.audio.AudioService.transcript_tts", return_value="audio-bytes")
+    @patch("controllers.web.audio.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_tts: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"text": "hello", "voice": "alloy"}
+
+        with app.test_request_context("/text-to-audio", method="POST"):
+            result = TextApi().post(_app_model(), _end_user())
+
+        assert result == "audio-bytes"
+        mock_tts.assert_called_once()
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_tts",
+        side_effect=InvokeError(description="invoke failed"),
+    )
+    @patch("controllers.web.audio.web_ns")
+    def test_invoke_error_mapped(self, mock_ns: MagicMock, mock_tts: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"text": "hello"}
+
+        with app.test_request_context("/text-to-audio", method="POST"):
+            with pytest.raises(CompletionRequestError):
+                TextApi().post(_app_model(), _end_user())
diff --git a/api/tests/unit_tests/controllers/web/test_completion.py b/api/tests/unit_tests/controllers/web/test_completion.py
new file mode 100644
index 0000000000..e88bcf2ae6
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_completion.py
@@ -0,0 +1,161 @@
+"""Unit tests for controllers.web.completion endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.completion import ChatApi, ChatStopApi, CompletionApi, CompletionStopApi
+from controllers.web.error import (
+    CompletionRequestError,
+    NotChatAppError,
+    NotCompletionAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from dify_graph.model_runtime.errors.invoke import InvokeError
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# CompletionApi
+# ---------------------------------------------------------------------------
+class TestCompletionApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                CompletionApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.completion.helper.compact_generate_response", return_value={"answer": "hi"})
+    @patch("controllers.web.completion.AppGenerateService.generate")
+    @patch("controllers.web.completion.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "test"}
+        mock_gen.return_value = "response-obj"
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            result = CompletionApi().post(_completion_app(), _end_user())
+
+        assert result == {"answer": "hi"}
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=ProviderTokenNotInitError(description="not init"),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_provider_not_init_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderNotInitializeError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=QuotaExceededError(),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_quota_exceeded_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderQuotaExceededError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=ModelCurrentlyNotSupportError(),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_model_not_support_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderModelCurrentlyNotSupportError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# CompletionStopApi
+# ---------------------------------------------------------------------------
+class TestCompletionStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/completion-messages/task-1/stop", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                CompletionStopApi().post(_chat_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.completion.AppTaskService.stop_task")
+    def test_stop_success(self, mock_stop: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/completion-messages/task-1/stop", method="POST"):
+            result, status = CompletionStopApi().post(_completion_app(), _end_user(), "task-1")
+
+        assert status == 200
+        assert result == {"result": "success"}
+
+
+# ---------------------------------------------------------------------------
+# ChatApi
+# ---------------------------------------------------------------------------
+class TestChatApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/chat-messages", method="POST"):
+            with pytest.raises(NotChatAppError):
+                ChatApi().post(_completion_app(), _end_user())
+
+    @patch("controllers.web.completion.helper.compact_generate_response", return_value={"answer": "reply"})
+    @patch("controllers.web.completion.AppGenerateService.generate")
+    @patch("controllers.web.completion.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "hi"}
+        mock_gen.return_value = "response"
+
+        with app.test_request_context("/chat-messages", method="POST"):
+            result = ChatApi().post(_chat_app(), _end_user())
+
+        assert result == {"answer": "reply"}
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=InvokeError(description="rate limit"),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_invoke_error_mapped(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "x"}
+
+        with app.test_request_context("/chat-messages", method="POST"):
+            with pytest.raises(CompletionRequestError):
+                ChatApi().post(_chat_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# ChatStopApi
+# ---------------------------------------------------------------------------
+class TestChatStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/chat-messages/task-1/stop", method="POST"):
+            with pytest.raises(NotChatAppError):
+                ChatStopApi().post(_completion_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.completion.AppTaskService.stop_task")
+    def test_stop_success(self, mock_stop: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/chat-messages/task-1/stop", method="POST"):
+            result, status = ChatStopApi().post(_chat_app(), _end_user(), "task-1")
+
+        assert status == 200
+        assert result == {"result": "success"}
diff --git a/api/tests/unit_tests/controllers/web/test_conversation.py b/api/tests/unit_tests/controllers/web/test_conversation.py
new file mode 100644
index 0000000000..e5adbbbf66
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_conversation.py
@@ -0,0 +1,183 @@
+"""Unit tests for controllers.web.conversation endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.conversation import (
+    ConversationApi,
+    ConversationListApi,
+    ConversationPinApi,
+    ConversationRenameApi,
+    ConversationUnPinApi,
+)
+from controllers.web.error import NotChatAppError
+from services.errors.conversation import ConversationNotExistsError
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# ConversationListApi
+# ---------------------------------------------------------------------------
+class TestConversationListApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/conversations"):
+            with pytest.raises(NotChatAppError):
+                ConversationListApi().get(_completion_app(), _end_user())
+
+    @patch("controllers.web.conversation.WebConversationService.pagination_by_last_id")
+    @patch("controllers.web.conversation.db")
+    def test_happy_path(self, mock_db: MagicMock, mock_paginate: MagicMock, app: Flask) -> None:
+        conv_id = str(uuid4())
+        conv = SimpleNamespace(
+            id=conv_id,
+            name="Test",
+            inputs={},
+            status="normal",
+            introduction="",
+            created_at=1700000000,
+            updated_at=1700000000,
+        )
+        mock_paginate.return_value = SimpleNamespace(limit=20, has_more=False, data=[conv])
+        mock_db.engine = "engine"
+
+        session_mock = MagicMock()
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+
+        with (
+            app.test_request_context("/conversations?limit=20"),
+            patch("controllers.web.conversation.Session", return_value=session_ctx),
+        ):
+            result = ConversationListApi().get(_chat_app(), _end_user())
+
+        assert result["limit"] == 20
+        assert result["has_more"] is False
+
+
+# ---------------------------------------------------------------------------
+# ConversationApi (delete)
+# ---------------------------------------------------------------------------
+class TestConversationApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}"):
+            with pytest.raises(NotChatAppError):
+                ConversationApi().delete(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.ConversationService.delete")
+    def test_delete_success(self, mock_delete: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}"):
+            result, status = ConversationApi().delete(_chat_app(), _end_user(), c_id)
+
+        assert status == 204
+        assert result["result"] == "success"
+
+    @patch("controllers.web.conversation.ConversationService.delete", side_effect=ConversationNotExistsError())
+    def test_delete_not_found(self, mock_delete: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}"):
+            with pytest.raises(NotFound, match="Conversation Not Exists"):
+                ConversationApi().delete(_chat_app(), _end_user(), c_id)
+
+
+# ---------------------------------------------------------------------------
+# ConversationRenameApi
+# ---------------------------------------------------------------------------
+class TestConversationRenameApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/name", method="POST", json={"name": "x"}):
+            with pytest.raises(NotChatAppError):
+                ConversationRenameApi().post(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.ConversationService.rename")
+    @patch("controllers.web.conversation.web_ns")
+    def test_rename_success(self, mock_ns: MagicMock, mock_rename: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        mock_ns.payload = {"name": "New Name", "auto_generate": False}
+        conv = SimpleNamespace(
+            id=str(c_id),
+            name="New Name",
+            inputs={},
+            status="normal",
+            introduction="",
+            created_at=1700000000,
+            updated_at=1700000000,
+        )
+        mock_rename.return_value = conv
+
+        with app.test_request_context(f"/conversations/{c_id}/name", method="POST", json={"name": "New Name"}):
+            result = ConversationRenameApi().post(_chat_app(), _end_user(), c_id)
+
+        assert result["name"] == "New Name"
+
+    @patch(
+        "controllers.web.conversation.ConversationService.rename",
+        side_effect=ConversationNotExistsError(),
+    )
+    @patch("controllers.web.conversation.web_ns")
+    def test_rename_not_found(self, mock_ns: MagicMock, mock_rename: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        mock_ns.payload = {"name": "X", "auto_generate": False}
+
+        with app.test_request_context(f"/conversations/{c_id}/name", method="POST", json={"name": "X"}):
+            with pytest.raises(NotFound, match="Conversation Not Exists"):
+                ConversationRenameApi().post(_chat_app(), _end_user(), c_id)
+
+
+# ---------------------------------------------------------------------------
+# ConversationPinApi / ConversationUnPinApi
+# ---------------------------------------------------------------------------
+class TestConversationPinApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/pin", method="PATCH"):
+            with pytest.raises(NotChatAppError):
+                ConversationPinApi().patch(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.WebConversationService.pin")
+    def test_pin_success(self, mock_pin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/pin", method="PATCH"):
+            result = ConversationPinApi().patch(_chat_app(), _end_user(), c_id)
+
+        assert result["result"] == "success"
+
+    @patch("controllers.web.conversation.WebConversationService.pin", side_effect=ConversationNotExistsError())
+    def test_pin_not_found(self, mock_pin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/pin", method="PATCH"):
+            with pytest.raises(NotFound):
+                ConversationPinApi().patch(_chat_app(), _end_user(), c_id)
+
+
+class TestConversationUnPinApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/unpin", method="PATCH"):
+            with pytest.raises(NotChatAppError):
+                ConversationUnPinApi().patch(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.WebConversationService.unpin")
+    def test_unpin_success(self, mock_unpin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/unpin", method="PATCH"):
+            result = ConversationUnPinApi().patch(_chat_app(), _end_user(), c_id)
+
+        assert result["result"] == "success"
diff --git a/api/tests/unit_tests/controllers/web/test_error.py b/api/tests/unit_tests/controllers/web/test_error.py
new file mode 100644
index 0000000000..0387d002ba
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_error.py
@@ -0,0 +1,75 @@
+"""Unit tests for controllers.web.error HTTP exception classes."""
+
+from __future__ import annotations
+
+import pytest
+
+from controllers.web.error import (
+    AppMoreLikeThisDisabledError,
+    AppSuggestedQuestionsAfterAnswerDisabledError,
+    AppUnavailableError,
+    AudioTooLargeError,
+    CompletionRequestError,
+    ConversationCompletedError,
+    InvalidArgumentError,
+    InvokeRateLimitError,
+    NoAudioUploadedError,
+    NotChatAppError,
+    NotCompletionAppError,
+    NotFoundError,
+    NotWorkflowAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderNotSupportSpeechToTextError,
+    ProviderQuotaExceededError,
+    UnsupportedAudioTypeError,
+    WebAppAuthAccessDeniedError,
+    WebAppAuthRequiredError,
+    WebFormRateLimitExceededError,
+)
+
+_ERROR_SPECS: list[tuple[type, str, int]] = [
+    (AppUnavailableError, "app_unavailable", 400),
+    (NotCompletionAppError, "not_completion_app", 400),
+    (NotChatAppError, "not_chat_app", 400),
+    (NotWorkflowAppError, "not_workflow_app", 400),
+    (ConversationCompletedError, "conversation_completed", 400),
+    (ProviderNotInitializeError, "provider_not_initialize", 400),
+    (ProviderQuotaExceededError, "provider_quota_exceeded", 400),
+    (ProviderModelCurrentlyNotSupportError, "model_currently_not_support", 400),
+    (CompletionRequestError, "completion_request_error", 400),
+    (AppMoreLikeThisDisabledError, "app_more_like_this_disabled", 403),
+    (AppSuggestedQuestionsAfterAnswerDisabledError, "app_suggested_questions_after_answer_disabled", 403),
+    (NoAudioUploadedError, "no_audio_uploaded", 400),
+    (AudioTooLargeError, "audio_too_large", 413),
+    (UnsupportedAudioTypeError, "unsupported_audio_type", 415),
+    (ProviderNotSupportSpeechToTextError, "provider_not_support_speech_to_text", 400),
+    (WebAppAuthRequiredError, "web_sso_auth_required", 401),
+    (WebAppAuthAccessDeniedError, "web_app_access_denied", 401),
+    (InvokeRateLimitError, "rate_limit_error", 429),
+    (WebFormRateLimitExceededError, "web_form_rate_limit_exceeded", 429),
+    (NotFoundError, "not_found", 404),
+    (InvalidArgumentError, "invalid_param", 400),
+]
+
+
+@pytest.mark.parametrize(
+    ("cls", "expected_code", "expected_status"),
+    _ERROR_SPECS,
+    ids=[cls.__name__ for cls, _, _ in _ERROR_SPECS],
+)
+def test_error_class_attributes(cls: type, expected_code: str, expected_status: int) -> None:
+    """Each error class exposes the correct error_code and HTTP status code."""
+    assert cls.error_code == expected_code
+    assert cls.code == expected_status
+
+
+def test_error_classes_have_description() -> None:
+    """Every error class has a description (string or None for generic errors)."""
+    # NotFoundError and InvalidArgumentError use None description by design
+    _NO_DESCRIPTION = {NotFoundError, InvalidArgumentError}
+    for cls, _, _ in _ERROR_SPECS:
+        if cls in _NO_DESCRIPTION:
+            continue
+        assert isinstance(cls.description, str), f"{cls.__name__} missing description"
+        assert len(cls.description) > 0, f"{cls.__name__} has empty description"
diff --git a/api/tests/unit_tests/controllers/web/test_feature.py b/api/tests/unit_tests/controllers/web/test_feature.py
new file mode 100644
index 0000000000..fe45d5f059
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_feature.py
@@ -0,0 +1,38 @@
+"""Unit tests for controllers.web.feature endpoints."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from flask import Flask
+
+from controllers.web.feature import SystemFeatureApi
+
+
+class TestSystemFeatureApi:
+    @patch("controllers.web.feature.FeatureService.get_system_features")
+    def test_returns_system_features(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_model = MagicMock()
+        mock_model.model_dump.return_value = {"sso_enforced_for_signin": False, "webapp_auth": {"enabled": False}}
+        mock_features.return_value = mock_model
+
+        with app.test_request_context("/system-features"):
+            result = SystemFeatureApi().get()
+
+        assert result == {"sso_enforced_for_signin": False, "webapp_auth": {"enabled": False}}
+        mock_features.assert_called_once()
+
+    @patch("controllers.web.feature.FeatureService.get_system_features")
+    def test_unauthenticated_access(self, mock_features: MagicMock, app: Flask) -> None:
+        """SystemFeatureApi is unauthenticated by design — no WebApiResource decorator."""
+        mock_model = MagicMock()
+        mock_model.model_dump.return_value = {}
+        mock_features.return_value = mock_model
+
+        # Verify it's a bare Resource, not WebApiResource
+        from flask_restx import Resource
+
+        from controllers.web.wraps import WebApiResource
+
+        assert issubclass(SystemFeatureApi, Resource)
+        assert not issubclass(SystemFeatureApi, WebApiResource)
diff --git a/api/tests/unit_tests/controllers/web/test_files.py b/api/tests/unit_tests/controllers/web/test_files.py
new file mode 100644
index 0000000000..a3921b0373
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_files.py
@@ -0,0 +1,89 @@
+"""Unit tests for controllers.web.files endpoints."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.common.errors import (
+    FilenameNotExistsError,
+    FileTooLargeError,
+    NoFileUploadedError,
+    TooManyFilesError,
+)
+from controllers.web.files import FileApi
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+class TestFileApi:
+    def test_no_file_uploaded(self, app: Flask) -> None:
+        with app.test_request_context("/files/upload", method="POST", content_type="multipart/form-data"):
+            with pytest.raises(NoFileUploadedError):
+                FileApi().post(_app_model(), _end_user())
+
+    def test_too_many_files(self, app: Flask) -> None:
+        data = {
+            "file": (BytesIO(b"a"), "a.txt"),
+            "file2": (BytesIO(b"b"), "b.txt"),
+        }
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            # Now has "file" key but len(request.files) > 1
+            with pytest.raises(TooManyFilesError):
+                FileApi().post(_app_model(), _end_user())
+
+    def test_filename_missing(self, app: Flask) -> None:
+        data = {"file": (BytesIO(b"content"), "")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(FilenameNotExistsError):
+                FileApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.files.FileService")
+    @patch("controllers.web.files.db")
+    def test_upload_success(self, mock_db: MagicMock, mock_file_svc_cls: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        from datetime import datetime
+
+        upload_file = SimpleNamespace(
+            id="file-1",
+            name="test.txt",
+            size=100,
+            extension="txt",
+            mime_type="text/plain",
+            created_by="eu-1",
+            created_at=datetime(2024, 1, 1),
+        )
+        mock_file_svc_cls.return_value.upload_file.return_value = upload_file
+
+        data = {"file": (BytesIO(b"content"), "test.txt")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            result, status = FileApi().post(_app_model(), _end_user())
+
+        assert status == 201
+        assert result["id"] == "file-1"
+        assert result["name"] == "test.txt"
+
+    @patch("controllers.web.files.FileService")
+    @patch("controllers.web.files.db")
+    def test_file_too_large_from_service(self, mock_db: MagicMock, mock_file_svc_cls: MagicMock, app: Flask) -> None:
+        import services.errors.file
+
+        mock_db.engine = "engine"
+        mock_file_svc_cls.return_value.upload_file.side_effect = services.errors.file.FileTooLargeError(
+            description="max 10MB"
+        )
+
+        data = {"file": (BytesIO(b"big"), "big.txt")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(FileTooLargeError):
+                FileApi().post(_app_model(), _end_user())
diff --git a/api/tests/unit_tests/controllers/web/test_message_endpoints.py b/api/tests/unit_tests/controllers/web/test_message_endpoints.py
new file mode 100644
index 0000000000..89ab93d8d4
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_message_endpoints.py
@@ -0,0 +1,156 @@
+"""Unit tests for controllers.web.message — feedback, more-like-this, suggested questions."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.error import (
+    AppMoreLikeThisDisabledError,
+    NotChatAppError,
+    NotCompletionAppError,
+)
+from controllers.web.message import (
+    MessageFeedbackApi,
+    MessageMoreLikeThisApi,
+    MessageSuggestedQuestionApi,
+)
+from services.errors.app import MoreLikeThisDisabledError
+from services.errors.message import MessageNotExistsError
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# MessageFeedbackApi
+# ---------------------------------------------------------------------------
+class TestMessageFeedbackApi:
+    @patch("controllers.web.message.MessageService.create_feedback")
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_success(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": "like", "content": "great"}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            result = MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+        assert result == {"result": "success"}
+        mock_create.assert_called_once()
+
+    @patch("controllers.web.message.MessageService.create_feedback")
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_null_rating(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": None}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            result = MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+        assert result == {"result": "success"}
+
+    @patch(
+        "controllers.web.message.MessageService.create_feedback",
+        side_effect=MessageNotExistsError(),
+    )
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_message_not_found(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": "dislike"}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+
+# ---------------------------------------------------------------------------
+# MessageMoreLikeThisApi
+# ---------------------------------------------------------------------------
+class TestMessageMoreLikeThisApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(NotCompletionAppError):
+                MessageMoreLikeThisApi().get(_chat_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.message.helper.compact_generate_response", return_value={"answer": "similar"})
+    @patch("controllers.web.message.AppGenerateService.generate_more_like_this")
+    def test_happy_path(self, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        mock_gen.return_value = "response"
+
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            result = MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+        assert result == {"answer": "similar"}
+
+    @patch(
+        "controllers.web.message.AppGenerateService.generate_more_like_this",
+        side_effect=MessageNotExistsError(),
+    )
+    def test_message_not_found(self, mock_gen: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+    @patch(
+        "controllers.web.message.AppGenerateService.generate_more_like_this",
+        side_effect=MoreLikeThisDisabledError(),
+    )
+    def test_feature_disabled(self, mock_gen: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(AppMoreLikeThisDisabledError):
+                MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+
+# ---------------------------------------------------------------------------
+# MessageSuggestedQuestionApi
+# ---------------------------------------------------------------------------
+class TestMessageSuggestedQuestionApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotChatAppError):
+                MessageSuggestedQuestionApi().get(_completion_app(), _end_user(), msg_id)
+
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotChatAppError):
+                MessageSuggestedQuestionApi().get(_completion_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.message.MessageService.get_suggested_questions_after_answer")
+    def test_happy_path(self, mock_suggest: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        mock_suggest.return_value = ["What about X?", "Tell me more about Y."]
+
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            result = MessageSuggestedQuestionApi().get(_chat_app(), _end_user(), msg_id)
+
+        assert result["data"] == ["What about X?", "Tell me more about Y."]
+
+    @patch(
+        "controllers.web.message.MessageService.get_suggested_questions_after_answer",
+        side_effect=MessageNotExistsError(),
+    )
+    def test_message_not_found(self, mock_suggest: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotFound, match="Message not found"):
+                MessageSuggestedQuestionApi().get(_chat_app(), _end_user(), msg_id)
diff --git a/api/tests/unit_tests/controllers/web/test_passport.py b/api/tests/unit_tests/controllers/web/test_passport.py
new file mode 100644
index 0000000000..58d58626b2
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_passport.py
@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from werkzeug.exceptions import NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthRequiredError
+from controllers.web.passport import (
+    PassportService,
+    decode_enterprise_webapp_user_id,
+    exchange_token_for_existing_web_user,
+    generate_session_id,
+)
+from services.webapp_auth_service import WebAppAuthType
+
+
+def test_decode_enterprise_webapp_user_id_none() -> None:
+    assert decode_enterprise_webapp_user_id(None) is None
+
+
+def test_decode_enterprise_webapp_user_id_invalid_source(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(PassportService, "verify", lambda *_args, **_kwargs: {"token_source": "bad"})
+    with pytest.raises(Unauthorized):
+        decode_enterprise_webapp_user_id("token")
+
+
+def test_decode_enterprise_webapp_user_id_valid(monkeypatch: pytest.MonkeyPatch) -> None:
+    decoded = {"token_source": "webapp_login_token", "user_id": "u1"}
+    monkeypatch.setattr(PassportService, "verify", lambda *_args, **_kwargs: decoded)
+    assert decode_enterprise_webapp_user_id("token") == decoded
+
+
+def test_exchange_token_public_flow(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True)
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        return site if _scalar_side_effect.calls == 1 else app_model
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+    monkeypatch.setattr("controllers.web.passport._exchange_for_public_app_token", lambda *_args, **_kwargs: "resp")
+
+    decoded = {"auth_type": "public"}
+    result = exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.PUBLIC)
+    assert result == "resp"
+
+
+def test_exchange_token_requires_external(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True)
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        return site if _scalar_side_effect.calls == 1 else app_model
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    decoded = {"auth_type": "internal"}
+    with pytest.raises(WebAppAuthRequiredError):
+        exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.EXTERNAL)
+
+
+def test_exchange_token_missing_session_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True, tenant_id="t1")
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        if _scalar_side_effect.calls == 1:
+            return site
+        if _scalar_side_effect.calls == 2:
+            return app_model
+        return None
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect, add=lambda *_a, **_k: None, commit=lambda: None)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    decoded = {"auth_type": "internal"}
+    with pytest.raises(NotFound):
+        exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.INTERNAL)
+
+
+def test_generate_session_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    counts = [1, 0]
+
+    def _scalar(*_args, **_kwargs):
+        return counts.pop(0)
+
+    db_session = SimpleNamespace(scalar=_scalar)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    session_id = generate_session_id()
+    assert session_id
diff --git a/api/tests/unit_tests/controllers/web/test_pydantic_models.py b/api/tests/unit_tests/controllers/web/test_pydantic_models.py
new file mode 100644
index 0000000000..dcf8133712
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_pydantic_models.py
@@ -0,0 +1,423 @@
+"""Unit tests for Pydantic models defined in controllers.web modules.
+
+Covers validation logic, field defaults, constraints, and custom validators
+for all ~15 Pydantic models across the web controller layer.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+import pytest
+from pydantic import ValidationError
+
+# ---------------------------------------------------------------------------
+# app.py models
+# ---------------------------------------------------------------------------
+from controllers.web.app import AppAccessModeQuery
+
+
+class TestAppAccessModeQuery:
+    def test_alias_resolution(self) -> None:
+        q = AppAccessModeQuery.model_validate({"appId": "abc", "appCode": "xyz"})
+        assert q.app_id == "abc"
+        assert q.app_code == "xyz"
+
+    def test_defaults_to_none(self) -> None:
+        q = AppAccessModeQuery.model_validate({})
+        assert q.app_id is None
+        assert q.app_code is None
+
+    def test_accepts_snake_case(self) -> None:
+        q = AppAccessModeQuery(app_id="id1", app_code="code1")
+        assert q.app_id == "id1"
+        assert q.app_code == "code1"
+
+
+# ---------------------------------------------------------------------------
+# audio.py models
+# ---------------------------------------------------------------------------
+from controllers.web.audio import TextToAudioPayload
+
+
+class TestTextToAudioPayload:
+    def test_defaults(self) -> None:
+        p = TextToAudioPayload.model_validate({})
+        assert p.message_id is None
+        assert p.voice is None
+        assert p.text is None
+        assert p.streaming is None
+
+    def test_valid_uuid_message_id(self) -> None:
+        uid = str(uuid4())
+        p = TextToAudioPayload(message_id=uid)
+        assert p.message_id == uid
+
+    def test_none_message_id_passthrough(self) -> None:
+        p = TextToAudioPayload(message_id=None)
+        assert p.message_id is None
+
+    def test_invalid_uuid_message_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            TextToAudioPayload(message_id="not-a-uuid")
+
+
+# ---------------------------------------------------------------------------
+# completion.py models
+# ---------------------------------------------------------------------------
+from controllers.web.completion import ChatMessagePayload, CompletionMessagePayload
+
+
+class TestCompletionMessagePayload:
+    def test_defaults(self) -> None:
+        p = CompletionMessagePayload(inputs={})
+        assert p.query == ""
+        assert p.files is None
+        assert p.response_mode is None
+        assert p.retriever_from == "web_app"
+
+    def test_accepts_full_payload(self) -> None:
+        p = CompletionMessagePayload(
+            inputs={"key": "val"},
+            query="test",
+            files=[{"id": "f1"}],
+            response_mode="streaming",
+        )
+        assert p.response_mode == "streaming"
+        assert p.files == [{"id": "f1"}]
+
+    def test_invalid_response_mode(self) -> None:
+        with pytest.raises(ValidationError):
+            CompletionMessagePayload(inputs={}, response_mode="invalid")
+
+
+class TestChatMessagePayload:
+    def test_valid_uuid_fields(self) -> None:
+        cid = str(uuid4())
+        pid = str(uuid4())
+        p = ChatMessagePayload(inputs={}, query="hi", conversation_id=cid, parent_message_id=pid)
+        assert p.conversation_id == cid
+        assert p.parent_message_id == pid
+
+    def test_none_uuid_fields(self) -> None:
+        p = ChatMessagePayload(inputs={}, query="hi")
+        assert p.conversation_id is None
+        assert p.parent_message_id is None
+
+    def test_invalid_conversation_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ChatMessagePayload(inputs={}, query="hi", conversation_id="bad")
+
+    def test_invalid_parent_message_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ChatMessagePayload(inputs={}, query="hi", parent_message_id="bad")
+
+    def test_query_required(self) -> None:
+        with pytest.raises(ValidationError):
+            ChatMessagePayload(inputs={})
+
+
+# ---------------------------------------------------------------------------
+# conversation.py models
+# ---------------------------------------------------------------------------
+from controllers.web.conversation import ConversationListQuery, ConversationRenamePayload
+
+
+class TestConversationListQuery:
+    def test_defaults(self) -> None:
+        q = ConversationListQuery()
+        assert q.last_id is None
+        assert q.limit == 20
+        assert q.pinned is None
+        assert q.sort_by == "-updated_at"
+
+    def test_limit_lower_bound(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(limit=0)
+
+    def test_limit_upper_bound(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(limit=101)
+
+    def test_limit_boundaries_valid(self) -> None:
+        assert ConversationListQuery(limit=1).limit == 1
+        assert ConversationListQuery(limit=100).limit == 100
+
+    def test_valid_sort_by_options(self) -> None:
+        for opt in ("created_at", "-created_at", "updated_at", "-updated_at"):
+            assert ConversationListQuery(sort_by=opt).sort_by == opt
+
+    def test_invalid_sort_by(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(sort_by="invalid")
+
+    def test_valid_last_id(self) -> None:
+        uid = str(uuid4())
+        assert ConversationListQuery(last_id=uid).last_id == uid
+
+    def test_invalid_last_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ConversationListQuery(last_id="not-uuid")
+
+
+class TestConversationRenamePayload:
+    def test_auto_generate_true_no_name_required(self) -> None:
+        p = ConversationRenamePayload(auto_generate=True)
+        assert p.name is None
+
+    def test_auto_generate_false_requires_name(self) -> None:
+        with pytest.raises(ValidationError, match="name is required"):
+            ConversationRenamePayload(auto_generate=False)
+
+    def test_auto_generate_false_blank_name_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="name is required"):
+            ConversationRenamePayload(auto_generate=False, name="   ")
+
+    def test_auto_generate_false_with_valid_name(self) -> None:
+        p = ConversationRenamePayload(auto_generate=False, name="My Chat")
+        assert p.name == "My Chat"
+
+    def test_defaults(self) -> None:
+        p = ConversationRenamePayload(name="test")
+        assert p.auto_generate is False
+        assert p.name == "test"
+
+
+# ---------------------------------------------------------------------------
+# message.py models
+# ---------------------------------------------------------------------------
+from controllers.web.message import MessageFeedbackPayload, MessageListQuery, MessageMoreLikeThisQuery
+
+
+class TestMessageListQuery:
+    def test_valid_query(self) -> None:
+        cid = str(uuid4())
+        q = MessageListQuery(conversation_id=cid)
+        assert q.conversation_id == cid
+        assert q.first_id is None
+        assert q.limit == 20
+
+    def test_invalid_conversation_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            MessageListQuery(conversation_id="bad")
+
+    def test_limit_bounds(self) -> None:
+        cid = str(uuid4())
+        with pytest.raises(ValidationError):
+            MessageListQuery(conversation_id=cid, limit=0)
+        with pytest.raises(ValidationError):
+            MessageListQuery(conversation_id=cid, limit=101)
+
+    def test_valid_first_id(self) -> None:
+        cid = str(uuid4())
+        fid = str(uuid4())
+        q = MessageListQuery(conversation_id=cid, first_id=fid)
+        assert q.first_id == fid
+
+    def test_invalid_first_id(self) -> None:
+        cid = str(uuid4())
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            MessageListQuery(conversation_id=cid, first_id="invalid")
+
+
+class TestMessageFeedbackPayload:
+    def test_defaults(self) -> None:
+        p = MessageFeedbackPayload()
+        assert p.rating is None
+        assert p.content is None
+
+    def test_valid_ratings(self) -> None:
+        assert MessageFeedbackPayload(rating="like").rating == "like"
+        assert MessageFeedbackPayload(rating="dislike").rating == "dislike"
+
+    def test_invalid_rating(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageFeedbackPayload(rating="neutral")
+
+
+class TestMessageMoreLikeThisQuery:
+    def test_valid_modes(self) -> None:
+        assert MessageMoreLikeThisQuery(response_mode="blocking").response_mode == "blocking"
+        assert MessageMoreLikeThisQuery(response_mode="streaming").response_mode == "streaming"
+
+    def test_invalid_mode(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageMoreLikeThisQuery(response_mode="invalid")
+
+    def test_required(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageMoreLikeThisQuery()
+
+
+# ---------------------------------------------------------------------------
+# remote_files.py models
+# ---------------------------------------------------------------------------
+from controllers.web.remote_files import RemoteFileUploadPayload
+
+
+class TestRemoteFileUploadPayload:
+    def test_valid_url(self) -> None:
+        p = RemoteFileUploadPayload(url="https://example.com/file.pdf")
+        assert str(p.url) == "https://example.com/file.pdf"
+
+    def test_invalid_url(self) -> None:
+        with pytest.raises(ValidationError):
+            RemoteFileUploadPayload(url="not-a-url")
+
+    def test_url_required(self) -> None:
+        with pytest.raises(ValidationError):
+            RemoteFileUploadPayload()
+
+
+# ---------------------------------------------------------------------------
+# saved_message.py models
+# ---------------------------------------------------------------------------
+from controllers.web.saved_message import SavedMessageCreatePayload, SavedMessageListQuery
+
+
+class TestSavedMessageListQuery:
+    def test_defaults(self) -> None:
+        q = SavedMessageListQuery()
+        assert q.last_id is None
+        assert q.limit == 20
+
+    def test_limit_bounds(self) -> None:
+        with pytest.raises(ValidationError):
+            SavedMessageListQuery(limit=0)
+        with pytest.raises(ValidationError):
+            SavedMessageListQuery(limit=101)
+
+    def test_valid_last_id(self) -> None:
+        uid = str(uuid4())
+        q = SavedMessageListQuery(last_id=uid)
+        assert q.last_id == uid
+
+    def test_empty_last_id(self) -> None:
+        q = SavedMessageListQuery(last_id="")
+        assert q.last_id == ""
+
+
+class TestSavedMessageCreatePayload:
+    def test_valid_message_id(self) -> None:
+        uid = str(uuid4())
+        p = SavedMessageCreatePayload(message_id=uid)
+        assert p.message_id == uid
+
+    def test_required(self) -> None:
+        with pytest.raises(ValidationError):
+            SavedMessageCreatePayload()
+
+
+# ---------------------------------------------------------------------------
+# workflow.py models
+# ---------------------------------------------------------------------------
+from controllers.web.workflow import WorkflowRunPayload
+
+
+class TestWorkflowRunPayload:
+    def test_defaults(self) -> None:
+        p = WorkflowRunPayload(inputs={})
+        assert p.inputs == {}
+        assert p.files is None
+
+    def test_with_files(self) -> None:
+        p = WorkflowRunPayload(inputs={"k": "v"}, files=[{"id": "f1"}])
+        assert p.files == [{"id": "f1"}]
+
+    def test_inputs_required(self) -> None:
+        with pytest.raises(ValidationError):
+            WorkflowRunPayload()
+
+
+# ---------------------------------------------------------------------------
+# forgot_password.py models
+# ---------------------------------------------------------------------------
+from controllers.web.forgot_password import (
+    ForgotPasswordCheckPayload,
+    ForgotPasswordResetPayload,
+    ForgotPasswordSendPayload,
+)
+
+
+class TestForgotPasswordSendPayload:
+    def test_valid_email(self) -> None:
+        p = ForgotPasswordSendPayload(email="user@example.com")
+        assert p.email == "user@example.com"
+
+    def test_invalid_email(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid email"):
+            ForgotPasswordSendPayload(email="not-an-email")
+
+    def test_language_optional(self) -> None:
+        p = ForgotPasswordSendPayload(email="a@b.com")
+        assert p.language is None
+
+
+class TestForgotPasswordCheckPayload:
+    def test_valid(self) -> None:
+        p = ForgotPasswordCheckPayload(email="a@b.com", code="1234", token="tok")
+        assert p.email == "a@b.com"
+        assert p.code == "1234"
+        assert p.token == "tok"
+
+    def test_empty_token_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            ForgotPasswordCheckPayload(email="a@b.com", code="1234", token="")
+
+
+class TestForgotPasswordResetPayload:
+    def test_valid_passwords(self) -> None:
+        p = ForgotPasswordResetPayload(token="tok", new_password="Valid1234", password_confirm="Valid1234")
+        assert p.new_password == "Valid1234"
+
+    def test_weak_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="short", password_confirm="short")
+
+    def test_letters_only_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="abcdefghi", password_confirm="abcdefghi")
+
+    def test_digits_only_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="123456789", password_confirm="123456789")
+
+
+# ---------------------------------------------------------------------------
+# login.py models
+# ---------------------------------------------------------------------------
+from controllers.web.login import EmailCodeLoginSendPayload, EmailCodeLoginVerifyPayload, LoginPayload
+
+
+class TestLoginPayload:
+    def test_valid(self) -> None:
+        p = LoginPayload(email="a@b.com", password="Valid1234")
+        assert p.email == "a@b.com"
+
+    def test_invalid_email(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid email"):
+            LoginPayload(email="bad", password="Valid1234")
+
+    def test_weak_password(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            LoginPayload(email="a@b.com", password="weak")
+
+
+class TestEmailCodeLoginSendPayload:
+    def test_valid(self) -> None:
+        p = EmailCodeLoginSendPayload(email="a@b.com")
+        assert p.language is None
+
+    def test_with_language(self) -> None:
+        p = EmailCodeLoginSendPayload(email="a@b.com", language="zh-Hans")
+        assert p.language == "zh-Hans"
+
+
+class TestEmailCodeLoginVerifyPayload:
+    def test_valid(self) -> None:
+        p = EmailCodeLoginVerifyPayload(email="a@b.com", code="1234", token="tok")
+        assert p.code == "1234"
+
+    def test_empty_token_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            EmailCodeLoginVerifyPayload(email="a@b.com", code="1234", token="")
diff --git a/api/tests/unit_tests/controllers/web/test_remote_files.py b/api/tests/unit_tests/controllers/web/test_remote_files.py
new file mode 100644
index 0000000000..8554f440b7
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_remote_files.py
@@ -0,0 +1,147 @@
+"""Unit tests for controllers.web.remote_files endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.common.errors import FileTooLargeError, RemoteFileUploadError
+from controllers.web.remote_files import RemoteFileInfoApi, RemoteFileUploadApi
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# RemoteFileInfoApi
+# ---------------------------------------------------------------------------
+class TestRemoteFileInfoApi:
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    def test_head_success(self, mock_proxy: MagicMock, app: Flask) -> None:
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.headers = {"Content-Type": "application/pdf", "Content-Length": "1024"}
+        mock_proxy.head.return_value = mock_resp
+
+        with app.test_request_context("/remote-files/https%3A%2F%2Fexample.com%2Ffile.pdf"):
+            result = RemoteFileInfoApi().get(_app_model(), _end_user(), "https%3A%2F%2Fexample.com%2Ffile.pdf")
+
+        assert result["file_type"] == "application/pdf"
+        assert result["file_length"] == 1024
+
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    def test_fallback_to_get(self, mock_proxy: MagicMock, app: Flask) -> None:
+        head_resp = MagicMock()
+        head_resp.status_code = 405  # Method not allowed
+        get_resp = MagicMock()
+        get_resp.status_code = 200
+        get_resp.headers = {"Content-Type": "text/plain", "Content-Length": "42"}
+        get_resp.raise_for_status = MagicMock()
+        mock_proxy.head.return_value = head_resp
+        mock_proxy.get.return_value = get_resp
+
+        with app.test_request_context("/remote-files/https%3A%2F%2Fexample.com%2Ffile.txt"):
+            result = RemoteFileInfoApi().get(_app_model(), _end_user(), "https%3A%2F%2Fexample.com%2Ffile.txt")
+
+        assert result["file_type"] == "text/plain"
+        mock_proxy.get.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# RemoteFileUploadApi
+# ---------------------------------------------------------------------------
+class TestRemoteFileUploadApi:
+    @patch("controllers.web.remote_files.file_helpers.get_signed_file_url", return_value="https://signed-url")
+    @patch("controllers.web.remote_files.FileService")
+    @patch("controllers.web.remote_files.helpers.guess_file_info_from_response")
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    @patch("controllers.web.remote_files.db")
+    def test_upload_success(
+        self,
+        mock_db: MagicMock,
+        mock_ns: MagicMock,
+        mock_proxy: MagicMock,
+        mock_guess: MagicMock,
+        mock_file_svc_cls: MagicMock,
+        mock_signed: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_db.engine = "engine"
+        mock_ns.payload = {"url": "https://example.com/file.pdf"}
+        head_resp = MagicMock()
+        head_resp.status_code = 200
+        head_resp.content = b"pdf-content"
+        head_resp.request.method = "HEAD"
+        mock_proxy.head.return_value = head_resp
+        get_resp = MagicMock()
+        get_resp.content = b"pdf-content"
+        mock_proxy.get.return_value = get_resp
+
+        mock_guess.return_value = SimpleNamespace(
+            filename="file.pdf", extension="pdf", mimetype="application/pdf", size=100
+        )
+        mock_file_svc_cls.is_file_size_within_limit.return_value = True
+
+        from datetime import datetime
+
+        upload_file = SimpleNamespace(
+            id="f-1",
+            name="file.pdf",
+            size=100,
+            extension="pdf",
+            mime_type="application/pdf",
+            created_by="eu-1",
+            created_at=datetime(2024, 1, 1),
+        )
+        mock_file_svc_cls.return_value.upload_file.return_value = upload_file
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            result, status = RemoteFileUploadApi().post(_app_model(), _end_user())
+
+        assert status == 201
+        assert result["id"] == "f-1"
+
+    @patch("controllers.web.remote_files.FileService.is_file_size_within_limit", return_value=False)
+    @patch("controllers.web.remote_files.helpers.guess_file_info_from_response")
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    def test_file_too_large(
+        self,
+        mock_ns: MagicMock,
+        mock_proxy: MagicMock,
+        mock_guess: MagicMock,
+        mock_size_check: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_ns.payload = {"url": "https://example.com/big.zip"}
+        head_resp = MagicMock()
+        head_resp.status_code = 200
+        mock_proxy.head.return_value = head_resp
+        mock_guess.return_value = SimpleNamespace(
+            filename="big.zip", extension="zip", mimetype="application/zip", size=999999999
+        )
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            with pytest.raises(FileTooLargeError):
+                RemoteFileUploadApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    def test_fetch_failure_raises(self, mock_ns: MagicMock, mock_proxy: MagicMock, app: Flask) -> None:
+        import httpx
+
+        mock_ns.payload = {"url": "https://example.com/bad"}
+        mock_proxy.head.side_effect = httpx.RequestError("connection failed")
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            with pytest.raises(RemoteFileUploadError):
+                RemoteFileUploadApi().post(_app_model(), _end_user())
diff --git a/api/tests/unit_tests/controllers/web/test_saved_message.py b/api/tests/unit_tests/controllers/web/test_saved_message.py
new file mode 100644
index 0000000000..3d55804912
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_saved_message.py
@@ -0,0 +1,97 @@
+"""Unit tests for controllers.web.saved_message endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.error import NotCompletionAppError
+from controllers.web.saved_message import SavedMessageApi, SavedMessageListApi
+from services.errors.message import MessageNotExistsError
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageListApi (GET)
+# ---------------------------------------------------------------------------
+class TestSavedMessageListApiGet:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/saved-messages"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageListApi().get(_chat_app(), _end_user())
+
+    @patch("controllers.web.saved_message.SavedMessageService.pagination_by_last_id")
+    def test_happy_path(self, mock_paginate: MagicMock, app: Flask) -> None:
+        mock_paginate.return_value = SimpleNamespace(limit=20, has_more=False, data=[])
+
+        with app.test_request_context("/saved-messages?limit=20"):
+            result = SavedMessageListApi().get(_completion_app(), _end_user())
+
+        assert result["limit"] == 20
+        assert result["has_more"] is False
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageListApi (POST)
+# ---------------------------------------------------------------------------
+class TestSavedMessageListApiPost:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/saved-messages", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageListApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.saved_message.SavedMessageService.save")
+    @patch("controllers.web.saved_message.web_ns")
+    def test_save_success(self, mock_ns: MagicMock, mock_save: MagicMock, app: Flask) -> None:
+        msg_id = str(uuid4())
+        mock_ns.payload = {"message_id": msg_id}
+
+        with app.test_request_context("/saved-messages", method="POST"):
+            result = SavedMessageListApi().post(_completion_app(), _end_user())
+
+        assert result["result"] == "success"
+
+    @patch("controllers.web.saved_message.SavedMessageService.save", side_effect=MessageNotExistsError())
+    @patch("controllers.web.saved_message.web_ns")
+    def test_save_not_found(self, mock_ns: MagicMock, mock_save: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"message_id": str(uuid4())}
+
+        with app.test_request_context("/saved-messages", method="POST"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                SavedMessageListApi().post(_completion_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageApi (DELETE)
+# ---------------------------------------------------------------------------
+class TestSavedMessageApi:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/saved-messages/{msg_id}", method="DELETE"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageApi().delete(_chat_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.saved_message.SavedMessageService.delete")
+    def test_delete_success(self, mock_delete: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/saved-messages/{msg_id}", method="DELETE"):
+            result, status = SavedMessageApi().delete(_completion_app(), _end_user(), msg_id)
+
+        assert status == 204
+        assert result["result"] == "success"
diff --git a/api/tests/unit_tests/controllers/web/test_site.py b/api/tests/unit_tests/controllers/web/test_site.py
new file mode 100644
index 0000000000..557bf93e9e
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_site.py
@@ -0,0 +1,126 @@
+"""Unit tests for controllers.web.site endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import Forbidden
+
+from controllers.web.site import AppSiteApi, AppSiteInfo
+
+
+def _tenant(*, status: str = "normal") -> SimpleNamespace:
+    return SimpleNamespace(
+        id="tenant-1",
+        status=status,
+        plan="basic",
+        custom_config_dict={"remove_webapp_brand": False, "replace_webapp_logo": False},
+    )
+
+
+def _site() -> SimpleNamespace:
+    return SimpleNamespace(
+        title="Site",
+        icon_type="emoji",
+        icon="robot",
+        icon_background="#fff",
+        description="desc",
+        default_language="en",
+        chat_color_theme="light",
+        chat_color_theme_inverted=False,
+        copyright=None,
+        privacy_policy=None,
+        custom_disclaimer=None,
+        prompt_public=False,
+        show_workflow_steps=True,
+        use_icon_as_answer_icon=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# AppSiteApi
+# ---------------------------------------------------------------------------
+class TestAppSiteApi:
+    @patch("controllers.web.site.FeatureService.get_features")
+    @patch("controllers.web.site.db")
+    def test_happy_path(self, mock_db: MagicMock, mock_features: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        mock_features.return_value = SimpleNamespace(can_replace_logo=False)
+        site_obj = _site()
+        mock_db.session.query.return_value.where.return_value.first.return_value = site_obj
+        tenant = _tenant()
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant, enable_site=True)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            result = AppSiteApi().get(app_model, end_user)
+
+        # marshal_with serializes AppSiteInfo to a dict
+        assert result["app_id"] == "app-1"
+        assert result["plan"] == "basic"
+        assert result["enable_site"] is True
+
+    @patch("controllers.web.site.db")
+    def test_missing_site_raises_forbidden(self, mock_db: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        mock_db.session.query.return_value.where.return_value.first.return_value = None
+        tenant = _tenant()
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            with pytest.raises(Forbidden):
+                AppSiteApi().get(app_model, end_user)
+
+    @patch("controllers.web.site.db")
+    def test_archived_tenant_raises_forbidden(self, mock_db: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        from models.account import TenantStatus
+
+        mock_db.session.query.return_value.where.return_value.first.return_value = _site()
+        tenant = SimpleNamespace(
+            id="tenant-1",
+            status=TenantStatus.ARCHIVE,
+            plan="basic",
+            custom_config_dict={},
+        )
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            with pytest.raises(Forbidden):
+                AppSiteApi().get(app_model, end_user)
+
+
+# ---------------------------------------------------------------------------
+# AppSiteInfo
+# ---------------------------------------------------------------------------
+class TestAppSiteInfo:
+    def test_basic_fields(self) -> None:
+        tenant = _tenant()
+        site_obj = _site()
+        info = AppSiteInfo(tenant, SimpleNamespace(id="app-1", enable_site=True), site_obj, "eu-1", False)
+
+        assert info.app_id == "app-1"
+        assert info.end_user_id == "eu-1"
+        assert info.enable_site is True
+        assert info.plan == "basic"
+        assert info.can_replace_logo is False
+        assert info.model_config is None
+
+    @patch("controllers.web.site.dify_config", SimpleNamespace(FILES_URL="https://files.example.com"))
+    def test_can_replace_logo_sets_custom_config(self) -> None:
+        tenant = SimpleNamespace(
+            id="tenant-1",
+            plan="pro",
+            custom_config_dict={"remove_webapp_brand": True, "replace_webapp_logo": True},
+        )
+        site_obj = _site()
+        info = AppSiteInfo(tenant, SimpleNamespace(id="app-1", enable_site=True), site_obj, "eu-1", True)
+
+        assert info.can_replace_logo is True
+        assert info.custom_config["remove_webapp_brand"] is True
+        assert "webapp-logo" in info.custom_config["replace_webapp_logo"]
diff --git a/api/tests/unit_tests/controllers/web/test_web_login.py b/api/tests/unit_tests/controllers/web/test_web_login.py
index e62993e8d5..0661c02578 100644
--- a/api/tests/unit_tests/controllers/web/test_web_login.py
+++ b/api/tests/unit_tests/controllers/web/test_web_login.py
@@ -5,7 +5,8 @@ from unittest.mock import MagicMock, patch
 import pytest
 from flask import Flask
 
-from controllers.web.login import EmailCodeLoginApi, EmailCodeLoginSendEmailApi
+import services.errors.account
+from controllers.web.login import EmailCodeLoginApi, EmailCodeLoginSendEmailApi, LoginApi, LoginStatusApi, LogoutApi
 
 
 def encode_code(code: str) -> str:
@@ -89,3 +90,114 @@ class TestEmailCodeLoginApi:
         mock_revoke_token.assert_called_once_with("token-123")
         mock_login.assert_called_once()
         mock_reset_login_rate.assert_called_once_with("user@example.com")
+
+
+class TestLoginApi:
+    @patch("controllers.web.login.WebAppAuthService.login", return_value="access-tok")
+    @patch("controllers.web.login.WebAppAuthService.authenticate")
+    def test_login_success(self, mock_auth: MagicMock, mock_login: MagicMock, app: Flask) -> None:
+        mock_auth.return_value = MagicMock()
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            response = LoginApi().post()
+
+        assert response.get_json()["data"]["access_token"] == "access-tok"
+        mock_auth.assert_called_once()
+
+    @patch(
+        "controllers.web.login.WebAppAuthService.authenticate",
+        side_effect=services.errors.account.AccountLoginError(),
+    )
+    def test_login_banned_account(self, mock_auth: MagicMock, app: Flask) -> None:
+        from controllers.console.error import AccountBannedError
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            with pytest.raises(AccountBannedError):
+                LoginApi().post()
+
+    @patch(
+        "controllers.web.login.WebAppAuthService.authenticate",
+        side_effect=services.errors.account.AccountPasswordError(),
+    )
+    def test_login_wrong_password(self, mock_auth: MagicMock, app: Flask) -> None:
+        from controllers.console.auth.error import AuthenticationFailedError
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            with pytest.raises(AuthenticationFailedError):
+                LoginApi().post()
+
+
+class TestLoginStatusApi:
+    @patch("controllers.web.login.extract_webapp_access_token", return_value=None)
+    def test_no_app_code_returns_logged_in_false(self, mock_extract: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/web/login/status"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is False
+        assert result["app_logged_in"] is False
+
+    @patch("controllers.web.login.decode_jwt_token")
+    @patch("controllers.web.login.PassportService")
+    @patch("controllers.web.login.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    @patch("controllers.web.login.AppService.get_app_id_by_code", return_value="app-1")
+    @patch("controllers.web.login.extract_webapp_access_token", return_value="tok")
+    def test_public_app_user_logged_in(
+        self,
+        mock_extract: MagicMock,
+        mock_app_id: MagicMock,
+        mock_perm: MagicMock,
+        mock_passport: MagicMock,
+        mock_decode: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_decode.return_value = (MagicMock(), MagicMock())
+
+        with app.test_request_context("/web/login/status?app_code=code1"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is True
+        assert result["app_logged_in"] is True
+
+    @patch("controllers.web.login.decode_jwt_token", side_effect=Exception("bad"))
+    @patch("controllers.web.login.PassportService")
+    @patch("controllers.web.login.WebAppAuthService.is_app_require_permission_check", return_value=True)
+    @patch("controllers.web.login.AppService.get_app_id_by_code", return_value="app-1")
+    @patch("controllers.web.login.extract_webapp_access_token", return_value="tok")
+    def test_private_app_passport_fails(
+        self,
+        mock_extract: MagicMock,
+        mock_app_id: MagicMock,
+        mock_perm: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_decode: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_passport_cls.return_value.verify.side_effect = Exception("bad")
+
+        with app.test_request_context("/web/login/status?app_code=code1"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is False
+        assert result["app_logged_in"] is False
+
+
+class TestLogoutApi:
+    @patch("controllers.web.login.clear_webapp_access_token_from_cookie")
+    def test_logout_success(self, mock_clear: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/web/logout", method="POST"):
+            response = LogoutApi().post()
+
+        assert response.get_json() == {"result": "success"}
+        mock_clear.assert_called_once()
diff --git a/api/tests/unit_tests/controllers/web/test_web_passport.py b/api/tests/unit_tests/controllers/web/test_web_passport.py
new file mode 100644
index 0000000000..19b1d8504a
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_web_passport.py
@@ -0,0 +1,192 @@
+"""Unit tests for controllers.web.passport — token issuance and enterprise auth exchange."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthRequiredError
+from controllers.web.passport import (
+    PassportResource,
+    decode_enterprise_webapp_user_id,
+    exchange_token_for_existing_web_user,
+    generate_session_id,
+)
+from services.webapp_auth_service import WebAppAuthType
+
+
+# ---------------------------------------------------------------------------
+# decode_enterprise_webapp_user_id
+# ---------------------------------------------------------------------------
+class TestDecodeEnterpriseWebappUserId:
+    def test_none_token_returns_none(self) -> None:
+        assert decode_enterprise_webapp_user_id(None) is None
+
+    @patch("controllers.web.passport.PassportService")
+    def test_valid_token_returns_decoded(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {
+            "token_source": "webapp_login_token",
+            "user_id": "u1",
+        }
+        result = decode_enterprise_webapp_user_id("valid-jwt")
+        assert result["user_id"] == "u1"
+
+    @patch("controllers.web.passport.PassportService")
+    def test_wrong_source_raises_unauthorized(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {
+            "token_source": "other_source",
+        }
+        with pytest.raises(Unauthorized, match="Expected 'webapp_login_token'"):
+            decode_enterprise_webapp_user_id("bad-jwt")
+
+    @patch("controllers.web.passport.PassportService")
+    def test_missing_source_raises_unauthorized(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {}
+        with pytest.raises(Unauthorized, match="Expected 'webapp_login_token'"):
+            decode_enterprise_webapp_user_id("no-source-jwt")
+
+
+# ---------------------------------------------------------------------------
+# generate_session_id
+# ---------------------------------------------------------------------------
+class TestGenerateSessionId:
+    @patch("controllers.web.passport.db")
+    def test_returns_unique_session_id(self, mock_db: MagicMock) -> None:
+        mock_db.session.scalar.return_value = 0
+        sid = generate_session_id()
+        assert isinstance(sid, str)
+        assert len(sid) == 36  # UUID format
+
+    @patch("controllers.web.passport.db")
+    def test_retries_on_collision(self, mock_db: MagicMock) -> None:
+        # First call returns count=1 (collision), second returns 0
+        mock_db.session.scalar.side_effect = [1, 0]
+        sid = generate_session_id()
+        assert isinstance(sid, str)
+        assert mock_db.session.scalar.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# exchange_token_for_existing_web_user
+# ---------------------------------------------------------------------------
+class TestExchangeTokenForExistingWebUser:
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_external_auth_type_mismatch_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        site = SimpleNamespace(code="code1", app_id="app-1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+
+        decoded = {"user_id": "u1", "auth_type": "internal"}  # mismatch: expected "external"
+        with pytest.raises(WebAppAuthRequiredError, match="external"):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.EXTERNAL
+            )
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_internal_auth_type_mismatch_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        site = SimpleNamespace(code="code1", app_id="app-1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+
+        decoded = {"user_id": "u1", "auth_type": "external"}  # mismatch: expected "internal"
+        with pytest.raises(WebAppAuthRequiredError, match="internal"):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.INTERNAL
+            )
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_site_not_found_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        mock_db.session.scalar.return_value = None
+        decoded = {"user_id": "u1", "auth_type": "external"}
+        with pytest.raises(NotFound):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.EXTERNAL
+            )
+
+
+# ---------------------------------------------------------------------------
+# PassportResource.get
+# ---------------------------------------------------------------------------
+class TestPassportResource:
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_missing_app_code_raises_unauthorized(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        with app.test_request_context("/passport"):
+            with pytest.raises(Unauthorized, match="X-App-Code"):
+                PassportResource().get()
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.generate_session_id", return_value="new-sess-id")
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_creates_new_end_user_when_no_user_id(
+        self,
+        mock_features: MagicMock,
+        mock_db: MagicMock,
+        mock_gen_session: MagicMock,
+        mock_passport_cls: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+        mock_passport_cls.return_value.issue.return_value = "issued-token"
+
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            response = PassportResource().get()
+
+        assert response.get_json()["access_token"] == "issued-token"
+        mock_db.session.add.assert_called_once()
+        mock_db.session.commit.assert_called_once()
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_reuses_existing_end_user_when_user_id_provided(
+        self,
+        mock_features: MagicMock,
+        mock_db: MagicMock,
+        mock_passport_cls: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        existing_user = SimpleNamespace(id="eu-1", session_id="sess-existing")
+        mock_db.session.scalar.side_effect = [site, app_model, existing_user]
+        mock_passport_cls.return_value.issue.return_value = "reused-token"
+
+        with app.test_request_context("/passport?user_id=sess-existing", headers={"X-App-Code": "code1"}):
+            response = PassportResource().get()
+
+        assert response.get_json()["access_token"] == "reused-token"
+        # Should not create a new end user
+        mock_db.session.add.assert_not_called()
+
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_site_not_found_raises(self, mock_features: MagicMock, mock_db: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        mock_db.session.scalar.return_value = None
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            with pytest.raises(NotFound):
+                PassportResource().get()
+
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_disabled_app_raises_not_found(self, mock_features: MagicMock, mock_db: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        disabled_app = SimpleNamespace(id="app-1", status="normal", enable_site=False)
+        mock_db.session.scalar.side_effect = [site, disabled_app]
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            with pytest.raises(NotFound):
+                PassportResource().get()
diff --git a/api/tests/unit_tests/controllers/web/test_workflow.py b/api/tests/unit_tests/controllers/web/test_workflow.py
new file mode 100644
index 0000000000..0973340527
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_workflow.py
@@ -0,0 +1,95 @@
+"""Unit tests for controllers.web.workflow endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.error import (
+    NotWorkflowAppError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from controllers.web.workflow import WorkflowRunApi, WorkflowTaskStopApi
+from core.errors.error import ProviderTokenNotInitError, QuotaExceededError
+
+
+def _workflow_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="workflow")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# WorkflowRunApi
+# ---------------------------------------------------------------------------
+class TestWorkflowRunApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(NotWorkflowAppError):
+                WorkflowRunApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.workflow.helper.compact_generate_response", return_value={"result": "ok"})
+    @patch("controllers.web.workflow.AppGenerateService.generate")
+    @patch("controllers.web.workflow.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {"key": "val"}}
+        mock_gen.return_value = "response"
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            result = WorkflowRunApi().post(_workflow_app(), _end_user())
+
+        assert result == {"result": "ok"}
+
+    @patch(
+        "controllers.web.workflow.AppGenerateService.generate",
+        side_effect=ProviderTokenNotInitError(description="not init"),
+    )
+    @patch("controllers.web.workflow.web_ns")
+    def test_provider_not_init(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(ProviderNotInitializeError):
+                WorkflowRunApi().post(_workflow_app(), _end_user())
+
+    @patch(
+        "controllers.web.workflow.AppGenerateService.generate",
+        side_effect=QuotaExceededError(),
+    )
+    @patch("controllers.web.workflow.web_ns")
+    def test_quota_exceeded(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(ProviderQuotaExceededError):
+                WorkflowRunApi().post(_workflow_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# WorkflowTaskStopApi
+# ---------------------------------------------------------------------------
+class TestWorkflowTaskStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/workflows/tasks/task-1/stop", method="POST"):
+            with pytest.raises(NotWorkflowAppError):
+                WorkflowTaskStopApi().post(_chat_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.workflow.GraphEngineManager.send_stop_command")
+    @patch("controllers.web.workflow.AppQueueManager.set_stop_flag_no_user_check")
+    def test_stop_calls_both_mechanisms(self, mock_legacy: MagicMock, mock_graph: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/workflows/tasks/task-1/stop", method="POST"):
+            result = WorkflowTaskStopApi().post(_workflow_app(), _end_user(), "task-1")
+
+        assert result == {"result": "success"}
+        mock_legacy.assert_called_once_with("task-1")
+        mock_graph.assert_called_once_with("task-1")
diff --git a/api/tests/unit_tests/controllers/web/test_workflow_events.py b/api/tests/unit_tests/controllers/web/test_workflow_events.py
new file mode 100644
index 0000000000..64c09b5e22
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_workflow_events.py
@@ -0,0 +1,127 @@
+"""Unit tests for controllers.web.workflow_events endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.error import NotFoundError
+from controllers.web.workflow_events import WorkflowEventsApi
+from models.enums import CreatorUserRole
+
+
+def _workflow_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", tenant_id="tenant-1", mode="workflow")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# WorkflowEventsApi
+# ---------------------------------------------------------------------------
+class TestWorkflowEventsApi:
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_not_found(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = None
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_wrong_app(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="other-app",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="eu-1",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_not_created_by_end_user(
+        self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask
+    ) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.ACCOUNT,
+            created_by="eu-1",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_wrong_end_user(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="other-user",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.WorkflowResponseConverter")
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_finished_run_returns_sse_response(
+        self, mock_db: MagicMock, mock_factory: MagicMock, mock_converter: MagicMock, app: Flask
+    ) -> None:
+        from datetime import datetime
+
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="eu-1",
+            finished_at=datetime(2024, 1, 1),
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        finish_response = MagicMock()
+        finish_response.model_dump.return_value = {"task_id": "run-1"}
+        finish_response.event.value = "workflow_finished"
+        mock_converter.workflow_run_result_to_finish_response.return_value = finish_response
+
+        with app.test_request_context("/workflow/run-1/events"):
+            response = WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+        assert response.mimetype == "text/event-stream"
diff --git a/api/tests/unit_tests/controllers/web/test_wraps.py b/api/tests/unit_tests/controllers/web/test_wraps.py
new file mode 100644
index 0000000000..85049ae975
--- /dev/null
+++ b/api/tests/unit_tests/controllers/web/test_wraps.py
@@ -0,0 +1,393 @@
+"""Unit tests for controllers.web.wraps — JWT auth decorator and validation helpers."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import BadRequest, NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthAccessDeniedError, WebAppAuthRequiredError
+from controllers.web.wraps import (
+    _validate_user_accessibility,
+    _validate_webapp_token,
+    decode_jwt_token,
+)
+
+
+# ---------------------------------------------------------------------------
+# _validate_webapp_token
+# ---------------------------------------------------------------------------
+class TestValidateWebappToken:
+    def test_enterprise_enabled_and_app_auth_requires_webapp_source(self) -> None:
+        """When both flags are true, a non-webapp source must raise."""
+        decoded = {"token_source": "other"}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_enterprise_enabled_and_app_auth_accepts_webapp_source(self) -> None:
+        decoded = {"token_source": "webapp"}
+        _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_enterprise_enabled_and_app_auth_missing_source_raises(self) -> None:
+        decoded = {}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_public_app_rejects_webapp_source(self) -> None:
+        """When auth is not required, a webapp-sourced token must be rejected."""
+        decoded = {"token_source": "webapp"}
+        with pytest.raises(Unauthorized):
+            _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_public_app_accepts_non_webapp_source(self) -> None:
+        decoded = {"token_source": "other"}
+        _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_public_app_accepts_no_source(self) -> None:
+        decoded = {}
+        _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_system_enabled_but_app_public(self) -> None:
+        """system_webapp_auth_enabled=True but app is public — webapp source rejected."""
+        decoded = {"token_source": "webapp"}
+        with pytest.raises(Unauthorized):
+            _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=True)
+
+
+# ---------------------------------------------------------------------------
+# _validate_user_accessibility
+# ---------------------------------------------------------------------------
+class TestValidateUserAccessibility:
+    def test_skips_when_auth_disabled(self) -> None:
+        """No checks when system or app auth is disabled."""
+        _validate_user_accessibility(
+            decoded={},
+            app_code="code",
+            app_web_auth_enabled=False,
+            system_webapp_auth_enabled=False,
+            webapp_settings=None,
+        )
+
+    def test_missing_user_id_raises(self) -> None:
+        decoded = {}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=SimpleNamespace(access_mode="internal"),
+            )
+
+    def test_missing_webapp_settings_raises(self) -> None:
+        decoded = {"user_id": "u1"}
+        with pytest.raises(WebAppAuthRequiredError, match="settings not found"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=None,
+            )
+
+    def test_missing_auth_type_raises(self) -> None:
+        decoded = {"user_id": "u1", "granted_at": 1}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="auth_type"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    def test_missing_granted_at_raises(self) -> None:
+        decoded = {"user_id": "u1", "auth_type": "external"}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="granted_at"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_app_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_external_auth_type_checks_sso_update_time(
+        self, mock_perm_check: MagicMock, mock_sso_time: MagicMock
+    ) -> None:
+        # granted_at is before SSO update time → denied
+        mock_sso_time.return_value = datetime.now(UTC)
+        old_granted = int((datetime.now(UTC) - timedelta(hours=1)).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": old_granted}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="SSO settings"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_workspace_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_internal_auth_type_checks_workspace_sso_update_time(
+        self, mock_perm_check: MagicMock, mock_workspace_sso: MagicMock
+    ) -> None:
+        mock_workspace_sso.return_value = datetime.now(UTC)
+        old_granted = int((datetime.now(UTC) - timedelta(hours=1)).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "internal", "granted_at": old_granted}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="SSO settings"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_app_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_external_auth_passes_when_granted_after_sso_update(
+        self, mock_perm_check: MagicMock, mock_sso_time: MagicMock
+    ) -> None:
+        mock_sso_time.return_value = datetime.now(UTC) - timedelta(hours=2)
+        recent_granted = int(datetime.now(UTC).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": recent_granted}
+        settings = SimpleNamespace(access_mode="public")
+        # Should not raise
+        _validate_user_accessibility(
+            decoded=decoded,
+            app_code="code",
+            app_web_auth_enabled=True,
+            system_webapp_auth_enabled=True,
+            webapp_settings=settings,
+        )
+
+    @patch("controllers.web.wraps.EnterpriseService.WebAppAuth.is_user_allowed_to_access_webapp", return_value=False)
+    @patch("controllers.web.wraps.AppService.get_app_id_by_code", return_value="app-id-1")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=True)
+    def test_permission_check_denies_unauthorized_user(
+        self, mock_perm: MagicMock, mock_app_id: MagicMock, mock_allowed: MagicMock
+    ) -> None:
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": int(datetime.now(UTC).timestamp())}
+        settings = SimpleNamespace(access_mode="internal")
+        with pytest.raises(WebAppAuthAccessDeniedError):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+
+# ---------------------------------------------------------------------------
+# decode_jwt_token
+# ---------------------------------------------------------------------------
+class TestDecodeJwtToken:
+    @patch("controllers.web.wraps._validate_user_accessibility")
+    @patch("controllers.web.wraps._validate_webapp_token")
+    @patch("controllers.web.wraps.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.wraps.AppService.get_app_id_by_code")
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_happy_path(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        mock_app_id: MagicMock,
+        mock_access_mode: MagicMock,
+        mock_validate_token: MagicMock,
+        mock_validate_user: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+        end_user = SimpleNamespace(id="eu-1", session_id="sess-1")
+
+        # Configure session mock to return correct objects via scalar()
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, end_user]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                result_app, result_user = decode_jwt_token()
+
+        assert result_app.id == "app-1"
+        assert result_user.id == "eu-1"
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    def test_missing_token_raises_unauthorized(
+        self, mock_extract: MagicMock, mock_features: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        mock_extract.return_value = None
+
+        with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+            with pytest.raises(Unauthorized):
+                decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_missing_app_raises_not_found(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        session_mock = MagicMock()
+        session_mock.scalar.return_value = None  # No app found
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(NotFound):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_disabled_site_raises_bad_request(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=False)
+
+        session_mock = MagicMock()
+        # scalar calls: app_model, site (code found), then end_user
+        session_mock.scalar.side_effect = [app_model, SimpleNamespace(code="code1"), None]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(BadRequest, match="Site is disabled"):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_missing_end_user_raises_not_found(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, None]  # end_user is None
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(NotFound):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_user_id_mismatch_raises_unauthorized(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+        end_user = SimpleNamespace(id="eu-1", session_id="sess-1")
+
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, end_user]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(Unauthorized, match="expired"):
+                    decode_jwt_token(user_id="different-user")

From bbfa28e8a756ee696d9e47937384964f67783fd8 Mon Sep 17 00:00:00 2001
From: wangxiaolei <fatelei@gmail.com>
Date: Mon, 9 Mar 2026 16:09:44 +0800
Subject: [PATCH 11/12] refactor: file saver decouple db engine and ssrf proxy
 (#33076)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
---
 api/.importlinter                             |  3 ---
 api/controllers/files/tool_files.py           |  3 +--
 api/core/tools/tool_file_manager.py           | 22 +++++-------------
 api/core/workflow/node_factory.py             |  2 ++
 .../knowledge_retrieval_node.py               | 13 -----------
 api/dify_graph/nodes/llm/file_saver.py        | 23 ++++---------------
 api/dify_graph/nodes/llm/node.py              |  3 +++
 .../question_classifier_node.py               |  3 +++
 .../workflow/nodes/test_llm.py                |  2 ++
 .../workflow/graph_engine/test_mock_nodes.py  |  3 +++
 .../test_knowledge_retrieval_node.py          |  1 -
 .../workflow/nodes/llm/test_file_saver.py     | 18 +++++++++------
 .../core/workflow/nodes/llm/test_node.py      |  4 ++++
 13 files changed, 40 insertions(+), 60 deletions(-)

diff --git a/api/.importlinter b/api/.importlinter
index e4536b1f10..57773f57d6 100644
--- a/api/.importlinter
+++ b/api/.importlinter
@@ -44,7 +44,6 @@ forbidden_modules =
 allow_indirect_imports = True
 ignore_imports =
     dify_graph.nodes.agent.agent_node -> extensions.ext_database
-    dify_graph.nodes.llm.file_saver -> extensions.ext_database
     dify_graph.nodes.llm.node -> extensions.ext_database
     dify_graph.nodes.tool.tool_node -> extensions.ext_database
     dify_graph.model_runtime.model_providers.__base.ai_model -> extensions.ext_redis
@@ -114,7 +113,6 @@ ignore_imports =
     dify_graph.nodes.tool.tool_node -> core.tools.utils.message_transformer
     dify_graph.nodes.tool.tool_node -> models
     dify_graph.nodes.agent.agent_node -> models.model
-    dify_graph.nodes.llm.file_saver -> core.helper.ssrf_proxy
     dify_graph.nodes.llm.node -> core.helper.code_executor
     dify_graph.nodes.llm.node -> core.llm_generator.output_parser.errors
     dify_graph.nodes.llm.node -> core.llm_generator.output_parser.structured_output
@@ -135,7 +133,6 @@ ignore_imports =
     dify_graph.nodes.llm.file_saver -> core.tools.tool_file_manager
     dify_graph.nodes.tool.tool_node -> core.tools.errors
     dify_graph.nodes.agent.agent_node -> extensions.ext_database
-    dify_graph.nodes.llm.file_saver -> extensions.ext_database
     dify_graph.nodes.llm.node -> extensions.ext_database
     dify_graph.nodes.tool.tool_node -> extensions.ext_database
     dify_graph.nodes.agent.agent_node -> models
diff --git a/api/controllers/files/tool_files.py b/api/controllers/files/tool_files.py
index f6032a8e49..9e3fb3a90b 100644
--- a/api/controllers/files/tool_files.py
+++ b/api/controllers/files/tool_files.py
@@ -10,7 +10,6 @@ from controllers.common.file_response import enforce_download_for_html
 from controllers.files import files_ns
 from core.tools.signature import verify_tool_file_signature
 from core.tools.tool_file_manager import ToolFileManager
-from extensions.ext_database import db as global_db
 
 DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 
@@ -57,7 +56,7 @@ class ToolFileApi(Resource):
             raise Forbidden("Invalid request.")
 
         try:
-            tool_file_manager = ToolFileManager(engine=global_db.engine)
+            tool_file_manager = ToolFileManager()
             stream, tool_file = tool_file_manager.get_file_generator_by_tool_file_id(
                 file_id,
             )
diff --git a/api/core/tools/tool_file_manager.py b/api/core/tools/tool_file_manager.py
index 83e4e53418..d16b919561 100644
--- a/api/core/tools/tool_file_manager.py
+++ b/api/core/tools/tool_file_manager.py
@@ -10,28 +10,18 @@ from typing import Union
 from uuid import uuid4
 
 import httpx
-from sqlalchemy.orm import Session
 
 from configs import dify_config
+from core.db.session_factory import session_factory
 from core.helper import ssrf_proxy
-from extensions.ext_database import db as global_db
 from extensions.ext_storage import storage
 from models.model import MessageFile
 from models.tools import ToolFile
 
 logger = logging.getLogger(__name__)
 
-from sqlalchemy.engine import Engine
-
 
 class ToolFileManager:
-    _engine: Engine
-
-    def __init__(self, engine: Engine | None = None):
-        if engine is None:
-            engine = global_db.engine
-        self._engine = engine
-
     @staticmethod
     def sign_file(tool_file_id: str, extension: str) -> str:
         """
@@ -89,7 +79,7 @@ class ToolFileManager:
         filepath = f"tools/{tenant_id}/{unique_filename}"
         storage.save(filepath, file_binary)
 
-        with Session(self._engine, expire_on_commit=False) as session:
+        with session_factory.create_session() as session:
             tool_file = ToolFile(
                 user_id=user_id,
                 tenant_id=tenant_id,
@@ -132,7 +122,7 @@ class ToolFileManager:
         filename = f"{unique_name}{extension}"
         filepath = f"tools/{tenant_id}/{filename}"
         storage.save(filepath, blob)
-        with Session(self._engine, expire_on_commit=False) as session:
+        with session_factory.create_session() as session:
             tool_file = ToolFile(
                 user_id=user_id,
                 tenant_id=tenant_id,
@@ -157,7 +147,7 @@ class ToolFileManager:
 
         :return: the binary of the file, mime type
         """
-        with Session(self._engine, expire_on_commit=False) as session:
+        with session_factory.create_session() as session:
             tool_file: ToolFile | None = (
                 session.query(ToolFile)
                 .where(
@@ -181,7 +171,7 @@ class ToolFileManager:
 
         :return: the binary of the file, mime type
         """
-        with Session(self._engine, expire_on_commit=False) as session:
+        with session_factory.create_session() as session:
             message_file: MessageFile | None = (
                 session.query(MessageFile)
                 .where(
@@ -225,7 +215,7 @@ class ToolFileManager:
 
         :return: the binary of the file, mime type
         """
-        with Session(self._engine, expire_on_commit=False) as session:
+        with session_factory.create_session() as session:
             tool_file: ToolFile | None = (
                 session.query(ToolFile)
                 .where(
diff --git a/api/core/workflow/node_factory.py b/api/core/workflow/node_factory.py
index 4cbee08a65..c1475f2f18 100644
--- a/api/core/workflow/node_factory.py
+++ b/api/core/workflow/node_factory.py
@@ -250,6 +250,7 @@ class DifyNodeFactory(NodeFactory):
                 model_factory=self._llm_model_factory,
                 model_instance=model_instance,
                 memory=memory,
+                http_client=self._http_request_http_client,
             )
 
         if node_type == NodeType.DATASOURCE:
@@ -292,6 +293,7 @@ class DifyNodeFactory(NodeFactory):
                 model_factory=self._llm_model_factory,
                 model_instance=model_instance,
                 memory=memory,
+                http_client=self._http_request_http_client,
             )
 
         if node_type == NodeType.PARAMETER_EXTRACTOR:
diff --git a/api/dify_graph/nodes/knowledge_retrieval/knowledge_retrieval_node.py b/api/dify_graph/nodes/knowledge_retrieval/knowledge_retrieval_node.py
index 803c9ccaf9..c67e14ce17 100644
--- a/api/dify_graph/nodes/knowledge_retrieval/knowledge_retrieval_node.py
+++ b/api/dify_graph/nodes/knowledge_retrieval/knowledge_retrieval_node.py
@@ -14,7 +14,6 @@ from dify_graph.model_runtime.utils.encoders import jsonable_encoder
 from dify_graph.node_events import NodeRunResult
 from dify_graph.nodes.base import LLMUsageTrackingMixin
 from dify_graph.nodes.base.node import Node
-from dify_graph.nodes.llm.file_saver import FileSaverImpl, LLMFileSaver
 from dify_graph.repositories.rag_retrieval_protocol import KnowledgeRetrievalRequest, RAGRetrievalProtocol, Source
 from dify_graph.variables import (
     ArrayFileSegment,
@@ -47,8 +46,6 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
     # Output variable for file
     _file_outputs: list["File"]
 
-    _llm_file_saver: LLMFileSaver
-
     def __init__(
         self,
         id: str,
@@ -56,8 +53,6 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
         graph_init_params: "GraphInitParams",
         graph_runtime_state: "GraphRuntimeState",
         rag_retrieval: RAGRetrievalProtocol,
-        *,
-        llm_file_saver: LLMFileSaver | None = None,
     ):
         super().__init__(
             id=id,
@@ -69,14 +64,6 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
         self._file_outputs = []
         self._rag_retrieval = rag_retrieval
 
-        if llm_file_saver is None:
-            dify_ctx = self.require_dify_context()
-            llm_file_saver = FileSaverImpl(
-                user_id=dify_ctx.user_id,
-                tenant_id=dify_ctx.tenant_id,
-            )
-        self._llm_file_saver = llm_file_saver
-
     @classmethod
     def version(cls):
         return "1"
diff --git a/api/dify_graph/nodes/llm/file_saver.py b/api/dify_graph/nodes/llm/file_saver.py
index b4f64f4093..50e52a3b6f 100644
--- a/api/dify_graph/nodes/llm/file_saver.py
+++ b/api/dify_graph/nodes/llm/file_saver.py
@@ -1,14 +1,11 @@
 import mimetypes
 import typing as tp
 
-from sqlalchemy import Engine
-
 from constants.mimetypes import DEFAULT_EXTENSION, DEFAULT_MIME_TYPE
-from core.helper import ssrf_proxy
 from core.tools.signature import sign_tool_file
 from core.tools.tool_file_manager import ToolFileManager
 from dify_graph.file import File, FileTransferMethod, FileType
-from extensions.ext_database import db as global_db
+from dify_graph.nodes.protocols import HttpClientProtocol
 
 
 class LLMFileSaver(tp.Protocol):
@@ -59,30 +56,20 @@ class LLMFileSaver(tp.Protocol):
         raise NotImplementedError()
 
 
-EngineFactory: tp.TypeAlias = tp.Callable[[], Engine]
-
-
 class FileSaverImpl(LLMFileSaver):
-    _engine_factory: EngineFactory
     _tenant_id: str
     _user_id: str
 
-    def __init__(self, user_id: str, tenant_id: str, engine_factory: EngineFactory | None = None):
-        if engine_factory is None:
-
-            def _factory():
-                return global_db.engine
-
-            engine_factory = _factory
-        self._engine_factory = engine_factory
+    def __init__(self, user_id: str, tenant_id: str, http_client: HttpClientProtocol):
         self._user_id = user_id
         self._tenant_id = tenant_id
+        self._http_client = http_client
 
     def _get_tool_file_manager(self):
-        return ToolFileManager(engine=self._engine_factory())
+        return ToolFileManager()
 
     def save_remote_url(self, url: str, file_type: FileType) -> File:
-        http_response = ssrf_proxy.get(url)
+        http_response = self._http_client.get(url)
         http_response.raise_for_status()
         data = http_response.content
         mime_type_from_header = http_response.headers.get("Content-Type")
diff --git a/api/dify_graph/nodes/llm/node.py b/api/dify_graph/nodes/llm/node.py
index c7697a0972..5e59c96cd6 100644
--- a/api/dify_graph/nodes/llm/node.py
+++ b/api/dify_graph/nodes/llm/node.py
@@ -64,6 +64,7 @@ from dify_graph.nodes.base.entities import VariableSelector
 from dify_graph.nodes.base.node import Node
 from dify_graph.nodes.base.variable_template_parser import VariableTemplateParser
 from dify_graph.nodes.llm.protocols import CredentialsProvider, ModelFactory
+from dify_graph.nodes.protocols import HttpClientProtocol
 from dify_graph.runtime import VariablePool
 from dify_graph.variables import (
     ArrayFileSegment,
@@ -127,6 +128,7 @@ class LLMNode(Node[LLMNodeData]):
         credentials_provider: CredentialsProvider,
         model_factory: ModelFactory,
         model_instance: ModelInstance,
+        http_client: HttpClientProtocol,
         memory: PromptMessageMemory | None = None,
         llm_file_saver: LLMFileSaver | None = None,
     ):
@@ -149,6 +151,7 @@ class LLMNode(Node[LLMNodeData]):
             llm_file_saver = FileSaverImpl(
                 user_id=dify_ctx.user_id,
                 tenant_id=dify_ctx.tenant_id,
+                http_client=http_client,
             )
         self._llm_file_saver = llm_file_saver
 
diff --git a/api/dify_graph/nodes/question_classifier/question_classifier_node.py b/api/dify_graph/nodes/question_classifier/question_classifier_node.py
index 97535d832d..443d216186 100644
--- a/api/dify_graph/nodes/question_classifier/question_classifier_node.py
+++ b/api/dify_graph/nodes/question_classifier/question_classifier_node.py
@@ -28,6 +28,7 @@ from dify_graph.nodes.llm import (
 )
 from dify_graph.nodes.llm.file_saver import FileSaverImpl, LLMFileSaver
 from dify_graph.nodes.llm.protocols import CredentialsProvider, ModelFactory
+from dify_graph.nodes.protocols import HttpClientProtocol
 from libs.json_in_md_parser import parse_and_check_json_markdown
 
 from .entities import QuestionClassifierNodeData
@@ -68,6 +69,7 @@ class QuestionClassifierNode(Node[QuestionClassifierNodeData]):
         credentials_provider: "CredentialsProvider",
         model_factory: "ModelFactory",
         model_instance: ModelInstance,
+        http_client: HttpClientProtocol,
         memory: PromptMessageMemory | None = None,
         llm_file_saver: LLMFileSaver | None = None,
     ):
@@ -90,6 +92,7 @@ class QuestionClassifierNode(Node[QuestionClassifierNodeData]):
             llm_file_saver = FileSaverImpl(
                 user_id=dify_ctx.user_id,
                 tenant_id=dify_ctx.tenant_id,
+                http_client=http_client,
             )
         self._llm_file_saver = llm_file_saver
 
diff --git a/api/tests/integration_tests/workflow/nodes/test_llm.py b/api/tests/integration_tests/workflow/nodes/test_llm.py
index b4779ebcdd..2aca9f5157 100644
--- a/api/tests/integration_tests/workflow/nodes/test_llm.py
+++ b/api/tests/integration_tests/workflow/nodes/test_llm.py
@@ -11,6 +11,7 @@ from dify_graph.enums import WorkflowNodeExecutionStatus
 from dify_graph.node_events import StreamCompletedEvent
 from dify_graph.nodes.llm.node import LLMNode
 from dify_graph.nodes.llm.protocols import CredentialsProvider, ModelFactory
+from dify_graph.nodes.protocols import HttpClientProtocol
 from dify_graph.runtime import GraphRuntimeState, VariablePool
 from dify_graph.system_variable import SystemVariable
 from extensions.ext_database import db
@@ -74,6 +75,7 @@ def init_llm_node(config: dict) -> LLMNode:
         credentials_provider=MagicMock(spec=CredentialsProvider),
         model_factory=MagicMock(spec=ModelFactory),
         model_instance=MagicMock(spec=ModelInstance),
+        http_client=MagicMock(spec=HttpClientProtocol),
     )
 
     return node
diff --git a/api/tests/unit_tests/core/workflow/graph_engine/test_mock_nodes.py b/api/tests/unit_tests/core/workflow/graph_engine/test_mock_nodes.py
index 3f458e9de9..43fadadbc2 100644
--- a/api/tests/unit_tests/core/workflow/graph_engine/test_mock_nodes.py
+++ b/api/tests/unit_tests/core/workflow/graph_engine/test_mock_nodes.py
@@ -22,6 +22,7 @@ from dify_graph.nodes.knowledge_retrieval import KnowledgeRetrievalNode
 from dify_graph.nodes.llm import LLMNode
 from dify_graph.nodes.llm.protocols import CredentialsProvider, ModelFactory
 from dify_graph.nodes.parameter_extractor import ParameterExtractorNode
+from dify_graph.nodes.protocols import HttpClientProtocol
 from dify_graph.nodes.question_classifier import QuestionClassifierNode
 from dify_graph.nodes.template_transform import TemplateTransformNode
 from dify_graph.nodes.template_transform.template_renderer import (
@@ -65,6 +66,8 @@ class MockNodeMixin:
             kwargs.setdefault("credentials_provider", MagicMock(spec=CredentialsProvider))
             kwargs.setdefault("model_factory", MagicMock(spec=ModelFactory))
             kwargs.setdefault("model_instance", MagicMock(spec=ModelInstance))
+            # LLM-like nodes now require an http_client; provide a mock by default for tests.
+            kwargs.setdefault("http_client", MagicMock(spec=HttpClientProtocol))
 
         # Ensure TemplateTransformNode receives a renderer now required by constructor
         if isinstance(self, TemplateTransformNode):
diff --git a/api/tests/unit_tests/core/workflow/nodes/knowledge_retrieval/test_knowledge_retrieval_node.py b/api/tests/unit_tests/core/workflow/nodes/knowledge_retrieval/test_knowledge_retrieval_node.py
index 9dacc5a39b..e929d652fd 100644
--- a/api/tests/unit_tests/core/workflow/nodes/knowledge_retrieval/test_knowledge_retrieval_node.py
+++ b/api/tests/unit_tests/core/workflow/nodes/knowledge_retrieval/test_knowledge_retrieval_node.py
@@ -112,7 +112,6 @@ class TestKnowledgeRetrievalNode:
         # Assert
         assert node.id == node_id
         assert node._rag_retrieval == mock_rag_retrieval
-        assert node._llm_file_saver is not None
 
     def test_run_with_no_query_or_attachment(
         self,
diff --git a/api/tests/unit_tests/core/workflow/nodes/llm/test_file_saver.py b/api/tests/unit_tests/core/workflow/nodes/llm/test_file_saver.py
index a3afd1ed5c..b0f0fd428b 100644
--- a/api/tests/unit_tests/core/workflow/nodes/llm/test_file_saver.py
+++ b/api/tests/unit_tests/core/workflow/nodes/llm/test_file_saver.py
@@ -1,10 +1,10 @@
 import uuid
 from typing import NamedTuple
 from unittest import mock
+from unittest.mock import MagicMock
 
 import httpx
 import pytest
-from sqlalchemy import Engine
 
 from core.helper import ssrf_proxy
 from core.tools import signature
@@ -44,7 +44,6 @@ class TestFileSaverImpl:
         )
         mock_tool_file.id = _gen_id()
         mocked_tool_file_manager = mock.MagicMock(spec=ToolFileManager)
-        mocked_engine = mock.MagicMock(spec=Engine)
 
         mocked_tool_file_manager.create_file_by_raw.return_value = mock_tool_file
         monkeypatch.setattr(FileSaverImpl, "_get_tool_file_manager", lambda _: mocked_tool_file_manager)
@@ -53,11 +52,12 @@ class TestFileSaverImpl:
         # Since `File.generate_url` used `signature.sign_tool_file` directly, we also need to patch it here.
         monkeypatch.setattr(models, "sign_tool_file", mocked_sign_file)
         mocked_sign_file.return_value = mock_signed_url
+        http_client = MagicMock()
 
         storage_file_manager = FileSaverImpl(
             user_id=user_id,
             tenant_id=tenant_id,
-            engine_factory=mocked_engine,
+            http_client=http_client,
         )
 
         file = storage_file_manager.save_binary_string(_PNG_DATA, mime_type, file_type)
@@ -87,16 +87,18 @@ class TestFileSaverImpl:
             status_code=401,
             request=mock_request,
         )
+        http_client = MagicMock()
+        http_client.get.return_value = mock_response
+
         file_saver = FileSaverImpl(
             user_id=_gen_id(),
             tenant_id=_gen_id(),
+            http_client=http_client,
         )
-        mock_get = mock.MagicMock(spec=ssrf_proxy.get, return_value=mock_response)
-        monkeypatch.setattr(ssrf_proxy, "get", mock_get)
 
         with pytest.raises(httpx.HTTPStatusError) as exc:
             file_saver.save_remote_url(_TEST_URL, FileType.IMAGE)
-        mock_get.assert_called_once_with(_TEST_URL)
+        http_client.get.assert_called_once_with(_TEST_URL)
         assert exc.value.response.status_code == 401
 
     def test_save_remote_url_success(self, monkeypatch: pytest.MonkeyPatch):
@@ -112,8 +114,10 @@ class TestFileSaverImpl:
             headers={"Content-Type": mime_type},
             request=mock_request,
         )
+        http_client = MagicMock()
+        http_client.get.return_value = mock_response
 
-        file_saver = FileSaverImpl(user_id=user_id, tenant_id=tenant_id)
+        file_saver = FileSaverImpl(user_id=user_id, tenant_id=tenant_id, http_client=http_client)
         mock_tool_file = ToolFile(
             user_id=user_id,
             tenant_id=tenant_id,
diff --git a/api/tests/unit_tests/core/workflow/nodes/llm/test_node.py b/api/tests/unit_tests/core/workflow/nodes/llm/test_node.py
index 90308facc3..d56035b6bc 100644
--- a/api/tests/unit_tests/core/workflow/nodes/llm/test_node.py
+++ b/api/tests/unit_tests/core/workflow/nodes/llm/test_node.py
@@ -111,6 +111,7 @@ def llm_node(
         "id": "1",
         "data": llm_node_data.model_dump(),
     }
+    http_client = mock.MagicMock()
     node = LLMNode(
         id="1",
         config=node_config,
@@ -120,6 +121,7 @@ def llm_node(
         model_factory=mock_model_factory,
         model_instance=mock.MagicMock(spec=ModelInstance),
         llm_file_saver=mock_file_saver,
+        http_client=http_client,
     )
     return node
 
@@ -632,6 +634,7 @@ def llm_node_for_multimodal(llm_node_data, graph_init_params, graph_runtime_stat
         "id": "1",
         "data": llm_node_data.model_dump(),
     }
+    http_client = mock.MagicMock()
     node = LLMNode(
         id="1",
         config=node_config,
@@ -641,6 +644,7 @@ def llm_node_for_multimodal(llm_node_data, graph_init_params, graph_runtime_stat
         model_factory=mock_model_factory,
         model_instance=mock.MagicMock(spec=ModelInstance),
         llm_file_saver=mock_file_saver,
+        http_client=http_client,
     )
     return node, mock_file_saver
 

From 03dcbeafdf60d42225d51e9e12515d23fc94016d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9D=9E=E6=B3=95=E6=93=8D=E4=BD=9C?= <hjlarry@163.com>
Date: Mon, 9 Mar 2026 16:27:45 +0800
Subject: [PATCH 12/12] fix: stop responding icon not display (#33154)

Co-authored-by: Stephen Zhou <38493346+hyoban@users.noreply.github.com>
---
 web/app/components/base/chat/chat/index.tsx |  3 +--
 web/package.json                            |  2 +-
 web/pnpm-lock.yaml                          | 10 +++++-----
 web/tailwind-common-config.ts               |  7 ++++++-
 4 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/web/app/components/base/chat/chat/index.tsx b/web/app/components/base/chat/chat/index.tsx
index 69c064e3e2..c3a02c798d 100644
--- a/web/app/components/base/chat/chat/index.tsx
+++ b/web/app/components/base/chat/chat/index.tsx
@@ -332,8 +332,7 @@ const Chat: FC<ChatProps> = ({
               !noStopResponding && isResponding && (
                 <div data-testid="stop-responding-container" className="mb-2 flex justify-center">
                   <Button className="border-components-panel-border bg-components-panel-bg text-components-button-secondary-text" onClick={onStopResponding}>
-                    {/* eslint-disable-next-line tailwindcss/no-unknown-classes */}
-                    <div className="i-custom-vender-solid-mediaanddevices-stop-circle mr-[5px] h-3.5 w-3.5" />
+                    <div className="i-custom-vender-solid-mediaAndDevices-stop-circle mr-[5px] h-3.5 w-3.5" />
                     <span className="text-xs font-normal">{t('operation.stopResponding', { ns: 'appDebug' })}</span>
                   </Button>
                 </div>
diff --git a/web/package.json b/web/package.json
index cf1dc4b428..53721239b8 100644
--- a/web/package.json
+++ b/web/package.json
@@ -228,7 +228,7 @@
     "eslint-plugin-sonarjs": "4.0.0",
     "eslint-plugin-storybook": "10.2.13",
     "husky": "9.1.7",
-    "iconify-import-svg": "0.1.1",
+    "iconify-import-svg": "0.1.2",
     "jsdom": "27.3.0",
     "jsdom-testing-mocks": "1.16.0",
     "knip": "5.78.0",
diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml
index d41c6183a6..bb0ee73624 100644
--- a/web/pnpm-lock.yaml
+++ b/web/pnpm-lock.yaml
@@ -552,8 +552,8 @@ importers:
         specifier: 9.1.7
         version: 9.1.7
       iconify-import-svg:
-        specifier: 0.1.1
-        version: 0.1.1
+        specifier: 0.1.2
+        version: 0.1.2
       jsdom:
         specifier: 27.3.0
         version: 27.3.0(canvas@3.2.1)
@@ -5263,8 +5263,8 @@ packages:
       typescript:
         optional: true
 
-  iconify-import-svg@0.1.1:
-    resolution: {integrity: sha512-8HwZIe3ZqCfZ68NZUCnHN264fwHWhE+O5hWDfBtOEY7u1V97yOogHaoXGRLOx17M0c8+z65xYqJXA16ieCYIwA==}
+  iconify-import-svg@0.1.2:
+    resolution: {integrity: sha512-8dwxdGK1a7oPDQhLQOPTbx51tpkxYB6HZvf4fxWz2QVYqEtgop0FWE7OXQ+4zqnrTVUpMIGnOsvqIHtPBK9Isw==}
 
   iconv-lite@0.6.3:
     resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
@@ -13145,7 +13145,7 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  iconify-import-svg@0.1.1:
+  iconify-import-svg@0.1.2:
     dependencies:
       '@iconify/tools': 4.2.0
       '@iconify/types': 2.0.0
diff --git a/web/tailwind-common-config.ts b/web/tailwind-common-config.ts
index cbd58e2809..20dfc09e30 100644
--- a/web/tailwind-common-config.ts
+++ b/web/tailwind-common-config.ts
@@ -14,11 +14,16 @@ const _dirname = typeof __dirname !== 'undefined'
   : path.dirname(fileURLToPath(import.meta.url))
 
 const disableSVGOptimize = process.env.TAILWIND_MODE === 'ESLINT'
+const parseColorOptions = {
+  fallback: () => 'currentColor',
+}
 const svgOptimizeConfig = {
   cleanupSVG: !disableSVGOptimize,
   deOptimisePaths: !disableSVGOptimize,
   runSVGO: !disableSVGOptimize,
-  parseColors: !disableSVGOptimize,
+  parseColors: !disableSVGOptimize
+    ? parseColorOptions
+    : false,
 }
 
 const config = {