fix: centralize access_mode validation and support sso_verified

- Add ALLOWED_ACCESS_MODES constant to centralize valid access modes
- Include 'sso_verified' in validation to fix app duplication errors
- Update error message to dynamically list all allowed modes
- Refactor for maintainability: single source of truth for access modes

This fixes the issue where apps with access_mode='sso_verified' could not
be duplicated because the validation in update_app_access_mode() was missing
this mode, even though it was documented in WebAppSettings model.

api/.env.example

@@ -553,6 +553,8 @@ WORKFLOW_LOG_CLEANUP_ENABLED=false
 WORKFLOW_LOG_RETENTION_DAYS=30
 # Batch size for workflow log cleanup operations (default: 100)
 WORKFLOW_LOG_CLEANUP_BATCH_SIZE=100
+# Comma-separated list of workflow IDs to clean logs for
+WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS=
 
 # App configuration
 APP_MAX_EXECUTION_TIME=1200
@@ -715,6 +717,7 @@ ANNOTATION_IMPORT_MAX_CONCURRENT=5
 # Sandbox expired records clean configuration
 SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD=21
 SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE=1000
+SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL=200
 SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS=30
 SANDBOX_EXPIRED_RECORDS_CLEAN_TASK_LOCK_TTL=90000
 

api/.vscode/launch.json.example

@@ -54,7 +54,7 @@
                 "--loglevel",
                 "DEBUG",
                 "-Q",
-                "dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor"
+                "dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,workflow_based_app_execution,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor"
             ]
         }
     ]

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.db_migration_lock import DbMigrationAutoRenewLock
 from libs.helper import email as email_validate
 from libs.password import hash_password, password_pattern, valid_password
 from libs.rsa import generate_key_pair
@@ -54,6 +55,8 @@ from tasks.remove_app_and_related_data_task import delete_draft_variables_batch
 
 logger = logging.getLogger(__name__)
 
+DB_UPGRADE_LOCK_TTL_SECONDS = 60
+
 
 @click.command("reset-password", help="Reset the account password.")
 @click.option("--email", prompt=True, help="Account email to reset password for")
@@ -727,8 +730,15 @@ def create_tenant(email: str, language: str | None = None, name: str | None = No
 @click.command("upgrade-db", help="Upgrade the database")
 def upgrade_db():
     click.echo("Preparing database migration...")
-    lock = redis_client.lock(name="db_upgrade_lock", timeout=60)
+    lock = DbMigrationAutoRenewLock(
+        redis_client=redis_client,
+        name="db_upgrade_lock",
+        ttl_seconds=DB_UPGRADE_LOCK_TTL_SECONDS,
+        logger=logger,
+        log_context="db_migration",
+    )
     if lock.acquire(blocking=False):
+        migration_succeeded = False
         try:
             click.echo(click.style("Starting database migration.", fg="green"))
 
@@ -737,6 +747,7 @@ def upgrade_db():
 
             flask_migrate.upgrade()
 
+            migration_succeeded = True
             click.echo(click.style("Database migration successful!", fg="green"))
 
         except Exception as e:
@@ -744,7 +755,8 @@ def upgrade_db():
             click.echo(click.style(f"Database migration failed: {e}", fg="red"))
             raise SystemExit(1)
         finally:
-            lock.release()
+            status = "successful" if migration_succeeded else "failed"
+            lock.release_safely(status=status)
     else:
         click.echo("Database migration skipped")
 

api/configs/feature/__init__.py

@@ -265,6 +265,11 @@ class PluginConfig(BaseSettings):
         default=60 * 60,
     )
 
+    PLUGIN_MAX_FILE_SIZE: PositiveInt = Field(
+        description="Maximum allowed size (bytes) for plugin-generated files",
+        default=50 * 1024 * 1024,
+    )
+
 
 class MarketplaceConfig(BaseSettings):
     """
@@ -1314,6 +1319,9 @@ class WorkflowLogConfig(BaseSettings):
     WORKFLOW_LOG_CLEANUP_BATCH_SIZE: int = Field(
         default=100, description="Batch size for workflow run log cleanup operations"
     )
+    WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS: str = Field(
+        default="", description="Comma-separated list of workflow IDs to clean logs for"
+    )
 
 
 class SwaggerUIConfig(BaseSettings):
@@ -1344,6 +1352,10 @@ class SandboxExpiredRecordsCleanConfig(BaseSettings):
         description="Maximum number of records to process in each batch",
         default=1000,
     )
+    SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL: PositiveInt = Field(
+        description="Maximum interval in milliseconds between batches",
+        default=200,
+    )
     SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS: PositiveInt = Field(
         description="Retention days for sandbox expired workflow_run records and message records",
         default=30,

api/configs/middleware/__init__.py

@@ -259,11 +259,20 @@ class CeleryConfig(DatabaseConfig):
         description="Password of the Redis Sentinel master.",
         default=None,
     )
+
     CELERY_SENTINEL_SOCKET_TIMEOUT: PositiveFloat | None = Field(
         description="Timeout for Redis Sentinel socket operations in seconds.",
         default=0.1,
     )
 
+    CELERY_TASK_ANNOTATIONS: dict[str, Any] | None = Field(
+        description=(
+            "Annotations for Celery tasks as a JSON mapping of task name -> options "
+            "(for example, rate limits or other task-specific settings)."
+        ),
+        default=None,
+    )
+
     @computed_field
     def CELERY_RESULT_BACKEND(self) -> str | None:
         if self.CELERY_BACKEND in ("database", "rabbitmq"):

api/configs/middleware/vdb/oceanbase_config.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from pydantic import Field, PositiveInt
 from pydantic_settings import BaseSettings
 
@@ -49,3 +51,43 @@ class OceanBaseVectorConfig(BaseSettings):
         ),
         default="ik",
     )
+
+    OCEANBASE_VECTOR_BATCH_SIZE: PositiveInt = Field(
+        description="Number of documents to insert per batch",
+        default=100,
+    )
+
+    OCEANBASE_VECTOR_METRIC_TYPE: Literal["l2", "cosine", "inner_product"] = Field(
+        description="Distance metric type for vector index: l2, cosine, or inner_product",
+        default="l2",
+    )
+
+    OCEANBASE_HNSW_M: PositiveInt = Field(
+        description="HNSW M parameter (max number of connections per node)",
+        default=16,
+    )
+
+    OCEANBASE_HNSW_EF_CONSTRUCTION: PositiveInt = Field(
+        description="HNSW efConstruction parameter (index build-time search width)",
+        default=256,
+    )
+
+    OCEANBASE_HNSW_EF_SEARCH: int = Field(
+        description="HNSW efSearch parameter (query-time search width, -1 uses server default)",
+        default=-1,
+    )
+
+    OCEANBASE_VECTOR_POOL_SIZE: PositiveInt = Field(
+        description="SQLAlchemy connection pool size",
+        default=5,
+    )
+
+    OCEANBASE_VECTOR_MAX_OVERFLOW: int = Field(
+        description="SQLAlchemy connection pool max overflow connections",
+        default=10,
+    )
+
+    OCEANBASE_HNSW_REFRESH_THRESHOLD: int = Field(
+        description="Minimum number of inserted documents to trigger an automatic HNSW index refresh (0 to disable)",
+        default=1000,
+    )

api/constants/languages.py

@@ -21,6 +21,7 @@ language_timezone_mapping = {
     "th-TH": "Asia/Bangkok",
     "id-ID": "Asia/Jakarta",
     "ar-TN": "Africa/Tunis",
+    "nl-NL": "Europe/Amsterdam",
 }
 
 languages = list(language_timezone_mapping.keys())

api/controllers/console/app/app.py

@@ -660,6 +660,19 @@ class AppCopyApi(Resource):
             )
             session.commit()
 
+            # Inherit web app permission from original app
+            if result.app_id and FeatureService.get_system_features().webapp_auth.enabled:
+                try:
+                    # Get the original app's access mode
+                    original_settings = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_model.id)
+                    access_mode = original_settings.access_mode
+                except Exception:
+                    # If original app has no settings (old app), default to public to match fallback behavior
+                    access_mode = "public"
+
+                # Apply the same access mode to the copied app
+                EnterpriseService.WebAppAuth.update_app_access_mode(result.app_id, access_mode)
+
             stmt = select(App).where(App.id == result.app_id)
             app = session.scalar(stmt)
 

api/controllers/console/app/conversation.py

@@ -599,7 +599,12 @@ def _get_conversation(app_model, conversation_id):
     db.session.execute(
         sa.update(Conversation)
         .where(Conversation.id == conversation_id, Conversation.read_at.is_(None))
-        .values(read_at=naive_utc_now(), read_account_id=current_user.id)
+        # Keep updated_at unchanged when only marking a conversation as read.
+        .values(
+            read_at=naive_utc_now(),
+            read_account_id=current_user.id,
+            updated_at=Conversation.updated_at,
+        )
     )
     db.session.commit()
     db.session.refresh(conversation)

api/controllers/console/remote_files.py

@@ -1,6 +1,7 @@
 import urllib.parse
 
 import httpx
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 import services
@@ -10,12 +11,12 @@ from controllers.common.errors import (
     RemoteFileUploadError,
     UnsupportedFileTypeError,
 )
-from controllers.fastopenapi import console_router
+from controllers.console import console_ns
 from core.file import helpers as file_helpers
 from core.helper import ssrf_proxy
 from extensions.ext_database import db
 from fields.file_fields import FileWithSignedUrl, RemoteFileInfo
-from libs.login import current_account_with_tenant
+from libs.login import current_account_with_tenant, login_required
 from services.file_service import FileService
 
 
@@ -23,69 +24,73 @@ class RemoteFileUploadPayload(BaseModel):
     url: str = Field(..., description="URL to fetch")
 
 
-@console_router.get(
-    "/remote-files/<path:url>",
-    response_model=RemoteFileInfo,
-    tags=["console"],
-)
-def get_remote_file_info(url: str) -> RemoteFileInfo:
-    decoded_url = urllib.parse.unquote(url)
-    resp = ssrf_proxy.head(decoded_url)
-    if resp.status_code != httpx.codes.OK:
-        resp = ssrf_proxy.get(decoded_url, timeout=3)
-    resp.raise_for_status()
-    return RemoteFileInfo(
-        file_type=resp.headers.get("Content-Type", "application/octet-stream"),
-        file_length=int(resp.headers.get("Content-Length", 0)),
-    )
-
-
-@console_router.post(
-    "/remote-files/upload",
-    response_model=FileWithSignedUrl,
-    tags=["console"],
-    status_code=201,
-)
-def upload_remote_file(payload: RemoteFileUploadPayload) -> FileWithSignedUrl:
-    url = payload.url
-
-    try:
-        resp = ssrf_proxy.head(url=url)
+@console_ns.route("/remote-files/<path:url>")
+class GetRemoteFileInfo(Resource):
+    @login_required
+    def get(self, url: str):
+        decoded_url = urllib.parse.unquote(url)
+        resp = ssrf_proxy.head(decoded_url)
         if resp.status_code != httpx.codes.OK:
-            resp = ssrf_proxy.get(url=url, timeout=3, follow_redirects=True)
-        if resp.status_code != httpx.codes.OK:
-            raise RemoteFileUploadError(f"Failed to fetch file from {url}: {resp.text}")
-    except httpx.RequestError as e:
-        raise RemoteFileUploadError(f"Failed to fetch file from {url}: {str(e)}")
+            resp = ssrf_proxy.get(decoded_url, timeout=3)
+        resp.raise_for_status()
+        return RemoteFileInfo(
+            file_type=resp.headers.get("Content-Type", "application/octet-stream"),
+            file_length=int(resp.headers.get("Content-Length", 0)),
+        ).model_dump(mode="json")
 
-    file_info = helpers.guess_file_info_from_response(resp)
 
-    if not FileService.is_file_size_within_limit(extension=file_info.extension, file_size=file_info.size):
-        raise FileTooLargeError
+@console_ns.route("/remote-files/upload")
+class RemoteFileUpload(Resource):
+    @login_required
+    def post(self):
+        payload = RemoteFileUploadPayload.model_validate(console_ns.payload)
+        url = payload.url
 
-    content = resp.content if resp.request.method == "GET" else ssrf_proxy.get(url).content
+        # Try to fetch remote file metadata/content first
+        try:
+            resp = ssrf_proxy.head(url=url)
+            if resp.status_code != httpx.codes.OK:
+                resp = ssrf_proxy.get(url=url, timeout=3, follow_redirects=True)
+            if resp.status_code != httpx.codes.OK:
+                # Normalize into a user-friendly error message expected by tests
+                raise RemoteFileUploadError(f"Failed to fetch file from {url}: {resp.text}")
+        except httpx.RequestError as e:
+            raise RemoteFileUploadError(f"Failed to fetch file from {url}: {str(e)}")
 
-    try:
-        user, _ = current_account_with_tenant()
-        upload_file = FileService(db.engine).upload_file(
-            filename=file_info.filename,
-            content=content,
-            mimetype=file_info.mimetype,
-            user=user,
-            source_url=url,
+        file_info = helpers.guess_file_info_from_response(resp)
+
+        # Enforce file size limit with 400 (Bad Request) per tests' expectation
+        if not FileService.is_file_size_within_limit(extension=file_info.extension, file_size=file_info.size):
+            raise FileTooLargeError()
+
+        # Load content if needed
+        content = resp.content if resp.request.method == "GET" else ssrf_proxy.get(url).content
+
+        try:
+            user, _ = current_account_with_tenant()
+            upload_file = FileService(db.engine).upload_file(
+                filename=file_info.filename,
+                content=content,
+                mimetype=file_info.mimetype,
+                user=user,
+                source_url=url,
+            )
+        except services.errors.file.FileTooLargeError as file_too_large_error:
+            raise FileTooLargeError(file_too_large_error.description)
+        except services.errors.file.UnsupportedFileTypeError:
+            raise UnsupportedFileTypeError()
+
+        # Success: return created resource with 201 status
+        return (
+            FileWithSignedUrl(
+                id=upload_file.id,
+                name=upload_file.name,
+                size=upload_file.size,
+                extension=upload_file.extension,
+                url=file_helpers.get_signed_file_url(upload_file_id=upload_file.id),
+                mime_type=upload_file.mime_type,
+                created_by=upload_file.created_by,
+                created_at=int(upload_file.created_at.timestamp()),
+            ).model_dump(mode="json"),
+            201,
         )
-    except services.errors.file.FileTooLargeError as file_too_large_error:
-        raise FileTooLargeError(file_too_large_error.description)
-    except services.errors.file.UnsupportedFileTypeError:
-        raise UnsupportedFileTypeError()
-
-    return FileWithSignedUrl(
-        id=upload_file.id,
-        name=upload_file.name,
-        size=upload_file.size,
-        extension=upload_file.extension,
-        url=file_helpers.get_signed_file_url(upload_file_id=upload_file.id),
-        mime_type=upload_file.mime_type,
-        created_by=upload_file.created_by,
-        created_at=int(upload_file.created_at.timestamp()),
-    )

api/controllers/console/setup.py

@@ -42,7 +42,15 @@ class SetupResponse(BaseModel):
     tags=["console"],
 )
 def get_setup_status_api() -> SetupStatusResponse:
-    """Get system setup status."""
+    """Get system setup status.
+
+    NOTE: This endpoint is unauthenticated by design.
+
+    During first-time bootstrap there is no admin account yet, so frontend initialization must be
+    able to query setup progress before any login flow exists.
+
+    Only bootstrap-safe status information should be returned by this endpoint.
+    """
     if dify_config.EDITION == "SELF_HOSTED":
         setup_status = get_setup_status()
         if setup_status and not isinstance(setup_status, bool):
@@ -61,7 +69,12 @@ def get_setup_status_api() -> SetupStatusResponse:
 )
 @only_edition_self_hosted
 def setup_system(payload: SetupRequestPayload) -> SetupResponse:
-    """Initialize system setup with admin account."""
+    """Initialize system setup with admin account.
+
+    NOTE: This endpoint is unauthenticated by design for first-time bootstrap.
+    Access is restricted by deployment mode (`SELF_HOSTED`), one-time setup guards,
+    and init-password validation rather than user session authentication.
+    """
     if get_setup_status():
         raise AlreadySetupError()
 

api/core/app/apps/streaming_utils.py

@@ -34,7 +34,7 @@ def stream_topic_events(
             on_subscribe()
         while True:
             try:
-                msg = sub.receive(timeout=0.1)
+                msg = sub.receive(timeout=1)
             except SubscriptionClosedError:
                 return
             if msg is None:

api/core/app/task_pipeline/easy_ui_based_generate_task_pipeline.py

@@ -45,6 +45,8 @@ from core.app.entities.task_entities import (
 from core.app.task_pipeline.based_generate_task_pipeline import BasedGenerateTaskPipeline
 from core.app.task_pipeline.message_cycle_manager import MessageCycleManager
 from core.base.tts import AppGeneratorTTSPublisher, AudioTrunk
+from core.file import helpers as file_helpers
+from core.file.enums import FileTransferMethod
 from core.model_manager import ModelInstance
 from core.model_runtime.entities.llm_entities import LLMResult, LLMResultChunk, LLMResultChunkDelta, LLMUsage
 from core.model_runtime.entities.message_entities import (
@@ -56,10 +58,11 @@ from core.ops.entities.trace_entity import TraceTaskName
 from core.ops.ops_trace_manager import TraceQueueManager, TraceTask
 from core.prompt.utils.prompt_message_util import PromptMessageUtil
 from core.prompt.utils.prompt_template_parser import PromptTemplateParser
+from core.tools.signature import sign_tool_file
 from events.message_event import message_was_created
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
-from models.model import AppMode, Conversation, Message, MessageAgentThought
+from models.model import AppMode, Conversation, Message, MessageAgentThought, MessageFile, UploadFile
 
 logger = logging.getLogger(__name__)
 
@@ -463,6 +466,85 @@ class EasyUIBasedGenerateTaskPipeline(BasedGenerateTaskPipeline):
             metadata=metadata_dict,
         )
 
+    def _record_files(self):
+        with Session(db.engine, expire_on_commit=False) as session:
+            message_files = session.scalars(select(MessageFile).where(MessageFile.message_id == self._message_id)).all()
+            if not message_files:
+                return None
+
+            files_list = []
+            upload_file_ids = [
+                mf.upload_file_id
+                for mf in message_files
+                if mf.transfer_method == FileTransferMethod.LOCAL_FILE and mf.upload_file_id
+            ]
+            upload_files_map = {}
+            if upload_file_ids:
+                upload_files = session.scalars(select(UploadFile).where(UploadFile.id.in_(upload_file_ids))).all()
+                upload_files_map = {uf.id: uf for uf in upload_files}
+
+            for message_file in message_files:
+                upload_file = None
+                if message_file.transfer_method == FileTransferMethod.LOCAL_FILE and message_file.upload_file_id:
+                    upload_file = upload_files_map.get(message_file.upload_file_id)
+
+                url = None
+                filename = "file"
+                mime_type = "application/octet-stream"
+                size = 0
+                extension = ""
+
+                if message_file.transfer_method == FileTransferMethod.REMOTE_URL:
+                    url = message_file.url
+                    if message_file.url:
+                        filename = message_file.url.split("/")[-1].split("?")[0]  # Remove query params
+                elif message_file.transfer_method == FileTransferMethod.LOCAL_FILE:
+                    if upload_file:
+                        url = file_helpers.get_signed_file_url(upload_file_id=str(upload_file.id))
+                        filename = upload_file.name
+                        mime_type = upload_file.mime_type or "application/octet-stream"
+                        size = upload_file.size or 0
+                        extension = f".{upload_file.extension}" if upload_file.extension else ""
+                    elif message_file.upload_file_id:
+                        # Fallback: generate URL even if upload_file not found
+                        url = file_helpers.get_signed_file_url(upload_file_id=str(message_file.upload_file_id))
+                elif message_file.transfer_method == FileTransferMethod.TOOL_FILE and message_file.url:
+                    # For tool files, use URL directly if it's HTTP, otherwise sign it
+                    if message_file.url.startswith("http"):
+                        url = message_file.url
+                        filename = message_file.url.split("/")[-1].split("?")[0]
+                    else:
+                        # Extract tool file id and extension from URL
+                        url_parts = message_file.url.split("/")
+                        if url_parts:
+                            file_part = url_parts[-1].split("?")[0]  # Remove query params first
+                            # Use rsplit to correctly handle filenames with multiple dots
+                            if "." in file_part:
+                                tool_file_id, ext = file_part.rsplit(".", 1)
+                                extension = f".{ext}"
+                            else:
+                                tool_file_id = file_part
+                                extension = ".bin"
+                            url = sign_tool_file(tool_file_id=tool_file_id, extension=extension)
+                            filename = file_part
+
+                transfer_method_value = message_file.transfer_method
+                remote_url = message_file.url if message_file.transfer_method == FileTransferMethod.REMOTE_URL else ""
+                file_dict = {
+                    "related_id": message_file.id,
+                    "extension": extension,
+                    "filename": filename,
+                    "size": size,
+                    "mime_type": mime_type,
+                    "transfer_method": transfer_method_value,
+                    "type": message_file.type,
+                    "url": url or "",
+                    "upload_file_id": message_file.upload_file_id or message_file.id,
+                    "remote_url": remote_url,
+                }
+                files_list.append(file_dict)
+            return files_list or None
+
     def _agent_message_to_stream_response(self, answer: str, message_id: str) -> AgentMessageStreamResponse:
         """
         Agent message to stream response.

api/core/app/task_pipeline/message_cycle_manager.py

@@ -64,7 +64,13 @@ class MessageCycleManager:
 
         # Use SQLAlchemy 2.x style session.scalar(select(...))
         with session_factory.create_session() as session:
-            message_file = session.scalar(select(MessageFile).where(MessageFile.message_id == message_id))
+            message_file = session.scalar(
+                select(MessageFile)
+                .where(
+                    MessageFile.message_id == message_id,
+                )
+                .where(MessageFile.belongs_to == "assistant")
+            )
 
         if message_file:
             self._message_has_file.add(message_id)

api/core/plugin/impl/tool.py

@@ -3,6 +3,8 @@ from typing import Any
 
 from pydantic import BaseModel
 
+from configs import dify_config
+
 # from core.plugin.entities.plugin import GenericProviderID, ToolProviderID
 from core.plugin.entities.plugin_daemon import CredentialType, PluginBasicBooleanResponse, PluginToolProviderEntity
 from core.plugin.impl.base import BasePluginClient
@@ -122,7 +124,7 @@ class PluginToolManager(BasePluginClient):
             },
         )
 
-        return merge_blob_chunks(response)
+        return merge_blob_chunks(response, max_file_size=dify_config.PLUGIN_MAX_FILE_SIZE)
 
     def validate_provider_credentials(
         self, tenant_id: str, user_id: str, provider: str, credentials: dict[str, Any]

api/core/rag/datasource/vdb/oceanbase/oceanbase_vector.py

@@ -1,12 +1,13 @@
 import json
 import logging
-import math
-from typing import Any
+import re
+from typing import Any, Literal
 
 from pydantic import BaseModel, model_validator
-from pyobvector import VECTOR, ObVecClient, l2_distance  # type: ignore
+from pyobvector import VECTOR, ObVecClient, cosine_distance, inner_product, l2_distance  # type: ignore
 from sqlalchemy import JSON, Column, String
 from sqlalchemy.dialects.mysql import LONGTEXT
+from sqlalchemy.exc import SQLAlchemyError
 
 from configs import dify_config
 from core.rag.datasource.vdb.vector_base import BaseVector
@@ -19,10 +20,14 @@ from models.dataset import Dataset
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_OCEANBASE_HNSW_BUILD_PARAM = {"M": 16, "efConstruction": 256}
-DEFAULT_OCEANBASE_HNSW_SEARCH_PARAM = {"efSearch": 64}
 OCEANBASE_SUPPORTED_VECTOR_INDEX_TYPE = "HNSW"
-DEFAULT_OCEANBASE_VECTOR_METRIC_TYPE = "l2"
+_VALID_TABLE_NAME_RE = re.compile(r"^[a-zA-Z0-9_]+$")
+
+_DISTANCE_FUNC_MAP = {
+    "l2": l2_distance,
+    "cosine": cosine_distance,
+    "inner_product": inner_product,
+}
 
 
 class OceanBaseVectorConfig(BaseModel):
@@ -32,6 +37,14 @@ class OceanBaseVectorConfig(BaseModel):
     password: str
     database: str
     enable_hybrid_search: bool = False
+    batch_size: int = 100
+    metric_type: Literal["l2", "cosine", "inner_product"] = "l2"
+    hnsw_m: int = 16
+    hnsw_ef_construction: int = 256
+    hnsw_ef_search: int = -1
+    pool_size: int = 5
+    max_overflow: int = 10
+    hnsw_refresh_threshold: int = 1000
 
     @model_validator(mode="before")
     @classmethod
@@ -49,14 +62,23 @@ class OceanBaseVectorConfig(BaseModel):
 
 class OceanBaseVector(BaseVector):
     def __init__(self, collection_name: str, config: OceanBaseVectorConfig):
+        if not _VALID_TABLE_NAME_RE.match(collection_name):
+            raise ValueError(
+                f"Invalid collection name '{collection_name}': "
+                "only alphanumeric characters and underscores are allowed."
+            )
         super().__init__(collection_name)
         self._config = config
-        self._hnsw_ef_search = -1
+        self._hnsw_ef_search = self._config.hnsw_ef_search
         self._client = ObVecClient(
             uri=f"{self._config.host}:{self._config.port}",
             user=self._config.user,
             password=self._config.password,
             db_name=self._config.database,
+            pool_size=self._config.pool_size,
+            max_overflow=self._config.max_overflow,
+            pool_recycle=3600,
+            pool_pre_ping=True,
         )
         self._fields: list[str] = []  # List of fields in the collection
         if self._client.check_table_exists(collection_name):
@@ -136,8 +158,8 @@ class OceanBaseVector(BaseVector):
                 field_name="vector",
                 index_type=OCEANBASE_SUPPORTED_VECTOR_INDEX_TYPE,
                 index_name="vector_index",
-                metric_type=DEFAULT_OCEANBASE_VECTOR_METRIC_TYPE,
-                params=DEFAULT_OCEANBASE_HNSW_BUILD_PARAM,
+                metric_type=self._config.metric_type,
+                params={"M": self._config.hnsw_m, "efConstruction": self._config.hnsw_ef_construction},
             )
 
             self._client.create_table_with_index_params(
@@ -178,6 +200,17 @@ class OceanBaseVector(BaseVector):
             else:
                 logger.debug("DEBUG: Hybrid search is NOT enabled for '%s'", self._collection_name)
 
+            try:
+                self._client.perform_raw_text_sql(
+                    f"CREATE INDEX IF NOT EXISTS idx_metadata_doc_id ON `{self._collection_name}` "
+                    f"((CAST(metadata->>'$.document_id' AS CHAR(64))))"
+                )
+            except SQLAlchemyError:
+                logger.warning(
+                    "Failed to create metadata functional index on '%s'; metadata queries may be slow without it.",
+                    self._collection_name,
+                )
+
             self._client.refresh_metadata([self._collection_name])
             self._load_collection_fields()
             redis_client.set(collection_exist_cache_key, 1, ex=3600)
@@ -205,24 +238,49 @@ class OceanBaseVector(BaseVector):
 
     def add_texts(self, documents: list[Document], embeddings: list[list[float]], **kwargs):
         ids = self._get_uuids(documents)
-        for id, doc, emb in zip(ids, documents, embeddings):
+        batch_size = self._config.batch_size
+        total = len(documents)
+
+        all_data = [
+            {
+                "id": doc_id,
+                "vector": emb,
+                "text": doc.page_content,
+                "metadata": doc.metadata,
+            }
+            for doc_id, doc, emb in zip(ids, documents, embeddings)
+        ]
+
+        for start in range(0, total, batch_size):
+            batch = all_data[start : start + batch_size]
             try:
                 self._client.insert(
                     table_name=self._collection_name,
-                    data={
-                        "id": id,
-                        "vector": emb,
-                        "text": doc.page_content,
-                        "metadata": doc.metadata,
-                    },
+                    data=batch,
                 )
             except Exception as e:
                 logger.exception(
-                    "Failed to insert document with id '%s' in collection '%s'",
-                    id,
+                    "Failed to insert batch [%d:%d] into collection '%s'",
+                    start,
+                    start + len(batch),
+                    self._collection_name,
+                )
+                raise Exception(
+                    f"Failed to insert batch [{start}:{start + len(batch)}] into collection '{self._collection_name}'"
+                ) from e
+
+        if self._config.hnsw_refresh_threshold > 0 and total >= self._config.hnsw_refresh_threshold:
+            try:
+                self._client.refresh_index(
+                    table_name=self._collection_name,
+                    index_name="vector_index",
+                )
+            except SQLAlchemyError:
+                logger.warning(
+                    "Failed to refresh HNSW index after inserting %d documents into '%s'",
+                    total,
                     self._collection_name,
                 )
-                raise Exception(f"Failed to insert document with id '{id}'") from e
 
     def text_exists(self, id: str) -> bool:
         try:
@@ -412,7 +470,7 @@ class OceanBaseVector(BaseVector):
                 vec_column_name="vector",
                 vec_data=query_vector,
                 topk=topk,
-                distance_func=l2_distance,
+                distance_func=self._get_distance_func(),
                 output_column_names=["text", "metadata"],
                 with_dist=True,
                 where_clause=_where_clause,
@@ -424,14 +482,31 @@ class OceanBaseVector(BaseVector):
             )
             raise Exception(f"Vector search failed for collection '{self._collection_name}'") from e
 
-        # Convert distance to score and prepare results for processing
         results = []
         for _text, metadata_str, distance in cur:
-            score = 1 - distance / math.sqrt(2)
+            score = self._distance_to_score(distance)
             results.append((_text, metadata_str, score))
 
         return self._process_search_results(results, score_threshold=score_threshold)
 
+    def _get_distance_func(self):
+        func = _DISTANCE_FUNC_MAP.get(self._config.metric_type)
+        if func is None:
+            raise ValueError(
+                f"Unsupported metric_type '{self._config.metric_type}'. Supported: {', '.join(_DISTANCE_FUNC_MAP)}"
+            )
+        return func
+
+    def _distance_to_score(self, distance: float) -> float:
+        metric = self._config.metric_type
+        if metric == "l2":
+            return 1.0 / (1.0 + distance)
+        elif metric == "cosine":
+            return 1.0 - distance
+        elif metric == "inner_product":
+            return -distance
+        raise ValueError(f"Unsupported metric_type '{metric}'")
+
     def delete(self):
         try:
             self._client.drop_table_if_exist(self._collection_name)
@@ -464,5 +539,13 @@ class OceanBaseVectorFactory(AbstractVectorFactory):
                 password=(dify_config.OCEANBASE_VECTOR_PASSWORD or ""),
                 database=dify_config.OCEANBASE_VECTOR_DATABASE or "",
                 enable_hybrid_search=dify_config.OCEANBASE_ENABLE_HYBRID_SEARCH or False,
+                batch_size=dify_config.OCEANBASE_VECTOR_BATCH_SIZE,
+                metric_type=dify_config.OCEANBASE_VECTOR_METRIC_TYPE,
+                hnsw_m=dify_config.OCEANBASE_HNSW_M,
+                hnsw_ef_construction=dify_config.OCEANBASE_HNSW_EF_CONSTRUCTION,
+                hnsw_ef_search=dify_config.OCEANBASE_HNSW_EF_SEARCH,
+                pool_size=dify_config.OCEANBASE_VECTOR_POOL_SIZE,
+                max_overflow=dify_config.OCEANBASE_VECTOR_MAX_OVERFLOW,
+                hnsw_refresh_threshold=dify_config.OCEANBASE_HNSW_REFRESH_THRESHOLD,
             ),
         )

api/core/tools/__base/tool.py

@@ -5,7 +5,7 @@ from collections.abc import Generator
 from copy import deepcopy
 from typing import TYPE_CHECKING, Any
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from models.model import File
 
 from core.tools.__base.tool_runtime import ToolRuntime
@@ -171,7 +171,7 @@ class Tool(ABC):
     def create_file_message(self, file: File) -> ToolInvokeMessage:
         return ToolInvokeMessage(
             type=ToolInvokeMessage.MessageType.FILE,
-            message=ToolInvokeMessage.FileMessage(),
+            message=ToolInvokeMessage.FileMessage(file_marker="file_marker"),
             meta={"file": file},
         )
 

api/extensions/ext_celery.py

@@ -80,8 +80,14 @@ def init_app(app: DifyApp) -> Celery:
         worker_hijack_root_logger=False,
         timezone=pytz.timezone(dify_config.LOG_TZ or "UTC"),
         task_ignore_result=True,
+        task_annotations=dify_config.CELERY_TASK_ANNOTATIONS,
     )
 
+    if dify_config.CELERY_BACKEND == "redis":
+        celery_app.conf.update(
+            result_backend_transport_options=broker_transport_options,
+        )
+
     # Apply SSL configuration if enabled
     ssl_options = _get_celery_ssl_options()
     if ssl_options:

api/extensions/ext_redis.py

@@ -119,7 +119,7 @@ class RedisClientWrapper:
 
 
 redis_client: RedisClientWrapper = RedisClientWrapper()
-pubsub_redis_client: RedisClientWrapper = RedisClientWrapper()
+_pubsub_redis_client: redis.Redis | RedisCluster | None = None
 
 
 def _get_ssl_configuration() -> tuple[type[Union[Connection, SSLConnection]], dict[str, Any]]:
@@ -232,7 +232,7 @@ def _create_standalone_client(redis_params: dict[str, Any]) -> Union[redis.Redis
     return client
 
 
-def _create_pubsub_client(pubsub_url: str, use_clusters: bool) -> Union[redis.Redis, RedisCluster]:
+def _create_pubsub_client(pubsub_url: str, use_clusters: bool) -> redis.Redis | RedisCluster:
     if use_clusters:
         return RedisCluster.from_url(pubsub_url)
     return redis.Redis.from_url(pubsub_url)
@@ -256,23 +256,19 @@ def init_app(app: DifyApp):
     redis_client.initialize(client)
     app.extensions["redis"] = redis_client
 
-    pubsub_client = client
+    global _pubsub_redis_client
+    _pubsub_redis_client = client
     if dify_config.normalized_pubsub_redis_url:
-        pubsub_client = _create_pubsub_client(
+        _pubsub_redis_client = _create_pubsub_client(
             dify_config.normalized_pubsub_redis_url, dify_config.PUBSUB_REDIS_USE_CLUSTERS
         )
-    pubsub_redis_client.initialize(pubsub_client)
-
-
-def get_pubsub_redis_client() -> RedisClientWrapper:
-    return pubsub_redis_client
 
 
 def get_pubsub_broadcast_channel() -> BroadcastChannelProtocol:
-    redis_conn = get_pubsub_redis_client()
+    assert _pubsub_redis_client is not None, "PubSub redis Client should be initialized here."
     if dify_config.PUBSUB_REDIS_CHANNEL_TYPE == "sharded":
-        return ShardedRedisBroadcastChannel(redis_conn)  # pyright: ignore[reportArgumentType]
-    return RedisBroadcastChannel(redis_conn)  # pyright: ignore[reportArgumentType]
+        return ShardedRedisBroadcastChannel(_pubsub_redis_client)
+    return RedisBroadcastChannel(_pubsub_redis_client)
 
 
 P = ParamSpec("P")

api/extensions/otel/decorators/base.py

@@ -1,6 +1,6 @@
 import functools
 from collections.abc import Callable
-from typing import Any, TypeVar, cast
+from typing import ParamSpec, TypeVar, cast
 
 from opentelemetry.trace import get_tracer
 
@@ -8,7 +8,8 @@ from configs import dify_config
 from extensions.otel.decorators.handler import SpanHandler
 from extensions.otel.runtime import is_instrument_flag_enabled
 
-T = TypeVar("T", bound=Callable[..., Any])
+P = ParamSpec("P")
+R = TypeVar("R")
 
 _HANDLER_INSTANCES: dict[type[SpanHandler], SpanHandler] = {SpanHandler: SpanHandler()}
 
@@ -20,7 +21,7 @@ def _get_handler_instance(handler_class: type[SpanHandler]) -> SpanHandler:
     return _HANDLER_INSTANCES[handler_class]
 
 
-def trace_span(handler_class: type[SpanHandler] | None = None) -> Callable[[T], T]:
+def trace_span(handler_class: type[SpanHandler] | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]:
     """
     Decorator that traces a function with an OpenTelemetry span.
 
@@ -30,9 +31,9 @@ def trace_span(handler_class: type[SpanHandler] | None = None) -> Callable[[T],
     :param handler_class: Optional handler class to use for this span. If None, uses the default SpanHandler.
     """
 
-    def decorator(func: T) -> T:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
         @functools.wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             if not (dify_config.ENABLE_OTEL or is_instrument_flag_enabled()):
                 return func(*args, **kwargs)
 
@@ -46,6 +47,6 @@ def trace_span(handler_class: type[SpanHandler] | None = None) -> Callable[[T],
                 kwargs=kwargs,
             )
 
-        return cast(T, wrapper)
+        return cast(Callable[P, R], wrapper)
 
     return decorator

api/extensions/otel/decorators/handler.py

@@ -1,9 +1,11 @@
 import inspect
 from collections.abc import Callable, Mapping
-from typing import Any
+from typing import Any, TypeVar
 
 from opentelemetry.trace import SpanKind, Status, StatusCode
 
+R = TypeVar("R")
+
 
 class SpanHandler:
     """
@@ -31,9 +33,9 @@ class SpanHandler:
 
     def _extract_arguments(
         self,
-        wrapped: Callable[..., Any],
-        args: tuple[Any, ...],
-        kwargs: Mapping[str, Any],
+        wrapped: Callable[..., R],
+        args: tuple[object, ...],
+        kwargs: Mapping[str, object],
     ) -> dict[str, Any] | None:
         """
         Extract function arguments using inspect.signature.
@@ -62,10 +64,10 @@ class SpanHandler:
     def wrapper(
         self,
         tracer: Any,
-        wrapped: Callable[..., Any],
-        args: tuple[Any, ...],
-        kwargs: Mapping[str, Any],
-    ) -> Any:
+        wrapped: Callable[..., R],
+        args: tuple[object, ...],
+        kwargs: Mapping[str, object],
+    ) -> R:
         """
         Fully control the wrapper behavior.
 

api/extensions/otel/decorators/handlers/generate_handler.py

@@ -1,6 +1,6 @@
 import logging
 from collections.abc import Callable, Mapping
-from typing import Any
+from typing import Any, TypeVar
 
 from opentelemetry.trace import SpanKind, Status, StatusCode
 from opentelemetry.util.types import AttributeValue
@@ -12,16 +12,19 @@ from models.model import Account
 logger = logging.getLogger(__name__)
 
 
+R = TypeVar("R")
+
+
 class AppGenerateHandler(SpanHandler):
     """Span handler for ``AppGenerateService.generate``."""
 
     def wrapper(
         self,
         tracer: Any,
-        wrapped: Callable[..., Any],
-        args: tuple[Any, ...],
-        kwargs: Mapping[str, Any],
-    ) -> Any:
+        wrapped: Callable[..., R],
+        args: tuple[object, ...],
+        kwargs: Mapping[str, object],
+    ) -> R:
         try:
             arguments = self._extract_arguments(wrapped, args, kwargs)
             if not arguments:

api/libs/broadcast_channel/redis/_subscription.py

@@ -152,7 +152,7 @@ class RedisSubscriptionBase(Subscription):
         """Iterator for consuming messages from the subscription."""
         while not self._closed.is_set():
             try:
-                item = self._queue.get(timeout=0.1)
+                item = self._queue.get(timeout=1)
             except queue.Empty:
                 continue
 

api/libs/broadcast_channel/redis/channel.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from libs.broadcast_channel.channel import Producer, Subscriber, Subscription
-from redis import Redis
+from redis import Redis, RedisCluster
 
 from ._subscription import RedisSubscriptionBase
 
@@ -18,7 +18,7 @@ class BroadcastChannel:
 
     def __init__(
         self,
-        redis_client: Redis,
+        redis_client: Redis | RedisCluster,
     ):
         self._client = redis_client
 
@@ -27,7 +27,7 @@ class BroadcastChannel:
 
 
 class Topic:
-    def __init__(self, redis_client: Redis, topic: str):
+    def __init__(self, redis_client: Redis | RedisCluster, topic: str):
         self._client = redis_client
         self._topic = topic
 

api/libs/broadcast_channel/redis/sharded_channel.py

@@ -70,8 +70,9 @@ class _RedisShardedSubscription(RedisSubscriptionBase):
         # Since we have already filtered at the caller's site, we can safely set
         # `ignore_subscribe_messages=False`.
         if isinstance(self._client, RedisCluster):
-            # NOTE(QuantumGhost): due to an issue in upstream code, calling `get_sharded_message`
-            # would use busy-looping to wait for incoming message, consuming excessive CPU quota.
+            # NOTE(QuantumGhost): due to an issue in upstream code, calling `get_sharded_message` without
+            # specifying the `target_node` argument would use busy-looping to wait
+            # for incoming message, consuming excessive CPU quota.
             #
             # Here we specify the `target_node` to mitigate this problem.
             node = self._client.get_node_from_key(self._topic)
@@ -80,8 +81,10 @@ class _RedisShardedSubscription(RedisSubscriptionBase):
                 timeout=1,
                 target_node=node,
             )
-        else:
+        elif isinstance(self._client, Redis):
             return self._pubsub.get_sharded_message(ignore_subscribe_messages=False, timeout=1)  # type: ignore[attr-defined]
+        else:
+            raise AssertionError("client should be either Redis or RedisCluster.")
 
     def _get_message_type(self) -> str:
         return "smessage"

api/libs/db_migration_lock.py

@@ -0,0 +1,213 @@
+"""
+DB migration Redis lock with heartbeat renewal.
+
+This is intentionally migration-specific. Background renewal is a trade-off that makes sense
+for unbounded, blocking operations like DB migrations (DDL/DML) where the main thread cannot
+periodically refresh the lock TTL.
+
+Do NOT use this as a general-purpose lock primitive for normal application code. Prefer explicit
+lock lifecycle management (e.g. redis-py Lock context manager + `extend()` / `reacquire()` from
+the same thread) when execution flow is under control.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+from redis.exceptions import LockNotOwnedError, RedisError
+
+logger = logging.getLogger(__name__)
+
+MIN_RENEW_INTERVAL_SECONDS = 0.1
+DEFAULT_RENEW_INTERVAL_DIVISOR = 3
+MIN_JOIN_TIMEOUT_SECONDS = 0.5
+MAX_JOIN_TIMEOUT_SECONDS = 5.0
+JOIN_TIMEOUT_MULTIPLIER = 2.0
+
+
+class DbMigrationAutoRenewLock:
+    """
+    Redis lock wrapper that automatically renews TTL while held (migration-only).
+
+    Notes:
+    - We force `thread_local=False` when creating the underlying redis-py lock, because the
+      lock token must be accessible from the heartbeat thread for `reacquire()` to work.
+    - `release_safely()` is best-effort: it never raises, so it won't mask the caller's
+      primary error/exit code.
+    """
+
+    _redis_client: Any
+    _name: str
+    _ttl_seconds: float
+    _renew_interval_seconds: float
+    _log_context: str | None
+    _logger: logging.Logger
+
+    _lock: Any
+    _stop_event: threading.Event | None
+    _thread: threading.Thread | None
+    _acquired: bool
+
+    def __init__(
+        self,
+        redis_client: Any,
+        name: str,
+        ttl_seconds: float = 60,
+        renew_interval_seconds: float | None = None,
+        *,
+        logger: logging.Logger | None = None,
+        log_context: str | None = None,
+    ) -> None:
+        self._redis_client = redis_client
+        self._name = name
+        self._ttl_seconds = float(ttl_seconds)
+        self._renew_interval_seconds = (
+            float(renew_interval_seconds)
+            if renew_interval_seconds is not None
+            else max(MIN_RENEW_INTERVAL_SECONDS, self._ttl_seconds / DEFAULT_RENEW_INTERVAL_DIVISOR)
+        )
+        self._logger = logger or logging.getLogger(__name__)
+        self._log_context = log_context
+
+        self._lock = None
+        self._stop_event = None
+        self._thread = None
+        self._acquired = False
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def acquire(self, *args: Any, **kwargs: Any) -> bool:
+        """
+        Acquire the lock and start heartbeat renewal on success.
+
+        Accepts the same args/kwargs as redis-py `Lock.acquire()`.
+        """
+        # Prevent accidental double-acquire which could leave the previous heartbeat thread running.
+        if self._acquired:
+            raise RuntimeError("DB migration lock is already acquired; call release_safely() before acquiring again.")
+
+        # Reuse the lock object if we already created one.
+        if self._lock is None:
+            self._lock = self._redis_client.lock(
+                name=self._name,
+                timeout=self._ttl_seconds,
+                thread_local=False,
+            )
+        acquired = bool(self._lock.acquire(*args, **kwargs))
+        self._acquired = acquired
+        if acquired:
+            self._start_heartbeat()
+        return acquired
+
+    def owned(self) -> bool:
+        if self._lock is None:
+            return False
+        try:
+            return bool(self._lock.owned())
+        except Exception:
+            # Ownership checks are best-effort and must not break callers.
+            return False
+
+    def _start_heartbeat(self) -> None:
+        if self._lock is None:
+            return
+        if self._stop_event is not None:
+            return
+
+        self._stop_event = threading.Event()
+        self._thread = threading.Thread(
+            target=self._heartbeat_loop,
+            args=(self._lock, self._stop_event),
+            daemon=True,
+            name=f"DbMigrationAutoRenewLock({self._name})",
+        )
+        self._thread.start()
+
+    def _heartbeat_loop(self, lock: Any, stop_event: threading.Event) -> None:
+        while not stop_event.wait(self._renew_interval_seconds):
+            try:
+                lock.reacquire()
+            except LockNotOwnedError:
+                self._logger.warning(
+                    "DB migration lock is no longer owned during heartbeat; stop renewing. log_context=%s",
+                    self._log_context,
+                    exc_info=True,
+                )
+                return
+            except RedisError:
+                self._logger.warning(
+                    "Failed to renew DB migration lock due to Redis error; will retry. log_context=%s",
+                    self._log_context,
+                    exc_info=True,
+                )
+            except Exception:
+                self._logger.warning(
+                    "Unexpected error while renewing DB migration lock; will retry. log_context=%s",
+                    self._log_context,
+                    exc_info=True,
+                )
+
+    def release_safely(self, *, status: str | None = None) -> None:
+        """
+        Stop heartbeat and release lock. Never raises.
+
+        Args:
+            status: Optional caller-provided status (e.g. 'successful'/'failed') to add context to logs.
+        """
+        lock = self._lock
+        if lock is None:
+            return
+
+        self._stop_heartbeat()
+
+        # Lock release errors should never mask the real error/exit code.
+        try:
+            lock.release()
+        except LockNotOwnedError:
+            self._logger.warning(
+                "DB migration lock not owned on release; ignoring. status=%s log_context=%s",
+                status,
+                self._log_context,
+                exc_info=True,
+            )
+        except RedisError:
+            self._logger.warning(
+                "Failed to release DB migration lock due to Redis error; ignoring. status=%s log_context=%s",
+                status,
+                self._log_context,
+                exc_info=True,
+            )
+        except Exception:
+            self._logger.warning(
+                "Unexpected error while releasing DB migration lock; ignoring. status=%s log_context=%s",
+                status,
+                self._log_context,
+                exc_info=True,
+            )
+        finally:
+            self._acquired = False
+            self._lock = None
+
+    def _stop_heartbeat(self) -> None:
+        if self._stop_event is None:
+            return
+        self._stop_event.set()
+        if self._thread is not None:
+            # Best-effort join: if Redis calls are blocked, the daemon thread may remain alive.
+            join_timeout_seconds = max(
+                MIN_JOIN_TIMEOUT_SECONDS,
+                min(MAX_JOIN_TIMEOUT_SECONDS, self._renew_interval_seconds * JOIN_TIMEOUT_MULTIPLIER),
+            )
+            self._thread.join(timeout=join_timeout_seconds)
+            if self._thread.is_alive():
+                self._logger.warning(
+                    "DB migration lock heartbeat thread did not stop within %.2fs; ignoring. log_context=%s",
+                    join_timeout_seconds,
+                    self._log_context,
+                )
+        self._stop_event = None
+        self._thread = None

api/migrations/versions/2026_02_10_1507-f55813ffe2c8_fix_tenant_default_model_unique.py

@@ -0,0 +1,59 @@
+"""add unique constraint to tenant_default_models
+
+Revision ID: fix_tenant_default_model_unique
+Revises: 9d77545f524e
+Create Date: 2026-01-19 15:07:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+def _is_pg(conn):
+    return conn.dialect.name == "postgresql"
+
+
+# revision identifiers, used by Alembic.
+revision = 'f55813ffe2c8'
+down_revision = 'c3df22613c99'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # First, remove duplicate records keeping only the most recent one per (tenant_id, model_type)
+    # This is necessary before adding the unique constraint
+    conn = op.get_bind()
+    
+    # Delete duplicates: keep the record with the latest updated_at for each (tenant_id, model_type)
+    # If updated_at is the same, keep the one with the largest id as tiebreaker
+    if _is_pg(conn):
+        # PostgreSQL: Use DISTINCT ON for efficient deduplication
+        conn.execute(sa.text("""
+            DELETE FROM tenant_default_models
+            WHERE id NOT IN (
+                SELECT DISTINCT ON (tenant_id, model_type) id
+                FROM tenant_default_models
+                ORDER BY tenant_id, model_type, updated_at DESC, id DESC
+            )
+        """))
+    else:
+        # MySQL: Use self-join to find and delete duplicates
+        # Keep the record with latest updated_at (or largest id if updated_at is equal)
+        conn.execute(sa.text("""
+            DELETE t1 FROM tenant_default_models t1
+            INNER JOIN tenant_default_models t2
+            ON t1.tenant_id = t2.tenant_id 
+               AND t1.model_type = t2.model_type 
+               AND (t1.updated_at < t2.updated_at 
+                    OR (t1.updated_at = t2.updated_at AND t1.id < t2.id))
+        """))
+    
+    # Now add the unique constraint
+    with op.batch_alter_table('tenant_default_models', schema=None) as batch_op:
+        batch_op.create_unique_constraint('unique_tenant_default_model_type', ['tenant_id', 'model_type'])
+
+
+def downgrade():
+    with op.batch_alter_table('tenant_default_models', schema=None) as batch_op:
+        batch_op.drop_constraint('unique_tenant_default_model_type', type_='unique')

api/migrations/versions/2026_02_11_1549-fce013ca180e_fix_index_to_optimize_message_clean_job_.py

@@ -0,0 +1,39 @@
+"""fix index to optimize message clean job performance
+
+Revision ID: fce013ca180e
+Revises: f55813ffe2c8
+Create Date: 2026-02-11 15:49:17.603638
+
+"""
+from alembic import op
+import models as models
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'fce013ca180e'
+down_revision = 'f55813ffe2c8'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('messages', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('message_created_at_idx'))
+
+    with op.batch_alter_table('saved_messages', schema=None) as batch_op:
+        batch_op.create_index('saved_message_message_id_idx', ['message_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('saved_messages', schema=None) as batch_op:
+        batch_op.drop_index('saved_message_message_id_idx')
+
+    with op.batch_alter_table('messages', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('message_created_at_idx'), ['created_at'], unique=False)
+
+    # ### end Alembic commands ###

api/models/model.py

@@ -227,7 +227,7 @@ class App(Base):
         with Session(db.engine) as session:
             if api_provider_ids:
                 existing_api_providers = [
-                    api_provider.id
+                    str(api_provider.id)
                     for api_provider in session.execute(
                         text("SELECT id FROM tool_api_providers WHERE id IN :provider_ids"),
                         {"provider_ids": tuple(api_provider_ids)},
@@ -1040,7 +1040,6 @@ class Message(Base):
         Index("message_end_user_idx", "app_id", "from_source", "from_end_user_id"),
         Index("message_account_idx", "app_id", "from_source", "from_account_id"),
         Index("message_workflow_run_id_idx", "conversation_id", "workflow_run_id"),
-        Index("message_created_at_idx", "created_at"),
         Index("message_app_mode_idx", "app_mode"),
         Index("message_created_at_id_idx", "created_at", "id"),
     )

api/models/provider.py

@@ -181,6 +181,7 @@ class TenantDefaultModel(TypeBase):
     __table_args__ = (
         sa.PrimaryKeyConstraint("id", name="tenant_default_model_pkey"),
         sa.Index("tenant_default_model_tenant_id_provider_type_idx", "tenant_id", "provider_name", "model_type"),
+        sa.UniqueConstraint("tenant_id", "model_type", name="unique_tenant_default_model_type"),
     )
 
     id: Mapped[str] = mapped_column(

api/models/web.py

@@ -16,6 +16,7 @@ class SavedMessage(TypeBase):
     __table_args__ = (
         sa.PrimaryKeyConstraint("id", name="saved_message_pkey"),
         sa.Index("saved_message_message_idx", "app_id", "message_id", "created_by_role", "created_by"),
+        sa.Index("saved_message_message_id_idx", "message_id"),
     )
 
     id: Mapped[str] = mapped_column(

api/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dify-api"
-version = "1.12.1"
+version = "1.13.0"
 requires-python = ">=3.11,<3.13"
 
 dependencies = [
@@ -23,7 +23,7 @@ dependencies = [
     "gevent~=25.9.1",
     "gmpy2~=2.2.1",
     "google-api-core==2.18.0",
-    "google-api-python-client==2.90.0",
+    "google-api-python-client==2.189.0",
     "google-auth==2.29.0",
     "google-auth-httplib2==0.2.0",
     "google-cloud-aiplatform==1.49.0",
@@ -67,7 +67,7 @@ dependencies = [
     "pycryptodome==3.23.0",
     "pydantic~=2.11.4",
     "pydantic-extra-types~=2.10.3",
-    "pydantic-settings~=2.11.0",
+    "pydantic-settings~=2.12.0",
     "pyjwt~=2.10.1",
     "pypdfium2==5.2.0",
     "python-docx~=1.1.0",

api/repositories/api_workflow_run_repository.py

@@ -264,9 +264,15 @@ class APIWorkflowRunRepository(WorkflowExecutionRepository, Protocol):
         batch_size: int,
         run_types: Sequence[WorkflowType] | None = None,
         tenant_ids: Sequence[str] | None = None,
+        workflow_ids: Sequence[str] | None = None,
     ) -> Sequence[WorkflowRun]:
         """
         Fetch ended workflow runs in a time window for archival and clean batching.
+
+        Optional filters:
+        - run_types
+        - tenant_ids
+        - workflow_ids
         """
         ...
 

api/repositories/sqlalchemy_api_workflow_run_repository.py

@@ -386,6 +386,7 @@ class DifyAPISQLAlchemyWorkflowRunRepository(APIWorkflowRunRepository):
         batch_size: int,
         run_types: Sequence[WorkflowType] | None = None,
         tenant_ids: Sequence[str] | None = None,
+        workflow_ids: Sequence[str] | None = None,
     ) -> Sequence[WorkflowRun]:
         """
         Fetch ended workflow runs in a time window for archival and clean batching.
@@ -394,7 +395,7 @@ class DifyAPISQLAlchemyWorkflowRunRepository(APIWorkflowRunRepository):
         - created_at in [start_from, end_before)
         - type in run_types (when provided)
         - status is an ended state
-        - optional tenant_id filter and cursor (last_seen) for pagination
+        - optional tenant_id, workflow_id filters and cursor (last_seen) for pagination
         """
         with self._session_maker() as session:
             stmt = (
@@ -417,6 +418,9 @@ class DifyAPISQLAlchemyWorkflowRunRepository(APIWorkflowRunRepository):
             if tenant_ids:
                 stmt = stmt.where(WorkflowRun.tenant_id.in_(tenant_ids))
 
+            if workflow_ids:
+                stmt = stmt.where(WorkflowRun.workflow_id.in_(workflow_ids))
+
             if last_seen:
                 stmt = stmt.where(
                     or_(

api/schedule/clean_workflow_runlogs_precise.py

@@ -4,7 +4,6 @@ import time
 from collections.abc import Sequence
 
 import click
-from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 
 import app
@@ -13,6 +12,7 @@ from extensions.ext_database import db
 from models.model import (
     AppAnnotationHitHistory,
     Conversation,
+    DatasetRetrieverResource,
     Message,
     MessageAgentThought,
     MessageAnnotation,
@@ -20,7 +20,10 @@ from models.model import (
     MessageFeedback,
     MessageFile,
 )
-from models.workflow import ConversationVariable, WorkflowAppLog, WorkflowNodeExecutionModel, WorkflowRun
+from models.web import SavedMessage
+from models.workflow import ConversationVariable, WorkflowRun
+from repositories.factory import DifyAPIRepositoryFactory
+from repositories.sqlalchemy_workflow_trigger_log_repository import SQLAlchemyWorkflowTriggerLogRepository
 
 logger = logging.getLogger(__name__)
 
@@ -29,8 +32,15 @@ MAX_RETRIES = 3
 BATCH_SIZE = dify_config.WORKFLOW_LOG_CLEANUP_BATCH_SIZE
 
 
-@app.celery.task(queue="dataset")
-def clean_workflow_runlogs_precise():
+def _get_specific_workflow_ids() -> list[str]:
+    workflow_ids_str = dify_config.WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS.strip()
+    if not workflow_ids_str:
+        return []
+    return [wid.strip() for wid in workflow_ids_str.split(",") if wid.strip()]
+
+
+@app.celery.task(queue="retention")
+def clean_workflow_runlogs_precise() -> None:
     """Clean expired workflow run logs with retry mechanism and complete message cascade"""
 
     click.echo(click.style("Start clean workflow run logs (precise mode with complete cascade).", fg="green"))
@@ -39,48 +49,48 @@ def clean_workflow_runlogs_precise():
     retention_days = dify_config.WORKFLOW_LOG_RETENTION_DAYS
     cutoff_date = datetime.datetime.now() - datetime.timedelta(days=retention_days)
     session_factory = sessionmaker(db.engine, expire_on_commit=False)
+    workflow_run_repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_factory)
+    workflow_ids = _get_specific_workflow_ids()
+    workflow_ids_filter = workflow_ids or None
 
     try:
-        with session_factory.begin() as session:
-            total_workflow_runs = session.query(WorkflowRun).where(WorkflowRun.created_at < cutoff_date).count()
-            if total_workflow_runs == 0:
-                logger.info("No expired workflow run logs found")
-                return
-            logger.info("Found %s expired workflow run logs to clean", total_workflow_runs)
-
         total_deleted = 0
         failed_batches = 0
         batch_count = 0
+        last_seen: tuple[datetime.datetime, str] | None = None
         while True:
+            run_rows = workflow_run_repo.get_runs_batch_by_time_range(
+                start_from=None,
+                end_before=cutoff_date,
+                last_seen=last_seen,
+                batch_size=BATCH_SIZE,
+                workflow_ids=workflow_ids_filter,
+            )
+
+            if not run_rows:
+                if batch_count == 0:
+                    logger.info("No expired workflow run logs found")
+                break
+
+            last_seen = (run_rows[-1].created_at, run_rows[-1].id)
+            batch_count += 1
             with session_factory.begin() as session:
-                workflow_run_ids = session.scalars(
-                    select(WorkflowRun.id)
-                    .where(WorkflowRun.created_at < cutoff_date)
-                    .order_by(WorkflowRun.created_at, WorkflowRun.id)
-                    .limit(BATCH_SIZE)
-                ).all()
+                success = _delete_batch(session, workflow_run_repo, run_rows, failed_batches)
 
-                if not workflow_run_ids:
+            if success:
+                total_deleted += len(run_rows)
+                failed_batches = 0
+            else:
+                failed_batches += 1
+                if failed_batches >= MAX_RETRIES:
+                    logger.error("Failed to delete batch after %s retries, aborting cleanup for today", MAX_RETRIES)
                     break
-
-                batch_count += 1
-
-                success = _delete_batch(session, workflow_run_ids, failed_batches)
-
-                if success:
-                    total_deleted += len(workflow_run_ids)
-                    failed_batches = 0
                 else:
-                    failed_batches += 1
-                    if failed_batches >= MAX_RETRIES:
-                        logger.error("Failed to delete batch after %s retries, aborting cleanup for today", MAX_RETRIES)
-                        break
-                    else:
-                        # Calculate incremental delay times: 5, 10, 15 minutes
-                        retry_delay_minutes = failed_batches * 5
-                        logger.warning("Batch deletion failed, retrying in %s minutes...", retry_delay_minutes)
-                        time.sleep(retry_delay_minutes * 60)
-                        continue
+                    # Calculate incremental delay times: 5, 10, 15 minutes
+                    retry_delay_minutes = failed_batches * 5
+                    logger.warning("Batch deletion failed, retrying in %s minutes...", retry_delay_minutes)
+                    time.sleep(retry_delay_minutes * 60)
+                    continue
 
         logger.info("Cleanup completed: %s expired workflow run logs deleted", total_deleted)
 
@@ -93,10 +103,16 @@ def clean_workflow_runlogs_precise():
     click.echo(click.style(f"Cleaned workflow run logs from db success latency: {execution_time:.2f}s", fg="green"))
 
 
-def _delete_batch(session: Session, workflow_run_ids: Sequence[str], attempt_count: int) -> bool:
+def _delete_batch(
+    session: Session,
+    workflow_run_repo,
+    workflow_runs: Sequence[WorkflowRun],
+    attempt_count: int,
+) -> bool:
     """Delete a single batch of workflow runs and all related data within a nested transaction."""
     try:
         with session.begin_nested():
+            workflow_run_ids = [run.id for run in workflow_runs]
             message_data = (
                 session.query(Message.id, Message.conversation_id)
                 .where(Message.workflow_run_id.in_(workflow_run_ids))
@@ -107,11 +123,13 @@ def _delete_batch(session: Session, workflow_run_ids: Sequence[str], attempt_cou
             if message_id_list:
                 message_related_models = [
                     AppAnnotationHitHistory,
+                    DatasetRetrieverResource,
                     MessageAgentThought,
                     MessageChain,
                     MessageFile,
                     MessageAnnotation,
                     MessageFeedback,
+                    SavedMessage,
                 ]
                 for model in message_related_models:
                     session.query(model).where(model.message_id.in_(message_id_list)).delete(synchronize_session=False)  # type: ignore
@@ -122,14 +140,6 @@ def _delete_batch(session: Session, workflow_run_ids: Sequence[str], attempt_cou
                     synchronize_session=False
                 )
 
-            session.query(WorkflowAppLog).where(WorkflowAppLog.workflow_run_id.in_(workflow_run_ids)).delete(
-                synchronize_session=False
-            )
-
-            session.query(WorkflowNodeExecutionModel).where(
-                WorkflowNodeExecutionModel.workflow_run_id.in_(workflow_run_ids)
-            ).delete(synchronize_session=False)
-
             if conversation_id_list:
                 session.query(ConversationVariable).where(
                     ConversationVariable.conversation_id.in_(conversation_id_list)
@@ -139,7 +149,22 @@ def _delete_batch(session: Session, workflow_run_ids: Sequence[str], attempt_cou
                     synchronize_session=False
                 )
 
-            session.query(WorkflowRun).where(WorkflowRun.id.in_(workflow_run_ids)).delete(synchronize_session=False)
+            def _delete_node_executions(active_session: Session, runs: Sequence[WorkflowRun]) -> tuple[int, int]:
+                run_ids = [run.id for run in runs]
+                repo = DifyAPIRepositoryFactory.create_api_workflow_node_execution_repository(
+                    session_maker=sessionmaker(bind=active_session.get_bind(), expire_on_commit=False)
+                )
+                return repo.delete_by_runs(active_session, run_ids)
+
+            def _delete_trigger_logs(active_session: Session, run_ids: Sequence[str]) -> int:
+                trigger_repo = SQLAlchemyWorkflowTriggerLogRepository(active_session)
+                return trigger_repo.delete_by_run_ids(run_ids)
+
+            workflow_run_repo.delete_runs_with_related(
+                workflow_runs,
+                delete_node_executions=_delete_node_executions,
+                delete_trigger_logs=_delete_trigger_logs,
+            )
 
             return True
 

api/services/account_service.py

@@ -1225,7 +1225,12 @@ class TenantService:
 
     @staticmethod
     def remove_member_from_tenant(tenant: Tenant, account: Account, operator: Account):
-        """Remove member from tenant"""
+        """Remove member from tenant.
+
+        If the removed member has ``AccountStatus.PENDING`` (invited but never
+        activated) and no remaining workspace memberships, the orphaned account
+        record is deleted as well.
+        """
         if operator.id == account.id:
             raise CannotOperateSelfError("Cannot operate self.")
 
@@ -1235,9 +1240,31 @@ class TenantService:
         if not ta:
             raise MemberNotInTenantError("Member not in tenant.")
 
+        # Capture identifiers before any deletions; attribute access on the ORM
+        # object may fail after commit() expires the instance.
+        account_id = account.id
+        account_email = account.email
+
         db.session.delete(ta)
+
+        # Clean up orphaned pending accounts (invited but never activated)
+        should_delete_account = False
+        if account.status == AccountStatus.PENDING:
+            # autoflush flushes ta deletion before this query, so 0 means no remaining joins
+            remaining_joins = db.session.query(TenantAccountJoin).filter_by(account_id=account_id).count()
+            if remaining_joins == 0:
+                db.session.delete(account)
+                should_delete_account = True
+
         db.session.commit()
 
+        if should_delete_account:
+            logger.info(
+                "Deleted orphaned pending account: account_id=%s, email=%s",
+                account_id,
+                account_email,
+            )
+
         if dify_config.BILLING_ENABLED:
             BillingService.clean_billing_info_cache(tenant.id)
 
@@ -1245,13 +1272,13 @@ class TenantService:
         from services.enterprise.account_deletion_sync import sync_workspace_member_removal
 
         sync_success = sync_workspace_member_removal(
-            workspace_id=tenant.id, member_id=account.id, source="workspace_member_removed"
+            workspace_id=tenant.id, member_id=account_id, source="workspace_member_removed"
         )
         if not sync_success:
             logger.warning(
                 "Enterprise workspace member removal sync failed: workspace_id=%s, member_id=%s",
                 tenant.id,
-                account.id,
+                account_id,
             )
 
     @staticmethod

api/services/enterprise/enterprise_service.py

@@ -4,6 +4,8 @@ from pydantic import BaseModel, Field
 
 from services.enterprise.base import EnterpriseRequest
 
+ALLOWED_ACCESS_MODES = ["public", "private", "private_all", "sso_verified"]
+
 
 class WebAppSettings(BaseModel):
     access_mode: str = Field(
@@ -123,8 +125,8 @@ class EnterpriseService:
         def update_app_access_mode(cls, app_id: str, access_mode: str):
             if not app_id:
                 raise ValueError("app_id must be provided.")
-            if access_mode not in ["public", "private", "private_all"]:
-                raise ValueError("access_mode must be either 'public', 'private', or 'private_all'")
+            if access_mode not in ALLOWED_ACCESS_MODES:
+                raise ValueError(f"access_mode must be one of: {', '.join(ALLOWED_ACCESS_MODES)}")
 
             data = {"appId": app_id, "accessMode": access_mode}
 

api/services/human_input_service.py

@@ -22,7 +22,7 @@ from libs.exception import BaseHTTPException
 from models.human_input import RecipientType
 from models.model import App, AppMode
 from repositories.factory import DifyAPIRepositoryFactory
-from tasks.app_generate.workflow_execute_task import WORKFLOW_BASED_APP_EXECUTION_QUEUE, resume_app_execution
+from tasks.app_generate.workflow_execute_task import resume_app_execution
 
 
 class Form:
@@ -230,7 +230,6 @@ class HumanInputService:
             try:
                 resume_app_execution.apply_async(
                     kwargs={"payload": payload},
-                    queue=WORKFLOW_BASED_APP_EXECUTION_QUEUE,
                 )
             except Exception:  # pragma: no cover
                 logger.exception("Failed to enqueue resume task for workflow run %s", workflow_run_id)

api/services/metadata_service.py

@@ -220,8 +220,8 @@ class MetadataService:
                     doc_metadata[BuiltInField.source] = MetadataDataSource[document.data_source_type]
                 document.doc_metadata = doc_metadata
                 db.session.add(document)
-                db.session.commit()
-                # deal metadata binding
+
+                # deal metadata binding (in the same transaction as the doc_metadata update)
                 if not operation.partial_update:
                     db.session.query(DatasetMetadataBinding).filter_by(document_id=operation.document_id).delete()
 
@@ -247,7 +247,9 @@ class MetadataService:
                     db.session.add(dataset_metadata_binding)
                 db.session.commit()
             except Exception:
+                db.session.rollback()
                 logger.exception("Update documents metadata failed")
+                raise
             finally:
                 redis_client.delete(lock_key)
 

api/services/retention/conversation/messages_clean_service.py

@@ -1,10 +1,13 @@
 import datetime
 import logging
+import os
 import random
+import time
 from collections.abc import Sequence
 from typing import cast
 
-from sqlalchemy import delete, select
+import sqlalchemy as sa
+from sqlalchemy import delete, select, tuple_
 from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
@@ -193,11 +196,15 @@ class MessagesCleanService:
             self._end_before,
         )
 
+        max_batch_interval_ms = int(os.environ.get("SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL", 200))
+
         while True:
             stats["batches"] += 1
+            batch_start = time.monotonic()
 
             # Step 1: Fetch a batch of messages using cursor
             with Session(db.engine, expire_on_commit=False) as session:
+                fetch_messages_start = time.monotonic()
                 msg_stmt = (
                     select(Message.id, Message.app_id, Message.created_at)
                     .where(Message.created_at < self._end_before)
@@ -209,13 +216,13 @@ class MessagesCleanService:
                     msg_stmt = msg_stmt.where(Message.created_at >= self._start_from)
 
                 # Apply cursor condition: (created_at, id) > (last_created_at, last_message_id)
-                # This translates to:
-                #   created_at > last_created_at OR (created_at = last_created_at AND id > last_message_id)
                 if _cursor:
-                    # Continuing from previous batch
                     msg_stmt = msg_stmt.where(
-                        (Message.created_at > _cursor[0])
-                        | ((Message.created_at == _cursor[0]) & (Message.id > _cursor[1]))
+                        tuple_(Message.created_at, Message.id)
+                        > tuple_(
+                            sa.literal(_cursor[0], type_=sa.DateTime()),
+                            sa.literal(_cursor[1], type_=Message.id.type),
+                        )
                     )
 
                 raw_messages = list(session.execute(msg_stmt).all())
@@ -223,6 +230,12 @@ class MessagesCleanService:
                     SimpleMessage(id=msg_id, app_id=app_id, created_at=msg_created_at)
                     for msg_id, app_id, msg_created_at in raw_messages
                 ]
+                logger.info(
+                    "clean_messages (batch %s): fetched %s messages in %sms",
+                    stats["batches"],
+                    len(messages),
+                    int((time.monotonic() - fetch_messages_start) * 1000),
+                )
 
                 # Track total messages fetched across all batches
                 stats["total_messages"] += len(messages)
@@ -241,8 +254,16 @@ class MessagesCleanService:
                     logger.info("clean_messages (batch %s): no app_ids found, skip", stats["batches"])
                     continue
 
+                fetch_apps_start = time.monotonic()
                 app_stmt = select(App.id, App.tenant_id).where(App.id.in_(app_ids))
                 apps = list(session.execute(app_stmt).all())
+                logger.info(
+                    "clean_messages (batch %s): fetched %s apps for %s app_ids in %sms",
+                    stats["batches"],
+                    len(apps),
+                    len(app_ids),
+                    int((time.monotonic() - fetch_apps_start) * 1000),
+                )
 
             if not apps:
                 logger.info("clean_messages (batch %s): no apps found, skip", stats["batches"])
@@ -252,7 +273,15 @@ class MessagesCleanService:
             app_to_tenant: dict[str, str] = {app.id: app.tenant_id for app in apps}
 
             # Step 3: Delegate to policy to determine which messages to delete
+            policy_start = time.monotonic()
             message_ids_to_delete = self._policy.filter_message_ids(messages, app_to_tenant)
+            logger.info(
+                "clean_messages (batch %s): policy selected %s/%s messages in %sms",
+                stats["batches"],
+                len(message_ids_to_delete),
+                len(messages),
+                int((time.monotonic() - policy_start) * 1000),
+            )
 
             if not message_ids_to_delete:
                 logger.info("clean_messages (batch %s): no messages to delete, skip", stats["batches"])
@@ -263,14 +292,20 @@ class MessagesCleanService:
             # Step 4: Batch delete messages and their relations
             if not self._dry_run:
                 with Session(db.engine, expire_on_commit=False) as session:
+                    delete_relations_start = time.monotonic()
                     # Delete related records first
                     self._batch_delete_message_relations(session, message_ids_to_delete)
+                    delete_relations_ms = int((time.monotonic() - delete_relations_start) * 1000)
 
                     # Delete messages
+                    delete_messages_start = time.monotonic()
                     delete_stmt = delete(Message).where(Message.id.in_(message_ids_to_delete))
                     delete_result = cast(CursorResult, session.execute(delete_stmt))
                     messages_deleted = delete_result.rowcount
+                    delete_messages_ms = int((time.monotonic() - delete_messages_start) * 1000)
+                    commit_start = time.monotonic()
                     session.commit()
+                    commit_ms = int((time.monotonic() - commit_start) * 1000)
 
                     stats["total_deleted"] += messages_deleted
 
@@ -280,6 +315,19 @@ class MessagesCleanService:
                         len(messages),
                         messages_deleted,
                     )
+                    logger.info(
+                        "clean_messages (batch %s): relations %sms,  messages %sms, commit %sms, batch total %sms",
+                        stats["batches"],
+                        delete_relations_ms,
+                        delete_messages_ms,
+                        commit_ms,
+                        int((time.monotonic() - batch_start) * 1000),
+                    )
+
+                # Random sleep between batches to avoid overwhelming the database
+                sleep_ms = random.uniform(0, max_batch_interval_ms)  # noqa: S311
+                logger.info("clean_messages (batch %s): sleeping for %.2fms", stats["batches"], sleep_ms)
+                time.sleep(sleep_ms / 1000)
             else:
                 # Log random sample of message IDs that would be deleted (up to 10)
                 sample_size = min(10, len(message_ids_to_delete))

api/services/retention/workflow_run/clear_free_plan_expired_workflow_run_logs.py

@@ -1,5 +1,8 @@
 import datetime
 import logging
+import os
+import random
+import time
 from collections.abc import Iterable, Sequence
 
 import click
@@ -72,7 +75,12 @@ class WorkflowRunCleanup:
         batch_index = 0
         last_seen: tuple[datetime.datetime, str] | None = None
 
+        max_batch_interval_ms = int(os.environ.get("SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL", 200))
+
         while True:
+            batch_start = time.monotonic()
+
+            fetch_start = time.monotonic()
             run_rows = self.workflow_run_repo.get_runs_batch_by_time_range(
                 start_from=self.window_start,
                 end_before=self.window_end,
@@ -80,12 +88,30 @@ class WorkflowRunCleanup:
                 batch_size=self.batch_size,
             )
             if not run_rows:
+                logger.info("workflow_run_cleanup (batch #%s): no more rows to process", batch_index + 1)
                 break
 
             batch_index += 1
             last_seen = (run_rows[-1].created_at, run_rows[-1].id)
+            logger.info(
+                "workflow_run_cleanup (batch #%s): fetched %s rows in %sms",
+                batch_index,
+                len(run_rows),
+                int((time.monotonic() - fetch_start) * 1000),
+            )
+
             tenant_ids = {row.tenant_id for row in run_rows}
+
+            filter_start = time.monotonic()
             free_tenants = self._filter_free_tenants(tenant_ids)
+            logger.info(
+                "workflow_run_cleanup (batch #%s): filtered %s free tenants from %s tenants in %sms",
+                batch_index,
+                len(free_tenants),
+                len(tenant_ids),
+                int((time.monotonic() - filter_start) * 1000),
+            )
+
             free_runs = [row for row in run_rows if row.tenant_id in free_tenants]
             paid_or_skipped = len(run_rows) - len(free_runs)
 
@@ -104,11 +130,17 @@ class WorkflowRunCleanup:
             total_runs_targeted += len(free_runs)
 
             if self.dry_run:
+                count_start = time.monotonic()
                 batch_counts = self.workflow_run_repo.count_runs_with_related(
                     free_runs,
                     count_node_executions=self._count_node_executions,
                     count_trigger_logs=self._count_trigger_logs,
                 )
+                logger.info(
+                    "workflow_run_cleanup (batch #%s, dry_run): counted related records in %sms",
+                    batch_index,
+                    int((time.monotonic() - count_start) * 1000),
+                )
                 if related_totals is not None:
                     for key in related_totals:
                         related_totals[key] += batch_counts.get(key, 0)
@@ -120,14 +152,21 @@ class WorkflowRunCleanup:
                         fg="yellow",
                     )
                 )
+                logger.info(
+                    "workflow_run_cleanup (batch #%s, dry_run): batch total %sms",
+                    batch_index,
+                    int((time.monotonic() - batch_start) * 1000),
+                )
                 continue
 
             try:
+                delete_start = time.monotonic()
                 counts = self.workflow_run_repo.delete_runs_with_related(
                     free_runs,
                     delete_node_executions=self._delete_node_executions,
                     delete_trigger_logs=self._delete_trigger_logs,
                 )
+                delete_ms = int((time.monotonic() - delete_start) * 1000)
             except Exception:
                 logger.exception("Failed to delete workflow runs batch ending at %s", last_seen[0])
                 raise
@@ -143,6 +182,17 @@ class WorkflowRunCleanup:
                     fg="green",
                 )
             )
+            logger.info(
+                "workflow_run_cleanup (batch #%s): delete %sms, batch total %sms",
+                batch_index,
+                delete_ms,
+                int((time.monotonic() - batch_start) * 1000),
+            )
+
+            # Random sleep between batches to avoid overwhelming the database
+            sleep_ms = random.uniform(0, max_batch_interval_ms)  # noqa: S311
+            logger.info("workflow_run_cleanup (batch #%s): sleeping for %.2fms", batch_index, sleep_ms)
+            time.sleep(sleep_ms / 1000)
 
         if self.dry_run:
             if self.window_start:

api/services/workflow_event_snapshot_service.py

@@ -129,15 +129,15 @@ def build_workflow_event_stream(
                         return
 
                     try:
-                        event = buffer_state.queue.get(timeout=0.1)
+                        event = buffer_state.queue.get(timeout=1)
                     except queue.Empty:
                         current_time = time.time()
                         if current_time - last_msg_time > idle_timeout:
                             logger.debug(
-                                "No workflow events received for %s seconds, keeping stream open",
+                                "Idle timeout of %s seconds reached, closing workflow event stream.",
                                 idle_timeout,
                             )
-                            last_msg_time = current_time
+                            return
                         if current_time - last_ping_time >= ping_interval:
                             yield StreamEvent.PING.value
                             last_ping_time = current_time
@@ -405,7 +405,7 @@ def _start_buffering(subscription) -> BufferState:
         dropped_count = 0
         try:
             while not buffer_state.stop_event.is_set():
-                msg = subscription.receive(timeout=0.1)
+                msg = subscription.receive(timeout=1)
                 if msg is None:
                     continue
                 event = _parse_event_message(msg)

api/services/workspace_service.py

@@ -1,6 +1,7 @@
 from flask_login import current_user
 
 from configs import dify_config
+from enums.cloud_plan import CloudPlan
 from extensions.ext_database import db
 from models.account import Tenant, TenantAccountJoin, TenantAccountRole
 from services.account_service import TenantService
@@ -53,7 +54,12 @@ class WorkspaceService:
             from services.credit_pool_service import CreditPoolService
 
             paid_pool = CreditPoolService.get_pool(tenant_id=tenant.id, pool_type="paid")
-            if paid_pool:
+            # if the tenant is not on the sandbox plan and the paid pool is not full, use the paid pool
+            if (
+                feature.billing.subscription.plan != CloudPlan.SANDBOX
+                and paid_pool is not None
+                and (paid_pool.quota_limit == -1 or paid_pool.quota_limit > paid_pool.quota_used)
+            ):
                 tenant_info["trial_credits"] = paid_pool.quota_limit
                 tenant_info["trial_credits_used"] = paid_pool.quota_used
             else:

api/tests/integration_tests/vdb/oceanbase/bench_oceanbase.py

@@ -0,0 +1,241 @@
+"""
+Benchmark: OceanBase vector store — old (single-row) vs new (batch) insertion,
+metadata query with/without functional index, and vector search across metrics.
+
+Usage:
+    uv run --project api python -m tests.integration_tests.vdb.oceanbase.bench_oceanbase
+"""
+
+import json
+import random
+import statistics
+import time
+import uuid
+
+from pyobvector import VECTOR, ObVecClient, cosine_distance, inner_product, l2_distance
+from sqlalchemy import JSON, Column, String, text
+from sqlalchemy.dialects.mysql import LONGTEXT
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+HOST = "127.0.0.1"
+PORT = 2881
+USER = "root@test"
+PASSWORD = "difyai123456"
+DATABASE = "test"
+
+VEC_DIM = 1536
+HNSW_BUILD = {"M": 16, "efConstruction": 256}
+DISTANCE_FUNCS = {"l2": l2_distance, "cosine": cosine_distance, "inner_product": inner_product}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _make_client(**extra):
+    return ObVecClient(
+        uri=f"{HOST}:{PORT}",
+        user=USER,
+        password=PASSWORD,
+        db_name=DATABASE,
+        **extra,
+    )
+
+
+def _rand_vec():
+    return [random.uniform(-1, 1) for _ in range(VEC_DIM)]  # noqa: S311
+
+
+def _drop(client, table):
+    client.drop_table_if_exist(table)
+
+
+def _create_table(client, table, metric="l2"):
+    cols = [
+        Column("id", String(36), primary_key=True, autoincrement=False),
+        Column("vector", VECTOR(VEC_DIM)),
+        Column("text", LONGTEXT),
+        Column("metadata", JSON),
+    ]
+    vidx = client.prepare_index_params()
+    vidx.add_index(
+        field_name="vector",
+        index_type="HNSW",
+        index_name="vector_index",
+        metric_type=metric,
+        params=HNSW_BUILD,
+    )
+    client.create_table_with_index_params(table_name=table, columns=cols, vidxs=vidx)
+    client.refresh_metadata([table])
+
+
+def _gen_rows(n):
+    doc_id = str(uuid.uuid4())
+    rows = []
+    for _ in range(n):
+        rows.append(
+            {
+                "id": str(uuid.uuid4()),
+                "vector": _rand_vec(),
+                "text": f"benchmark text {uuid.uuid4().hex[:12]}",
+                "metadata": json.dumps({"document_id": doc_id, "dataset_id": str(uuid.uuid4())}),
+            }
+        )
+    return rows, doc_id
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Insertion
+# ---------------------------------------------------------------------------
+def bench_insert_single(client, table, rows):
+    """Old approach: one INSERT per row."""
+    t0 = time.perf_counter()
+    for row in rows:
+        client.insert(table_name=table, data=row)
+    return time.perf_counter() - t0
+
+
+def bench_insert_batch(client, table, rows, batch_size=100):
+    """New approach: batch INSERT."""
+    t0 = time.perf_counter()
+    for start in range(0, len(rows), batch_size):
+        batch = rows[start : start + batch_size]
+        client.insert(table_name=table, data=batch)
+    return time.perf_counter() - t0
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Metadata query
+# ---------------------------------------------------------------------------
+def bench_metadata_query(client, table, doc_id, with_index=False):
+    """Query by metadata->>'$.document_id' with/without functional index."""
+    if with_index:
+        try:
+            client.perform_raw_text_sql(f"CREATE INDEX idx_metadata_doc_id ON `{table}` ((metadata->>'$.document_id'))")
+        except Exception:
+            pass  # already exists
+
+    sql = text(f"SELECT id FROM `{table}` WHERE metadata->>'$.document_id' = :val")
+    times = []
+    with client.engine.connect() as conn:
+        for _ in range(10):
+            t0 = time.perf_counter()
+            result = conn.execute(sql, {"val": doc_id})
+            _ = result.fetchall()
+            times.append(time.perf_counter() - t0)
+    return times
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Vector search
+# ---------------------------------------------------------------------------
+def bench_vector_search(client, table, metric, topk=10, n_queries=20):
+    dist_func = DISTANCE_FUNCS[metric]
+    times = []
+    for _ in range(n_queries):
+        q = _rand_vec()
+        t0 = time.perf_counter()
+        cur = client.ann_search(
+            table_name=table,
+            vec_column_name="vector",
+            vec_data=q,
+            topk=topk,
+            distance_func=dist_func,
+            output_column_names=["text", "metadata"],
+            with_dist=True,
+        )
+        _ = list(cur)
+        times.append(time.perf_counter() - t0)
+    return times
+
+
+def _fmt(times):
+    """Format list of durations as 'mean ± stdev'."""
+    m = statistics.mean(times) * 1000
+    s = statistics.stdev(times) * 1000 if len(times) > 1 else 0
+    return f"{m:.1f} ± {s:.1f} ms"
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def main():
+    client = _make_client()
+    client_pooled = _make_client(pool_size=5, max_overflow=10, pool_recycle=3600, pool_pre_ping=True)
+
+    print("=" * 70)
+    print("OceanBase Vector Store — Performance Benchmark")
+    print(f"  Endpoint : {HOST}:{PORT}")
+    print(f"  Vec dim  : {VEC_DIM}")
+    print("=" * 70)
+
+    # ------------------------------------------------------------------
+    # 1. Insertion benchmark
+    # ------------------------------------------------------------------
+    for n_docs in [100, 500, 1000]:
+        rows, doc_id = _gen_rows(n_docs)
+        tbl_single = f"bench_single_{n_docs}"
+        tbl_batch = f"bench_batch_{n_docs}"
+
+        _drop(client, tbl_single)
+        _drop(client, tbl_batch)
+        _create_table(client, tbl_single)
+        _create_table(client, tbl_batch)
+
+        t_single = bench_insert_single(client, tbl_single, rows)
+        t_batch = bench_insert_batch(client_pooled, tbl_batch, rows, batch_size=100)
+
+        speedup = t_single / t_batch if t_batch > 0 else float("inf")
+        print(f"\n[Insert {n_docs} docs]")
+        print(f"  Single-row : {t_single:.2f}s")
+        print(f"  Batch(100) : {t_batch:.2f}s")
+        print(f"  Speedup    : {speedup:.1f}x")
+
+    # ------------------------------------------------------------------
+    # 2. Metadata query benchmark (use the 1000-doc batch table)
+    # ------------------------------------------------------------------
+    tbl_meta = "bench_batch_1000"
+    rows_1000, doc_id_1000 = _gen_rows(1000)
+    # The table already has 1000 rows from step 1; use that doc_id
+    # Re-query doc_id from one of the rows we inserted
+    with client.engine.connect() as conn:
+        res = conn.execute(text(f"SELECT metadata->>'$.document_id' FROM `{tbl_meta}` LIMIT 1"))
+        doc_id_1000 = res.fetchone()[0]
+
+    print("\n[Metadata filter query — 1000 rows, by document_id]")
+    times_no_idx = bench_metadata_query(client, tbl_meta, doc_id_1000, with_index=False)
+    print(f"  Without index : {_fmt(times_no_idx)}")
+    times_with_idx = bench_metadata_query(client, tbl_meta, doc_id_1000, with_index=True)
+    print(f"  With index    : {_fmt(times_with_idx)}")
+
+    # ------------------------------------------------------------------
+    # 3. Vector search benchmark — across metrics
+    # ------------------------------------------------------------------
+    print("\n[Vector search — top-10, 20 queries each, on 1000 rows]")
+
+    for metric in ["l2", "cosine", "inner_product"]:
+        tbl_vs = f"bench_vs_{metric}"
+        _drop(client_pooled, tbl_vs)
+        _create_table(client_pooled, tbl_vs, metric=metric)
+        # Insert 1000 rows
+        rows_vs, _ = _gen_rows(1000)
+        bench_insert_batch(client_pooled, tbl_vs, rows_vs, batch_size=100)
+        times = bench_vector_search(client_pooled, tbl_vs, metric, topk=10, n_queries=20)
+        print(f"  {metric:15s}: {_fmt(times)}")
+        _drop(client_pooled, tbl_vs)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+    for n in [100, 500, 1000]:
+        _drop(client, f"bench_single_{n}")
+        _drop(client, f"bench_batch_{n}")
+
+    print("\n" + "=" * 70)
+    print("Benchmark complete.")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

api/tests/integration_tests/vdb/oceanbase/test_oceanbase.py

@@ -21,6 +21,7 @@ def oceanbase_vector():
             database="test",
             password="difyai123456",
             enable_hybrid_search=True,
+            batch_size=10,
         ),
     )
 

api/tests/test_containers_integration_tests/libs/test_auto_renew_redis_lock_integration.py

@@ -0,0 +1,38 @@
+"""
+Integration tests for DbMigrationAutoRenewLock using real Redis via TestContainers.
+"""
+
+import time
+import uuid
+
+import pytest
+
+from extensions.ext_redis import redis_client
+from libs.db_migration_lock import DbMigrationAutoRenewLock
+
+
+@pytest.mark.usefixtures("flask_app_with_containers")
+def test_db_migration_lock_renews_ttl_and_releases():
+    lock_name = f"test:db_migration_auto_renew_lock:{uuid.uuid4().hex}"
+
+    # Keep base TTL very small, and renew frequently so the test is stable even on slower CI.
+    lock = DbMigrationAutoRenewLock(
+        redis_client=redis_client,
+        name=lock_name,
+        ttl_seconds=1.0,
+        renew_interval_seconds=0.2,
+        log_context="test_db_migration_lock",
+    )
+
+    acquired = lock.acquire(blocking=True, blocking_timeout=5)
+    assert acquired is True
+
+    # Wait beyond the base TTL; key should still exist due to renewal.
+    time.sleep(1.5)
+    ttl = redis_client.ttl(lock_name)
+    assert ttl > 0
+
+    lock.release_safely(status="successful")
+
+    # After release, the key should not exist.
+    assert redis_client.exists(lock_name) == 0

api/tests/test_containers_integration_tests/services/test_metadata_service.py

@@ -914,9 +914,6 @@ class TestMetadataService:
         metadata_args = MetadataArgs(type="string", name="test_metadata")
         metadata = MetadataService.create_metadata(dataset.id, metadata_args)
 
-        # Mock DocumentService.get_document to return None (document not found)
-        mock_external_service_dependencies["document_service"].get_document.return_value = None
-
         # Create metadata operation data
         from services.entities.knowledge_entities.knowledge_entities import (
             DocumentMetadataOperation,
@@ -926,16 +923,17 @@ class TestMetadataService:
 
         metadata_detail = MetadataDetail(id=metadata.id, name=metadata.name, value="test_value")
 
-        operation = DocumentMetadataOperation(document_id="non-existent-document-id", metadata_list=[metadata_detail])
+        # Use a valid UUID format that does not exist in the database
+        operation = DocumentMetadataOperation(
+            document_id="00000000-0000-0000-0000-000000000000", metadata_list=[metadata_detail]
+        )
 
         operation_data = MetadataOperationData(operation_data=[operation])
 
-        # Act: Execute the method under test
-        # The method should handle the error gracefully and continue
-        MetadataService.update_documents_metadata(dataset, operation_data)
-
-        # Assert: Verify the method completes without raising exceptions
-        # The main functionality (error handling) is verified
+        # Act & Assert: The method should raise ValueError("Document not found.")
+        # because the exception is now re-raised after rollback
+        with pytest.raises(ValueError, match="Document not found"):
+            MetadataService.update_documents_metadata(dataset, operation_data)
 
     def test_knowledge_base_metadata_lock_check_dataset_id(
         self, db_session_with_containers, mock_external_service_dependencies

api/tests/unit_tests/commands/test_upgrade_db.py

@@ -0,0 +1,146 @@
+import sys
+import threading
+import types
+from unittest.mock import MagicMock
+
+import commands
+from libs.db_migration_lock import LockNotOwnedError, RedisError
+
+HEARTBEAT_WAIT_TIMEOUT_SECONDS = 5.0
+
+
+def _install_fake_flask_migrate(monkeypatch, upgrade_impl) -> None:
+    module = types.ModuleType("flask_migrate")
+    module.upgrade = upgrade_impl
+    monkeypatch.setitem(sys.modules, "flask_migrate", module)
+
+
+def _invoke_upgrade_db() -> int:
+    try:
+        commands.upgrade_db.callback()
+    except SystemExit as e:
+        return int(e.code or 0)
+    return 0
+
+
+def test_upgrade_db_skips_when_lock_not_acquired(monkeypatch, capsys):
+    monkeypatch.setattr(commands, "DB_UPGRADE_LOCK_TTL_SECONDS", 1234)
+
+    lock = MagicMock()
+    lock.acquire.return_value = False
+    commands.redis_client.lock.return_value = lock
+
+    exit_code = _invoke_upgrade_db()
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert "Database migration skipped" in captured.out
+
+    commands.redis_client.lock.assert_called_once_with(name="db_upgrade_lock", timeout=1234, thread_local=False)
+    lock.acquire.assert_called_once_with(blocking=False)
+    lock.release.assert_not_called()
+
+
+def test_upgrade_db_failure_not_masked_by_lock_release(monkeypatch, capsys):
+    monkeypatch.setattr(commands, "DB_UPGRADE_LOCK_TTL_SECONDS", 321)
+
+    lock = MagicMock()
+    lock.acquire.return_value = True
+    lock.release.side_effect = LockNotOwnedError("simulated")
+    commands.redis_client.lock.return_value = lock
+
+    def _upgrade():
+        raise RuntimeError("boom")
+
+    _install_fake_flask_migrate(monkeypatch, _upgrade)
+
+    exit_code = _invoke_upgrade_db()
+    captured = capsys.readouterr()
+
+    assert exit_code == 1
+    assert "Database migration failed: boom" in captured.out
+
+    commands.redis_client.lock.assert_called_once_with(name="db_upgrade_lock", timeout=321, thread_local=False)
+    lock.acquire.assert_called_once_with(blocking=False)
+    lock.release.assert_called_once()
+
+
+def test_upgrade_db_success_ignores_lock_not_owned_on_release(monkeypatch, capsys):
+    monkeypatch.setattr(commands, "DB_UPGRADE_LOCK_TTL_SECONDS", 999)
+
+    lock = MagicMock()
+    lock.acquire.return_value = True
+    lock.release.side_effect = LockNotOwnedError("simulated")
+    commands.redis_client.lock.return_value = lock
+
+    _install_fake_flask_migrate(monkeypatch, lambda: None)
+
+    exit_code = _invoke_upgrade_db()
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert "Database migration successful!" in captured.out
+
+    commands.redis_client.lock.assert_called_once_with(name="db_upgrade_lock", timeout=999, thread_local=False)
+    lock.acquire.assert_called_once_with(blocking=False)
+    lock.release.assert_called_once()
+
+
+def test_upgrade_db_renews_lock_during_migration(monkeypatch, capsys):
+    """
+    Ensure the lock is renewed while migrations are running, so the base TTL can stay short.
+    """
+
+    # Use a small TTL so the heartbeat interval triggers quickly.
+    monkeypatch.setattr(commands, "DB_UPGRADE_LOCK_TTL_SECONDS", 0.3)
+
+    lock = MagicMock()
+    lock.acquire.return_value = True
+    commands.redis_client.lock.return_value = lock
+
+    renewed = threading.Event()
+
+    def _reacquire():
+        renewed.set()
+        return True
+
+    lock.reacquire.side_effect = _reacquire
+
+    def _upgrade():
+        assert renewed.wait(HEARTBEAT_WAIT_TIMEOUT_SECONDS)
+
+    _install_fake_flask_migrate(monkeypatch, _upgrade)
+
+    exit_code = _invoke_upgrade_db()
+    _ = capsys.readouterr()
+
+    assert exit_code == 0
+    assert lock.reacquire.call_count >= 1
+
+
+def test_upgrade_db_ignores_reacquire_errors(monkeypatch, capsys):
+    # Use a small TTL so heartbeat runs during the upgrade call.
+    monkeypatch.setattr(commands, "DB_UPGRADE_LOCK_TTL_SECONDS", 0.3)
+
+    lock = MagicMock()
+    lock.acquire.return_value = True
+    commands.redis_client.lock.return_value = lock
+
+    attempted = threading.Event()
+
+    def _reacquire():
+        attempted.set()
+        raise RedisError("simulated")
+
+    lock.reacquire.side_effect = _reacquire
+
+    def _upgrade():
+        assert attempted.wait(HEARTBEAT_WAIT_TIMEOUT_SECONDS)
+
+    _install_fake_flask_migrate(monkeypatch, _upgrade)
+
+    exit_code = _invoke_upgrade_db()
+    _ = capsys.readouterr()
+
+    assert exit_code == 0
+    assert lock.reacquire.call_count >= 1

api/tests/unit_tests/conftest.py

@@ -51,7 +51,7 @@ def _patch_redis_clients_on_loaded_modules():
             continue
         if hasattr(module, "redis_client"):
             module.redis_client = redis_mock
-        if hasattr(module, "pubsub_redis_client"):
+        if hasattr(module, "_pubsub_redis_client"):
             module.pubsub_redis_client = redis_mock
 
 
@@ -72,7 +72,7 @@ def _patch_redis_clients():
 
     with (
         patch.object(ext_redis, "redis_client", redis_mock),
-        patch.object(ext_redis, "pubsub_redis_client", redis_mock),
+        patch.object(ext_redis, "_pubsub_redis_client", redis_mock),
     ):
         _patch_redis_clients_on_loaded_modules()
         yield

api/tests/unit_tests/controllers/console/app/test_conversation_read_timestamp.py

@@ -0,0 +1,34 @@
+from datetime import datetime
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from controllers.console.app.conversation import _get_conversation
+
+
+def test_get_conversation_mark_read_keeps_updated_at_unchanged():
+    app_model = SimpleNamespace(id="app-id")
+    account = SimpleNamespace(id="account-id")
+    conversation = MagicMock()
+    conversation.id = "conversation-id"
+
+    with (
+        patch("controllers.console.app.conversation.current_account_with_tenant", return_value=(account, None)),
+        patch("controllers.console.app.conversation.naive_utc_now", return_value=datetime(2026, 2, 9, 0, 0, 0)),
+        patch("controllers.console.app.conversation.db.session") as mock_session,
+    ):
+        mock_session.query.return_value.where.return_value.first.return_value = conversation
+
+        _get_conversation(app_model, "conversation-id")
+
+        statement = mock_session.execute.call_args[0][0]
+        compiled = statement.compile()
+        sql_text = str(compiled).lower()
+        compact_sql_text = sql_text.replace(" ", "")
+        params = compiled.params
+
+        assert "updated_at=current_timestamp" not in compact_sql_text
+        assert "updated_at=conversations.updated_at" in compact_sql_text
+        assert "read_at=:read_at" in compact_sql_text
+        assert "read_account_id=:read_account_id" in compact_sql_text
+        assert params["read_at"] == datetime(2026, 2, 9, 0, 0, 0)
+        assert params["read_account_id"] == "account-id"

api/tests/unit_tests/controllers/console/test_fastopenapi_remote_files.py

@@ -1,92 +1,286 @@
-import builtins
+"""Tests for remote file upload API endpoints using Flask-RESTX."""
+
+import contextlib
 from datetime import datetime
 from types import SimpleNamespace
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 import httpx
 import pytest
-from flask import Flask
-from flask.views import MethodView
-
-from extensions import ext_fastopenapi
-
-if not hasattr(builtins, "MethodView"):
-    builtins.MethodView = MethodView  # type: ignore[attr-defined]
+from flask import Flask, g
 
 
 @pytest.fixture
 def app() -> Flask:
+    """Create Flask app for testing."""
     app = Flask(__name__)
     app.config["TESTING"] = True
+    app.config["SECRET_KEY"] = "test-secret-key"
     return app
 
 
-def test_console_remote_files_fastopenapi_get_info(app: Flask):
-    ext_fastopenapi.init_app(app)
+@pytest.fixture
+def client(app):
+    """Create test client with console blueprint registered."""
+    from controllers.console import bp
 
-    response = httpx.Response(
-        200,
-        request=httpx.Request("HEAD", "http://example.com/file.txt"),
-        headers={"Content-Type": "text/plain", "Content-Length": "10"},
-    )
-
-    with patch("controllers.console.remote_files.ssrf_proxy.head", return_value=response):
-        client = app.test_client()
-        encoded_url = "http%3A%2F%2Fexample.com%2Ffile.txt"
-        resp = client.get(f"/console/api/remote-files/{encoded_url}")
-
-    assert resp.status_code == 200
-    assert resp.get_json() == {"file_type": "text/plain", "file_length": 10}
+    app.register_blueprint(bp)
+    return app.test_client()
 
 
-def test_console_remote_files_fastopenapi_upload(app: Flask):
-    ext_fastopenapi.init_app(app)
+@pytest.fixture
+def mock_account():
+    """Create a mock account for testing."""
+    from models import Account
 
-    head_response = httpx.Response(
-        200,
-        request=httpx.Request("GET", "http://example.com/file.txt"),
-        content=b"hello",
-    )
-    file_info = SimpleNamespace(
-        extension="txt",
-        size=5,
-        filename="file.txt",
-        mimetype="text/plain",
-    )
-    uploaded = SimpleNamespace(
-        id="file-id",
-        name="file.txt",
-        size=5,
-        extension="txt",
-        mime_type="text/plain",
-        created_by="user-id",
-        created_at=datetime(2024, 1, 1),
-    )
+    account = Mock(spec=Account)
+    account.id = "test-account-id"
+    account.current_tenant_id = "test-tenant-id"
+    return account
 
-    with (
-        patch("controllers.console.remote_files.db", new=SimpleNamespace(engine=object())),
-        patch("controllers.console.remote_files.ssrf_proxy.head", return_value=head_response),
-        patch("controllers.console.remote_files.helpers.guess_file_info_from_response", return_value=file_info),
-        patch("controllers.console.remote_files.FileService.is_file_size_within_limit", return_value=True),
-        patch("controllers.console.remote_files.FileService.__init__", return_value=None),
-        patch("controllers.console.remote_files.current_account_with_tenant", return_value=(object(), "tenant-id")),
-        patch("controllers.console.remote_files.FileService.upload_file", return_value=uploaded),
-        patch("controllers.console.remote_files.file_helpers.get_signed_file_url", return_value="signed-url"),
-    ):
-        client = app.test_client()
-        resp = client.post(
-            "/console/api/remote-files/upload",
-            json={"url": "http://example.com/file.txt"},
+
+@pytest.fixture
+def auth_ctx(app, mock_account):
+    """Context manager to set auth/tenant context in flask.g for a request."""
+
+    @contextlib.contextmanager
+    def _ctx():
+        with app.test_request_context():
+            g._login_user = mock_account
+            g._current_tenant = mock_account.current_tenant_id
+            yield
+
+    return _ctx
+
+
+class TestGetRemoteFileInfo:
+    """Test GET /console/api/remote-files/<path:url> endpoint."""
+
+    def test_get_remote_file_info_success(self, app, client, mock_account):
+        """Test successful retrieval of remote file info."""
+        response = httpx.Response(
+            200,
+            request=httpx.Request("HEAD", "http://example.com/file.txt"),
+            headers={"Content-Type": "text/plain", "Content-Length": "1024"},
         )
 
-    assert resp.status_code == 201
-    assert resp.get_json() == {
-        "id": "file-id",
-        "name": "file.txt",
-        "size": 5,
-        "extension": "txt",
-        "url": "signed-url",
-        "mime_type": "text/plain",
-        "created_by": "user-id",
-        "created_at": int(uploaded.created_at.timestamp()),
-    }
+        with (
+            patch(
+                "controllers.console.remote_files.current_account_with_tenant",
+                return_value=(mock_account, "test-tenant-id"),
+            ),
+            patch("controllers.console.remote_files.ssrf_proxy.head", return_value=response),
+            patch("libs.login.check_csrf_token", return_value=None),
+        ):
+            with app.test_request_context():
+                g._login_user = mock_account
+                g._current_tenant = mock_account.current_tenant_id
+                encoded_url = "http%3A%2F%2Fexample.com%2Ffile.txt"
+                resp = client.get(f"/console/api/remote-files/{encoded_url}")
+
+        assert resp.status_code == 200
+        data = resp.get_json()
+        assert data["file_type"] == "text/plain"
+        assert data["file_length"] == 1024
+
+    def test_get_remote_file_info_fallback_to_get_on_head_failure(self, app, client, mock_account):
+        """Test fallback to GET when HEAD returns non-200 status."""
+        head_response = httpx.Response(
+            404,
+            request=httpx.Request("HEAD", "http://example.com/file.pdf"),
+        )
+        get_response = httpx.Response(
+            200,
+            request=httpx.Request("GET", "http://example.com/file.pdf"),
+            headers={"Content-Type": "application/pdf", "Content-Length": "2048"},
+        )
+
+        with (
+            patch(
+                "controllers.console.remote_files.current_account_with_tenant",
+                return_value=(mock_account, "test-tenant-id"),
+            ),
+            patch("controllers.console.remote_files.ssrf_proxy.head", return_value=head_response),
+            patch("controllers.console.remote_files.ssrf_proxy.get", return_value=get_response),
+            patch("libs.login.check_csrf_token", return_value=None),
+        ):
+            with app.test_request_context():
+                g._login_user = mock_account
+                g._current_tenant = mock_account.current_tenant_id
+                encoded_url = "http%3A%2F%2Fexample.com%2Ffile.pdf"
+                resp = client.get(f"/console/api/remote-files/{encoded_url}")
+
+        assert resp.status_code == 200
+        data = resp.get_json()
+        assert data["file_type"] == "application/pdf"
+        assert data["file_length"] == 2048
+
+
+class TestRemoteFileUpload:
+    """Test POST /console/api/remote-files/upload endpoint."""
+
+    @pytest.mark.parametrize(
+        ("head_status", "use_get"),
+        [
+            (200, False),  # HEAD succeeds
+            (405, True),  # HEAD fails -> fallback GET
+        ],
+    )
+    def test_upload_remote_file_success_paths(self, client, mock_account, auth_ctx, head_status, use_get):
+        url = "http://example.com/file.pdf"
+        head_resp = httpx.Response(
+            head_status,
+            request=httpx.Request("HEAD", url),
+            headers={"Content-Type": "application/pdf", "Content-Length": "1024"},
+        )
+        get_resp = httpx.Response(
+            200,
+            request=httpx.Request("GET", url),
+            headers={"Content-Type": "application/pdf", "Content-Length": "1024"},
+            content=b"file content",
+        )
+
+        file_info = SimpleNamespace(
+            extension="pdf",
+            size=1024,
+            filename="file.pdf",
+            mimetype="application/pdf",
+        )
+        uploaded_file = SimpleNamespace(
+            id="uploaded-file-id",
+            name="file.pdf",
+            size=1024,
+            extension="pdf",
+            mime_type="application/pdf",
+            created_by="test-account-id",
+            created_at=datetime(2024, 1, 1, 12, 0, 0),
+        )
+
+        with (
+            patch(
+                "controllers.console.remote_files.current_account_with_tenant",
+                return_value=(mock_account, "test-tenant-id"),
+            ),
+            patch("controllers.console.remote_files.ssrf_proxy.head", return_value=head_resp) as p_head,
+            patch("controllers.console.remote_files.ssrf_proxy.get", return_value=get_resp) as p_get,
+            patch(
+                "controllers.console.remote_files.helpers.guess_file_info_from_response",
+                return_value=file_info,
+            ),
+            patch(
+                "controllers.console.remote_files.FileService.is_file_size_within_limit",
+                return_value=True,
+            ),
+            patch("controllers.console.remote_files.db", spec=["engine"]),
+            patch("controllers.console.remote_files.FileService") as mock_file_service,
+            patch(
+                "controllers.console.remote_files.file_helpers.get_signed_file_url",
+                return_value="http://example.com/signed-url",
+            ),
+            patch("libs.login.check_csrf_token", return_value=None),
+        ):
+            mock_file_service.return_value.upload_file.return_value = uploaded_file
+
+            with auth_ctx():
+                resp = client.post(
+                    "/console/api/remote-files/upload",
+                    json={"url": url},
+                )
+
+        assert resp.status_code == 201
+        p_head.assert_called_once()
+        # GET is used either for fallback (HEAD fails) or to fetch content after HEAD succeeds
+        p_get.assert_called_once()
+        mock_file_service.return_value.upload_file.assert_called_once()
+
+        data = resp.get_json()
+        assert data["id"] == "uploaded-file-id"
+        assert data["name"] == "file.pdf"
+        assert data["size"] == 1024
+        assert data["extension"] == "pdf"
+        assert data["url"] == "http://example.com/signed-url"
+        assert data["mime_type"] == "application/pdf"
+        assert data["created_by"] == "test-account-id"
+
+    @pytest.mark.parametrize(
+        ("size_ok", "raises", "expected_status", "expected_msg"),
+        [
+            # When size check fails in controller, API returns 413 with message "File size exceeded..."
+            (False, None, 413, "file size exceeded"),
+            # When service raises unsupported type, controller maps to 415 with message "File type not allowed."
+            (True, "unsupported", 415, "file type not allowed"),
+        ],
+    )
+    def test_upload_remote_file_errors(
+        self, client, mock_account, auth_ctx, size_ok, raises, expected_status, expected_msg
+    ):
+        url = "http://example.com/x.pdf"
+        head_resp = httpx.Response(
+            200,
+            request=httpx.Request("HEAD", url),
+            headers={"Content-Type": "application/pdf", "Content-Length": "9"},
+        )
+        file_info = SimpleNamespace(extension="pdf", size=9, filename="x.pdf", mimetype="application/pdf")
+
+        with (
+            patch(
+                "controllers.console.remote_files.current_account_with_tenant",
+                return_value=(mock_account, "test-tenant-id"),
+            ),
+            patch("controllers.console.remote_files.ssrf_proxy.head", return_value=head_resp),
+            patch(
+                "controllers.console.remote_files.helpers.guess_file_info_from_response",
+                return_value=file_info,
+            ),
+            patch(
+                "controllers.console.remote_files.FileService.is_file_size_within_limit",
+                return_value=size_ok,
+            ),
+            patch("controllers.console.remote_files.db", spec=["engine"]),
+            patch("libs.login.check_csrf_token", return_value=None),
+        ):
+            if raises == "unsupported":
+                from services.errors.file import UnsupportedFileTypeError
+
+                with patch("controllers.console.remote_files.FileService") as mock_file_service:
+                    mock_file_service.return_value.upload_file.side_effect = UnsupportedFileTypeError("bad")
+                    with auth_ctx():
+                        resp = client.post(
+                            "/console/api/remote-files/upload",
+                            json={"url": url},
+                        )
+            else:
+                with auth_ctx():
+                    resp = client.post(
+                        "/console/api/remote-files/upload",
+                        json={"url": url},
+                    )
+
+        assert resp.status_code == expected_status
+        data = resp.get_json()
+        msg = (data.get("error") or {}).get("message") or data.get("message", "")
+        assert expected_msg in msg.lower()
+
+    def test_upload_remote_file_fetch_failure(self, client, mock_account, auth_ctx):
+        """Test upload when fetching of remote file fails."""
+        with (
+            patch(
+                "controllers.console.remote_files.current_account_with_tenant",
+                return_value=(mock_account, "test-tenant-id"),
+            ),
+            patch(
+                "controllers.console.remote_files.ssrf_proxy.head",
+                side_effect=httpx.RequestError("Connection failed"),
+            ),
+            patch("libs.login.check_csrf_token", return_value=None),
+        ):
+            with auth_ctx():
+                resp = client.post(
+                    "/console/api/remote-files/upload",
+                    json={"url": "http://unreachable.com/file.pdf"},
+                )
+
+        assert resp.status_code == 400
+        data = resp.get_json()
+        msg = (data.get("error") or {}).get("message") or data.get("message", "")
+        assert "failed to fetch" in msg.lower()

api/tests/unit_tests/core/app/task_pipeline/test_message_cycle_manager_optimization.py

@@ -25,15 +25,19 @@ class TestMessageCycleManagerOptimization:
         task_state = Mock()
         return MessageCycleManager(application_generate_entity=mock_application_generate_entity, task_state=task_state)
 
-    def test_get_message_event_type_with_message_file(self, message_cycle_manager):
-        """Test get_message_event_type returns MESSAGE_FILE when message has files."""
+    def test_get_message_event_type_with_assistant_file(self, message_cycle_manager):
+        """Test get_message_event_type returns MESSAGE_FILE when message has assistant-generated files.
+
+        This ensures that AI-generated images (belongs_to='assistant') trigger the MESSAGE_FILE event,
+        allowing the frontend to properly display generated image files with url field.
+        """
         with patch("core.app.task_pipeline.message_cycle_manager.session_factory") as mock_session_factory:
             # Setup mock session and message file
             mock_session = Mock()
             mock_session_factory.create_session.return_value.__enter__.return_value = mock_session
 
             mock_message_file = Mock()
-            # Current implementation uses session.scalar(select(...))
+            mock_message_file.belongs_to = "assistant"
             mock_session.scalar.return_value = mock_message_file
 
             # Execute
@@ -44,6 +48,31 @@ class TestMessageCycleManagerOptimization:
             assert result == StreamEvent.MESSAGE_FILE
             mock_session.scalar.assert_called_once()
 
+    def test_get_message_event_type_with_user_file(self, message_cycle_manager):
+        """Test get_message_event_type returns MESSAGE when message only has user-uploaded files.
+
+        This is a regression test for the issue where user-uploaded images (belongs_to='user')
+        caused the LLM text response to be incorrectly tagged with MESSAGE_FILE event,
+        resulting in broken images in the chat UI. The query filters for belongs_to='assistant',
+        so when only user files exist, the database query returns None, resulting in MESSAGE event type.
+        """
+        with patch("core.app.task_pipeline.message_cycle_manager.session_factory") as mock_session_factory:
+            # Setup mock session and message file
+            mock_session = Mock()
+            mock_session_factory.create_session.return_value.__enter__.return_value = mock_session
+
+            # When querying for assistant files with only user files present, return None
+            # (simulates database query with belongs_to='assistant' filter returning no results)
+            mock_session.scalar.return_value = None
+
+            # Execute
+            with current_app.app_context():
+                result = message_cycle_manager.get_message_event_type("test-message-id")
+
+            # Assert
+            assert result == StreamEvent.MESSAGE
+            mock_session.scalar.assert_called_once()
+
     def test_get_message_event_type_without_message_file(self, message_cycle_manager):
         """Test get_message_event_type returns MESSAGE when message has no files."""
         with patch("core.app.task_pipeline.message_cycle_manager.session_factory") as mock_session_factory:
@@ -69,7 +98,7 @@ class TestMessageCycleManagerOptimization:
             mock_session_factory.create_session.return_value.__enter__.return_value = mock_session
 
             mock_message_file = Mock()
-            # Current implementation uses session.scalar(select(...))
+            mock_message_file.belongs_to = "assistant"
             mock_session.scalar.return_value = mock_message_file
 
             # Execute: compute event type once, then pass to message_to_stream_response

api/tests/unit_tests/core/schemas/test_resolver.py

@@ -496,6 +496,9 @@ class TestSchemaResolverClass:
         avg_time_no_cache = sum(results1) / len(results1)
 
         # Second run (with cache) - run multiple times
+        # Warm up cache first
+        resolve_dify_schema_refs(schema)
+
         results2 = []
         for _ in range(3):
             start = time.perf_counter()

api/tests/unit_tests/core/tools/test_base_tool.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import Any, cast
+
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.tools.__base.tool import Tool
+from core.tools.__base.tool_runtime import ToolRuntime
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolEntity, ToolIdentity, ToolInvokeMessage, ToolProviderType
+
+
+class DummyCastType:
+    def cast_value(self, value: Any) -> str:
+        return f"cast:{value}"
+
+
+@dataclass
+class DummyParameter:
+    name: str
+    type: DummyCastType
+    form: str = "llm"
+    required: bool = False
+    default: Any = None
+    options: list[Any] | None = None
+    llm_description: str | None = None
+
+
+class DummyTool(Tool):
+    def __init__(self, entity: ToolEntity, runtime: ToolRuntime):
+        super().__init__(entity=entity, runtime=runtime)
+        self.result: ToolInvokeMessage | list[ToolInvokeMessage] | Generator[ToolInvokeMessage, None, None] = (
+            self.create_text_message("default")
+        )
+        self.runtime_parameter_overrides: list[Any] | None = None
+        self.last_invocation: dict[str, Any] | None = None
+
+    def tool_provider_type(self) -> ToolProviderType:
+        return ToolProviderType.BUILT_IN
+
+    def _invoke(
+        self,
+        user_id: str,
+        tool_parameters: dict[str, Any],
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> ToolInvokeMessage | list[ToolInvokeMessage] | Generator[ToolInvokeMessage, None, None]:
+        self.last_invocation = {
+            "user_id": user_id,
+            "tool_parameters": tool_parameters,
+            "conversation_id": conversation_id,
+            "app_id": app_id,
+            "message_id": message_id,
+        }
+        return self.result
+
+    def get_runtime_parameters(
+        self,
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ):
+        if self.runtime_parameter_overrides is not None:
+            return self.runtime_parameter_overrides
+        return super().get_runtime_parameters(
+            conversation_id=conversation_id,
+            app_id=app_id,
+            message_id=message_id,
+        )
+
+
+def _build_tool(runtime: ToolRuntime | None = None) -> DummyTool:
+    entity = ToolEntity(
+        identity=ToolIdentity(author="test", name="dummy", label=I18nObject(en_US="dummy"), provider="test"),
+        parameters=[],
+        description=None,
+        has_runtime_parameters=False,
+    )
+    runtime = runtime or ToolRuntime(tenant_id="tenant-1", invoke_from=InvokeFrom.DEBUGGER, runtime_parameters={})
+    return DummyTool(entity=entity, runtime=runtime)
+
+
+def test_invoke_supports_single_message_and_parameter_casting():
+    runtime = ToolRuntime(
+        tenant_id="tenant-1",
+        invoke_from=InvokeFrom.DEBUGGER,
+        runtime_parameters={"from_runtime": "runtime-value"},
+    )
+    tool = _build_tool(runtime)
+    tool.entity.parameters = cast(
+        Any,
+        [
+            DummyParameter(name="unused", type=DummyCastType()),
+            DummyParameter(name="age", type=DummyCastType()),
+        ],
+    )
+    tool.result = tool.create_text_message("ok")
+
+    messages = list(
+        tool.invoke(
+            user_id="user-1",
+            tool_parameters={"age": "18", "raw": "keep"},
+            conversation_id="conv-1",
+            app_id="app-1",
+            message_id="msg-1",
+        )
+    )
+
+    assert len(messages) == 1
+    assert messages[0].message.text == "ok"
+    assert tool.last_invocation == {
+        "user_id": "user-1",
+        "tool_parameters": {"age": "cast:18", "raw": "keep", "from_runtime": "runtime-value"},
+        "conversation_id": "conv-1",
+        "app_id": "app-1",
+        "message_id": "msg-1",
+    }
+
+
+def test_invoke_supports_list_and_generator_results():
+    tool = _build_tool()
+    tool.result = [tool.create_text_message("a"), tool.create_text_message("b")]
+    list_messages = list(tool.invoke(user_id="user-1", tool_parameters={}))
+    assert [msg.message.text for msg in list_messages] == ["a", "b"]
+
+    def _message_generator() -> Generator[ToolInvokeMessage, None, None]:
+        yield tool.create_text_message("g1")
+        yield tool.create_text_message("g2")
+
+    tool.result = _message_generator()
+    generated_messages = list(tool.invoke(user_id="user-2", tool_parameters={}))
+    assert [msg.message.text for msg in generated_messages] == ["g1", "g2"]
+
+
+def test_fork_tool_runtime_returns_new_tool_with_copied_entity():
+    tool = _build_tool()
+    new_runtime = ToolRuntime(tenant_id="tenant-2", invoke_from=InvokeFrom.EXPLORE, runtime_parameters={})
+
+    forked = tool.fork_tool_runtime(new_runtime)
+
+    assert isinstance(forked, DummyTool)
+    assert forked is not tool
+    assert forked.runtime == new_runtime
+    assert forked.entity == tool.entity
+    assert forked.entity is not tool.entity
+
+
+def test_get_runtime_parameters_and_merge_runtime_parameters():
+    tool = _build_tool()
+    original = DummyParameter(name="temperature", type=DummyCastType(), form="schema", required=True, default="0.7")
+    tool.entity.parameters = cast(Any, [original])
+
+    default_runtime_parameters = tool.get_runtime_parameters()
+    assert default_runtime_parameters == [original]
+
+    override = DummyParameter(name="temperature", type=DummyCastType(), form="llm", required=False, default="0.5")
+    appended = DummyParameter(name="new_param", type=DummyCastType(), form="form", required=False, default="x")
+    tool.runtime_parameter_overrides = [override, appended]
+
+    merged = tool.get_merged_runtime_parameters()
+    assert len(merged) == 2
+    assert merged[0].name == "temperature"
+    assert merged[0].form == "llm"
+    assert merged[0].required is False
+    assert merged[0].default == "0.5"
+    assert merged[1].name == "new_param"
+
+
+def test_message_factory_helpers():
+    tool = _build_tool()
+
+    image_message = tool.create_image_message("https://example.com/image.png")
+    assert image_message.type == ToolInvokeMessage.MessageType.IMAGE
+    assert image_message.message.text == "https://example.com/image.png"
+
+    file_obj = object()
+    file_message = tool.create_file_message(file_obj)  # type: ignore[arg-type]
+    assert file_message.type == ToolInvokeMessage.MessageType.FILE
+    assert file_message.message.file_marker == "file_marker"
+    assert file_message.meta == {"file": file_obj}
+
+    link_message = tool.create_link_message("https://example.com")
+    assert link_message.type == ToolInvokeMessage.MessageType.LINK
+    assert link_message.message.text == "https://example.com"
+
+    text_message = tool.create_text_message("hello")
+    assert text_message.type == ToolInvokeMessage.MessageType.TEXT
+    assert text_message.message.text == "hello"
+
+    blob_message = tool.create_blob_message(b"blob", meta={"source": "unit-test"})
+    assert blob_message.type == ToolInvokeMessage.MessageType.BLOB
+    assert blob_message.message.blob == b"blob"
+    assert blob_message.meta == {"source": "unit-test"}
+
+    json_message = tool.create_json_message({"k": "v"}, suppress_output=True)
+    assert json_message.type == ToolInvokeMessage.MessageType.JSON
+    assert json_message.message.json_object == {"k": "v"}
+    assert json_message.message.suppress_output is True
+
+    variable_message = tool.create_variable_message("answer", 42, stream=False)
+    assert variable_message.type == ToolInvokeMessage.MessageType.VARIABLE
+    assert variable_message.message.variable_name == "answer"
+    assert variable_message.message.variable_value == 42
+    assert variable_message.message.stream is False
+
+
+def test_base_abstract_invoke_placeholder_returns_none():
+    tool = _build_tool()
+    assert Tool._invoke(tool, user_id="u", tool_parameters={}) is None

api/tests/unit_tests/core/tools/workflow_as_tool/test_tool.py

@@ -255,6 +255,32 @@ def test_create_variable_message():
         assert message.message.stream is False
 
 
+def test_create_file_message_should_include_file_marker():
+    entity = ToolEntity(
+        identity=ToolIdentity(author="test", name="test tool", label=I18nObject(en_US="test tool"), provider="test"),
+        parameters=[],
+        description=None,
+        has_runtime_parameters=False,
+    )
+    runtime = ToolRuntime(tenant_id="test_tool", invoke_from=InvokeFrom.EXPLORE)
+    tool = WorkflowTool(
+        workflow_app_id="",
+        workflow_as_tool_id="",
+        version="1",
+        workflow_entities={},
+        workflow_call_depth=1,
+        entity=entity,
+        runtime=runtime,
+    )
+
+    file_obj = object()
+    message = tool.create_file_message(file_obj)  # type: ignore[arg-type]
+
+    assert message.type == ToolInvokeMessage.MessageType.FILE
+    assert message.message.file_marker == "file_marker"
+    assert message.meta == {"file": file_obj}
+
+
 def test_resolve_user_from_database_falls_back_to_end_user(monkeypatch: pytest.MonkeyPatch):
     """Ensure worker context can resolve EndUser when Account is missing."""
 

api/tests/unit_tests/libs/broadcast_channel/redis/test_channel_unit_tests.py

@@ -198,6 +198,15 @@ class SubscriptionTestCase:
     description: str = ""
 
 
+class FakeRedisClient:
+    """Minimal fake Redis client for unit tests."""
+
+    def __init__(self) -> None:
+        self.publish = MagicMock()
+        self.spublish = MagicMock()
+        self.pubsub = MagicMock(return_value=MagicMock())
+
+
 class TestRedisSubscription:
     """Test cases for the _RedisSubscription class."""
 
@@ -619,10 +628,13 @@ class TestRedisSubscription:
 class TestRedisShardedSubscription:
     """Test cases for the _RedisShardedSubscription class."""
 
+    @pytest.fixture(autouse=True)
+    def patch_sharded_redis_type(self, monkeypatch):
+        monkeypatch.setattr("libs.broadcast_channel.redis.sharded_channel.Redis", FakeRedisClient)
+
     @pytest.fixture
-    def mock_redis_client(self) -> MagicMock:
-        client = MagicMock()
-        return client
+    def mock_redis_client(self) -> FakeRedisClient:
+        return FakeRedisClient()
 
     @pytest.fixture
     def mock_pubsub(self) -> MagicMock:
@@ -636,7 +648,7 @@ class TestRedisShardedSubscription:
 
     @pytest.fixture
     def sharded_subscription(
-        self, mock_pubsub: MagicMock, mock_redis_client: MagicMock
+        self, mock_pubsub: MagicMock, mock_redis_client: FakeRedisClient
     ) -> Generator[_RedisShardedSubscription, None, None]:
         """Create a _RedisShardedSubscription instance for testing."""
         subscription = _RedisShardedSubscription(
@@ -657,7 +669,7 @@ class TestRedisShardedSubscription:
 
     # ==================== Lifecycle Tests ====================
 
-    def test_sharded_subscription_initialization(self, mock_pubsub: MagicMock, mock_redis_client: MagicMock):
+    def test_sharded_subscription_initialization(self, mock_pubsub: MagicMock, mock_redis_client: FakeRedisClient):
         """Test that sharded subscription is properly initialized."""
         subscription = _RedisShardedSubscription(
             client=mock_redis_client,
@@ -970,7 +982,7 @@ class TestRedisShardedSubscription:
         ],
     )
     def test_sharded_subscription_scenarios(
-        self, test_case: SubscriptionTestCase, mock_pubsub: MagicMock, mock_redis_client: MagicMock
+        self, test_case: SubscriptionTestCase, mock_pubsub: MagicMock, mock_redis_client: FakeRedisClient
     ):
         """Test various sharded subscription scenarios using table-driven approach."""
         subscription = _RedisShardedSubscription(
@@ -1058,7 +1070,7 @@ class TestRedisShardedSubscription:
         # Close should still work
         sharded_subscription.close()  # Should not raise
 
-    def test_channel_name_variations(self, mock_pubsub: MagicMock, mock_redis_client: MagicMock):
+    def test_channel_name_variations(self, mock_pubsub: MagicMock, mock_redis_client: FakeRedisClient):
         """Test various sharded channel name formats."""
         channel_names = [
             "simple",
@@ -1120,10 +1132,13 @@ class TestRedisSubscriptionCommon:
         """Parameterized fixture providing subscription type and class."""
         return request.param
 
+    @pytest.fixture(autouse=True)
+    def patch_sharded_redis_type(self, monkeypatch):
+        monkeypatch.setattr("libs.broadcast_channel.redis.sharded_channel.Redis", FakeRedisClient)
+
     @pytest.fixture
-    def mock_redis_client(self) -> MagicMock:
-        client = MagicMock()
-        return client
+    def mock_redis_client(self) -> FakeRedisClient:
+        return FakeRedisClient()
 
     @pytest.fixture
     def mock_pubsub(self) -> MagicMock:
@@ -1140,7 +1155,7 @@ class TestRedisSubscriptionCommon:
         return pubsub
 
     @pytest.fixture
-    def subscription(self, subscription_params, mock_pubsub: MagicMock, mock_redis_client: MagicMock):
+    def subscription(self, subscription_params, mock_pubsub: MagicMock, mock_redis_client: FakeRedisClient):
         """Create a subscription instance based on parameterized type."""
         subscription_type, subscription_class = subscription_params
         topic_name = f"test-{subscription_type}-topic"

api/tests/unit_tests/services/test_account_service.py

@@ -698,6 +698,132 @@ class TestTenantService:
 
         self._assert_database_operations_called(mock_db_dependencies["db"])
 
+    # ==================== Member Removal Tests ====================
+
+    def test_remove_pending_member_deletes_orphaned_account(self):
+        """Test that removing a pending member with no other workspaces deletes the account."""
+        # Arrange
+        mock_tenant = MagicMock()
+        mock_tenant.id = "tenant-456"
+        mock_operator = TestAccountAssociatedDataFactory.create_account_mock(account_id="operator-123", role="owner")
+        mock_pending_member = TestAccountAssociatedDataFactory.create_account_mock(
+            account_id="pending-user-789", email="pending@example.com", status=AccountStatus.PENDING
+        )
+
+        mock_ta = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+            tenant_id="tenant-456", account_id="pending-user-789", role="normal"
+        )
+
+        with patch("services.account_service.db") as mock_db:
+            mock_operator_join = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+                tenant_id="tenant-456", account_id="operator-123", role="owner"
+            )
+
+            query_mock_permission = MagicMock()
+            query_mock_permission.filter_by.return_value.first.return_value = mock_operator_join
+
+            query_mock_ta = MagicMock()
+            query_mock_ta.filter_by.return_value.first.return_value = mock_ta
+
+            query_mock_count = MagicMock()
+            query_mock_count.filter_by.return_value.count.return_value = 0
+
+            mock_db.session.query.side_effect = [query_mock_permission, query_mock_ta, query_mock_count]
+
+            with patch("services.enterprise.account_deletion_sync.sync_workspace_member_removal") as mock_sync:
+                mock_sync.return_value = True
+
+                # Act
+                TenantService.remove_member_from_tenant(mock_tenant, mock_pending_member, mock_operator)
+
+                # Assert: enterprise sync still receives the correct member ID
+                mock_sync.assert_called_once_with(
+                    workspace_id="tenant-456",
+                    member_id="pending-user-789",
+                    source="workspace_member_removed",
+                )
+
+            # Assert: both join record and account should be deleted
+            mock_db.session.delete.assert_any_call(mock_ta)
+            mock_db.session.delete.assert_any_call(mock_pending_member)
+            assert mock_db.session.delete.call_count == 2
+
+    def test_remove_pending_member_keeps_account_with_other_workspaces(self):
+        """Test that removing a pending member who belongs to other workspaces preserves the account."""
+        # Arrange
+        mock_tenant = MagicMock()
+        mock_tenant.id = "tenant-456"
+        mock_operator = TestAccountAssociatedDataFactory.create_account_mock(account_id="operator-123", role="owner")
+        mock_pending_member = TestAccountAssociatedDataFactory.create_account_mock(
+            account_id="pending-user-789", email="pending@example.com", status=AccountStatus.PENDING
+        )
+
+        mock_ta = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+            tenant_id="tenant-456", account_id="pending-user-789", role="normal"
+        )
+
+        with patch("services.account_service.db") as mock_db:
+            mock_operator_join = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+                tenant_id="tenant-456", account_id="operator-123", role="owner"
+            )
+
+            query_mock_permission = MagicMock()
+            query_mock_permission.filter_by.return_value.first.return_value = mock_operator_join
+
+            query_mock_ta = MagicMock()
+            query_mock_ta.filter_by.return_value.first.return_value = mock_ta
+
+            # Remaining join count = 1 (still in another workspace)
+            query_mock_count = MagicMock()
+            query_mock_count.filter_by.return_value.count.return_value = 1
+
+            mock_db.session.query.side_effect = [query_mock_permission, query_mock_ta, query_mock_count]
+
+            with patch("services.enterprise.account_deletion_sync.sync_workspace_member_removal") as mock_sync:
+                mock_sync.return_value = True
+
+                # Act
+                TenantService.remove_member_from_tenant(mock_tenant, mock_pending_member, mock_operator)
+
+            # Assert: only the join record should be deleted, not the account
+            mock_db.session.delete.assert_called_once_with(mock_ta)
+
+    def test_remove_active_member_preserves_account(self):
+        """Test that removing an active member never deletes the account, even with no other workspaces."""
+        # Arrange
+        mock_tenant = MagicMock()
+        mock_tenant.id = "tenant-456"
+        mock_operator = TestAccountAssociatedDataFactory.create_account_mock(account_id="operator-123", role="owner")
+        mock_active_member = TestAccountAssociatedDataFactory.create_account_mock(
+            account_id="active-user-789", email="active@example.com", status=AccountStatus.ACTIVE
+        )
+
+        mock_ta = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+            tenant_id="tenant-456", account_id="active-user-789", role="normal"
+        )
+
+        with patch("services.account_service.db") as mock_db:
+            mock_operator_join = TestAccountAssociatedDataFactory.create_tenant_join_mock(
+                tenant_id="tenant-456", account_id="operator-123", role="owner"
+            )
+
+            query_mock_permission = MagicMock()
+            query_mock_permission.filter_by.return_value.first.return_value = mock_operator_join
+
+            query_mock_ta = MagicMock()
+            query_mock_ta.filter_by.return_value.first.return_value = mock_ta
+
+            mock_db.session.query.side_effect = [query_mock_permission, query_mock_ta]
+
+            with patch("services.enterprise.account_deletion_sync.sync_workspace_member_removal") as mock_sync:
+                mock_sync.return_value = True
+
+                # Act
+                TenantService.remove_member_from_tenant(mock_tenant, mock_active_member, mock_operator)
+
+            # Assert: only the join record should be deleted
+            mock_db.session.delete.assert_called_once_with(mock_ta)
+
     # ==================== Tenant Switching Tests ====================
 
     def test_switch_tenant_success(self):

api/tests/unit_tests/services/test_clear_free_plan_expired_workflow_run_logs.py

@@ -62,6 +62,9 @@ class FakeRepo:
         end_before: datetime.datetime,
         last_seen: tuple[datetime.datetime, str] | None,
         batch_size: int,
+        run_types=None,
+        tenant_ids=None,
+        workflow_ids=None,
     ) -> list[FakeRun]:
         if self.call_idx >= len(self.batches):
             return []

api/tests/unit_tests/services/test_human_input_service.py

@@ -17,7 +17,6 @@ from core.workflow.nodes.human_input.entities import (
 from core.workflow.nodes.human_input.enums import FormInputType, HumanInputFormKind, HumanInputFormStatus
 from models.human_input import RecipientType
 from services.human_input_service import Form, FormExpiredError, HumanInputService, InvalidFormDataError
-from tasks.app_generate.workflow_execute_task import WORKFLOW_BASED_APP_EXECUTION_QUEUE
 
 
 @pytest.fixture
@@ -88,7 +87,6 @@ def test_enqueue_resume_dispatches_task_for_workflow(mocker, mock_session_factor
 
     resume_task.apply_async.assert_called_once()
     call_kwargs = resume_task.apply_async.call_args.kwargs
-    assert call_kwargs["queue"] == WORKFLOW_BASED_APP_EXECUTION_QUEUE
     assert call_kwargs["kwargs"]["payload"]["workflow_run_id"] == "workflow-run-id"
 
 
@@ -130,7 +128,6 @@ def test_enqueue_resume_dispatches_task_for_advanced_chat(mocker, mock_session_f
 
     resume_task.apply_async.assert_called_once()
     call_kwargs = resume_task.apply_async.call_args.kwargs
-    assert call_kwargs["queue"] == WORKFLOW_BASED_APP_EXECUTION_QUEUE
     assert call_kwargs["kwargs"]["payload"]["workflow_run_id"] == "workflow-run-id"
 
 

api/tests/unit_tests/services/test_metadata_partial_update.py

@@ -1,6 +1,8 @@
 import unittest
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from models.dataset import Dataset, Document
 from services.entities.knowledge_entities.knowledge_entities import (
     DocumentMetadataOperation,
@@ -148,6 +150,38 @@ class TestMetadataPartialUpdate(unittest.TestCase):
         # If it were added, there would be 2 calls. If skipped, 1 call.
         assert mock_db.session.add.call_count == 1
 
+    @patch("services.metadata_service.db")
+    @patch("services.metadata_service.DocumentService")
+    @patch("services.metadata_service.current_account_with_tenant")
+    @patch("services.metadata_service.redis_client")
+    def test_rollback_called_on_commit_failure(self, mock_redis, mock_current_account, mock_document_service, mock_db):
+        """When db.session.commit() raises, rollback must be called and the exception must propagate."""
+        # Setup mocks
+        mock_redis.get.return_value = None
+        mock_document_service.get_document.return_value = self.document
+        mock_current_account.return_value = (MagicMock(id="user_id"), "tenant_id")
+        mock_db.session.query.return_value.filter_by.return_value.first.return_value = None
+
+        # Make commit raise an exception
+        mock_db.session.commit.side_effect = RuntimeError("database connection lost")
+
+        operation = DocumentMetadataOperation(
+            document_id="doc_id",
+            metadata_list=[MetadataDetail(id="meta_id", name="key", value="value")],
+            partial_update=True,
+        )
+        metadata_args = MetadataOperationData(operation_data=[operation])
+
+        # Act & Assert: the exception must propagate
+        with pytest.raises(RuntimeError, match="database connection lost"):
+            MetadataService.update_documents_metadata(self.dataset, metadata_args)
+
+        # Verify rollback was called
+        mock_db.session.rollback.assert_called_once()
+
+        # Verify the lock key was cleaned up despite the failure
+        mock_redis.delete.assert_called_with("document_metadata_lock_doc_id")
+
 
 if __name__ == "__main__":
     unittest.main()

api/uv.lock

@@ -1237,49 +1237,47 @@ wheels = [
 
 [[package]]
 name = "cryptography"
-version = "46.0.3"
+version = "46.0.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9f/33/c00162f49c0e2fe8064a62cb92b93e50c74a72bc370ab92f86112b33ff62/cryptography-46.0.3.tar.gz", hash = "sha256:a8b17438104fed022ce745b362294d9ce35b4c2e45c1d958ad4a4b019285f4a1", size = 749258, upload-time = "2025-10-15T23:18:31.74Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/60/04/ee2a9e8542e4fa2773b81771ff8349ff19cdd56b7258a0cc442639052edb/cryptography-46.0.5.tar.gz", hash = "sha256:abace499247268e3757271b2f1e244b36b06f8515cf27c4d49468fc9eb16e93d", size = 750064, upload-time = "2026-02-10T19:18:38.255Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1d/42/9c391dd801d6cf0d561b5890549d4b27bafcc53b39c31a817e69d87c625b/cryptography-46.0.3-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:109d4ddfadf17e8e7779c39f9b18111a09efb969a301a31e987416a0191ed93a", size = 7225004, upload-time = "2025-10-15T23:16:52.239Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/67/38769ca6b65f07461eb200e85fc1639b438bdc667be02cf7f2cd6a64601c/cryptography-46.0.3-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:09859af8466b69bc3c27bdf4f5d84a665e0f7ab5088412e9e2ec49758eca5cbc", size = 4296667, upload-time = "2025-10-15T23:16:54.369Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/49/498c86566a1d80e978b42f0d702795f69887005548c041636df6ae1ca64c/cryptography-46.0.3-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:01ca9ff2885f3acc98c29f1860552e37f6d7c7d013d7334ff2a9de43a449315d", size = 4450807, upload-time = "2025-10-15T23:16:56.414Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/0a/863a3604112174c8624a2ac3c038662d9e59970c7f926acdcfaed8d61142/cryptography-46.0.3-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:6eae65d4c3d33da080cff9c4ab1f711b15c1d9760809dad6ea763f3812d254cb", size = 4299615, upload-time = "2025-10-15T23:16:58.442Z" },
-    { url = "https://files.pythonhosted.org/packages/64/02/b73a533f6b64a69f3cd3872acb6ebc12aef924d8d103133bb3ea750dc703/cryptography-46.0.3-cp311-abi3-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e5bf0ed4490068a2e72ac03d786693adeb909981cc596425d09032d372bcc849", size = 4016800, upload-time = "2025-10-15T23:17:00.378Z" },
-    { url = "https://files.pythonhosted.org/packages/25/d5/16e41afbfa450cde85a3b7ec599bebefaef16b5c6ba4ec49a3532336ed72/cryptography-46.0.3-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:5ecfccd2329e37e9b7112a888e76d9feca2347f12f37918facbb893d7bb88ee8", size = 4984707, upload-time = "2025-10-15T23:17:01.98Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/56/e7e69b427c3878352c2fb9b450bd0e19ed552753491d39d7d0a2f5226d41/cryptography-46.0.3-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:a2c0cd47381a3229c403062f764160d57d4d175e022c1df84e168c6251a22eec", size = 4482541, upload-time = "2025-10-15T23:17:04.078Z" },
-    { url = "https://files.pythonhosted.org/packages/78/f6/50736d40d97e8483172f1bb6e698895b92a223dba513b0ca6f06b2365339/cryptography-46.0.3-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:549e234ff32571b1f4076ac269fcce7a808d3bf98b76c8dd560e42dbc66d7d91", size = 4299464, upload-time = "2025-10-15T23:17:05.483Z" },
-    { url = "https://files.pythonhosted.org/packages/00/de/d8e26b1a855f19d9994a19c702fa2e93b0456beccbcfe437eda00e0701f2/cryptography-46.0.3-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:c0a7bb1a68a5d3471880e264621346c48665b3bf1c3759d682fc0864c540bd9e", size = 4950838, upload-time = "2025-10-15T23:17:07.425Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/29/798fc4ec461a1c9e9f735f2fc58741b0daae30688f41b2497dcbc9ed1355/cryptography-46.0.3-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:10b01676fc208c3e6feeb25a8b83d81767e8059e1fe86e1dc62d10a3018fa926", size = 4481596, upload-time = "2025-10-15T23:17:09.343Z" },
-    { url = "https://files.pythonhosted.org/packages/15/8d/03cd48b20a573adfff7652b76271078e3045b9f49387920e7f1f631d125e/cryptography-46.0.3-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:0abf1ffd6e57c67e92af68330d05760b7b7efb243aab8377e583284dbab72c71", size = 4426782, upload-time = "2025-10-15T23:17:11.22Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/b1/ebacbfe53317d55cf33165bda24c86523497a6881f339f9aae5c2e13e57b/cryptography-46.0.3-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:a04bee9ab6a4da801eb9b51f1b708a1b5b5c9eb48c03f74198464c66f0d344ac", size = 4698381, upload-time = "2025-10-15T23:17:12.829Z" },
-    { url = "https://files.pythonhosted.org/packages/96/92/8a6a9525893325fc057a01f654d7efc2c64b9de90413adcf605a85744ff4/cryptography-46.0.3-cp311-abi3-win32.whl", hash = "sha256:f260d0d41e9b4da1ed1e0f1ce571f97fe370b152ab18778e9e8f67d6af432018", size = 3055988, upload-time = "2025-10-15T23:17:14.65Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/bf/80fbf45253ea585a1e492a6a17efcb93467701fa79e71550a430c5e60df0/cryptography-46.0.3-cp311-abi3-win_amd64.whl", hash = "sha256:a9a3008438615669153eb86b26b61e09993921ebdd75385ddd748702c5adfddb", size = 3514451, upload-time = "2025-10-15T23:17:16.142Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/af/9b302da4c87b0beb9db4e756386a7c6c5b8003cd0e742277888d352ae91d/cryptography-46.0.3-cp311-abi3-win_arm64.whl", hash = "sha256:5d7f93296ee28f68447397bf5198428c9aeeab45705a55d53a6343455dcb2c3c", size = 2928007, upload-time = "2025-10-15T23:17:18.04Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/23/45fe7f376a7df8daf6da3556603b36f53475a99ce4faacb6ba2cf3d82021/cryptography-46.0.3-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:cb3d760a6117f621261d662bccc8ef5bc32ca673e037c83fbe565324f5c46936", size = 7218248, upload-time = "2025-10-15T23:17:46.294Z" },
-    { url = "https://files.pythonhosted.org/packages/27/32/b68d27471372737054cbd34c84981f9edbc24fe67ca225d389799614e27f/cryptography-46.0.3-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:4b7387121ac7d15e550f5cb4a43aef2559ed759c35df7336c402bb8275ac9683", size = 4294089, upload-time = "2025-10-15T23:17:48.269Z" },
-    { url = "https://files.pythonhosted.org/packages/26/42/fa8389d4478368743e24e61eea78846a0006caffaf72ea24a15159215a14/cryptography-46.0.3-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:15ab9b093e8f09daab0f2159bb7e47532596075139dd74365da52ecc9cb46c5d", size = 4440029, upload-time = "2025-10-15T23:17:49.837Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/eb/f483db0ec5ac040824f269e93dd2bd8a21ecd1027e77ad7bdf6914f2fd80/cryptography-46.0.3-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:46acf53b40ea38f9c6c229599a4a13f0d46a6c3fa9ef19fc1a124d62e338dfa0", size = 4297222, upload-time = "2025-10-15T23:17:51.357Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/cf/da9502c4e1912cb1da3807ea3618a6829bee8207456fbbeebc361ec38ba3/cryptography-46.0.3-cp38-abi3-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:10ca84c4668d066a9878890047f03546f3ae0a6b8b39b697457b7757aaf18dbc", size = 4012280, upload-time = "2025-10-15T23:17:52.964Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/8f/9adb86b93330e0df8b3dcf03eae67c33ba89958fc2e03862ef1ac2b42465/cryptography-46.0.3-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:36e627112085bb3b81b19fed209c05ce2a52ee8b15d161b7c643a7d5a88491f3", size = 4978958, upload-time = "2025-10-15T23:17:54.965Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/a0/5fa77988289c34bdb9f913f5606ecc9ada1adb5ae870bd0d1054a7021cc4/cryptography-46.0.3-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:1000713389b75c449a6e979ffc7dcc8ac90b437048766cef052d4d30b8220971", size = 4473714, upload-time = "2025-10-15T23:17:56.754Z" },
-    { url = "https://files.pythonhosted.org/packages/14/e5/fc82d72a58d41c393697aa18c9abe5ae1214ff6f2a5c18ac470f92777895/cryptography-46.0.3-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:b02cf04496f6576afffef5ddd04a0cb7d49cf6be16a9059d793a30b035f6b6ac", size = 4296970, upload-time = "2025-10-15T23:17:58.588Z" },
-    { url = "https://files.pythonhosted.org/packages/78/06/5663ed35438d0b09056973994f1aec467492b33bd31da36e468b01ec1097/cryptography-46.0.3-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:71e842ec9bc7abf543b47cf86b9a743baa95f4677d22baa4c7d5c69e49e9bc04", size = 4940236, upload-time = "2025-10-15T23:18:00.897Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/59/873633f3f2dcd8a053b8dd1d38f783043b5fce589c0f6988bf55ef57e43e/cryptography-46.0.3-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:402b58fc32614f00980b66d6e56a5b4118e6cb362ae8f3fda141ba4689bd4506", size = 4472642, upload-time = "2025-10-15T23:18:02.749Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/39/8e71f3930e40f6877737d6f69248cf74d4e34b886a3967d32f919cc50d3b/cryptography-46.0.3-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:ef639cb3372f69ec44915fafcd6698b6cc78fbe0c2ea41be867f6ed612811963", size = 4423126, upload-time = "2025-10-15T23:18:04.85Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/c7/f65027c2810e14c3e7268353b1681932b87e5a48e65505d8cc17c99e36ae/cryptography-46.0.3-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:3b51b8ca4f1c6453d8829e1eb7299499ca7f313900dd4d89a24b8b87c0a780d4", size = 4686573, upload-time = "2025-10-15T23:18:06.908Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/6e/1c8331ddf91ca4730ab3086a0f1be19c65510a33b5a441cb334e7a2d2560/cryptography-46.0.3-cp38-abi3-win32.whl", hash = "sha256:6276eb85ef938dc035d59b87c8a7dc559a232f954962520137529d77b18ff1df", size = 3036695, upload-time = "2025-10-15T23:18:08.672Z" },
-    { url = "https://files.pythonhosted.org/packages/90/45/b0d691df20633eff80955a0fc7695ff9051ffce8b69741444bd9ed7bd0db/cryptography-46.0.3-cp38-abi3-win_amd64.whl", hash = "sha256:416260257577718c05135c55958b674000baef9a1c7d9e8f306ec60d71db850f", size = 3501720, upload-time = "2025-10-15T23:18:10.632Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/cb/2da4cc83f5edb9c3257d09e1e7ab7b23f049c7962cae8d842bbef0a9cec9/cryptography-46.0.3-cp38-abi3-win_arm64.whl", hash = "sha256:d89c3468de4cdc4f08a57e214384d0471911a3830fcdaf7a8cc587e42a866372", size = 2918740, upload-time = "2025-10-15T23:18:12.277Z" },
-    { url = "https://files.pythonhosted.org/packages/06/8a/e60e46adab4362a682cf142c7dcb5bf79b782ab2199b0dcb81f55970807f/cryptography-46.0.3-pp311-pypy311_pp73-macosx_10_9_x86_64.whl", hash = "sha256:7ce938a99998ed3c8aa7e7272dca1a610401ede816d36d0693907d863b10d9ea", size = 3698132, upload-time = "2025-10-15T23:18:17.056Z" },
-    { url = "https://files.pythonhosted.org/packages/da/38/f59940ec4ee91e93d3311f7532671a5cef5570eb04a144bf203b58552d11/cryptography-46.0.3-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:191bb60a7be5e6f54e30ba16fdfae78ad3a342a0599eb4193ba88e3f3d6e185b", size = 4243992, upload-time = "2025-10-15T23:18:18.695Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/0c/35b3d92ddebfdfda76bb485738306545817253d0a3ded0bfe80ef8e67aa5/cryptography-46.0.3-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:c70cc23f12726be8f8bc72e41d5065d77e4515efae3690326764ea1b07845cfb", size = 4409944, upload-time = "2025-10-15T23:18:20.597Z" },
-    { url = "https://files.pythonhosted.org/packages/99/55/181022996c4063fc0e7666a47049a1ca705abb9c8a13830f074edb347495/cryptography-46.0.3-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:9394673a9f4de09e28b5356e7fff97d778f8abad85c9d5ac4a4b7e25a0de7717", size = 4242957, upload-time = "2025-10-15T23:18:22.18Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/af/72cd6ef29f9c5f731251acadaeb821559fe25f10852f44a63374c9ca08c1/cryptography-46.0.3-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:94cd0549accc38d1494e1f8de71eca837d0509d0d44bf11d158524b0e12cebf9", size = 4409447, upload-time = "2025-10-15T23:18:24.209Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/c3/e90f4a4feae6410f914f8ebac129b9ae7a8c92eb60a638012dde42030a9d/cryptography-46.0.3-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:6b5063083824e5509fdba180721d55909ffacccc8adbec85268b48439423d78c", size = 3438528, upload-time = "2025-10-15T23:18:26.227Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/81/b0bb27f2ba931a65409c6b8a8b358a7f03c0e46eceacddff55f7c84b1f3b/cryptography-46.0.5-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:351695ada9ea9618b3500b490ad54c739860883df6c1f555e088eaf25b1bbaad", size = 7176289, upload-time = "2026-02-10T19:17:08.274Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/9e/6b4397a3e3d15123de3b1806ef342522393d50736c13b20ec4c9ea6693a6/cryptography-46.0.5-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c18ff11e86df2e28854939acde2d003f7984f721eba450b56a200ad90eeb0e6b", size = 4275637, upload-time = "2026-02-10T19:17:10.53Z" },
+    { url = "https://files.pythonhosted.org/packages/63/e7/471ab61099a3920b0c77852ea3f0ea611c9702f651600397ac567848b897/cryptography-46.0.5-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d7e3d356b8cd4ea5aff04f129d5f66ebdc7b6f8eae802b93739ed520c47c79b", size = 4424742, upload-time = "2026-02-10T19:17:12.388Z" },
+    { url = "https://files.pythonhosted.org/packages/37/53/a18500f270342d66bf7e4d9f091114e31e5ee9e7375a5aba2e85a91e0044/cryptography-46.0.5-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:50bfb6925eff619c9c023b967d5b77a54e04256c4281b0e21336a130cd7fc263", size = 4277528, upload-time = "2026-02-10T19:17:13.853Z" },
+    { url = "https://files.pythonhosted.org/packages/22/29/c2e812ebc38c57b40e7c583895e73c8c5adb4d1e4a0cc4c5a4fdab2b1acc/cryptography-46.0.5-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:803812e111e75d1aa73690d2facc295eaefd4439be1023fefc4995eaea2af90d", size = 4947993, upload-time = "2026-02-10T19:17:15.618Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/e7/237155ae19a9023de7e30ec64e5d99a9431a567407ac21170a046d22a5a3/cryptography-46.0.5-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ee190460e2fbe447175cda91b88b84ae8322a104fc27766ad09428754a618ed", size = 4456855, upload-time = "2026-02-10T19:17:17.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/87/fc628a7ad85b81206738abbd213b07702bcbdada1dd43f72236ef3cffbb5/cryptography-46.0.5-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:f145bba11b878005c496e93e257c1e88f154d278d2638e6450d17e0f31e558d2", size = 3984635, upload-time = "2026-02-10T19:17:18.792Z" },
+    { url = "https://files.pythonhosted.org/packages/84/29/65b55622bde135aedf4565dc509d99b560ee4095e56989e815f8fd2aa910/cryptography-46.0.5-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e9251e3be159d1020c4030bd2e5f84d6a43fe54b6c19c12f51cde9542a2817b2", size = 4277038, upload-time = "2026-02-10T19:17:20.256Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/36/45e76c68d7311432741faf1fbf7fac8a196a0a735ca21f504c75d37e2558/cryptography-46.0.5-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:47fb8a66058b80e509c47118ef8a75d14c455e81ac369050f20ba0d23e77fee0", size = 4912181, upload-time = "2026-02-10T19:17:21.825Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/1a/c1ba8fead184d6e3d5afcf03d569acac5ad063f3ac9fb7258af158f7e378/cryptography-46.0.5-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4c3341037c136030cb46e4b1e17b7418ea4cbd9dd207e4a6f3b2b24e0d4ac731", size = 4456482, upload-time = "2026-02-10T19:17:25.133Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/e5/3fb22e37f66827ced3b902cf895e6a6bc1d095b5b26be26bd13c441fdf19/cryptography-46.0.5-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:890bcb4abd5a2d3f852196437129eb3667d62630333aacc13dfd470fad3aaa82", size = 4405497, upload-time = "2026-02-10T19:17:26.66Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/df/9d58bb32b1121a8a2f27383fabae4d63080c7ca60b9b5c88be742be04ee7/cryptography-46.0.5-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80a8d7bfdf38f87ca30a5391c0c9ce4ed2926918e017c29ddf643d0ed2778ea1", size = 4667819, upload-time = "2026-02-10T19:17:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/ed/325d2a490c5e94038cdb0117da9397ece1f11201f425c4e9c57fe5b9f08b/cryptography-46.0.5-cp311-abi3-win32.whl", hash = "sha256:60ee7e19e95104d4c03871d7d7dfb3d22ef8a9b9c6778c94e1c8fcc8365afd48", size = 3028230, upload-time = "2026-02-10T19:17:30.518Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/5a/ac0f49e48063ab4255d9e3b79f5def51697fce1a95ea1370f03dc9db76f6/cryptography-46.0.5-cp311-abi3-win_amd64.whl", hash = "sha256:38946c54b16c885c72c4f59846be9743d699eee2b69b6988e0a00a01f46a61a4", size = 3480909, upload-time = "2026-02-10T19:17:32.083Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/fa/a66aa722105ad6a458bebd64086ca2b72cdd361fed31763d20390f6f1389/cryptography-46.0.5-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:4108d4c09fbbf2789d0c926eb4152ae1760d5a2d97612b92d508d96c861e4d31", size = 7170514, upload-time = "2026-02-10T19:17:56.267Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/04/c85bdeab78c8bc77b701bf0d9bdcf514c044e18a46dcff330df5448631b0/cryptography-46.0.5-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7d1f30a86d2757199cb2d56e48cce14deddf1f9c95f1ef1b64ee91ea43fe2e18", size = 4275349, upload-time = "2026-02-10T19:17:58.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/32/9b87132a2f91ee7f5223b091dc963055503e9b442c98fc0b8a5ca765fab0/cryptography-46.0.5-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:039917b0dc418bb9f6edce8a906572d69e74bd330b0b3fea4f79dab7f8ddd235", size = 4420667, upload-time = "2026-02-10T19:18:00.619Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/a6/a7cb7010bec4b7c5692ca6f024150371b295ee1c108bdc1c400e4c44562b/cryptography-46.0.5-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:ba2a27ff02f48193fc4daeadf8ad2590516fa3d0adeeb34336b96f7fa64c1e3a", size = 4276980, upload-time = "2026-02-10T19:18:02.379Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/7c/c4f45e0eeff9b91e3f12dbd0e165fcf2a38847288fcfd889deea99fb7b6d/cryptography-46.0.5-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:61aa400dce22cb001a98014f647dc21cda08f7915ceb95df0c9eaf84b4b6af76", size = 4939143, upload-time = "2026-02-10T19:18:03.964Z" },
+    { url = "https://files.pythonhosted.org/packages/37/19/e1b8f964a834eddb44fa1b9a9976f4e414cbb7aa62809b6760c8803d22d1/cryptography-46.0.5-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ce58ba46e1bc2aac4f7d9290223cead56743fa6ab94a5d53292ffaac6a91614", size = 4453674, upload-time = "2026-02-10T19:18:05.588Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ed/db15d3956f65264ca204625597c410d420e26530c4e2943e05a0d2f24d51/cryptography-46.0.5-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:420d0e909050490d04359e7fdb5ed7e667ca5c3c402b809ae2563d7e66a92229", size = 3978801, upload-time = "2026-02-10T19:18:07.167Z" },
+    { url = "https://files.pythonhosted.org/packages/41/e2/df40a31d82df0a70a0daf69791f91dbb70e47644c58581d654879b382d11/cryptography-46.0.5-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:582f5fcd2afa31622f317f80426a027f30dc792e9c80ffee87b993200ea115f1", size = 4276755, upload-time = "2026-02-10T19:18:09.813Z" },
+    { url = "https://files.pythonhosted.org/packages/33/45/726809d1176959f4a896b86907b98ff4391a8aa29c0aaaf9450a8a10630e/cryptography-46.0.5-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:bfd56bb4b37ed4f330b82402f6f435845a5f5648edf1ad497da51a8452d5d62d", size = 4901539, upload-time = "2026-02-10T19:18:11.263Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0f/a3076874e9c88ecb2ecc31382f6e7c21b428ede6f55aafa1aa272613e3cd/cryptography-46.0.5-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:a3d507bb6a513ca96ba84443226af944b0f7f47dcc9a399d110cd6146481d24c", size = 4452794, upload-time = "2026-02-10T19:18:12.914Z" },
+    { url = "https://files.pythonhosted.org/packages/02/ef/ffeb542d3683d24194a38f66ca17c0a4b8bf10631feef44a7ef64e631b1a/cryptography-46.0.5-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9f16fbdf4da055efb21c22d81b89f155f02ba420558db21288b3d0035bafd5f4", size = 4404160, upload-time = "2026-02-10T19:18:14.375Z" },
+    { url = "https://files.pythonhosted.org/packages/96/93/682d2b43c1d5f1406ed048f377c0fc9fc8f7b0447a478d5c65ab3d3a66eb/cryptography-46.0.5-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ced80795227d70549a411a4ab66e8ce307899fad2220ce5ab2f296e687eacde9", size = 4667123, upload-time = "2026-02-10T19:18:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/45/2d/9c5f2926cb5300a8eefc3f4f0b3f3df39db7f7ce40c8365444c49363cbda/cryptography-46.0.5-cp38-abi3-win32.whl", hash = "sha256:02f547fce831f5096c9a567fd41bc12ca8f11df260959ecc7c3202555cc47a72", size = 3010220, upload-time = "2026-02-10T19:18:17.361Z" },
+    { url = "https://files.pythonhosted.org/packages/48/ef/0c2f4a8e31018a986949d34a01115dd057bf536905dca38897bacd21fac3/cryptography-46.0.5-cp38-abi3-win_amd64.whl", hash = "sha256:556e106ee01aa13484ce9b0239bca667be5004efb0aabbed28d353df86445595", size = 3467050, upload-time = "2026-02-10T19:18:18.899Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/dd/2d9fdb07cebdf3d51179730afb7d5e576153c6744c3ff8fded23030c204e/cryptography-46.0.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:3b4995dc971c9fb83c25aa44cf45f02ba86f71ee600d81091c2f0cbae116b06c", size = 3476964, upload-time = "2026-02-10T19:18:20.687Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/6f/6cc6cc9955caa6eaf83660b0da2b077c7fe8ff9950a3c5e45d605038d439/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:bc84e875994c3b445871ea7181d424588171efec3e185dced958dad9e001950a", size = 4218321, upload-time = "2026-02-10T19:18:22.349Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/5d/c4da701939eeee699566a6c1367427ab91a8b7088cc2328c09dbee940415/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:2ae6971afd6246710480e3f15824ed3029a60fc16991db250034efd0b9fb4356", size = 4381786, upload-time = "2026-02-10T19:18:24.529Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/97/a538654732974a94ff96c1db621fa464f455c02d4bb7d2652f4edc21d600/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:d861ee9e76ace6cf36a6a89b959ec08e7bc2493ee39d07ffe5acb23ef46d27da", size = 4217990, upload-time = "2026-02-10T19:18:25.957Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/11/7e500d2dd3ba891197b9efd2da5454b74336d64a7cc419aa7327ab74e5f6/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:2b7a67c9cd56372f3249b39699f2ad479f6991e62ea15800973b956f4b73e257", size = 4381252, upload-time = "2026-02-10T19:18:27.496Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/58/6b3d24e6b9bc474a2dcdee65dfd1f008867015408a271562e4b690561a4d/cryptography-46.0.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:8456928655f856c6e1533ff59d5be76578a7157224dbd9ce6872f25055ab9ab7", size = 3407605, upload-time = "2026-02-10T19:18:29.233Z" },
 ]
 
 [[package]]
@@ -1368,7 +1366,7 @@ wheels = [
 
 [[package]]
 name = "dify-api"
-version = "1.12.1"
+version = "1.13.0"
 source = { virtual = "." }
 dependencies = [
     { name = "aliyun-log-python-sdk" },
@@ -1594,7 +1592,7 @@ requires-dist = [
     { name = "gevent", specifier = "~=25.9.1" },
     { name = "gmpy2", specifier = "~=2.2.1" },
     { name = "google-api-core", specifier = "==2.18.0" },
-    { name = "google-api-python-client", specifier = "==2.90.0" },
+    { name = "google-api-python-client", specifier = "==2.189.0" },
     { name = "google-auth", specifier = "==2.29.0" },
     { name = "google-auth-httplib2", specifier = "==0.2.0" },
     { name = "google-cloud-aiplatform", specifier = "==1.49.0" },
@@ -1637,7 +1635,7 @@ requires-dist = [
     { name = "pycryptodome", specifier = "==3.23.0" },
     { name = "pydantic", specifier = "~=2.11.4" },
     { name = "pydantic-extra-types", specifier = "~=2.10.3" },
-    { name = "pydantic-settings", specifier = "~=2.11.0" },
+    { name = "pydantic-settings", specifier = "~=2.12.0" },
     { name = "pyjwt", specifier = "~=2.10.1" },
     { name = "pypdfium2", specifier = "==5.2.0" },
     { name = "python-docx", specifier = "~=1.1.0" },
@@ -2306,7 +2304,7 @@ grpc = [
 
 [[package]]
 name = "google-api-python-client"
-version = "2.90.0"
+version = "2.189.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "google-api-core" },
@@ -2315,9 +2313,9 @@ dependencies = [
     { name = "httplib2" },
     { name = "uritemplate" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/35/8b/d990f947c261304a5c1599d45717d02c27d46af5f23e1fee5dc19c8fa79d/google-api-python-client-2.90.0.tar.gz", hash = "sha256:cbcb3ba8be37c6806676a49df16ac412077e5e5dc7fa967941eff977b31fba03", size = 10891311, upload-time = "2023-06-20T16:29:25.008Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/f8/0783aeca3410ee053d4dd1fccafd85197847b8f84dd038e036634605d083/google_api_python_client-2.189.0.tar.gz", hash = "sha256:45f2d8559b5c895dde6ad3fb33de025f5cb2c197fa5862f18df7f5295a172741", size = 13979470, upload-time = "2026-02-03T19:24:55.432Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/03/209b5c36a621ae644dc7d4743746cd3b38b18e133f8779ecaf6b95cc01ce/google_api_python_client-2.90.0-py2.py3-none-any.whl", hash = "sha256:4a41ffb7797d4f28e44635fb1e7076240b741c6493e7c3233c0e4421cec7c913", size = 11379891, upload-time = "2023-06-20T16:29:19.532Z" },
+    { url = "https://files.pythonhosted.org/packages/04/44/3677ff27998214f2fa7957359da48da378a0ffff1bd0bdaba42e752bc13e/google_api_python_client-2.189.0-py3-none-any.whl", hash = "sha256:a258c09660a49c6159173f8bbece171278e917e104a11f0640b34751b79c8a1a", size = 14547633, upload-time = "2026-02-03T19:24:52.845Z" },
 ]
 
 [[package]]
@@ -4475,39 +4473,39 @@ wheels = [
 
 [[package]]
 name = "pillow"
-version = "12.0.0"
+version = "12.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/5a/b0/cace85a1b0c9775a9f8f5d5423c8261c858760e2466c79b2dd184638b056/pillow-12.0.0.tar.gz", hash = "sha256:87d4f8125c9988bfbed67af47dd7a953e2fc7b0cc1e7800ec6d2080d490bb353", size = 47008828, upload-time = "2025-10-15T18:24:14.008Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1f/42/5c74462b4fd957fcd7b13b04fb3205ff8349236ea74c7c375766d6c82288/pillow-12.1.1.tar.gz", hash = "sha256:9ad8fa5937ab05218e2b6a4cff30295ad35afd2f83ac592e68c0d871bb0fdbc4", size = 46980264, upload-time = "2026-02-11T04:23:07.146Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0e/5a/a2f6773b64edb921a756eb0729068acad9fc5208a53f4a349396e9436721/pillow-12.0.0-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:0fd00cac9c03256c8b2ff58f162ebcd2587ad3e1f2e397eab718c47e24d231cc", size = 5289798, upload-time = "2025-10-15T18:21:47.763Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/05/069b1f8a2e4b5a37493da6c5868531c3f77b85e716ad7a590ef87d58730d/pillow-12.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a3475b96f5908b3b16c47533daaa87380c491357d197564e0ba34ae75c0f3257", size = 4650589, upload-time = "2025-10-15T18:21:49.515Z" },
-    { url = "https://files.pythonhosted.org/packages/61/e3/2c820d6e9a36432503ead175ae294f96861b07600a7156154a086ba7111a/pillow-12.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:110486b79f2d112cf6add83b28b627e369219388f64ef2f960fef9ebaf54c642", size = 6230472, upload-time = "2025-10-15T18:21:51.052Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/89/63427f51c64209c5e23d4d52071c8d0f21024d3a8a487737caaf614a5795/pillow-12.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5269cc1caeedb67e6f7269a42014f381f45e2e7cd42d834ede3c703a1d915fe3", size = 8033887, upload-time = "2025-10-15T18:21:52.604Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/1b/c9711318d4901093c15840f268ad649459cd81984c9ec9887756cca049a5/pillow-12.0.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:aa5129de4e174daccbc59d0a3b6d20eaf24417d59851c07ebb37aeb02947987c", size = 6343964, upload-time = "2025-10-15T18:21:54.619Z" },
-    { url = "https://files.pythonhosted.org/packages/41/1e/db9470f2d030b4995083044cd8738cdd1bf773106819f6d8ba12597d5352/pillow-12.0.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bee2a6db3a7242ea309aa7ee8e2780726fed67ff4e5b40169f2c940e7eb09227", size = 7034756, upload-time = "2025-10-15T18:21:56.151Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/b0/6177a8bdd5ee4ed87cba2de5a3cc1db55ffbbec6176784ce5bb75aa96798/pillow-12.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:90387104ee8400a7b4598253b4c406f8958f59fcf983a6cea2b50d59f7d63d0b", size = 6458075, upload-time = "2025-10-15T18:21:57.759Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/5e/61537aa6fa977922c6a03253a0e727e6e4a72381a80d63ad8eec350684f2/pillow-12.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bc91a56697869546d1b8f0a3ff35224557ae7f881050e99f615e0119bf934b4e", size = 7125955, upload-time = "2025-10-15T18:21:59.372Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/3d/d5033539344ee3cbd9a4d69e12e63ca3a44a739eb2d4c8da350a3d38edd7/pillow-12.0.0-cp311-cp311-win32.whl", hash = "sha256:27f95b12453d165099c84f8a8bfdfd46b9e4bda9e0e4b65f0635430027f55739", size = 6298440, upload-time = "2025-10-15T18:22:00.982Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/42/aaca386de5cc8bd8a0254516957c1f265e3521c91515b16e286c662854c4/pillow-12.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:b583dc9070312190192631373c6c8ed277254aa6e6084b74bdd0a6d3b221608e", size = 6999256, upload-time = "2025-10-15T18:22:02.617Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/f1/9197c9c2d5708b785f631a6dfbfa8eb3fb9672837cb92ae9af812c13b4ed/pillow-12.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:759de84a33be3b178a64c8ba28ad5c135900359e85fb662bc6e403ad4407791d", size = 2436025, upload-time = "2025-10-15T18:22:04.598Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/90/4fcce2c22caf044e660a198d740e7fbc14395619e3cb1abad12192c0826c/pillow-12.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:53561a4ddc36facb432fae7a9d8afbfaf94795414f5cdc5fc52f28c1dca90371", size = 5249377, upload-time = "2025-10-15T18:22:05.993Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/e0/ed960067543d080691d47d6938ebccbf3976a931c9567ab2fbfab983a5dd/pillow-12.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:71db6b4c1653045dacc1585c1b0d184004f0d7e694c7b34ac165ca70c0838082", size = 4650343, upload-time = "2025-10-15T18:22:07.718Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/a1/f81fdeddcb99c044bf7d6faa47e12850f13cee0849537a7d27eeab5534d4/pillow-12.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2fa5f0b6716fc88f11380b88b31fe591a06c6315e955c096c35715788b339e3f", size = 6232981, upload-time = "2025-10-15T18:22:09.287Z" },
-    { url = "https://files.pythonhosted.org/packages/88/e1/9098d3ce341a8750b55b0e00c03f1630d6178f38ac191c81c97a3b047b44/pillow-12.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:82240051c6ca513c616f7f9da06e871f61bfd7805f566275841af15015b8f98d", size = 8041399, upload-time = "2025-10-15T18:22:10.872Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/62/a22e8d3b602ae8cc01446d0c57a54e982737f44b6f2e1e019a925143771d/pillow-12.0.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:55f818bd74fe2f11d4d7cbc65880a843c4075e0ac7226bc1a23261dbea531953", size = 6347740, upload-time = "2025-10-15T18:22:12.769Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/87/424511bdcd02c8d7acf9f65caa09f291a519b16bd83c3fb3374b3d4ae951/pillow-12.0.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b87843e225e74576437fd5b6a4c2205d422754f84a06942cfaf1dc32243e45a8", size = 7040201, upload-time = "2025-10-15T18:22:14.813Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/4d/435c8ac688c54d11755aedfdd9f29c9eeddf68d150fe42d1d3dbd2365149/pillow-12.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c607c90ba67533e1b2355b821fef6764d1dd2cbe26b8c1005ae84f7aea25ff79", size = 6462334, upload-time = "2025-10-15T18:22:16.375Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/f2/ad34167a8059a59b8ad10bc5c72d4d9b35acc6b7c0877af8ac885b5f2044/pillow-12.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:21f241bdd5080a15bc86d3466a9f6074a9c2c2b314100dd896ac81ee6db2f1ba", size = 7134162, upload-time = "2025-10-15T18:22:17.996Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/b1/a7391df6adacf0a5c2cf6ac1cf1fcc1369e7d439d28f637a847f8803beb3/pillow-12.0.0-cp312-cp312-win32.whl", hash = "sha256:dd333073e0cacdc3089525c7df7d39b211bcdf31fc2824e49d01c6b6187b07d0", size = 6298769, upload-time = "2025-10-15T18:22:19.923Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/0b/d87733741526541c909bbf159e338dcace4f982daac6e5a8d6be225ca32d/pillow-12.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:9fe611163f6303d1619bbcb653540a4d60f9e55e622d60a3108be0d5b441017a", size = 7001107, upload-time = "2025-10-15T18:22:21.644Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/96/aaa61ce33cc98421fb6088af2a03be4157b1e7e0e87087c888e2370a7f45/pillow-12.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:7dfb439562f234f7d57b1ac6bc8fe7f838a4bd49c79230e0f6a1da93e82f1fad", size = 2436012, upload-time = "2025-10-15T18:22:23.621Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/b3/582327e6c9f86d037b63beebe981425d6811104cb443e8193824ef1a2f27/pillow-12.0.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:b22bd8c974942477156be55a768f7aa37c46904c175be4e158b6a86e3a6b7ca8", size = 5215068, upload-time = "2025-10-15T18:23:59.594Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/d6/67748211d119f3b6540baf90f92fae73ae51d5217b171b0e8b5f7e5d558f/pillow-12.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:805ebf596939e48dbb2e4922a1d3852cfc25c38160751ce02da93058b48d252a", size = 4614994, upload-time = "2025-10-15T18:24:01.669Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/e1/f8281e5d844c41872b273b9f2c34a4bf64ca08905668c8ae730eedc7c9fa/pillow-12.0.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:cae81479f77420d217def5f54b5b9d279804d17e982e0f2fa19b1d1e14ab5197", size = 5246639, upload-time = "2025-10-15T18:24:03.403Z" },
-    { url = "https://files.pythonhosted.org/packages/94/5a/0d8ab8ffe8a102ff5df60d0de5af309015163bf710c7bb3e8311dd3b3ad0/pillow-12.0.0-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aeaefa96c768fc66818730b952a862235d68825c178f1b3ffd4efd7ad2edcb7c", size = 6986839, upload-time = "2025-10-15T18:24:05.344Z" },
-    { url = "https://files.pythonhosted.org/packages/20/2e/3434380e8110b76cd9eb00a363c484b050f949b4bbe84ba770bb8508a02c/pillow-12.0.0-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:09f2d0abef9e4e2f349305a4f8cc784a8a6c2f58a8c4892eea13b10a943bd26e", size = 5313505, upload-time = "2025-10-15T18:24:07.137Z" },
-    { url = "https://files.pythonhosted.org/packages/57/ca/5a9d38900d9d74785141d6580950fe705de68af735ff6e727cb911b64740/pillow-12.0.0-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bdee52571a343d721fb2eb3b090a82d959ff37fc631e3f70422e0c2e029f3e76", size = 5963654, upload-time = "2025-10-15T18:24:09.579Z" },
-    { url = "https://files.pythonhosted.org/packages/95/7e/f896623c3c635a90537ac093c6a618ebe1a90d87206e42309cb5d98a1b9e/pillow-12.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:b290fd8aa38422444d4b50d579de197557f182ef1068b75f5aa8558638b8d0a5", size = 6997850, upload-time = "2025-10-15T18:24:11.495Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/46/5da1ec4a5171ee7bf1a0efa064aba70ba3d6e0788ce3f5acd1375d23c8c0/pillow-12.1.1-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:e879bb6cd5c73848ef3b2b48b8af9ff08c5b71ecda8048b7dd22d8a33f60be32", size = 5304084, upload-time = "2026-02-11T04:20:27.501Z" },
+    { url = "https://files.pythonhosted.org/packages/78/93/a29e9bc02d1cf557a834da780ceccd54e02421627200696fcf805ebdc3fb/pillow-12.1.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:365b10bb9417dd4498c0e3b128018c4a624dc11c7b97d8cc54effe3b096f4c38", size = 4657866, upload-time = "2026-02-11T04:20:29.827Z" },
+    { url = "https://files.pythonhosted.org/packages/13/84/583a4558d492a179d31e4aae32eadce94b9acf49c0337c4ce0b70e0a01f2/pillow-12.1.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d4ce8e329c93845720cd2014659ca67eac35f6433fd3050393d85f3ecef0dad5", size = 6232148, upload-time = "2026-02-11T04:20:31.329Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/e2/53c43334bbbb2d3b938978532fbda8e62bb6e0b23a26ce8592f36bcc4987/pillow-12.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc354a04072b765eccf2204f588a7a532c9511e8b9c7f900e1b64e3e33487090", size = 8038007, upload-time = "2026-02-11T04:20:34.225Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/a6/3d0e79c8a9d58150dd98e199d7c1c56861027f3829a3a60b3c2784190180/pillow-12.1.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7e7976bf1910a8116b523b9f9f58bf410f3e8aa330cd9a2bb2953f9266ab49af", size = 6345418, upload-time = "2026-02-11T04:20:35.858Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/c8/46dfeac5825e600579157eea177be43e2f7ff4a99da9d0d0a49533509ac5/pillow-12.1.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:597bd9c8419bc7c6af5604e55847789b69123bbe25d65cc6ad3012b4f3c98d8b", size = 7034590, upload-time = "2026-02-11T04:20:37.91Z" },
+    { url = "https://files.pythonhosted.org/packages/af/bf/e6f65d3db8a8bbfeaf9e13cc0417813f6319863a73de934f14b2229ada18/pillow-12.1.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:2c1fc0f2ca5f96a3c8407e41cca26a16e46b21060fe6d5b099d2cb01412222f5", size = 6458655, upload-time = "2026-02-11T04:20:39.496Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/c2/66091f3f34a25894ca129362e510b956ef26f8fb67a0e6417bc5744e56f1/pillow-12.1.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:578510d88c6229d735855e1f278aa305270438d36a05031dfaae5067cc8eb04d", size = 7159286, upload-time = "2026-02-11T04:20:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5a/24bc8eb526a22f957d0cec6243146744966d40857e3d8deb68f7902ca6c1/pillow-12.1.1-cp311-cp311-win32.whl", hash = "sha256:7311c0a0dcadb89b36b7025dfd8326ecfa36964e29913074d47382706e516a7c", size = 6328663, upload-time = "2026-02-11T04:20:43.184Z" },
+    { url = "https://files.pythonhosted.org/packages/31/03/bef822e4f2d8f9d7448c133d0a18185d3cce3e70472774fffefe8b0ed562/pillow-12.1.1-cp311-cp311-win_amd64.whl", hash = "sha256:fbfa2a7c10cc2623f412753cddf391c7f971c52ca40a3f65dc5039b2939e8563", size = 7031448, upload-time = "2026-02-11T04:20:44.696Z" },
+    { url = "https://files.pythonhosted.org/packages/49/70/f76296f53610bd17b2e7d31728b8b7825e3ac3b5b3688b51f52eab7c0818/pillow-12.1.1-cp311-cp311-win_arm64.whl", hash = "sha256:b81b5e3511211631b3f672a595e3221252c90af017e399056d0faabb9538aa80", size = 2453651, upload-time = "2026-02-11T04:20:46.243Z" },
+    { url = "https://files.pythonhosted.org/packages/07/d3/8df65da0d4df36b094351dce696f2989bec731d4f10e743b1c5f4da4d3bf/pillow-12.1.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ab323b787d6e18b3d91a72fc99b1a2c28651e4358749842b8f8dfacd28ef2052", size = 5262803, upload-time = "2026-02-11T04:20:47.653Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/71/5026395b290ff404b836e636f51d7297e6c83beceaa87c592718747e670f/pillow-12.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:adebb5bee0f0af4909c30db0d890c773d1a92ffe83da908e2e9e720f8edf3984", size = 4657601, upload-time = "2026-02-11T04:20:49.328Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/2e/1001613d941c67442f745aff0f7cc66dd8df9a9c084eb497e6a543ee6f7e/pillow-12.1.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bb66b7cc26f50977108790e2456b7921e773f23db5630261102233eb355a3b79", size = 6234995, upload-time = "2026-02-11T04:20:51.032Z" },
+    { url = "https://files.pythonhosted.org/packages/07/26/246ab11455b2549b9233dbd44d358d033a2f780fa9007b61a913c5b2d24e/pillow-12.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aee2810642b2898bb187ced9b349e95d2a7272930796e022efaf12e99dccd293", size = 8045012, upload-time = "2026-02-11T04:20:52.882Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/8b/07587069c27be7535ac1fe33874e32de118fbd34e2a73b7f83436a88368c/pillow-12.1.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a0b1cd6232e2b618adcc54d9882e4e662a089d5768cd188f7c245b4c8c44a397", size = 6349638, upload-time = "2026-02-11T04:20:54.444Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/79/6df7b2ee763d619cda2fb4fea498e5f79d984dae304d45a8999b80d6cf5c/pillow-12.1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7aac39bcf8d4770d089588a2e1dd111cbaa42df5a94be3114222057d68336bd0", size = 7041540, upload-time = "2026-02-11T04:20:55.97Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/5e/2ba19e7e7236d7529f4d873bdaf317a318896bac289abebd4bb00ef247f0/pillow-12.1.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:ab174cd7d29a62dd139c44bf74b698039328f45cb03b4596c43473a46656b2f3", size = 6462613, upload-time = "2026-02-11T04:20:57.542Z" },
+    { url = "https://files.pythonhosted.org/packages/03/03/31216ec124bb5c3dacd74ce8efff4cc7f52643653bad4825f8f08c697743/pillow-12.1.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:339ffdcb7cbeaa08221cd401d517d4b1fe7a9ed5d400e4a8039719238620ca35", size = 7166745, upload-time = "2026-02-11T04:20:59.196Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/e7/7c4552d80052337eb28653b617eafdef39adfb137c49dd7e831b8dc13bc5/pillow-12.1.1-cp312-cp312-win32.whl", hash = "sha256:5d1f9575a12bed9e9eedd9a4972834b08c97a352bd17955ccdebfeca5913fa0a", size = 6328823, upload-time = "2026-02-11T04:21:01.385Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/17/688626d192d7261bbbf98846fc98995726bddc2c945344b65bec3a29d731/pillow-12.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:21329ec8c96c6e979cd0dfd29406c40c1d52521a90544463057d2aaa937d66a6", size = 7033367, upload-time = "2026-02-11T04:21:03.536Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/fe/a0ef1f73f939b0eca03ee2c108d0043a87468664770612602c63266a43c4/pillow-12.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:af9a332e572978f0218686636610555ae3defd1633597be015ed50289a03c523", size = 2453811, upload-time = "2026-02-11T04:21:05.116Z" },
+    { url = "https://files.pythonhosted.org/packages/56/11/5d43209aa4cb58e0cc80127956ff1796a68b928e6324bbf06ef4db34367b/pillow-12.1.1-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:600fd103672b925fe62ed08e0d874ea34d692474df6f4bf7ebe148b30f89f39f", size = 5228606, upload-time = "2026-02-11T04:22:52.106Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/d5/3b005b4e4fda6698b371fa6c21b097d4707585d7db99e98d9b0b87ac612a/pillow-12.1.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:665e1b916b043cef294bc54d47bf02d87e13f769bc4bc5fa225a24b3a6c5aca9", size = 4622321, upload-time = "2026-02-11T04:22:53.827Z" },
+    { url = "https://files.pythonhosted.org/packages/df/36/ed3ea2d594356fd8037e5a01f6156c74bc8d92dbb0fa60746cc96cabb6e8/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:495c302af3aad1ca67420ddd5c7bd480c8867ad173528767d906428057a11f0e", size = 5247579, upload-time = "2026-02-11T04:22:56.094Z" },
+    { url = "https://files.pythonhosted.org/packages/54/9a/9cc3e029683cf6d20ae5085da0dafc63148e3252c2f13328e553aaa13cfb/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8fd420ef0c52c88b5a035a0886f367748c72147b2b8f384c9d12656678dfdfa9", size = 6989094, upload-time = "2026-02-11T04:22:58.288Z" },
+    { url = "https://files.pythonhosted.org/packages/00/98/fc53ab36da80b88df0967896b6c4b4cd948a0dc5aa40a754266aa3ae48b3/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f975aa7ef9684ce7e2c18a3aa8f8e2106ce1e46b94ab713d156b2898811651d3", size = 5313850, upload-time = "2026-02-11T04:23:00.554Z" },
+    { url = "https://files.pythonhosted.org/packages/30/02/00fa585abfd9fe9d73e5f6e554dc36cc2b842898cbfc46d70353dae227f8/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8089c852a56c2966cf18835db62d9b34fef7ba74c726ad943928d494fa7f4735", size = 5963343, upload-time = "2026-02-11T04:23:02.934Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/26/c56ce33ca856e358d27fda9676c055395abddb82c35ac0f593877ed4562e/pillow-12.1.1-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:cb9bb857b2d057c6dfc72ac5f3b44836924ba15721882ef103cecb40d002d80e", size = 7029880, upload-time = "2026-02-11T04:23:04.783Z" },
 ]
 
 [[package]]
@@ -4902,16 +4900,16 @@ wheels = [
 
 [[package]]
 name = "pydantic-settings"
-version = "2.11.0"
+version = "2.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pydantic" },
     { name = "python-dotenv" },
     { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/20/c5/dbbc27b814c71676593d1c3f718e6cd7d4f00652cefa24b75f7aa3efb25e/pydantic_settings-2.11.0.tar.gz", hash = "sha256:d0e87a1c7d33593beb7194adb8470fc426e95ba02af83a0f23474a04c9a08180", size = 188394, upload-time = "2025-09-24T14:19:11.764Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/4b/ac7e0aae12027748076d72a8764ff1c9d82ca75a7a52622e67ed3f765c54/pydantic_settings-2.12.0.tar.gz", hash = "sha256:005538ef951e3c2a68e1c08b292b5f2e71490def8589d4221b95dab00dafcfd0", size = 194184, upload-time = "2025-11-10T14:25:47.013Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/83/d6/887a1ff844e64aa823fb4905978d882a633cfe295c32eacad582b78a7d8b/pydantic_settings-2.11.0-py3-none-any.whl", hash = "sha256:fe2cea3413b9530d10f3a5875adffb17ada5c1e1bab0b2885546d7310415207c", size = 48608, upload-time = "2025-09-24T14:19:10.015Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/60/5d4751ba3f4a40a6891f24eec885f51afd78d208498268c734e256fb13c4/pydantic_settings-2.12.0-py3-none-any.whl", hash = "sha256:fddb9fd99a5b18da837b29710391e945b1e30c135477f484084ee513adb93809", size = 51880, upload-time = "2025-11-10T14:25:45.546Z" },
 ]
 
 [[package]]
@@ -5892,11 +5890,11 @@ wheels = [
 
 [[package]]
 name = "sqlparse"
-version = "0.5.3"
+version = "0.5.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e5/40/edede8dd6977b0d3da179a342c198ed100dd2aba4be081861ee5911e4da4/sqlparse-0.5.3.tar.gz", hash = "sha256:09f67787f56a0b16ecdbde1bfc7f5d9c3371ca683cfeaa8e6ff60b4807ec9272", size = 84999, upload-time = "2024-12-10T12:05:30.728Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/18/67/701f86b28d63b2086de47c942eccf8ca2208b3be69715a1119a4e384415a/sqlparse-0.5.4.tar.gz", hash = "sha256:4396a7d3cf1cd679c1be976cf3dc6e0a51d0111e87787e7a8d780e7d5a998f9e", size = 120112, upload-time = "2025-11-28T07:10:18.377Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a9/5c/bfd6bd0bf979426d405cc6e71eceb8701b148b16c21d2dc3c261efc61c7b/sqlparse-0.5.3-py3-none-any.whl", hash = "sha256:cf2196ed3418f3ba5de6af7e82c694a9fbdbfecccdfc72e281548517081f16ca", size = 44415, upload-time = "2024-12-10T12:05:27.824Z" },
+    { url = "https://files.pythonhosted.org/packages/25/70/001ee337f7aa888fb2e3f5fd7592a6afc5283adb1ed44ce8df5764070f22/sqlparse-0.5.4-py3-none-any.whl", hash = "sha256:99a9f0314977b76d776a0fcb8554de91b9bb8a18560631d6bc48721d07023dcb", size = 45933, upload-time = "2025-11-28T07:10:19.73Z" },
 ]
 
 [[package]]

dev/start-worker

@@ -106,10 +106,10 @@ if [[ -z "${QUEUES}" ]]; then
   # Configure queues based on edition
   if [[ "${EDITION}" == "CLOUD" ]]; then
     # Cloud edition: separate queues for dataset and trigger tasks
-    QUEUES="dataset,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow_professional,workflow_team,workflow_sandbox,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention"
+    QUEUES="dataset,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow_professional,workflow_team,workflow_sandbox,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution"
   else
     # Community edition (SELF_HOSTED): dataset and workflow have separate queues
-    QUEUES="dataset,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention"
+    QUEUES="dataset,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution"
   fi
 
   echo "No queues specified, using edition-based defaults: ${QUEUES}"

docker/.env.example

@@ -62,6 +62,9 @@ LANG=C.UTF-8
 LC_ALL=C.UTF-8
 PYTHONIOENCODING=utf-8
 
+# Set UV cache directory to avoid permission issues with non-existent home directory
+UV_CACHE_DIR=/tmp/.uv-cache
+
 # ------------------------------
 # Server Configuration
 # ------------------------------
@@ -384,6 +387,8 @@ CELERY_USE_SENTINEL=false
 CELERY_SENTINEL_MASTER_NAME=
 CELERY_SENTINEL_PASSWORD=
 CELERY_SENTINEL_SOCKET_TIMEOUT=0.1
+# e.g. {"tasks.add": {"rate_limit": "10/s"}}
+CELERY_TASK_ANNOTATIONS=null
 
 # ------------------------------
 # CORS Configuration
@@ -1068,6 +1073,8 @@ WORKFLOW_LOG_CLEANUP_ENABLED=false
 WORKFLOW_LOG_RETENTION_DAYS=30
 # Batch size for workflow log cleanup operations (default: 100)
 WORKFLOW_LOG_CLEANUP_BATCH_SIZE=100
+# Comma-separated list of workflow IDs to clean logs for
+WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS=
 
 # Aliyun SLS Logstore Configuration
 # Aliyun Access Key ID
@@ -1518,6 +1525,7 @@ AMPLITUDE_API_KEY=
 # Sandbox expired records clean configuration
 SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD=21
 SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE=1000
+SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL=200
 SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS=30
 
 

docker/docker-compose-template.yaml

@@ -21,7 +21,7 @@ services:
 
   # API service
   api:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -63,7 +63,7 @@ services:
   # worker service
   # The Celery worker for processing all queues (dataset, workflow, mail, etc.)
   worker:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -102,7 +102,7 @@ services:
   # worker_beat service
   # Celery beat for scheduling periodic tasks.
   worker_beat:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -132,7 +132,7 @@ services:
 
   # Frontend web application.
   web:
-    image: langgenius/dify-web:1.12.1
+    image: langgenius/dify-web:1.13.0
     restart: always
     environment:
       CONSOLE_API_URL: ${CONSOLE_API_URL:-}

docker/docker-compose.yaml

@@ -16,6 +16,7 @@ x-shared-env: &shared-api-worker-env
   LANG: ${LANG:-C.UTF-8}
   LC_ALL: ${LC_ALL:-C.UTF-8}
   PYTHONIOENCODING: ${PYTHONIOENCODING:-utf-8}
+  UV_CACHE_DIR: ${UV_CACHE_DIR:-/tmp/.uv-cache}
   LOG_LEVEL: ${LOG_LEVEL:-INFO}
   LOG_OUTPUT_FORMAT: ${LOG_OUTPUT_FORMAT:-text}
   LOG_FILE: ${LOG_FILE:-/app/logs/server.log}
@@ -105,6 +106,7 @@ x-shared-env: &shared-api-worker-env
   CELERY_SENTINEL_MASTER_NAME: ${CELERY_SENTINEL_MASTER_NAME:-}
   CELERY_SENTINEL_PASSWORD: ${CELERY_SENTINEL_PASSWORD:-}
   CELERY_SENTINEL_SOCKET_TIMEOUT: ${CELERY_SENTINEL_SOCKET_TIMEOUT:-0.1}
+  CELERY_TASK_ANNOTATIONS: ${CELERY_TASK_ANNOTATIONS:-null}
   WEB_API_CORS_ALLOW_ORIGINS: ${WEB_API_CORS_ALLOW_ORIGINS:-*}
   CONSOLE_CORS_ALLOW_ORIGINS: ${CONSOLE_CORS_ALLOW_ORIGINS:-*}
   COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
@@ -468,6 +470,7 @@ x-shared-env: &shared-api-worker-env
   WORKFLOW_LOG_CLEANUP_ENABLED: ${WORKFLOW_LOG_CLEANUP_ENABLED:-false}
   WORKFLOW_LOG_RETENTION_DAYS: ${WORKFLOW_LOG_RETENTION_DAYS:-30}
   WORKFLOW_LOG_CLEANUP_BATCH_SIZE: ${WORKFLOW_LOG_CLEANUP_BATCH_SIZE:-100}
+  WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS: ${WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS:-}
   ALIYUN_SLS_ACCESS_KEY_ID: ${ALIYUN_SLS_ACCESS_KEY_ID:-}
   ALIYUN_SLS_ACCESS_KEY_SECRET: ${ALIYUN_SLS_ACCESS_KEY_SECRET:-}
   ALIYUN_SLS_ENDPOINT: ${ALIYUN_SLS_ENDPOINT:-}
@@ -682,6 +685,7 @@ x-shared-env: &shared-api-worker-env
   AMPLITUDE_API_KEY: ${AMPLITUDE_API_KEY:-}
   SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD: ${SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD:-21}
   SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE: ${SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE:-1000}
+  SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL: ${SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL:-200}
   SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS: ${SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS:-30}
   PUBSUB_REDIS_URL: ${PUBSUB_REDIS_URL:-}
   PUBSUB_REDIS_CHANNEL_TYPE: ${PUBSUB_REDIS_CHANNEL_TYPE:-pubsub}
@@ -712,7 +716,7 @@ services:
 
   # API service
   api:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -754,7 +758,7 @@ services:
   # worker service
   # The Celery worker for processing all queues (dataset, workflow, mail, etc.)
   worker:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -793,7 +797,7 @@ services:
   # worker_beat service
   # Celery beat for scheduling periodic tasks.
   worker_beat:
-    image: langgenius/dify-api:1.12.1
+    image: langgenius/dify-api:1.13.0
     restart: always
     environment:
       # Use the shared environment variables.
@@ -823,7 +827,7 @@ services:
 
   # Frontend web application.
   web:
-    image: langgenius/dify-web:1.12.1
+    image: langgenius/dify-web:1.13.0
     restart: always
     environment:
       CONSOLE_API_URL: ${CONSOLE_API_URL:-}

sdks/nodejs-client/pnpm-lock.yaml

@@ -10,7 +10,7 @@ importers:
     dependencies:
       axios:
         specifier: ^1.13.2
-        version: 1.13.2
+        version: 1.13.5
     devDependencies:
       '@eslint/js':
         specifier: ^9.39.2
@@ -544,8 +544,8 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
-  axios@1.13.2:
-    resolution: {integrity: sha512-VPk9ebNqPcy5lRGuSlKx752IlDatOjT9paPlm8A7yOuW2Fbvp4X3JznJtT4f0GzGLLiWE9W8onz51SqLYwzGaA==}
+  axios@1.13.5:
+    resolution: {integrity: sha512-cz4ur7Vb0xS4/KUN0tPWe44eqxrIu31me+fbang3ijiNscE129POzipJJA6zniq2C/Z6sJCjMimjS8Lc/GAs8Q==}
 
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
@@ -1677,7 +1677,7 @@ snapshots:
 
   asynckit@0.4.0: {}
 
-  axios@1.13.2:
+  axios@1.13.5:
     dependencies:
       follow-redirects: 1.15.11
       form-data: 4.0.5

web/__tests__/apps/app-card-operations-flow.test.tsx

@@ -0,0 +1,462 @@
+/**
+ * Integration test: App Card Operations Flow
+ *
+ * Tests the end-to-end user flows for app card operations:
+ *   - Editing app info
+ *   - Duplicating an app
+ *   - Deleting an app
+ *   - Exporting app DSL
+ *   - Navigation on card click
+ *   - Access mode icons
+ */
+import type { App } from '@/types/app'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import AppCard from '@/app/components/apps/app-card'
+import { AccessMode } from '@/models/access-control'
+import { deleteApp, exportAppConfig, updateAppInfo } from '@/service/apps'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+const mockRouterPush = vi.fn()
+const mockNotify = vi.fn()
+const mockOnPlanInfoChanged = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+  }),
+}))
+
+// Mock headless UI Popover so it renders content without transition
+vi.mock('@headlessui/react', async () => {
+  const actual = await vi.importActual<typeof import('@headlessui/react')>('@headlessui/react')
+  return {
+    ...actual,
+    Popover: ({ children, className }: { children: ((bag: { open: boolean }) => React.ReactNode) | React.ReactNode, className?: string }) => (
+      <div className={className} data-testid="popover-wrapper">
+        {typeof children === 'function' ? children({ open: true }) : children}
+      </div>
+    ),
+    PopoverButton: ({ children, className, ref: _ref, ...rest }: Record<string, unknown>) => (
+      <button className={className as string} {...rest}>{children as React.ReactNode}</button>
+    ),
+    PopoverPanel: ({ children, className }: { children: ((bag: { close: () => void }) => React.ReactNode) | React.ReactNode, className?: string }) => (
+      <div className={className}>
+        {typeof children === 'function' ? children({ close: vi.fn() }) : children}
+      </div>
+    ),
+    Transition: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  }
+})
+
+vi.mock('next/dynamic', () => ({
+  default: (loader: () => Promise<{ default: React.ComponentType }>) => {
+    let Component: React.ComponentType<Record<string, unknown>> | null = null
+    loader().then((mod) => {
+      Component = mod.default as React.ComponentType<Record<string, unknown>>
+    }).catch(() => {})
+    const Wrapper = (props: Record<string, unknown>) => {
+      if (Component)
+        return <Component {...props} />
+      return null
+    }
+    Wrapper.displayName = 'DynamicWrapper'
+    return Wrapper
+  },
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    if (typeof selector === 'function')
+      return selector(state)
+    return mockSystemFeatures
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: mockOnPlanInfoChanged,
+  }),
+}))
+
+// Mock the ToastContext used via useContext from use-context-selector
+vi.mock('use-context-selector', async () => {
+  const actual = await vi.importActual<typeof import('use-context-selector')>('use-context-selector')
+  return {
+    ...actual,
+    useContext: () => ({ notify: mockNotify }),
+  }
+})
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: false,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/apps', () => ({
+  deleteApp: vi.fn().mockResolvedValue({}),
+  updateAppInfo: vi.fn().mockResolvedValue({}),
+  copyApp: vi.fn().mockResolvedValue({ id: 'new-app-id', mode: 'chat' }),
+  exportAppConfig: vi.fn().mockResolvedValue({ data: 'yaml-content' }),
+}))
+
+vi.mock('@/service/explore', () => ({
+  fetchInstalledAppList: vi.fn().mockResolvedValue({ installed_apps: [] }),
+}))
+
+vi.mock('@/service/workflow', () => ({
+  fetchWorkflowDraft: vi.fn().mockResolvedValue({ environment_variables: [] }),
+}))
+
+vi.mock('@/service/access-control', () => ({
+  useGetUserCanAccessApp: () => ({ data: { result: true }, isLoading: false }),
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => vi.fn(),
+}))
+
+// Mock modals loaded via next/dynamic
+vi.mock('@/app/components/explore/create-app-modal', () => ({
+  default: ({ show, onConfirm, onHide, appName }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="edit-app-modal">
+        <span data-testid="modal-app-name">{appName as string}</span>
+        <button
+          data-testid="confirm-edit"
+          onClick={() => (onConfirm as (data: Record<string, unknown>) => void)({
+            name: 'Updated App Name',
+            icon_type: 'emoji',
+            icon: '🔥',
+            icon_background: '#fff',
+            description: 'Updated description',
+          })}
+        >
+          Confirm
+        </button>
+        <button data-testid="cancel-edit" onClick={onHide as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/duplicate-modal', () => ({
+  default: ({ show, onConfirm, onHide }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="duplicate-app-modal">
+        <button
+          data-testid="confirm-duplicate"
+          onClick={() => (onConfirm as (data: Record<string, unknown>) => void)({
+            name: 'Copied App',
+            icon_type: 'emoji',
+            icon: '📋',
+            icon_background: '#fff',
+          })}
+        >
+          Confirm Duplicate
+        </button>
+        <button data-testid="cancel-duplicate" onClick={onHide as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/switch-app-modal', () => ({
+  default: ({ show, onClose, onSuccess }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="switch-app-modal">
+        <button data-testid="confirm-switch" onClick={onSuccess as () => void}>Confirm Switch</button>
+        <button data-testid="cancel-switch" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/base/confirm', () => ({
+  default: ({ isShow, onConfirm, onCancel, title }: Record<string, unknown>) => {
+    if (!isShow)
+      return null
+    return (
+      <div data-testid="confirm-delete-modal">
+        <span>{title as string}</span>
+        <button data-testid="confirm-delete" onClick={onConfirm as () => void}>Delete</button>
+        <button data-testid="cancel-delete" onClick={onCancel as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/workflow/dsl-export-confirm-modal', () => ({
+  default: ({ onConfirm, onClose }: Record<string, unknown>) => (
+    <div data-testid="dsl-export-confirm-modal">
+      <button data-testid="export-include" onClick={() => (onConfirm as (include: boolean) => void)(true)}>Include</button>
+      <button data-testid="export-close" onClick={onClose as () => void}>Close</button>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/app/app-access-control', () => ({
+  default: ({ onConfirm, onClose }: Record<string, unknown>) => (
+    <div data-testid="access-control-modal">
+      <button data-testid="confirm-access" onClick={onConfirm as () => void}>Confirm</button>
+      <button data-testid="cancel-access" onClick={onClose as () => void}>Cancel</button>
+    </div>
+  ),
+}))
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'Test Chat App',
+  description: overrides.description ?? 'A chat application',
+  author_name: overrides.author_name ?? 'Test Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const mockOnRefresh = vi.fn()
+
+const renderAppCard = (app?: Partial<App>) => {
+  return render(<AppCard app={createMockApp(app)} onRefresh={mockOnRefresh} />)
+}
+
+describe('App Card Operations Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('Card Rendering', () => {
+    it('should render app name and description', () => {
+      renderAppCard({ name: 'My AI Bot', description: 'An intelligent assistant' })
+
+      expect(screen.getByText('My AI Bot')).toBeInTheDocument()
+      expect(screen.getByText('An intelligent assistant')).toBeInTheDocument()
+    })
+
+    it('should render author name', () => {
+      renderAppCard({ author_name: 'John Doe' })
+
+      expect(screen.getByText('John Doe')).toBeInTheDocument()
+    })
+
+    it('should navigate to app config page when card is clicked', () => {
+      renderAppCard({ id: 'app-123', mode: AppModeEnum.CHAT })
+
+      const card = screen.getByText('Test Chat App').closest('[class*="cursor-pointer"]')
+      if (card)
+        fireEvent.click(card)
+
+      expect(mockRouterPush).toHaveBeenCalledWith('/app/app-123/configuration')
+    })
+
+    it('should navigate to workflow page for workflow apps', () => {
+      renderAppCard({ id: 'app-wf', mode: AppModeEnum.WORKFLOW, name: 'WF App' })
+
+      const card = screen.getByText('WF App').closest('[class*="cursor-pointer"]')
+      if (card)
+        fireEvent.click(card)
+
+      expect(mockRouterPush).toHaveBeenCalledWith('/app/app-wf/workflow')
+    })
+  })
+
+  // -- Delete flow --
+  describe('Delete App Flow', () => {
+    it('should show delete confirmation and call API on confirm', async () => {
+      renderAppCard({ id: 'app-to-delete', name: 'Deletable App' })
+
+      // Find and click the more button (popover trigger)
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const deleteBtn = screen.queryByText('common.operation.delete')
+          if (deleteBtn)
+            fireEvent.click(deleteBtn)
+        })
+
+        const confirmBtn = screen.queryByTestId('confirm-delete')
+        if (confirmBtn) {
+          fireEvent.click(confirmBtn)
+
+          await waitFor(() => {
+            expect(deleteApp).toHaveBeenCalledWith('app-to-delete')
+          })
+        }
+      }
+    })
+  })
+
+  // -- Edit flow --
+  describe('Edit App Flow', () => {
+    it('should open edit modal and call updateAppInfo on confirm', async () => {
+      renderAppCard({ id: 'app-edit', name: 'Editable App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const editBtn = screen.queryByText('app.editApp')
+          if (editBtn)
+            fireEvent.click(editBtn)
+        })
+
+        const confirmEdit = screen.queryByTestId('confirm-edit')
+        if (confirmEdit) {
+          fireEvent.click(confirmEdit)
+
+          await waitFor(() => {
+            expect(updateAppInfo).toHaveBeenCalledWith(
+              expect.objectContaining({
+                appID: 'app-edit',
+                name: 'Updated App Name',
+              }),
+            )
+          })
+        }
+      }
+    })
+  })
+
+  // -- Export flow --
+  describe('Export App Flow', () => {
+    it('should call exportAppConfig for completion apps', async () => {
+      renderAppCard({ id: 'app-export', mode: AppModeEnum.COMPLETION, name: 'Export App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const exportBtn = screen.queryByText('app.export')
+          if (exportBtn)
+            fireEvent.click(exportBtn)
+        })
+
+        await waitFor(() => {
+          expect(exportAppConfig).toHaveBeenCalledWith(
+            expect.objectContaining({ appID: 'app-export' }),
+          )
+        })
+      }
+    })
+  })
+
+  // -- Access mode display --
+  describe('Access Mode Display', () => {
+    it('should not render operations menu for non-editor users', () => {
+      mockIsCurrentWorkspaceEditor = false
+      renderAppCard({ name: 'Readonly App' })
+
+      expect(screen.queryByText('app.editApp')).not.toBeInTheDocument()
+      expect(screen.queryByText('common.operation.delete')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Switch mode (only for CHAT/COMPLETION) --
+  describe('Switch App Mode', () => {
+    it('should show switch option for chat mode apps', async () => {
+      renderAppCard({ id: 'app-switch', mode: AppModeEnum.CHAT })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          expect(screen.queryByText('app.switch')).toBeInTheDocument()
+        })
+      }
+    })
+
+    it('should not show switch option for workflow apps', async () => {
+      renderAppCard({ id: 'app-wf', mode: AppModeEnum.WORKFLOW, name: 'WF App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          expect(screen.queryByText('app.switch')).not.toBeInTheDocument()
+        })
+      }
+    })
+  })
+})

web/__tests__/apps/app-list-browsing-flow.test.tsx

@@ -0,0 +1,442 @@
+/**
+ * Integration test: App List Browsing Flow
+ *
+ * Tests the end-to-end user flow of browsing, filtering, searching,
+ * and tab switching in the apps list page.
+ *
+ * Covers: List, Empty, Footer, AppCardSkeleton, useAppsQueryState, NewAppCard
+ */
+import type { AppListResponse } from '@/models/app'
+import type { App } from '@/types/app'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import List from '@/app/components/apps/list'
+import { AccessMode } from '@/models/access-control'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockIsCurrentWorkspaceDatasetOperator = false
+let mockIsLoadingCurrentWorkspace = false
+
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+let mockPages: AppListResponse[] = []
+let mockIsLoading = false
+let mockIsFetching = false
+let mockIsFetchingNextPage = false
+let mockHasNextPage = false
+let mockError: Error | null = null
+const mockRefetch = vi.fn()
+const mockFetchNextPage = vi.fn()
+
+let mockShowTagManagementModal = false
+
+const mockRouterPush = vi.fn()
+const mockRouterReplace = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+    replace: mockRouterReplace,
+  }),
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('next/dynamic', () => ({
+  default: (_loader: () => Promise<{ default: React.ComponentType }>) => {
+    const LazyComponent = (props: Record<string, unknown>) => {
+      return <div data-testid="dynamic-component" {...props} />
+    }
+    LazyComponent.displayName = 'DynamicComponent'
+    return LazyComponent
+  },
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+    isCurrentWorkspaceDatasetOperator: mockIsCurrentWorkspaceDatasetOperator,
+    isLoadingCurrentWorkspace: mockIsLoadingCurrentWorkspace,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    return selector ? selector(state) : state
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: vi.fn(),
+  }),
+}))
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: mockShowTagManagementModal,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/use-apps', () => ({
+  useInfiniteAppList: () => ({
+    data: { pages: mockPages },
+    isLoading: mockIsLoading,
+    isFetching: mockIsFetching,
+    isFetchingNextPage: mockIsFetchingNextPage,
+    fetchNextPage: mockFetchNextPage,
+    hasNextPage: mockHasNextPage,
+    error: mockError,
+    refetch: mockRefetch,
+  }),
+}))
+
+vi.mock('@/hooks/use-pay', () => ({
+  CheckModal: () => null,
+}))
+
+vi.mock('ahooks', async () => {
+  const actual = await vi.importActual<typeof import('ahooks')>('ahooks')
+  const React = await vi.importActual<typeof import('react')>('react')
+  return {
+    ...actual,
+    useDebounceFn: (fn: (...args: unknown[]) => void) => {
+      const fnRef = React.useRef(fn)
+      fnRef.current = fn
+      return {
+        run: (...args: unknown[]) => fnRef.current(...args),
+      }
+    },
+  }
+})
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'My Chat App',
+  description: overrides.description ?? 'A chat application',
+  author_name: overrides.author_name ?? 'Test Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const createPage = (apps: App[], hasMore = false, page = 1): AppListResponse => ({
+  data: apps,
+  has_more: hasMore,
+  limit: 30,
+  page,
+  total: apps.length,
+})
+
+const renderList = (searchParams?: Record<string, string>) => {
+  return render(
+    <NuqsTestingAdapter searchParams={searchParams}>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
+  )
+}
+
+describe('App List Browsing Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockIsCurrentWorkspaceDatasetOperator = false
+    mockIsLoadingCurrentWorkspace = false
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+    mockPages = []
+    mockIsLoading = false
+    mockIsFetching = false
+    mockIsFetchingNextPage = false
+    mockHasNextPage = false
+    mockError = null
+    mockShowTagManagementModal = false
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('Loading and Empty States', () => {
+    it('should show skeleton cards during initial loading', () => {
+      mockIsLoading = true
+      renderList()
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+    })
+
+    it('should show empty state when no apps exist', () => {
+      mockPages = [createPage([])]
+      renderList()
+
+      expect(screen.getByText('app.newApp.noAppsFound')).toBeInTheDocument()
+    })
+
+    it('should transition from loading to content when data loads', () => {
+      mockIsLoading = true
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+
+      // Data loads
+      mockIsLoading = false
+      mockPages = [createPage([
+        createMockApp({ id: 'app-1', name: 'Loaded App' }),
+      ])]
+
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      expect(screen.getByText('Loaded App')).toBeInTheDocument()
+    })
+  })
+
+  // -- Rendering apps --
+  describe('App List Rendering', () => {
+    it('should render all app cards from the data', () => {
+      mockPages = [createPage([
+        createMockApp({ id: 'app-1', name: 'Chat Bot' }),
+        createMockApp({ id: 'app-2', name: 'Workflow Engine', mode: AppModeEnum.WORKFLOW }),
+        createMockApp({ id: 'app-3', name: 'Completion Tool', mode: AppModeEnum.COMPLETION }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('Chat Bot')).toBeInTheDocument()
+      expect(screen.getByText('Workflow Engine')).toBeInTheDocument()
+      expect(screen.getByText('Completion Tool')).toBeInTheDocument()
+    })
+
+    it('should display app descriptions', () => {
+      mockPages = [createPage([
+        createMockApp({ name: 'My App', description: 'A powerful AI assistant' }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('A powerful AI assistant')).toBeInTheDocument()
+    })
+
+    it('should show the NewAppCard for workspace editors', () => {
+      mockPages = [createPage([
+        createMockApp({ name: 'Test App' }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+
+    it('should hide NewAppCard when user is not a workspace editor', () => {
+      mockIsCurrentWorkspaceEditor = false
+      mockPages = [createPage([
+        createMockApp({ name: 'Test App' }),
+      ])]
+
+      renderList()
+
+      expect(screen.queryByText('app.createApp')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Footer visibility --
+  describe('Footer Visibility', () => {
+    it('should show footer when branding is disabled', () => {
+      mockSystemFeatures = { ...mockSystemFeatures, branding: { enabled: false } }
+      mockPages = [createPage([createMockApp()])]
+
+      renderList()
+
+      expect(screen.getByText('app.join')).toBeInTheDocument()
+      expect(screen.getByText('app.communityIntro')).toBeInTheDocument()
+    })
+
+    it('should hide footer when branding is enabled', () => {
+      mockSystemFeatures = { ...mockSystemFeatures, branding: { enabled: true } }
+      mockPages = [createPage([createMockApp()])]
+
+      renderList()
+
+      expect(screen.queryByText('app.join')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- DSL drag-drop hint --
+  describe('DSL Drag-Drop Hint', () => {
+    it('should show drag-drop hint for workspace editors', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
+    })
+
+    it('should hide drag-drop hint for non-editors', () => {
+      mockIsCurrentWorkspaceEditor = false
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.queryByText('app.newApp.dropDSLToCreateApp')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Tab navigation --
+  describe('Tab Navigation', () => {
+    it('should render all category tabs', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.types.all')).toBeInTheDocument()
+      expect(screen.getByText('app.types.workflow')).toBeInTheDocument()
+      expect(screen.getByText('app.types.advanced')).toBeInTheDocument()
+      expect(screen.getByText('app.types.chatbot')).toBeInTheDocument()
+      expect(screen.getByText('app.types.agent')).toBeInTheDocument()
+      expect(screen.getByText('app.types.completion')).toBeInTheDocument()
+    })
+  })
+
+  // -- Search --
+  describe('Search Filtering', () => {
+    it('should render search input', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const input = document.querySelector('input')
+      expect(input).toBeInTheDocument()
+    })
+
+    it('should allow typing in search input', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const input = document.querySelector('input')!
+      fireEvent.change(input, { target: { value: 'test search' } })
+      expect(input.value).toBe('test search')
+    })
+  })
+
+  // -- "Created by me" filter --
+  describe('Created By Me Filter', () => {
+    it('should render the "created by me" checkbox', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
+    })
+
+    it('should toggle the "created by me" filter on click', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const checkbox = screen.getByText('app.showMyCreatedAppsOnly')
+      fireEvent.click(checkbox)
+
+      expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
+    })
+  })
+
+  // -- Fetching next page skeleton --
+  describe('Pagination Loading', () => {
+    it('should show skeleton when fetching next page', () => {
+      mockPages = [createPage([createMockApp()])]
+      mockIsFetchingNextPage = true
+
+      renderList()
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+    })
+  })
+
+  // -- Dataset operator redirect --
+  describe('Dataset Operator Redirect', () => {
+    it('should redirect dataset operators to /datasets', () => {
+      mockIsCurrentWorkspaceDatasetOperator = true
+      renderList()
+
+      expect(mockRouterReplace).toHaveBeenCalledWith('/datasets')
+    })
+  })
+
+  // -- Multiple pages of data --
+  describe('Multi-page Data', () => {
+    it('should render apps from multiple pages', () => {
+      mockPages = [
+        createPage([
+          createMockApp({ id: 'app-1', name: 'Page One App' }),
+        ], true, 1),
+        createPage([
+          createMockApp({ id: 'app-2', name: 'Page Two App' }),
+        ], false, 2),
+      ]
+
+      renderList()
+
+      expect(screen.getByText('Page One App')).toBeInTheDocument()
+      expect(screen.getByText('Page Two App')).toBeInTheDocument()
+    })
+  })
+
+  // -- controlRefreshList triggers refetch --
+  describe('Refresh List', () => {
+    it('should call refetch when controlRefreshList increments', () => {
+      mockPages = [createPage([createMockApp()])]
+
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={1} />
+        </NuqsTestingAdapter>,
+      )
+
+      expect(mockRefetch).toHaveBeenCalled()
+    })
+  })
+})

web/__tests__/apps/create-app-flow.test.tsx

@@ -0,0 +1,464 @@
+/**
+ * Integration test: Create App Flow
+ *
+ * Tests the end-to-end user flows for creating new apps:
+ *   - Creating from blank via NewAppCard
+ *   - Creating from template via NewAppCard
+ *   - Creating from DSL import via NewAppCard
+ *   - Apps page top-level state management
+ */
+import type { AppListResponse } from '@/models/app'
+import type { App } from '@/types/app'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import List from '@/app/components/apps/list'
+import { AccessMode } from '@/models/access-control'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockIsCurrentWorkspaceDatasetOperator = false
+let mockIsLoadingCurrentWorkspace = false
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+let mockPages: AppListResponse[] = []
+let mockIsLoading = false
+let mockIsFetching = false
+const mockRefetch = vi.fn()
+const mockFetchNextPage = vi.fn()
+let mockShowTagManagementModal = false
+
+const mockRouterPush = vi.fn()
+const mockRouterReplace = vi.fn()
+const mockOnPlanInfoChanged = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+    replace: mockRouterReplace,
+  }),
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+    isCurrentWorkspaceDatasetOperator: mockIsCurrentWorkspaceDatasetOperator,
+    isLoadingCurrentWorkspace: mockIsLoadingCurrentWorkspace,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    return selector ? selector(state) : state
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: mockOnPlanInfoChanged,
+  }),
+}))
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: mockShowTagManagementModal,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/use-apps', () => ({
+  useInfiniteAppList: () => ({
+    data: { pages: mockPages },
+    isLoading: mockIsLoading,
+    isFetching: mockIsFetching,
+    isFetchingNextPage: false,
+    fetchNextPage: mockFetchNextPage,
+    hasNextPage: false,
+    error: null,
+    refetch: mockRefetch,
+  }),
+}))
+
+vi.mock('@/hooks/use-pay', () => ({
+  CheckModal: () => null,
+}))
+
+vi.mock('ahooks', async () => {
+  const actual = await vi.importActual<typeof import('ahooks')>('ahooks')
+  const React = await vi.importActual<typeof import('react')>('react')
+  return {
+    ...actual,
+    useDebounceFn: (fn: (...args: unknown[]) => void) => {
+      const fnRef = React.useRef(fn)
+      fnRef.current = fn
+      return {
+        run: (...args: unknown[]) => fnRef.current(...args),
+      }
+    },
+  }
+})
+
+// Mock dynamically loaded modals with test stubs
+vi.mock('next/dynamic', () => ({
+  default: (loader: () => Promise<{ default: React.ComponentType }>) => {
+    let Component: React.ComponentType<Record<string, unknown>> | null = null
+    loader().then((mod) => {
+      Component = mod.default as React.ComponentType<Record<string, unknown>>
+    }).catch(() => {})
+    const Wrapper = (props: Record<string, unknown>) => {
+      if (Component)
+        return <Component {...props} />
+      return null
+    }
+    Wrapper.displayName = 'DynamicWrapper'
+    return Wrapper
+  },
+}))
+
+vi.mock('@/app/components/app/create-app-modal', () => ({
+  default: ({ show, onClose, onSuccess, onCreateFromTemplate }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="create-app-modal">
+        <button data-testid="create-blank-confirm" onClick={onSuccess as () => void}>Create Blank</button>
+        {!!onCreateFromTemplate && (
+          <button data-testid="switch-to-template" onClick={onCreateFromTemplate as () => void}>From Template</button>
+        )}
+        <button data-testid="create-blank-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/create-app-dialog', () => ({
+  default: ({ show, onClose, onSuccess, onCreateFromBlank }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="template-dialog">
+        <button data-testid="template-confirm" onClick={onSuccess as () => void}>Create from Template</button>
+        {!!onCreateFromBlank && (
+          <button data-testid="switch-to-blank" onClick={onCreateFromBlank as () => void}>From Blank</button>
+        )}
+        <button data-testid="template-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/create-from-dsl-modal', () => ({
+  default: ({ show, onClose, onSuccess }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="create-from-dsl-modal">
+        <button data-testid="dsl-import-confirm" onClick={onSuccess as () => void}>Import DSL</button>
+        <button data-testid="dsl-import-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+  CreateFromDSLModalTab: {
+    FROM_URL: 'from-url',
+    FROM_FILE: 'from-file',
+  },
+}))
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'Test App',
+  description: overrides.description ?? 'A test app',
+  author_name: overrides.author_name ?? 'Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const createPage = (apps: App[]): AppListResponse => ({
+  data: apps,
+  has_more: false,
+  limit: 30,
+  page: 1,
+  total: apps.length,
+})
+
+const renderList = () => {
+  return render(
+    <NuqsTestingAdapter>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
+  )
+}
+
+describe('Create App Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockIsCurrentWorkspaceDatasetOperator = false
+    mockIsLoadingCurrentWorkspace = false
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+    mockPages = [createPage([createMockApp()])]
+    mockIsLoading = false
+    mockIsFetching = false
+    mockShowTagManagementModal = false
+  })
+
+  describe('NewAppCard Rendering', () => {
+    it('should render the "Create App" card with all options', () => {
+      renderList()
+
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+      expect(screen.getByText('app.newApp.startFromBlank')).toBeInTheDocument()
+      expect(screen.getByText('app.newApp.startFromTemplate')).toBeInTheDocument()
+      expect(screen.getByText('app.importDSL')).toBeInTheDocument()
+    })
+
+    it('should not render NewAppCard when user is not an editor', () => {
+      mockIsCurrentWorkspaceEditor = false
+      renderList()
+
+      expect(screen.queryByText('app.createApp')).not.toBeInTheDocument()
+    })
+
+    it('should show loading state when workspace is loading', () => {
+      mockIsLoadingCurrentWorkspace = true
+      renderList()
+
+      // NewAppCard renders but with loading style (pointer-events-none opacity-50)
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+  })
+
+  // -- Create from blank --
+  describe('Create from Blank Flow', () => {
+    it('should open the create app modal when "Start from Blank" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+    })
+
+    it('should close the create app modal on cancel', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('create-blank-cancel'))
+      await waitFor(() => {
+        expect(screen.queryByTestId('create-app-modal')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should call onPlanInfoChanged and refetch on successful creation', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('create-blank-confirm'))
+      await waitFor(() => {
+        expect(mockOnPlanInfoChanged).toHaveBeenCalled()
+        expect(mockRefetch).toHaveBeenCalled()
+      })
+    })
+  })
+
+  // -- Create from template --
+  describe('Create from Template Flow', () => {
+    it('should open template dialog when "Start from Template" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+      })
+    })
+
+    it('should allow switching from template to blank modal', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('switch-to-blank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+        expect(screen.queryByTestId('template-dialog')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should allow switching from blank to template dialog', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('switch-to-template'))
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+        expect(screen.queryByTestId('create-app-modal')).not.toBeInTheDocument()
+      })
+    })
+  })
+
+  // -- Create from DSL import (via NewAppCard button) --
+  describe('Create from DSL Import Flow', () => {
+    it('should open DSL import modal when "Import DSL" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+    })
+
+    it('should close DSL import modal on cancel', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('dsl-import-cancel'))
+      await waitFor(() => {
+        expect(screen.queryByTestId('create-from-dsl-modal')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should call onPlanInfoChanged and refetch on successful DSL import', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('dsl-import-confirm'))
+      await waitFor(() => {
+        expect(mockOnPlanInfoChanged).toHaveBeenCalled()
+        expect(mockRefetch).toHaveBeenCalled()
+      })
+    })
+  })
+
+  // -- DSL drag-and-drop flow (via List component) --
+  describe('DSL Drag-Drop Flow', () => {
+    it('should show drag-drop hint in the list', () => {
+      renderList()
+
+      expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
+    })
+
+    it('should open create-from-DSL modal when DSL file is dropped', async () => {
+      const { act } = await import('@testing-library/react')
+      renderList()
+
+      const container = document.querySelector('[class*="overflow-y-auto"]')
+      if (container) {
+        const yamlFile = new File(['app: test'], 'app.yaml', { type: 'application/yaml' })
+
+        // Simulate the full drag-drop sequence wrapped in act
+        await act(async () => {
+          const dragEnterEvent = new Event('dragenter', { bubbles: true })
+          Object.defineProperty(dragEnterEvent, 'dataTransfer', {
+            value: { types: ['Files'], files: [] },
+          })
+          Object.defineProperty(dragEnterEvent, 'preventDefault', { value: vi.fn() })
+          Object.defineProperty(dragEnterEvent, 'stopPropagation', { value: vi.fn() })
+          container.dispatchEvent(dragEnterEvent)
+
+          const dropEvent = new Event('drop', { bubbles: true })
+          Object.defineProperty(dropEvent, 'dataTransfer', {
+            value: { files: [yamlFile], types: ['Files'] },
+          })
+          Object.defineProperty(dropEvent, 'preventDefault', { value: vi.fn() })
+          Object.defineProperty(dropEvent, 'stopPropagation', { value: vi.fn() })
+          container.dispatchEvent(dropEvent)
+        })
+
+        await waitFor(() => {
+          const modal = screen.queryByTestId('create-from-dsl-modal')
+          if (modal)
+            expect(modal).toBeInTheDocument()
+        })
+      }
+    })
+  })
+
+  // -- Edge cases --
+  describe('Edge Cases', () => {
+    it('should not show create options when no data and user is editor', () => {
+      mockPages = [createPage([])]
+      renderList()
+
+      // NewAppCard should still be visible even with no apps
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+
+    it('should handle multiple rapid clicks on create buttons without crashing', async () => {
+      renderList()
+
+      // Rapidly click different create options
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+      fireEvent.click(screen.getByText('app.importDSL'))
+
+      // Should not crash, and some modal should be present
+      await waitFor(() => {
+        const anyModal = screen.queryByTestId('create-app-modal')
+          || screen.queryByTestId('template-dialog')
+          || screen.queryByTestId('create-from-dsl-modal')
+        expect(anyModal).toBeTruthy()
+      })
+    })
+  })
+})

web/__tests__/billing/billing-integration.test.tsx

@@ -0,0 +1,991 @@
+import type { UsagePlanInfo, UsageResetInfo } from '@/app/components/billing/type'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import AnnotationFull from '@/app/components/billing/annotation-full'
+import AnnotationFullModal from '@/app/components/billing/annotation-full/modal'
+import AppsFull from '@/app/components/billing/apps-full-in-dialog'
+import Billing from '@/app/components/billing/billing-page'
+import { defaultPlan, NUM_INFINITE } from '@/app/components/billing/config'
+import HeaderBillingBtn from '@/app/components/billing/header-billing-btn'
+import PlanComp from '@/app/components/billing/plan'
+import PlanUpgradeModal from '@/app/components/billing/plan-upgrade-modal'
+import PriorityLabel from '@/app/components/billing/priority-label'
+import TriggerEventsLimitModal from '@/app/components/billing/trigger-events-limit-modal'
+import { Plan } from '@/app/components/billing/type'
+import UpgradeBtn from '@/app/components/billing/upgrade-btn'
+import VectorSpaceFull from '@/app/components/billing/vector-space-full'
+
+let mockProviderCtx: Record<string, unknown> = {}
+let mockAppCtx: Record<string, unknown> = {}
+const mockSetShowPricingModal = vi.fn()
+const mockSetShowAccountSettingModal = vi.fn()
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => mockProviderCtx,
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => mockAppCtx,
+}))
+
+vi.mock('@/context/modal-context', () => ({
+  useModalContext: () => ({
+    setShowPricingModal: mockSetShowPricingModal,
+  }),
+  useModalContextSelector: (selector: (s: Record<string, unknown>) => unknown) =>
+    selector({
+      setShowAccountSettingModal: mockSetShowAccountSettingModal,
+    }),
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en-US',
+  useGetPricingPageLanguage: () => 'en',
+}))
+
+// ─── Service mocks ──────────────────────────────────────────────────────────
+const mockRefetch = vi.fn().mockResolvedValue({ data: 'https://billing.example.com' })
+vi.mock('@/service/use-billing', () => ({
+  useBillingUrl: () => ({
+    data: 'https://billing.example.com',
+    isFetching: false,
+    refetch: mockRefetch,
+  }),
+  useBindPartnerStackInfo: () => ({ mutateAsync: vi.fn() }),
+}))
+
+vi.mock('@/service/use-education', () => ({
+  useEducationVerify: () => ({
+    mutateAsync: vi.fn().mockResolvedValue({ token: 'test-token' }),
+    isPending: false,
+  }),
+}))
+
+// ─── Navigation mocks ───────────────────────────────────────────────────────
+const mockRouterPush = vi.fn()
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: mockRouterPush }),
+  usePathname: () => '/billing',
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => vi.fn(),
+}))
+
+// ─── External component mocks ───────────────────────────────────────────────
+vi.mock('@/app/education-apply/verify-state-modal', () => ({
+  default: ({ isShow }: { isShow: boolean }) =>
+    isShow ? <div data-testid="verify-state-modal" /> : null,
+}))
+
+vi.mock('@/app/components/header/utils/util', () => ({
+  mailToSupport: () => 'mailto:support@test.com',
+}))
+
+// ─── Test data factories ────────────────────────────────────────────────────
+type PlanOverrides = {
+  type?: string
+  usage?: Partial<UsagePlanInfo>
+  total?: Partial<UsagePlanInfo>
+  reset?: Partial<UsageResetInfo>
+}
+
+const createPlanData = (overrides: PlanOverrides = {}) => ({
+  ...defaultPlan,
+  ...overrides,
+  type: overrides.type ?? defaultPlan.type,
+  usage: { ...defaultPlan.usage, ...overrides.usage },
+  total: { ...defaultPlan.total, ...overrides.total },
+  reset: { ...defaultPlan.reset, ...overrides.reset },
+})
+
+const setupProviderContext = (planOverrides: PlanOverrides = {}, extra: Record<string, unknown> = {}) => {
+  mockProviderCtx = {
+    plan: createPlanData(planOverrides),
+    enableBilling: true,
+    isFetchedPlan: true,
+    enableEducationPlan: false,
+    isEducationAccount: false,
+    allowRefreshEducationVerify: false,
+    ...extra,
+  }
+}
+
+const setupAppContext = (overrides: Record<string, unknown> = {}) => {
+  mockAppCtx = {
+    isCurrentWorkspaceManager: true,
+    userProfile: { email: 'test@example.com' },
+    langGeniusVersionInfo: { current_version: '1.0.0' },
+    ...overrides,
+  }
+}
+
+// Vitest hoists vi.mock() calls, so imports above will use mocked modules
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. Billing Page + Plan Component Integration
+// Tests the full data flow: BillingPage → PlanComp → UsageInfo → ProgressBar
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Billing Page + Plan Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  // Verify that the billing page renders PlanComp with all 7 usage items
+  describe('Rendering complete plan information', () => {
+    it('should display all 7 usage metrics for sandbox plan', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: {
+          buildApps: 3,
+          teamMembers: 1,
+          documentsUploadQuota: 10,
+          vectorSpace: 20,
+          annotatedResponse: 5,
+          triggerEvents: 1000,
+          apiRateLimit: 2000,
+        },
+        total: {
+          buildApps: 5,
+          teamMembers: 1,
+          documentsUploadQuota: 50,
+          vectorSpace: 50,
+          annotatedResponse: 10,
+          triggerEvents: 3000,
+          apiRateLimit: 5000,
+        },
+      })
+
+      render(<Billing />)
+
+      // Plan name
+      expect(screen.getByText(/plans\.sandbox\.name/i)).toBeInTheDocument()
+
+      // All 7 usage items should be visible
+      expect(screen.getByText(/usagePage\.buildApps/i)).toBeInTheDocument()
+      expect(screen.getByText(/usagePage\.teamMembers/i)).toBeInTheDocument()
+      expect(screen.getByText(/usagePage\.documentsUploadQuota/i)).toBeInTheDocument()
+      expect(screen.getByText(/usagePage\.vectorSpace/i)).toBeInTheDocument()
+      expect(screen.getByText(/usagePage\.annotationQuota/i)).toBeInTheDocument()
+      expect(screen.getByText(/usagePage\.triggerEvents/i)).toBeInTheDocument()
+      expect(screen.getByText(/plansCommon\.apiRateLimit/i)).toBeInTheDocument()
+    })
+
+    it('should display usage values as "usage / total" format', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { buildApps: 3, teamMembers: 1 },
+        total: { buildApps: 5, teamMembers: 1 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Check that the buildApps usage fraction "3 / 5" is rendered
+      const usageContainers = screen.getAllByText('3')
+      expect(usageContainers.length).toBeGreaterThan(0)
+      const totalContainers = screen.getAllByText('5')
+      expect(totalContainers.length).toBeGreaterThan(0)
+    })
+
+    it('should show "unlimited" for infinite quotas (professional API rate limit)', () => {
+      setupProviderContext({
+        type: Plan.professional,
+        total: { apiRateLimit: NUM_INFINITE },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.getByText(/plansCommon\.unlimited/i)).toBeInTheDocument()
+    })
+
+    it('should display reset days for trigger events when applicable', () => {
+      setupProviderContext({
+        type: Plan.professional,
+        total: { triggerEvents: 20000 },
+        reset: { triggerEvents: 7 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Reset text should be visible
+      expect(screen.getByText(/usagePage\.resetsIn/i)).toBeInTheDocument()
+    })
+  })
+
+  // Verify billing URL button visibility and behavior
+  describe('Billing URL button', () => {
+    it('should show billing button when enableBilling and isCurrentWorkspaceManager', () => {
+      setupProviderContext({ type: Plan.sandbox })
+      setupAppContext({ isCurrentWorkspaceManager: true })
+
+      render(<Billing />)
+
+      expect(screen.getByText(/viewBillingTitle/i)).toBeInTheDocument()
+      expect(screen.getByText(/viewBillingAction/i)).toBeInTheDocument()
+    })
+
+    it('should hide billing button when user is not workspace manager', () => {
+      setupProviderContext({ type: Plan.sandbox })
+      setupAppContext({ isCurrentWorkspaceManager: false })
+
+      render(<Billing />)
+
+      expect(screen.queryByText(/viewBillingTitle/i)).not.toBeInTheDocument()
+    })
+
+    it('should hide billing button when billing is disabled', () => {
+      setupProviderContext({ type: Plan.sandbox }, { enableBilling: false })
+
+      render(<Billing />)
+
+      expect(screen.queryByText(/viewBillingTitle/i)).not.toBeInTheDocument()
+    })
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. Plan Type Display Integration
+// Tests that different plan types render correct visual elements
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Plan Type Display Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  it('should render sandbox plan with upgrade button (premium badge)', () => {
+    setupProviderContext({ type: Plan.sandbox })
+
+    render(<PlanComp loc="test" />)
+
+    expect(screen.getByText(/plans\.sandbox\.name/i)).toBeInTheDocument()
+    expect(screen.getByText(/plans\.sandbox\.for/i)).toBeInTheDocument()
+    // Sandbox shows premium badge upgrade button (not plain)
+    expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+  })
+
+  it('should render professional plan with plain upgrade button', () => {
+    setupProviderContext({ type: Plan.professional })
+
+    render(<PlanComp loc="test" />)
+
+    expect(screen.getByText(/plans\.professional\.name/i)).toBeInTheDocument()
+    // Professional shows plain button because it's not team
+    expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+  })
+
+  it('should render team plan with plain-style upgrade button', () => {
+    setupProviderContext({ type: Plan.team })
+
+    render(<PlanComp loc="test" />)
+
+    expect(screen.getByText(/plans\.team\.name/i)).toBeInTheDocument()
+    // Team plan has isPlain=true, so shows "upgradeBtn.plain" text
+    expect(screen.getByText(/upgradeBtn\.plain/i)).toBeInTheDocument()
+  })
+
+  it('should not render upgrade button for enterprise plan', () => {
+    setupProviderContext({ type: Plan.enterprise })
+
+    render(<PlanComp loc="test" />)
+
+    expect(screen.queryByText(/upgradeBtn\.encourageShort/i)).not.toBeInTheDocument()
+    expect(screen.queryByText(/upgradeBtn\.plain/i)).not.toBeInTheDocument()
+  })
+
+  it('should show education verify button when enableEducationPlan is true and not yet verified', () => {
+    setupProviderContext({ type: Plan.sandbox }, {
+      enableEducationPlan: true,
+      isEducationAccount: false,
+    })
+
+    render(<PlanComp loc="test" />)
+
+    expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. Upgrade Flow Integration
+// Tests the flow: UpgradeBtn click → setShowPricingModal
+// and PlanUpgradeModal → close + trigger pricing
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Upgrade Flow Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+    setupProviderContext({ type: Plan.sandbox })
+  })
+
+  // UpgradeBtn triggers pricing modal
+  describe('UpgradeBtn triggers pricing modal', () => {
+    it('should call setShowPricingModal when clicking premium badge upgrade button', async () => {
+      const user = userEvent.setup()
+
+      render(<UpgradeBtn />)
+
+      const badgeText = screen.getByText(/upgradeBtn\.encourage/i)
+      await user.click(badgeText)
+
+      expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call setShowPricingModal when clicking plain upgrade button', async () => {
+      const user = userEvent.setup()
+
+      render(<UpgradeBtn isPlain />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+    })
+
+    it('should use custom onClick when provided instead of setShowPricingModal', async () => {
+      const customOnClick = vi.fn()
+      const user = userEvent.setup()
+
+      render(<UpgradeBtn onClick={customOnClick} />)
+
+      const badgeText = screen.getByText(/upgradeBtn\.encourage/i)
+      await user.click(badgeText)
+
+      expect(customOnClick).toHaveBeenCalledTimes(1)
+      expect(mockSetShowPricingModal).not.toHaveBeenCalled()
+    })
+
+    it('should fire gtag event with loc parameter when clicked', async () => {
+      const mockGtag = vi.fn()
+      ;(window as unknown as Record<string, unknown>).gtag = mockGtag
+      const user = userEvent.setup()
+
+      render(<UpgradeBtn loc="billing-page" />)
+
+      const badgeText = screen.getByText(/upgradeBtn\.encourage/i)
+      await user.click(badgeText)
+
+      expect(mockGtag).toHaveBeenCalledWith('event', 'click_upgrade_btn', { loc: 'billing-page' })
+      delete (window as unknown as Record<string, unknown>).gtag
+    })
+  })
+
+  // PlanUpgradeModal integration: close modal and trigger pricing
+  describe('PlanUpgradeModal upgrade flow', () => {
+    it('should call onClose and setShowPricingModal when clicking upgrade button in modal', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <PlanUpgradeModal
+          show={true}
+          onClose={onClose}
+          title="Upgrade Required"
+          description="You need a better plan"
+        />,
+      )
+
+      // The modal should show title and description
+      expect(screen.getByText('Upgrade Required')).toBeInTheDocument()
+      expect(screen.getByText('You need a better plan')).toBeInTheDocument()
+
+      // Click the upgrade button inside the modal
+      const upgradeText = screen.getByText(/triggerLimitModal\.upgrade/i)
+      await user.click(upgradeText)
+
+      // Should close the current modal first
+      expect(onClose).toHaveBeenCalledTimes(1)
+      // Then open pricing modal
+      expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onClose and custom onUpgrade when provided', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+      const onUpgrade = vi.fn()
+
+      render(
+        <PlanUpgradeModal
+          show={true}
+          onClose={onClose}
+          onUpgrade={onUpgrade}
+          title="Test"
+          description="Test"
+        />,
+      )
+
+      const upgradeText = screen.getByText(/triggerLimitModal\.upgrade/i)
+      await user.click(upgradeText)
+
+      expect(onClose).toHaveBeenCalledTimes(1)
+      expect(onUpgrade).toHaveBeenCalledTimes(1)
+      // Custom onUpgrade replaces default setShowPricingModal
+      expect(mockSetShowPricingModal).not.toHaveBeenCalled()
+    })
+
+    it('should call onClose when clicking dismiss button', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <PlanUpgradeModal
+          show={true}
+          onClose={onClose}
+          title="Test"
+          description="Test"
+        />,
+      )
+
+      const dismissBtn = screen.getByText(/triggerLimitModal\.dismiss/i)
+      await user.click(dismissBtn)
+
+      expect(onClose).toHaveBeenCalledTimes(1)
+      expect(mockSetShowPricingModal).not.toHaveBeenCalled()
+    })
+  })
+
+  // Upgrade from PlanComp: clicking upgrade button in plan component triggers pricing
+  describe('PlanComp upgrade button triggers pricing', () => {
+    it('should open pricing modal when clicking upgrade in sandbox plan', async () => {
+      const user = userEvent.setup()
+      setupProviderContext({ type: Plan.sandbox })
+
+      render(<PlanComp loc="test-loc" />)
+
+      const upgradeText = screen.getByText(/upgradeBtn\.encourageShort/i)
+      await user.click(upgradeText)
+
+      expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+    })
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. Capacity Full Components Integration
+// Tests AppsFull, VectorSpaceFull, AnnotationFull, TriggerEventsLimitModal
+// with real child components (UsageInfo, ProgressBar, UpgradeBtn)
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Capacity Full Components Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  // AppsFull renders with correct messaging and components
+  describe('AppsFull integration', () => {
+    it('should display upgrade tip and upgrade button for sandbox plan at capacity', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { buildApps: 5 },
+        total: { buildApps: 5 },
+      })
+
+      render(<AppsFull loc="test" />)
+
+      // Should show "full" tip
+      expect(screen.getByText(/apps\.fullTip1$/i)).toBeInTheDocument()
+      // Should show upgrade button
+      expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+      // Should show usage/total fraction "5/5"
+      expect(screen.getByText(/5\/5/)).toBeInTheDocument()
+      // Should have a progress bar rendered
+      expect(screen.getByTestId('billing-progress-bar')).toBeInTheDocument()
+    })
+
+    it('should display upgrade tip and upgrade button for professional plan', () => {
+      setupProviderContext({
+        type: Plan.professional,
+        usage: { buildApps: 48 },
+        total: { buildApps: 50 },
+      })
+
+      render(<AppsFull loc="test" />)
+
+      expect(screen.getByText(/apps\.fullTip1$/i)).toBeInTheDocument()
+      expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+    })
+
+    it('should display contact tip and contact button for team plan', () => {
+      setupProviderContext({
+        type: Plan.team,
+        usage: { buildApps: 200 },
+        total: { buildApps: 200 },
+      })
+
+      render(<AppsFull loc="test" />)
+
+      // Team plan shows different tip
+      expect(screen.getByText(/apps\.fullTip2$/i)).toBeInTheDocument()
+      // Team plan shows "Contact Us" instead of upgrade
+      expect(screen.getByText(/apps\.contactUs/i)).toBeInTheDocument()
+      expect(screen.queryByText(/upgradeBtn\.encourageShort/i)).not.toBeInTheDocument()
+    })
+
+    it('should render progress bar with correct color based on usage percentage', () => {
+      // 100% usage should show error color
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { buildApps: 5 },
+        total: { buildApps: 5 },
+      })
+
+      render(<AppsFull loc="test" />)
+
+      const progressBar = screen.getByTestId('billing-progress-bar')
+      expect(progressBar).toHaveClass('bg-components-progress-error-progress')
+    })
+  })
+
+  // VectorSpaceFull renders with VectorSpaceInfo and UpgradeBtn
+  describe('VectorSpaceFull integration', () => {
+    it('should display full tip, upgrade button, and vector space usage info', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { vectorSpace: 50 },
+        total: { vectorSpace: 50 },
+      })
+
+      render(<VectorSpaceFull />)
+
+      // Should show full tip
+      expect(screen.getByText(/vectorSpace\.fullTip/i)).toBeInTheDocument()
+      expect(screen.getByText(/vectorSpace\.fullSolution/i)).toBeInTheDocument()
+      // Should show upgrade button
+      expect(screen.getByText(/upgradeBtn\.encourage$/i)).toBeInTheDocument()
+      // Should show vector space usage info
+      expect(screen.getByText(/usagePage\.vectorSpace/i)).toBeInTheDocument()
+    })
+  })
+
+  // AnnotationFull renders with Usage component and UpgradeBtn
+  describe('AnnotationFull integration', () => {
+    it('should display annotation full tip, upgrade button, and usage info', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { annotatedResponse: 10 },
+        total: { annotatedResponse: 10 },
+      })
+
+      render(<AnnotationFull />)
+
+      expect(screen.getByText(/annotatedResponse\.fullTipLine1/i)).toBeInTheDocument()
+      expect(screen.getByText(/annotatedResponse\.fullTipLine2/i)).toBeInTheDocument()
+      // UpgradeBtn rendered
+      expect(screen.getByText(/upgradeBtn\.encourage$/i)).toBeInTheDocument()
+      // Usage component should show annotation quota
+      expect(screen.getByText(/annotatedResponse\.quotaTitle/i)).toBeInTheDocument()
+    })
+  })
+
+  // AnnotationFullModal shows modal with usage and upgrade button
+  describe('AnnotationFullModal integration', () => {
+    it('should render modal with annotation info and upgrade button when show is true', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { annotatedResponse: 10 },
+        total: { annotatedResponse: 10 },
+      })
+
+      render(<AnnotationFullModal show={true} onHide={vi.fn()} />)
+
+      expect(screen.getByText(/annotatedResponse\.fullTipLine1/i)).toBeInTheDocument()
+      expect(screen.getByText(/annotatedResponse\.quotaTitle/i)).toBeInTheDocument()
+      expect(screen.getByText(/upgradeBtn\.encourage$/i)).toBeInTheDocument()
+    })
+
+    it('should not render content when show is false', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { annotatedResponse: 10 },
+        total: { annotatedResponse: 10 },
+      })
+
+      render(<AnnotationFullModal show={false} onHide={vi.fn()} />)
+
+      expect(screen.queryByText(/annotatedResponse\.fullTipLine1/i)).not.toBeInTheDocument()
+    })
+  })
+
+  // TriggerEventsLimitModal renders PlanUpgradeModal with embedded UsageInfo
+  describe('TriggerEventsLimitModal integration', () => {
+    it('should display trigger limit title, usage info, and upgrade button', () => {
+      setupProviderContext({ type: Plan.professional })
+
+      render(
+        <TriggerEventsLimitModal
+          show={true}
+          onClose={vi.fn()}
+          onUpgrade={vi.fn()}
+          usage={18000}
+          total={20000}
+          resetInDays={5}
+        />,
+      )
+
+      // Modal title and description
+      expect(screen.getByText(/triggerLimitModal\.title/i)).toBeInTheDocument()
+      expect(screen.getByText(/triggerLimitModal\.description/i)).toBeInTheDocument()
+      // Embedded UsageInfo with trigger events data
+      expect(screen.getByText(/triggerLimitModal\.usageTitle/i)).toBeInTheDocument()
+      expect(screen.getByText('18000')).toBeInTheDocument()
+      expect(screen.getByText('20000')).toBeInTheDocument()
+      // Reset info
+      expect(screen.getByText(/usagePage\.resetsIn/i)).toBeInTheDocument()
+      // Upgrade and dismiss buttons
+      expect(screen.getByText(/triggerLimitModal\.upgrade/i)).toBeInTheDocument()
+      expect(screen.getByText(/triggerLimitModal\.dismiss/i)).toBeInTheDocument()
+    })
+
+    it('should call onClose and onUpgrade when clicking upgrade', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+      const onUpgrade = vi.fn()
+      setupProviderContext({ type: Plan.professional })
+
+      render(
+        <TriggerEventsLimitModal
+          show={true}
+          onClose={onClose}
+          onUpgrade={onUpgrade}
+          usage={20000}
+          total={20000}
+        />,
+      )
+
+      const upgradeBtn = screen.getByText(/triggerLimitModal\.upgrade/i)
+      await user.click(upgradeBtn)
+
+      expect(onClose).toHaveBeenCalledTimes(1)
+      expect(onUpgrade).toHaveBeenCalledTimes(1)
+    })
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. Header Billing Button Integration
+// Tests HeaderBillingBtn behavior for different plan states
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Header Billing Button Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  it('should render UpgradeBtn (premium badge) for sandbox plan', () => {
+    setupProviderContext({ type: Plan.sandbox })
+
+    render(<HeaderBillingBtn />)
+
+    expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+  })
+
+  it('should render "pro" badge for professional plan', () => {
+    setupProviderContext({ type: Plan.professional })
+
+    render(<HeaderBillingBtn />)
+
+    expect(screen.getByText('pro')).toBeInTheDocument()
+    expect(screen.queryByText(/upgradeBtn/i)).not.toBeInTheDocument()
+  })
+
+  it('should render "team" badge for team plan', () => {
+    setupProviderContext({ type: Plan.team })
+
+    render(<HeaderBillingBtn />)
+
+    expect(screen.getByText('team')).toBeInTheDocument()
+  })
+
+  it('should return null when billing is disabled', () => {
+    setupProviderContext({ type: Plan.sandbox }, { enableBilling: false })
+
+    const { container } = render(<HeaderBillingBtn />)
+
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('should return null when plan is not fetched yet', () => {
+    setupProviderContext({ type: Plan.sandbox }, { isFetchedPlan: false })
+
+    const { container } = render(<HeaderBillingBtn />)
+
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('should call onClick when clicking pro/team badge in non-display-only mode', async () => {
+    const user = userEvent.setup()
+    const onClick = vi.fn()
+    setupProviderContext({ type: Plan.professional })
+
+    render(<HeaderBillingBtn onClick={onClick} />)
+
+    await user.click(screen.getByText('pro'))
+
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not call onClick when isDisplayOnly is true', async () => {
+    const user = userEvent.setup()
+    const onClick = vi.fn()
+    setupProviderContext({ type: Plan.professional })
+
+    render(<HeaderBillingBtn onClick={onClick} isDisplayOnly />)
+
+    await user.click(screen.getByText('pro'))
+
+    expect(onClick).not.toHaveBeenCalled()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. PriorityLabel Integration
+// Tests priority badge display for different plan types
+// ═══════════════════════════════════════════════════════════════════════════
+describe('PriorityLabel Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  it('should display "standard" priority for sandbox plan', () => {
+    setupProviderContext({ type: Plan.sandbox })
+
+    render(<PriorityLabel />)
+
+    expect(screen.getByText(/plansCommon\.priority\.standard/i)).toBeInTheDocument()
+  })
+
+  it('should display "priority" for professional plan with icon', () => {
+    setupProviderContext({ type: Plan.professional })
+
+    const { container } = render(<PriorityLabel />)
+
+    expect(screen.getByText(/plansCommon\.priority\.priority/i)).toBeInTheDocument()
+    // Professional plan should show the priority icon
+    expect(container.querySelector('svg')).toBeInTheDocument()
+  })
+
+  it('should display "top-priority" for team plan with icon', () => {
+    setupProviderContext({ type: Plan.team })
+
+    const { container } = render(<PriorityLabel />)
+
+    expect(screen.getByText(/plansCommon\.priority\.top-priority/i)).toBeInTheDocument()
+    expect(container.querySelector('svg')).toBeInTheDocument()
+  })
+
+  it('should display "top-priority" for enterprise plan', () => {
+    setupProviderContext({ type: Plan.enterprise })
+
+    render(<PriorityLabel />)
+
+    expect(screen.getByText(/plansCommon\.priority\.top-priority/i)).toBeInTheDocument()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. Usage Display Edge Cases
+// Tests storage mode, threshold logic, and progress bar color integration
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Usage Display Edge Cases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  // Vector space storage mode behavior
+  describe('VectorSpace storage mode in PlanComp', () => {
+    it('should show "< 50" for sandbox plan with low vector space usage', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { vectorSpace: 10 },
+        total: { vectorSpace: 50 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Storage mode: usage below threshold shows "< 50"
+      expect(screen.getByText(/</)).toBeInTheDocument()
+    })
+
+    it('should show indeterminate progress bar for usage below threshold', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { vectorSpace: 10 },
+        total: { vectorSpace: 50 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Should have an indeterminate progress bar
+      expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
+    })
+
+    it('should show actual usage for pro plan above threshold', () => {
+      setupProviderContext({
+        type: Plan.professional,
+        usage: { vectorSpace: 1024 },
+        total: { vectorSpace: 5120 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Pro plan above threshold shows actual value
+      expect(screen.getByText('1024')).toBeInTheDocument()
+    })
+  })
+
+  // Progress bar color logic through real components
+  describe('Progress bar color reflects usage severity', () => {
+    it('should show normal color for low usage percentage', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        usage: { buildApps: 1 },
+        total: { buildApps: 5 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // 20% usage - normal color
+      const progressBars = screen.getAllByTestId('billing-progress-bar')
+      // At least one should have the normal progress color
+      const hasNormalColor = progressBars.some(bar =>
+        bar.classList.contains('bg-components-progress-bar-progress-solid'),
+      )
+      expect(hasNormalColor).toBe(true)
+    })
+  })
+
+  // Reset days calculation in PlanComp
+  describe('Reset days integration', () => {
+    it('should not show reset for sandbox trigger events (no reset_date)', () => {
+      setupProviderContext({
+        type: Plan.sandbox,
+        total: { triggerEvents: 3000 },
+        reset: { triggerEvents: null },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Find the trigger events section - should not have reset text
+      const triggerSection = screen.getByText(/usagePage\.triggerEvents/i)
+      const parent = triggerSection.closest('[class*="flex flex-col"]')
+      // No reset text should appear (sandbox doesn't show reset for triggerEvents)
+      expect(parent?.textContent).not.toContain('usagePage.resetsIn')
+    })
+
+    it('should show reset for professional trigger events with reset date', () => {
+      setupProviderContext({
+        type: Plan.professional,
+        total: { triggerEvents: 20000 },
+        reset: { triggerEvents: 14 },
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Professional plan with finite triggerEvents should show reset
+      const resetTexts = screen.getAllByText(/usagePage\.resetsIn/i)
+      expect(resetTexts.length).toBeGreaterThan(0)
+    })
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 8. Cross-Component Upgrade Flow (End-to-End)
+// Tests the complete chain: capacity alert → upgrade button → pricing
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Cross-Component Upgrade Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setupAppContext()
+  })
+
+  it('should trigger pricing from AppsFull upgrade button', async () => {
+    const user = userEvent.setup()
+    setupProviderContext({
+      type: Plan.sandbox,
+      usage: { buildApps: 5 },
+      total: { buildApps: 5 },
+    })
+
+    render(<AppsFull loc="app-create" />)
+
+    const upgradeText = screen.getByText(/upgradeBtn\.encourageShort/i)
+    await user.click(upgradeText)
+
+    expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+  })
+
+  it('should trigger pricing from VectorSpaceFull upgrade button', async () => {
+    const user = userEvent.setup()
+    setupProviderContext({
+      type: Plan.sandbox,
+      usage: { vectorSpace: 50 },
+      total: { vectorSpace: 50 },
+    })
+
+    render(<VectorSpaceFull />)
+
+    const upgradeText = screen.getByText(/upgradeBtn\.encourage$/i)
+    await user.click(upgradeText)
+
+    expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+  })
+
+  it('should trigger pricing from AnnotationFull upgrade button', async () => {
+    const user = userEvent.setup()
+    setupProviderContext({
+      type: Plan.sandbox,
+      usage: { annotatedResponse: 10 },
+      total: { annotatedResponse: 10 },
+    })
+
+    render(<AnnotationFull />)
+
+    const upgradeText = screen.getByText(/upgradeBtn\.encourage$/i)
+    await user.click(upgradeText)
+
+    expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+  })
+
+  it('should trigger pricing from TriggerEventsLimitModal through PlanUpgradeModal', async () => {
+    const user = userEvent.setup()
+    const onClose = vi.fn()
+    setupProviderContext({ type: Plan.professional })
+
+    render(
+      <TriggerEventsLimitModal
+        show={true}
+        onClose={onClose}
+        onUpgrade={vi.fn()}
+        usage={20000}
+        total={20000}
+      />,
+    )
+
+    // TriggerEventsLimitModal passes onUpgrade to PlanUpgradeModal
+    // PlanUpgradeModal's upgrade button calls onClose then onUpgrade
+    const upgradeBtn = screen.getByText(/triggerLimitModal\.upgrade/i)
+    await user.click(upgradeBtn)
+
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('should trigger pricing from AnnotationFullModal upgrade button', async () => {
+    const user = userEvent.setup()
+    setupProviderContext({
+      type: Plan.sandbox,
+      usage: { annotatedResponse: 10 },
+      total: { annotatedResponse: 10 },
+    })
+
+    render(<AnnotationFullModal show={true} onHide={vi.fn()} />)
+
+    const upgradeText = screen.getByText(/upgradeBtn\.encourage$/i)
+    await user.click(upgradeText)
+
+    expect(mockSetShowPricingModal).toHaveBeenCalledTimes(1)
+  })
+})

web/__tests__/billing/cloud-plan-payment-flow.test.tsx

@@ -0,0 +1,296 @@
+/**
+ * Integration test: Cloud Plan Payment Flow
+ *
+ * Tests the payment flow for cloud plan items:
+ *   CloudPlanItem → Button click → permission check → fetch URL → redirect
+ *
+ * Covers plan comparison, downgrade prevention, monthly/yearly pricing,
+ * and workspace manager permission enforcement.
+ */
+import type { BasicPlan } from '@/app/components/billing/type'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import { ALL_PLANS } from '@/app/components/billing/config'
+import { PlanRange } from '@/app/components/billing/pricing/plan-switcher/plan-range-switcher'
+import CloudPlanItem from '@/app/components/billing/pricing/plans/cloud-plan-item'
+import { Plan } from '@/app/components/billing/type'
+
+// ─── Mock state ──────────────────────────────────────────────────────────────
+let mockAppCtx: Record<string, unknown> = {}
+const mockFetchSubscriptionUrls = vi.fn()
+const mockInvoices = vi.fn()
+const mockOpenAsyncWindow = vi.fn()
+const mockToastNotify = vi.fn()
+
+// ─── Context mocks ───────────────────────────────────────────────────────────
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => mockAppCtx,
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en-US',
+}))
+
+// ─── Service mocks ───────────────────────────────────────────────────────────
+vi.mock('@/service/billing', () => ({
+  fetchSubscriptionUrls: (...args: unknown[]) => mockFetchSubscriptionUrls(...args),
+}))
+
+vi.mock('@/service/client', () => ({
+  consoleClient: {
+    billing: {
+      invoices: () => mockInvoices(),
+    },
+  },
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => mockOpenAsyncWindow,
+}))
+
+vi.mock('@/app/components/base/toast', () => ({
+  default: { notify: (args: unknown) => mockToastNotify(args) },
+}))
+
+// ─── Navigation mocks ───────────────────────────────────────────────────────
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn() }),
+  usePathname: () => '/billing',
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const setupAppContext = (overrides: Record<string, unknown> = {}) => {
+  mockAppCtx = {
+    isCurrentWorkspaceManager: true,
+    ...overrides,
+  }
+}
+
+type RenderCloudPlanItemOptions = {
+  currentPlan?: BasicPlan
+  plan?: BasicPlan
+  planRange?: PlanRange
+  canPay?: boolean
+}
+
+const renderCloudPlanItem = ({
+  currentPlan = Plan.sandbox,
+  plan = Plan.professional,
+  planRange = PlanRange.monthly,
+  canPay = true,
+}: RenderCloudPlanItemOptions = {}) => {
+  return render(
+    <CloudPlanItem
+      currentPlan={currentPlan}
+      plan={plan}
+      planRange={planRange}
+      canPay={canPay}
+    />,
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+describe('Cloud Plan Payment Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+    setupAppContext()
+    mockFetchSubscriptionUrls.mockResolvedValue({ url: 'https://pay.example.com/checkout' })
+    mockInvoices.mockResolvedValue({ url: 'https://billing.example.com/invoices' })
+  })
+
+  // ─── 1. Plan Display ────────────────────────────────────────────────────
+  describe('Plan display', () => {
+    it('should render plan name and description', () => {
+      renderCloudPlanItem({ plan: Plan.professional })
+
+      expect(screen.getByText(/plans\.professional\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.professional\.description/i)).toBeInTheDocument()
+    })
+
+    it('should show "Free" price for sandbox plan', () => {
+      renderCloudPlanItem({ plan: Plan.sandbox })
+
+      expect(screen.getByText(/plansCommon\.free/i)).toBeInTheDocument()
+    })
+
+    it('should show monthly price for paid plans', () => {
+      renderCloudPlanItem({ plan: Plan.professional, planRange: PlanRange.monthly })
+
+      expect(screen.getByText(`$${ALL_PLANS.professional.price}`)).toBeInTheDocument()
+    })
+
+    it('should show yearly discounted price (10 months) and strikethrough original (12 months)', () => {
+      renderCloudPlanItem({ plan: Plan.professional, planRange: PlanRange.yearly })
+
+      const yearlyPrice = ALL_PLANS.professional.price * 10
+      const originalPrice = ALL_PLANS.professional.price * 12
+
+      expect(screen.getByText(`$${yearlyPrice}`)).toBeInTheDocument()
+      expect(screen.getByText(`$${originalPrice}`)).toBeInTheDocument()
+    })
+
+    it('should show "most popular" badge for professional plan', () => {
+      renderCloudPlanItem({ plan: Plan.professional })
+
+      expect(screen.getByText(/plansCommon\.mostPopular/i)).toBeInTheDocument()
+    })
+
+    it('should not show "most popular" badge for sandbox or team plans', () => {
+      const { unmount } = renderCloudPlanItem({ plan: Plan.sandbox })
+      expect(screen.queryByText(/plansCommon\.mostPopular/i)).not.toBeInTheDocument()
+      unmount()
+
+      renderCloudPlanItem({ plan: Plan.team })
+      expect(screen.queryByText(/plansCommon\.mostPopular/i)).not.toBeInTheDocument()
+    })
+  })
+
+  // ─── 2. Button Text Logic ───────────────────────────────────────────────
+  describe('Button text logic', () => {
+    it('should show "Current Plan" when plan matches current plan', () => {
+      renderCloudPlanItem({ currentPlan: Plan.professional, plan: Plan.professional })
+
+      expect(screen.getByText(/plansCommon\.currentPlan/i)).toBeInTheDocument()
+    })
+
+    it('should show "Start for Free" for sandbox plan when not current', () => {
+      renderCloudPlanItem({ currentPlan: Plan.professional, plan: Plan.sandbox })
+
+      expect(screen.getByText(/plansCommon\.startForFree/i)).toBeInTheDocument()
+    })
+
+    it('should show "Start Building" for professional plan when not current', () => {
+      renderCloudPlanItem({ currentPlan: Plan.sandbox, plan: Plan.professional })
+
+      expect(screen.getByText(/plansCommon\.startBuilding/i)).toBeInTheDocument()
+    })
+
+    it('should show "Get Started" for team plan when not current', () => {
+      renderCloudPlanItem({ currentPlan: Plan.sandbox, plan: Plan.team })
+
+      expect(screen.getByText(/plansCommon\.getStarted/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 3. Downgrade Prevention ────────────────────────────────────────────
+  describe('Downgrade prevention', () => {
+    it('should disable sandbox button when user is on professional plan (downgrade)', () => {
+      renderCloudPlanItem({ currentPlan: Plan.professional, plan: Plan.sandbox })
+
+      const button = screen.getByRole('button')
+      expect(button).toBeDisabled()
+    })
+
+    it('should disable sandbox and professional buttons when user is on team plan', () => {
+      const { unmount } = renderCloudPlanItem({ currentPlan: Plan.team, plan: Plan.sandbox })
+      expect(screen.getByRole('button')).toBeDisabled()
+      unmount()
+
+      renderCloudPlanItem({ currentPlan: Plan.team, plan: Plan.professional })
+      expect(screen.getByRole('button')).toBeDisabled()
+    })
+
+    it('should not disable current paid plan button (for invoice management)', () => {
+      renderCloudPlanItem({ currentPlan: Plan.professional, plan: Plan.professional })
+
+      const button = screen.getByRole('button')
+      expect(button).not.toBeDisabled()
+    })
+
+    it('should enable higher-tier plan buttons for upgrade', () => {
+      renderCloudPlanItem({ currentPlan: Plan.sandbox, plan: Plan.team })
+
+      const button = screen.getByRole('button')
+      expect(button).not.toBeDisabled()
+    })
+  })
+
+  // ─── 4. Payment URL Flow ────────────────────────────────────────────────
+  describe('Payment URL flow', () => {
+    it('should call fetchSubscriptionUrls with plan and "month" for monthly range', async () => {
+      const user = userEvent.setup()
+      // Simulate clicking on a professional plan button (user is on sandbox)
+      renderCloudPlanItem({
+        currentPlan: Plan.sandbox,
+        plan: Plan.professional,
+        planRange: PlanRange.monthly,
+      })
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockFetchSubscriptionUrls).toHaveBeenCalledWith(Plan.professional, 'month')
+      })
+    })
+
+    it('should call fetchSubscriptionUrls with plan and "year" for yearly range', async () => {
+      const user = userEvent.setup()
+      renderCloudPlanItem({
+        currentPlan: Plan.sandbox,
+        plan: Plan.team,
+        planRange: PlanRange.yearly,
+      })
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockFetchSubscriptionUrls).toHaveBeenCalledWith(Plan.team, 'year')
+      })
+    })
+
+    it('should open invoice management for current paid plan', async () => {
+      const user = userEvent.setup()
+      renderCloudPlanItem({ currentPlan: Plan.professional, plan: Plan.professional })
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockOpenAsyncWindow).toHaveBeenCalled()
+      })
+      // Should NOT call fetchSubscriptionUrls (invoice, not subscription)
+      expect(mockFetchSubscriptionUrls).not.toHaveBeenCalled()
+    })
+
+    it('should not do anything when clicking on sandbox free plan button', async () => {
+      const user = userEvent.setup()
+      renderCloudPlanItem({ currentPlan: Plan.sandbox, plan: Plan.sandbox })
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      // Wait a tick and verify no actions were taken
+      await waitFor(() => {
+        expect(mockFetchSubscriptionUrls).not.toHaveBeenCalled()
+        expect(mockOpenAsyncWindow).not.toHaveBeenCalled()
+      })
+    })
+  })
+
+  // ─── 5. Permission Check ────────────────────────────────────────────────
+  describe('Permission check', () => {
+    it('should show error toast when non-manager clicks upgrade button', async () => {
+      setupAppContext({ isCurrentWorkspaceManager: false })
+      const user = userEvent.setup()
+      renderCloudPlanItem({ currentPlan: Plan.sandbox, plan: Plan.professional })
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockToastNotify).toHaveBeenCalledWith(
+          expect.objectContaining({
+            type: 'error',
+          }),
+        )
+      })
+      // Should not proceed with payment
+      expect(mockFetchSubscriptionUrls).not.toHaveBeenCalled()
+    })
+  })
+})

web/__tests__/billing/education-verification-flow.test.tsx

@@ -0,0 +1,318 @@
+/**
+ * Integration test: Education Verification Flow
+ *
+ * Tests the education plan verification flow in PlanComp:
+ *   PlanComp → handleVerify → useEducationVerify → router.push → education-apply
+ *   PlanComp → handleVerify → error → show VerifyStateModal
+ *
+ * Also covers education button visibility based on context flags.
+ */
+import type { UsagePlanInfo, UsageResetInfo } from '@/app/components/billing/type'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import { defaultPlan } from '@/app/components/billing/config'
+import PlanComp from '@/app/components/billing/plan'
+import { Plan } from '@/app/components/billing/type'
+
+// ─── Mock state ──────────────────────────────────────────────────────────────
+let mockProviderCtx: Record<string, unknown> = {}
+let mockAppCtx: Record<string, unknown> = {}
+const mockSetShowPricingModal = vi.fn()
+const mockSetShowAccountSettingModal = vi.fn()
+const mockRouterPush = vi.fn()
+const mockMutateAsync = vi.fn()
+
+// ─── Context mocks ───────────────────────────────────────────────────────────
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => mockProviderCtx,
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => mockAppCtx,
+}))
+
+vi.mock('@/context/modal-context', () => ({
+  useModalContext: () => ({
+    setShowPricingModal: mockSetShowPricingModal,
+  }),
+  useModalContextSelector: (selector: (s: Record<string, unknown>) => unknown) =>
+    selector({
+      setShowAccountSettingModal: mockSetShowAccountSettingModal,
+    }),
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en-US',
+}))
+
+// ─── Service mocks ───────────────────────────────────────────────────────────
+vi.mock('@/service/use-education', () => ({
+  useEducationVerify: () => ({
+    mutateAsync: mockMutateAsync,
+    isPending: false,
+  }),
+}))
+
+vi.mock('@/service/use-billing', () => ({
+  useBillingUrl: () => ({
+    data: 'https://billing.example.com',
+    isFetching: false,
+    refetch: vi.fn(),
+  }),
+}))
+
+// ─── Navigation mocks ───────────────────────────────────────────────────────
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: mockRouterPush }),
+  usePathname: () => '/billing',
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => vi.fn(),
+}))
+
+// ─── External component mocks ───────────────────────────────────────────────
+vi.mock('@/app/education-apply/verify-state-modal', () => ({
+  default: ({ isShow, title, content, email, showLink }: {
+    isShow: boolean
+    title?: string
+    content?: string
+    email?: string
+    showLink?: boolean
+  }) =>
+    isShow
+      ? (
+          <div data-testid="verify-state-modal">
+            {title && <span data-testid="modal-title">{title}</span>}
+            {content && <span data-testid="modal-content">{content}</span>}
+            {email && <span data-testid="modal-email">{email}</span>}
+            {showLink && <span data-testid="modal-show-link">link</span>}
+          </div>
+        )
+      : null,
+}))
+
+// ─── Test data factories ────────────────────────────────────────────────────
+type PlanOverrides = {
+  type?: string
+  usage?: Partial<UsagePlanInfo>
+  total?: Partial<UsagePlanInfo>
+  reset?: Partial<UsageResetInfo>
+}
+
+const createPlanData = (overrides: PlanOverrides = {}) => ({
+  ...defaultPlan,
+  ...overrides,
+  type: overrides.type ?? defaultPlan.type,
+  usage: { ...defaultPlan.usage, ...overrides.usage },
+  total: { ...defaultPlan.total, ...overrides.total },
+  reset: { ...defaultPlan.reset, ...overrides.reset },
+})
+
+const setupContexts = (
+  planOverrides: PlanOverrides = {},
+  providerOverrides: Record<string, unknown> = {},
+  appOverrides: Record<string, unknown> = {},
+) => {
+  mockProviderCtx = {
+    plan: createPlanData(planOverrides),
+    enableBilling: true,
+    isFetchedPlan: true,
+    enableEducationPlan: false,
+    isEducationAccount: false,
+    allowRefreshEducationVerify: false,
+    ...providerOverrides,
+  }
+  mockAppCtx = {
+    isCurrentWorkspaceManager: true,
+    userProfile: { email: 'student@university.edu' },
+    langGeniusVersionInfo: { current_version: '1.0.0' },
+    ...appOverrides,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+describe('Education Verification Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+    setupContexts()
+  })
+
+  // ─── 1. Education Button Visibility ─────────────────────────────────────
+  describe('Education button visibility', () => {
+    it('should not show verify button when enableEducationPlan is false', () => {
+      setupContexts({}, { enableEducationPlan: false })
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.queryByText(/toVerified/i)).not.toBeInTheDocument()
+    })
+
+    it('should show verify button when enableEducationPlan is true and not yet verified', () => {
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+    })
+
+    it('should not show verify button when already verified and not about to expire', () => {
+      setupContexts({}, {
+        enableEducationPlan: true,
+        isEducationAccount: true,
+        allowRefreshEducationVerify: false,
+      })
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.queryByText(/toVerified/i)).not.toBeInTheDocument()
+    })
+
+    it('should show verify button when about to expire (allowRefreshEducationVerify is true)', () => {
+      setupContexts({}, {
+        enableEducationPlan: true,
+        isEducationAccount: true,
+        allowRefreshEducationVerify: true,
+      })
+
+      render(<PlanComp loc="test" />)
+
+      // Shown because isAboutToExpire = allowRefreshEducationVerify = true
+      expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 2. Successful Verification Flow ────────────────────────────────────
+  describe('Successful verification flow', () => {
+    it('should navigate to education-apply with token on successful verification', async () => {
+      mockMutateAsync.mockResolvedValue({ token: 'edu-token-123' })
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+      const user = userEvent.setup()
+
+      render(<PlanComp loc="test" />)
+
+      const verifyButton = screen.getByText(/toVerified/i)
+      await user.click(verifyButton)
+
+      await waitFor(() => {
+        expect(mockMutateAsync).toHaveBeenCalledTimes(1)
+        expect(mockRouterPush).toHaveBeenCalledWith('/education-apply?token=edu-token-123')
+      })
+    })
+
+    it('should remove education verifying flag from localStorage on success', async () => {
+      mockMutateAsync.mockResolvedValue({ token: 'token-xyz' })
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+      const user = userEvent.setup()
+
+      render(<PlanComp loc="test" />)
+
+      await user.click(screen.getByText(/toVerified/i))
+
+      await waitFor(() => {
+        expect(localStorage.removeItem).toHaveBeenCalledWith('educationVerifying')
+      })
+    })
+  })
+
+  // ─── 3. Failed Verification Flow ────────────────────────────────────────
+  describe('Failed verification flow', () => {
+    it('should show VerifyStateModal with rejection info on error', async () => {
+      mockMutateAsync.mockRejectedValue(new Error('Verification failed'))
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+      const user = userEvent.setup()
+
+      render(<PlanComp loc="test" />)
+
+      // Modal should not be visible initially
+      expect(screen.queryByTestId('verify-state-modal')).not.toBeInTheDocument()
+
+      const verifyButton = screen.getByText(/toVerified/i)
+      await user.click(verifyButton)
+
+      // Modal should appear after verification failure
+      await waitFor(() => {
+        expect(screen.getByTestId('verify-state-modal')).toBeInTheDocument()
+      })
+
+      // Modal should display rejection title and content
+      expect(screen.getByTestId('modal-title')).toHaveTextContent(/rejectTitle/i)
+      expect(screen.getByTestId('modal-content')).toHaveTextContent(/rejectContent/i)
+    })
+
+    it('should show email and link in VerifyStateModal', async () => {
+      mockMutateAsync.mockRejectedValue(new Error('fail'))
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+      const user = userEvent.setup()
+
+      render(<PlanComp loc="test" />)
+
+      await user.click(screen.getByText(/toVerified/i))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('modal-email')).toHaveTextContent('student@university.edu')
+        expect(screen.getByTestId('modal-show-link')).toBeInTheDocument()
+      })
+    })
+
+    it('should not redirect on verification failure', async () => {
+      mockMutateAsync.mockRejectedValue(new Error('fail'))
+      setupContexts({}, { enableEducationPlan: true, isEducationAccount: false })
+      const user = userEvent.setup()
+
+      render(<PlanComp loc="test" />)
+
+      await user.click(screen.getByText(/toVerified/i))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('verify-state-modal')).toBeInTheDocument()
+      })
+
+      // Should NOT navigate
+      expect(mockRouterPush).not.toHaveBeenCalled()
+    })
+  })
+
+  // ─── 4. Education + Upgrade Coexistence ─────────────────────────────────
+  describe('Education and upgrade button coexistence', () => {
+    it('should show both education verify and upgrade buttons for sandbox user', () => {
+      setupContexts(
+        { type: Plan.sandbox },
+        { enableEducationPlan: true, isEducationAccount: false },
+      )
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+      expect(screen.getByText(/upgradeBtn\.encourageShort/i)).toBeInTheDocument()
+    })
+
+    it('should not show upgrade button for enterprise plan', () => {
+      setupContexts(
+        { type: Plan.enterprise },
+        { enableEducationPlan: true, isEducationAccount: false },
+      )
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+      expect(screen.queryByText(/upgradeBtn\.encourageShort/i)).not.toBeInTheDocument()
+      expect(screen.queryByText(/upgradeBtn\.plain/i)).not.toBeInTheDocument()
+    })
+
+    it('should show team plan with plain upgrade button and education button', () => {
+      setupContexts(
+        { type: Plan.team },
+        { enableEducationPlan: true, isEducationAccount: false },
+      )
+
+      render(<PlanComp loc="test" />)
+
+      expect(screen.getByText(/toVerified/i)).toBeInTheDocument()
+      expect(screen.getByText(/upgradeBtn\.plain/i)).toBeInTheDocument()
+    })
+  })
+})

web/__tests__/billing/partner-stack-flow.test.tsx

@@ -0,0 +1,326 @@
+/**
+ * Integration test: Partner Stack Flow
+ *
+ * Tests the PartnerStack integration:
+ *   PartnerStack component → usePSInfo hook → cookie management → bind API call
+ *
+ * Covers URL param reading, cookie persistence, API bind on mount,
+ * cookie cleanup after successful bind, and error handling for 400 status.
+ */
+import { act, cleanup, render, renderHook, waitFor } from '@testing-library/react'
+import Cookies from 'js-cookie'
+import * as React from 'react'
+import usePSInfo from '@/app/components/billing/partner-stack/use-ps-info'
+import { PARTNER_STACK_CONFIG } from '@/config'
+
+// ─── Mock state ──────────────────────────────────────────────────────────────
+let mockSearchParams = new URLSearchParams()
+const mockMutateAsync = vi.fn()
+
+// ─── Module mocks ────────────────────────────────────────────────────────────
+vi.mock('next/navigation', () => ({
+  useSearchParams: () => mockSearchParams,
+  useRouter: () => ({ push: vi.fn() }),
+  usePathname: () => '/',
+}))
+
+vi.mock('@/service/use-billing', () => ({
+  useBindPartnerStackInfo: () => ({
+    mutateAsync: mockMutateAsync,
+  }),
+  useBillingUrl: () => ({
+    data: '',
+    isFetching: false,
+    refetch: vi.fn(),
+  }),
+}))
+
+vi.mock('@/config', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    IS_CLOUD_EDITION: true,
+    PARTNER_STACK_CONFIG: {
+      cookieName: 'partner_stack_info',
+      saveCookieDays: 90,
+    },
+  }
+})
+
+// ─── Cookie helpers ──────────────────────────────────────────────────────────
+const getCookieData = () => {
+  const raw = Cookies.get(PARTNER_STACK_CONFIG.cookieName)
+  if (!raw)
+    return null
+  try {
+    return JSON.parse(raw)
+  }
+  catch {
+    return null
+  }
+}
+
+const setCookieData = (data: Record<string, string>) => {
+  Cookies.set(PARTNER_STACK_CONFIG.cookieName, JSON.stringify(data))
+}
+
+const clearCookie = () => {
+  Cookies.remove(PARTNER_STACK_CONFIG.cookieName)
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+describe('Partner Stack Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+    clearCookie()
+    mockSearchParams = new URLSearchParams()
+    mockMutateAsync.mockResolvedValue({})
+  })
+
+  // ─── 1. URL Param Reading ───────────────────────────────────────────────
+  describe('URL param reading', () => {
+    it('should read ps_partner_key and ps_xid from URL search params', () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'partner-123',
+        ps_xid: 'click-456',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+
+      expect(result.current.psPartnerKey).toBe('partner-123')
+      expect(result.current.psClickId).toBe('click-456')
+    })
+
+    it('should fall back to cookie when URL params are not present', () => {
+      setCookieData({ partnerKey: 'cookie-partner', clickId: 'cookie-click' })
+
+      const { result } = renderHook(() => usePSInfo())
+
+      expect(result.current.psPartnerKey).toBe('cookie-partner')
+      expect(result.current.psClickId).toBe('cookie-click')
+    })
+
+    it('should prefer URL params over cookie values', () => {
+      setCookieData({ partnerKey: 'cookie-partner', clickId: 'cookie-click' })
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'url-partner',
+        ps_xid: 'url-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+
+      expect(result.current.psPartnerKey).toBe('url-partner')
+      expect(result.current.psClickId).toBe('url-click')
+    })
+
+    it('should return null for both values when no params and no cookie', () => {
+      const { result } = renderHook(() => usePSInfo())
+
+      expect(result.current.psPartnerKey).toBeUndefined()
+      expect(result.current.psClickId).toBeUndefined()
+    })
+  })
+
+  // ─── 2. Cookie Persistence (saveOrUpdate) ───────────────────────────────
+  describe('Cookie persistence via saveOrUpdate', () => {
+    it('should save PS info to cookie when URL params provide new values', () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'new-partner',
+        ps_xid: 'new-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      act(() => result.current.saveOrUpdate())
+
+      const cookieData = getCookieData()
+      expect(cookieData).toEqual({
+        partnerKey: 'new-partner',
+        clickId: 'new-click',
+      })
+    })
+
+    it('should not update cookie when values have not changed', () => {
+      setCookieData({ partnerKey: 'same-partner', clickId: 'same-click' })
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'same-partner',
+        ps_xid: 'same-click',
+      })
+
+      const cookieSetSpy = vi.spyOn(Cookies, 'set')
+      const { result } = renderHook(() => usePSInfo())
+      act(() => result.current.saveOrUpdate())
+
+      // Should not call set because values haven't changed
+      expect(cookieSetSpy).not.toHaveBeenCalled()
+      cookieSetSpy.mockRestore()
+    })
+
+    it('should not save to cookie when partner key is missing', () => {
+      mockSearchParams = new URLSearchParams({
+        ps_xid: 'click-only',
+      })
+
+      const cookieSetSpy = vi.spyOn(Cookies, 'set')
+      const { result } = renderHook(() => usePSInfo())
+      act(() => result.current.saveOrUpdate())
+
+      expect(cookieSetSpy).not.toHaveBeenCalled()
+      cookieSetSpy.mockRestore()
+    })
+
+    it('should not save to cookie when click ID is missing', () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'partner-only',
+      })
+
+      const cookieSetSpy = vi.spyOn(Cookies, 'set')
+      const { result } = renderHook(() => usePSInfo())
+      act(() => result.current.saveOrUpdate())
+
+      expect(cookieSetSpy).not.toHaveBeenCalled()
+      cookieSetSpy.mockRestore()
+    })
+  })
+
+  // ─── 3. Bind API Flow ──────────────────────────────────────────────────
+  describe('Bind API flow', () => {
+    it('should call mutateAsync with partnerKey and clickId on bind', async () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'bind-partner',
+        ps_xid: 'bind-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      await act(async () => {
+        await result.current.bind()
+      })
+
+      expect(mockMutateAsync).toHaveBeenCalledWith({
+        partnerKey: 'bind-partner',
+        clickId: 'bind-click',
+      })
+    })
+
+    it('should remove cookie after successful bind', async () => {
+      setCookieData({ partnerKey: 'rm-partner', clickId: 'rm-click' })
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'rm-partner',
+        ps_xid: 'rm-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      await act(async () => {
+        await result.current.bind()
+      })
+
+      // Cookie should be removed after successful bind
+      expect(Cookies.get(PARTNER_STACK_CONFIG.cookieName)).toBeUndefined()
+    })
+
+    it('should remove cookie on 400 error (already bound)', async () => {
+      mockMutateAsync.mockRejectedValue({ status: 400 })
+      setCookieData({ partnerKey: 'err-partner', clickId: 'err-click' })
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'err-partner',
+        ps_xid: 'err-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      await act(async () => {
+        await result.current.bind()
+      })
+
+      // Cookie should be removed even on 400
+      expect(Cookies.get(PARTNER_STACK_CONFIG.cookieName)).toBeUndefined()
+    })
+
+    it('should not remove cookie on non-400 errors', async () => {
+      mockMutateAsync.mockRejectedValue({ status: 500 })
+      setCookieData({ partnerKey: 'keep-partner', clickId: 'keep-click' })
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'keep-partner',
+        ps_xid: 'keep-click',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      await act(async () => {
+        await result.current.bind()
+      })
+
+      // Cookie should still exist for non-400 errors
+      const cookieData = getCookieData()
+      expect(cookieData).toBeTruthy()
+    })
+
+    it('should not call bind when partner key is missing', async () => {
+      mockSearchParams = new URLSearchParams({
+        ps_xid: 'click-only',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+      await act(async () => {
+        await result.current.bind()
+      })
+
+      expect(mockMutateAsync).not.toHaveBeenCalled()
+    })
+
+    it('should not call bind a second time (idempotency)', async () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'partner-once',
+        ps_xid: 'click-once',
+      })
+
+      const { result } = renderHook(() => usePSInfo())
+
+      // First bind
+      await act(async () => {
+        await result.current.bind()
+      })
+      expect(mockMutateAsync).toHaveBeenCalledTimes(1)
+
+      // Second bind should be skipped (hasBind = true)
+      await act(async () => {
+        await result.current.bind()
+      })
+      expect(mockMutateAsync).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  // ─── 4. PartnerStack Component Mount ────────────────────────────────────
+  describe('PartnerStack component mount behavior', () => {
+    it('should call saveOrUpdate and bind on mount when IS_CLOUD_EDITION is true', async () => {
+      mockSearchParams = new URLSearchParams({
+        ps_partner_key: 'mount-partner',
+        ps_xid: 'mount-click',
+      })
+
+      // Use lazy import so the mocks are applied
+      const { default: PartnerStack } = await import('@/app/components/billing/partner-stack')
+
+      render(<PartnerStack />)
+
+      // The component calls saveOrUpdate and bind in useEffect
+      await waitFor(() => {
+        // Bind should have been called
+        expect(mockMutateAsync).toHaveBeenCalledWith({
+          partnerKey: 'mount-partner',
+          clickId: 'mount-click',
+        })
+      })
+
+      // Cookie should have been saved (saveOrUpdate was called before bind)
+      // After bind succeeds, cookie is removed
+      expect(Cookies.get(PARTNER_STACK_CONFIG.cookieName)).toBeUndefined()
+    })
+
+    it('should render nothing (return null)', async () => {
+      const { default: PartnerStack } = await import('@/app/components/billing/partner-stack')
+
+      const { container } = render(<PartnerStack />)
+
+      expect(container.innerHTML).toBe('')
+    })
+  })
+})

web/__tests__/billing/pricing-modal-flow.test.tsx

@@ -0,0 +1,327 @@
+/**
+ * Integration test: Pricing Modal Flow
+ *
+ * Tests the full Pricing modal lifecycle:
+ *   Pricing → PlanSwitcher (category + range toggle) → Plans (cloud / self-hosted)
+ *   → CloudPlanItem / SelfHostedPlanItem → Footer
+ *
+ * Validates cross-component state propagation when the user switches between
+ * cloud / self-hosted categories and monthly / yearly plan ranges.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import { ALL_PLANS } from '@/app/components/billing/config'
+import Pricing from '@/app/components/billing/pricing'
+import { Plan } from '@/app/components/billing/type'
+
+// ─── Mock state ──────────────────────────────────────────────────────────────
+let mockProviderCtx: Record<string, unknown> = {}
+let mockAppCtx: Record<string, unknown> = {}
+
+// ─── Context mocks ───────────────────────────────────────────────────────────
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => mockProviderCtx,
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => mockAppCtx,
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en-US',
+  useGetPricingPageLanguage: () => 'en',
+}))
+
+// ─── Service mocks ───────────────────────────────────────────────────────────
+vi.mock('@/service/billing', () => ({
+  fetchSubscriptionUrls: vi.fn().mockResolvedValue({ url: 'https://pay.example.com' }),
+}))
+
+vi.mock('@/service/client', () => ({
+  consoleClient: {
+    billing: {
+      invoices: vi.fn().mockResolvedValue({ url: 'https://invoice.example.com' }),
+    },
+  },
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => vi.fn(),
+}))
+
+// ─── Navigation mocks ───────────────────────────────────────────────────────
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn() }),
+  usePathname: () => '/billing',
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+// ─── External component mocks (lightweight) ─────────────────────────────────
+vi.mock('@/app/components/base/icons/src/public/billing', () => ({
+  Azure: () => <span data-testid="icon-azure" />,
+  GoogleCloud: () => <span data-testid="icon-gcloud" />,
+  AwsMarketplaceLight: () => <span data-testid="icon-aws-light" />,
+  AwsMarketplaceDark: () => <span data-testid="icon-aws-dark" />,
+}))
+
+vi.mock('@/hooks/use-theme', () => ({
+  default: () => ({ theme: 'light' }),
+  useTheme: () => ({ theme: 'light' }),
+}))
+
+// Self-hosted List uses t() with returnObjects which returns string in mock;
+// mock it to avoid deep i18n dependency (unit tests cover this component)
+vi.mock('@/app/components/billing/pricing/plans/self-hosted-plan-item/list', () => ({
+  default: ({ plan }: { plan: string }) => (
+    <div data-testid={`self-hosted-list-${plan}`}>Features</div>
+  ),
+}))
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const defaultPlanData = {
+  type: Plan.sandbox,
+  usage: {
+    buildApps: 1,
+    teamMembers: 1,
+    documentsUploadQuota: 0,
+    vectorSpace: 10,
+    annotatedResponse: 1,
+    triggerEvents: 0,
+    apiRateLimit: 0,
+  },
+  total: {
+    buildApps: 5,
+    teamMembers: 1,
+    documentsUploadQuota: 50,
+    vectorSpace: 50,
+    annotatedResponse: 10,
+    triggerEvents: 3000,
+    apiRateLimit: 5000,
+  },
+}
+
+const setupContexts = (planOverrides: Record<string, unknown> = {}, appOverrides: Record<string, unknown> = {}) => {
+  mockProviderCtx = {
+    plan: { ...defaultPlanData, ...planOverrides },
+    enableBilling: true,
+    isFetchedPlan: true,
+    enableEducationPlan: false,
+    isEducationAccount: false,
+    allowRefreshEducationVerify: false,
+  }
+  mockAppCtx = {
+    isCurrentWorkspaceManager: true,
+    userProfile: { email: 'test@example.com' },
+    langGeniusVersionInfo: { current_version: '1.0.0' },
+    ...appOverrides,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+describe('Pricing Modal Flow', () => {
+  const onCancel = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+    setupContexts()
+  })
+
+  // ─── 1. Initial Rendering ────────────────────────────────────────────────
+  describe('Initial rendering', () => {
+    it('should render header with close button and footer with pricing link', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      // Header close button exists (multiple plan buttons also exist)
+      const buttons = screen.getAllByRole('button')
+      expect(buttons.length).toBeGreaterThanOrEqual(1)
+      // Footer pricing link
+      expect(screen.getByText(/plansCommon\.comparePlanAndFeatures/i)).toBeInTheDocument()
+    })
+
+    it('should default to cloud category with three cloud plans', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      // Three cloud plans: sandbox, professional, team
+      expect(screen.getByText(/plans\.sandbox\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.professional\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.team\.name/i)).toBeInTheDocument()
+    })
+
+    it('should show plan range switcher (annual billing toggle) by default for cloud', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      expect(screen.getByText(/plansCommon\.annualBilling/i)).toBeInTheDocument()
+    })
+
+    it('should show tax tip in footer for cloud category', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      // Use exact match to avoid matching taxTipSecond
+      expect(screen.getByText('billing.plansCommon.taxTip')).toBeInTheDocument()
+      expect(screen.getByText('billing.plansCommon.taxTipSecond')).toBeInTheDocument()
+    })
+  })
+
+  // ─── 2. Category Switching ───────────────────────────────────────────────
+  describe('Category switching', () => {
+    it('should switch to self-hosted plans when clicking self-hosted tab', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      // Click the self-hosted tab
+      const selfTab = screen.getByText(/plansCommon\.self/i)
+      await user.click(selfTab)
+
+      // Self-hosted plans should appear
+      expect(screen.getByText(/plans\.community\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.premium\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.enterprise\.name/i)).toBeInTheDocument()
+
+      // Cloud plans should disappear
+      expect(screen.queryByText(/plans\.sandbox\.name/i)).not.toBeInTheDocument()
+    })
+
+    it('should hide plan range switcher for self-hosted category', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      await user.click(screen.getByText(/plansCommon\.self/i))
+
+      // Annual billing toggle should not be visible
+      expect(screen.queryByText(/plansCommon\.annualBilling/i)).not.toBeInTheDocument()
+    })
+
+    it('should hide tax tip in footer for self-hosted category', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      await user.click(screen.getByText(/plansCommon\.self/i))
+
+      expect(screen.queryByText('billing.plansCommon.taxTip')).not.toBeInTheDocument()
+    })
+
+    it('should switch back to cloud plans when clicking cloud tab', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      // Switch to self-hosted
+      await user.click(screen.getByText(/plansCommon\.self/i))
+      expect(screen.queryByText(/plans\.sandbox\.name/i)).not.toBeInTheDocument()
+
+      // Switch back to cloud
+      await user.click(screen.getByText(/plansCommon\.cloud/i))
+      expect(screen.getByText(/plans\.sandbox\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plansCommon\.annualBilling/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 3. Plan Range Switching (Monthly ↔ Yearly) ──────────────────────────
+  describe('Plan range switching', () => {
+    it('should show monthly prices by default', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      // Professional monthly price: $59
+      const proPriceStr = `$${ALL_PLANS.professional.price}`
+      expect(screen.getByText(proPriceStr)).toBeInTheDocument()
+
+      // Team monthly price: $159
+      const teamPriceStr = `$${ALL_PLANS.team.price}`
+      expect(screen.getByText(teamPriceStr)).toBeInTheDocument()
+    })
+
+    it('should show "Free" for sandbox plan regardless of range', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      expect(screen.getByText(/plansCommon\.free/i)).toBeInTheDocument()
+    })
+
+    it('should show "most popular" badge only for professional plan', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      expect(screen.getByText(/plansCommon\.mostPopular/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 4. Cloud Plan Button States ─────────────────────────────────────────
+  describe('Cloud plan button states', () => {
+    it('should show "Current Plan" for the current plan (sandbox)', () => {
+      setupContexts({ type: Plan.sandbox })
+      render(<Pricing onCancel={onCancel} />)
+
+      expect(screen.getByText(/plansCommon\.currentPlan/i)).toBeInTheDocument()
+    })
+
+    it('should show specific button text for non-current plans', () => {
+      setupContexts({ type: Plan.sandbox })
+      render(<Pricing onCancel={onCancel} />)
+
+      // Professional button text
+      expect(screen.getByText(/plansCommon\.startBuilding/i)).toBeInTheDocument()
+      // Team button text
+      expect(screen.getByText(/plansCommon\.getStarted/i)).toBeInTheDocument()
+    })
+
+    it('should mark sandbox as "Current Plan" for professional user (enterprise normalized to team)', () => {
+      setupContexts({ type: Plan.enterprise })
+      render(<Pricing onCancel={onCancel} />)
+
+      // Enterprise is normalized to team for display, so team is "Current Plan"
+      expect(screen.getByText(/plansCommon\.currentPlan/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 5. Self-Hosted Plan Details ─────────────────────────────────────────
+  describe('Self-hosted plan details', () => {
+    it('should show cloud provider icons only for premium plan', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      await user.click(screen.getByText(/plansCommon\.self/i))
+
+      // Premium plan should show Azure and Google Cloud icons
+      expect(screen.getByTestId('icon-azure')).toBeInTheDocument()
+      expect(screen.getByTestId('icon-gcloud')).toBeInTheDocument()
+    })
+
+    it('should show "coming soon" text for premium plan cloud providers', async () => {
+      const user = userEvent.setup()
+      render(<Pricing onCancel={onCancel} />)
+
+      await user.click(screen.getByText(/plansCommon\.self/i))
+
+      expect(screen.getByText(/plans\.premium\.comingSoon/i)).toBeInTheDocument()
+    })
+  })
+
+  // ─── 6. Close Handling ───────────────────────────────────────────────────
+  describe('Close handling', () => {
+    it('should call onCancel when pressing ESC key', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      // ahooks useKeyPress listens on document for keydown events
+      document.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        code: 'Escape',
+        keyCode: 27,
+        bubbles: true,
+      }))
+
+      expect(onCancel).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  // ─── 7. Pricing URL ─────────────────────────────────────────────────────
+  describe('Pricing page URL', () => {
+    it('should render pricing link with correct URL', () => {
+      render(<Pricing onCancel={onCancel} />)
+
+      const link = screen.getByText(/plansCommon\.comparePlanAndFeatures/i)
+      expect(link.closest('a')).toHaveAttribute(
+        'href',
+        'https://dify.ai/en/pricing#plans-and-features',
+      )
+    })
+  })
+})

web/__tests__/billing/self-hosted-plan-flow.test.tsx

@@ -0,0 +1,225 @@
+/**
+ * Integration test: Self-Hosted Plan Flow
+ *
+ * Tests the self-hosted plan items:
+ *   SelfHostedPlanItem → Button click → permission check → redirect to external URL
+ *
+ * Covers community/premium/enterprise plan rendering, external URL navigation,
+ * and workspace manager permission enforcement.
+ */
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import { contactSalesUrl, getStartedWithCommunityUrl, getWithPremiumUrl } from '@/app/components/billing/config'
+import SelfHostedPlanItem from '@/app/components/billing/pricing/plans/self-hosted-plan-item'
+import { SelfHostedPlan } from '@/app/components/billing/type'
+
+let mockAppCtx: Record<string, unknown> = {}
+const mockToastNotify = vi.fn()
+
+const originalLocation = window.location
+let assignedHref = ''
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => mockAppCtx,
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en-US',
+}))
+
+vi.mock('@/hooks/use-theme', () => ({
+  default: () => ({ theme: 'light' }),
+  useTheme: () => ({ theme: 'light' }),
+}))
+
+vi.mock('@/app/components/base/icons/src/public/billing', () => ({
+  Azure: () => <span data-testid="icon-azure" />,
+  GoogleCloud: () => <span data-testid="icon-gcloud" />,
+  AwsMarketplaceLight: () => <span data-testid="icon-aws-light" />,
+  AwsMarketplaceDark: () => <span data-testid="icon-aws-dark" />,
+}))
+
+vi.mock('@/app/components/base/toast', () => ({
+  default: { notify: (args: unknown) => mockToastNotify(args) },
+}))
+
+vi.mock('@/app/components/billing/pricing/plans/self-hosted-plan-item/list', () => ({
+  default: ({ plan }: { plan: string }) => (
+    <div data-testid={`self-hosted-list-${plan}`}>Features</div>
+  ),
+}))
+
+const setupAppContext = (overrides: Record<string, unknown> = {}) => {
+  mockAppCtx = {
+    isCurrentWorkspaceManager: true,
+    ...overrides,
+  }
+}
+
+describe('Self-Hosted Plan Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+    setupAppContext()
+
+    // Mock window.location with minimal getter/setter (Location props are non-enumerable)
+    assignedHref = ''
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: {
+        get href() { return assignedHref },
+        set href(value: string) { assignedHref = value },
+      },
+    })
+  })
+
+  afterEach(() => {
+    // Restore original location
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: originalLocation,
+    })
+  })
+
+  // ─── 1. Plan Rendering ──────────────────────────────────────────────────
+  describe('Plan rendering', () => {
+    it('should render community plan with name and description', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.community} />)
+
+      expect(screen.getByText(/plans\.community\.name/i)).toBeInTheDocument()
+      expect(screen.getByText(/plans\.community\.description/i)).toBeInTheDocument()
+    })
+
+    it('should render premium plan with cloud provider icons', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+
+      expect(screen.getByText(/plans\.premium\.name/i)).toBeInTheDocument()
+      expect(screen.getByTestId('icon-azure')).toBeInTheDocument()
+      expect(screen.getByTestId('icon-gcloud')).toBeInTheDocument()
+    })
+
+    it('should render enterprise plan without cloud provider icons', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.enterprise} />)
+
+      expect(screen.getByText(/plans\.enterprise\.name/i)).toBeInTheDocument()
+      expect(screen.queryByTestId('icon-azure')).not.toBeInTheDocument()
+    })
+
+    it('should not show price tip for community (free) plan', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.community} />)
+
+      expect(screen.queryByText(/plans\.community\.priceTip/i)).not.toBeInTheDocument()
+    })
+
+    it('should show price tip for premium plan', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+
+      expect(screen.getByText(/plans\.premium\.priceTip/i)).toBeInTheDocument()
+    })
+
+    it('should render features list for each plan', () => {
+      const { unmount: unmount1 } = render(<SelfHostedPlanItem plan={SelfHostedPlan.community} />)
+      expect(screen.getByTestId('self-hosted-list-community')).toBeInTheDocument()
+      unmount1()
+
+      const { unmount: unmount2 } = render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+      expect(screen.getByTestId('self-hosted-list-premium')).toBeInTheDocument()
+      unmount2()
+
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.enterprise} />)
+      expect(screen.getByTestId('self-hosted-list-enterprise')).toBeInTheDocument()
+    })
+
+    it('should show AWS marketplace icon for premium plan button', () => {
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+
+      expect(screen.getByTestId('icon-aws-light')).toBeInTheDocument()
+    })
+  })
+
+  // ─── 2. Navigation Flow ─────────────────────────────────────────────────
+  describe('Navigation flow', () => {
+    it('should redirect to GitHub when clicking community plan button', async () => {
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.community} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(assignedHref).toBe(getStartedWithCommunityUrl)
+    })
+
+    it('should redirect to AWS Marketplace when clicking premium plan button', async () => {
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(assignedHref).toBe(getWithPremiumUrl)
+    })
+
+    it('should redirect to Typeform when clicking enterprise plan button', async () => {
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.enterprise} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(assignedHref).toBe(contactSalesUrl)
+    })
+  })
+
+  // ─── 3. Permission Check ────────────────────────────────────────────────
+  describe('Permission check', () => {
+    it('should show error toast when non-manager clicks community button', async () => {
+      setupAppContext({ isCurrentWorkspaceManager: false })
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.community} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockToastNotify).toHaveBeenCalledWith(
+          expect.objectContaining({ type: 'error' }),
+        )
+      })
+      // Should NOT redirect
+      expect(assignedHref).toBe('')
+    })
+
+    it('should show error toast when non-manager clicks premium button', async () => {
+      setupAppContext({ isCurrentWorkspaceManager: false })
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.premium} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockToastNotify).toHaveBeenCalledWith(
+          expect.objectContaining({ type: 'error' }),
+        )
+      })
+      expect(assignedHref).toBe('')
+    })
+
+    it('should show error toast when non-manager clicks enterprise button', async () => {
+      setupAppContext({ isCurrentWorkspaceManager: false })
+      const user = userEvent.setup()
+      render(<SelfHostedPlanItem plan={SelfHostedPlan.enterprise} />)
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      await waitFor(() => {
+        expect(mockToastNotify).toHaveBeenCalledWith(
+          expect.objectContaining({ type: 'error' }),
+        )
+      })
+      expect(assignedHref).toBe('')
+    })
+  })
+})

web/__tests__/datasets/create-dataset-flow.test.tsx

@@ -0,0 +1,301 @@
+/**
+ * Integration Test: Create Dataset Flow
+ *
+ * Tests cross-module data flow: step-one data → step-two hooks → creation params → API call
+ * Validates data contracts between steps.
+ */
+
+import type { CustomFile } from '@/models/datasets'
+import type { RetrievalConfig } from '@/types/app'
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ChunkingMode, DataSourceType, ProcessMode } from '@/models/datasets'
+import { RETRIEVE_METHOD } from '@/types/app'
+
+const mockCreateFirstDocument = vi.fn()
+const mockCreateDocument = vi.fn()
+vi.mock('@/service/knowledge/use-create-dataset', () => ({
+  useCreateFirstDocument: () => ({ mutateAsync: mockCreateFirstDocument, isPending: false }),
+  useCreateDocument: () => ({ mutateAsync: mockCreateDocument, isPending: false }),
+  getNotionInfo: (pages: { page_id: string }[], credentialId: string) => ({
+    workspace_id: 'ws-1',
+    pages: pages.map(p => p.page_id),
+    notion_credential_id: credentialId,
+  }),
+  getWebsiteInfo: (opts: { websitePages: { url: string }[], websiteCrawlProvider: string }) => ({
+    urls: opts.websitePages.map(p => p.url),
+    only_main_content: true,
+    provider: opts.websiteCrawlProvider,
+  }),
+}))
+
+vi.mock('@/service/knowledge/use-dataset', () => ({
+  useInvalidDatasetList: () => vi.fn(),
+}))
+
+vi.mock('@/app/components/base/toast', () => ({
+  default: { notify: vi.fn() },
+}))
+
+vi.mock('@/app/components/base/amplitude', () => ({
+  trackEvent: vi.fn(),
+}))
+
+// Import hooks after mocks
+const { useSegmentationState, DEFAULT_SEGMENT_IDENTIFIER, DEFAULT_MAXIMUM_CHUNK_LENGTH, DEFAULT_OVERLAP }
+  = await import('@/app/components/datasets/create/step-two/hooks')
+const { useDocumentCreation, IndexingType }
+  = await import('@/app/components/datasets/create/step-two/hooks')
+
+const createMockFile = (overrides?: Partial<CustomFile>): CustomFile => ({
+  id: 'file-1',
+  name: 'test.txt',
+  type: 'text/plain',
+  size: 1024,
+  extension: '.txt',
+  mime_type: 'text/plain',
+  created_at: 0,
+  created_by: '',
+  ...overrides,
+} as CustomFile)
+
+describe('Create Dataset Flow - Cross-Step Data Contract', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Step-One → Step-Two: Segmentation Defaults', () => {
+    it('should initialise with correct default segmentation values', () => {
+      const { result } = renderHook(() => useSegmentationState())
+      expect(result.current.segmentIdentifier).toBe(DEFAULT_SEGMENT_IDENTIFIER)
+      expect(result.current.maxChunkLength).toBe(DEFAULT_MAXIMUM_CHUNK_LENGTH)
+      expect(result.current.overlap).toBe(DEFAULT_OVERLAP)
+      expect(result.current.segmentationType).toBe(ProcessMode.general)
+    })
+
+    it('should produce valid process rule for general chunking', () => {
+      const { result } = renderHook(() => useSegmentationState())
+      const processRule = result.current.getProcessRule(ChunkingMode.text)
+
+      // mode should be segmentationType = ProcessMode.general = 'custom'
+      expect(processRule.mode).toBe('custom')
+      expect(processRule.rules.segmentation).toEqual({
+        separator: '\n\n', // unescaped from \\n\\n
+        max_tokens: DEFAULT_MAXIMUM_CHUNK_LENGTH,
+        chunk_overlap: DEFAULT_OVERLAP,
+      })
+      // rules is empty initially since no default config loaded
+      expect(processRule.rules.pre_processing_rules).toEqual([])
+    })
+
+    it('should produce valid process rule for parent-child chunking', () => {
+      const { result } = renderHook(() => useSegmentationState())
+      const processRule = result.current.getProcessRule(ChunkingMode.parentChild)
+
+      expect(processRule.mode).toBe('hierarchical')
+      expect(processRule.rules.parent_mode).toBe('paragraph')
+      expect(processRule.rules.segmentation).toEqual({
+        separator: '\n\n',
+        max_tokens: 1024,
+      })
+      expect(processRule.rules.subchunk_segmentation).toEqual({
+        separator: '\n',
+        max_tokens: 512,
+      })
+    })
+  })
+
+  describe('Step-Two → Creation API: Params Building', () => {
+    it('should build valid creation params for file upload workflow', () => {
+      const files = [createMockFile()]
+      const { result: segResult } = renderHook(() => useSegmentationState())
+      const { result: creationResult } = renderHook(() =>
+        useDocumentCreation({
+          dataSourceType: DataSourceType.FILE,
+          files,
+          notionPages: [],
+          notionCredentialId: '',
+          websitePages: [],
+        }),
+      )
+
+      const processRule = segResult.current.getProcessRule(ChunkingMode.text)
+      const retrievalConfig: RetrievalConfig = {
+        search_method: RETRIEVE_METHOD.semantic,
+        reranking_enable: false,
+        reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+        top_k: 3,
+        score_threshold_enabled: false,
+        score_threshold: 0,
+      }
+
+      const params = creationResult.current.buildCreationParams(
+        ChunkingMode.text,
+        'English',
+        processRule,
+        retrievalConfig,
+        { provider: 'openai', model: 'text-embedding-ada-002' },
+        IndexingType.QUALIFIED,
+      )
+
+      expect(params).not.toBeNull()
+      // File IDs come from file.id (not file.file.id)
+      expect(params!.data_source.type).toBe(DataSourceType.FILE)
+      expect(params!.data_source.info_list.file_info_list?.file_ids).toContain('file-1')
+
+      expect(params!.indexing_technique).toBe(IndexingType.QUALIFIED)
+      expect(params!.doc_form).toBe(ChunkingMode.text)
+      expect(params!.doc_language).toBe('English')
+      expect(params!.embedding_model).toBe('text-embedding-ada-002')
+      expect(params!.embedding_model_provider).toBe('openai')
+      expect(params!.process_rule.mode).toBe('custom')
+    })
+
+    it('should validate params: overlap must not exceed maxChunkLength', () => {
+      const { result } = renderHook(() =>
+        useDocumentCreation({
+          dataSourceType: DataSourceType.FILE,
+          files: [createMockFile()],
+          notionPages: [],
+          notionCredentialId: '',
+          websitePages: [],
+        }),
+      )
+
+      // validateParams returns false (invalid) when overlap > maxChunkLength for general mode
+      const isValid = result.current.validateParams({
+        segmentationType: 'general',
+        maxChunkLength: 100,
+        limitMaxChunkLength: 4000,
+        overlap: 200, // overlap > maxChunkLength
+        indexType: IndexingType.QUALIFIED,
+        embeddingModel: { provider: 'openai', model: 'text-embedding-ada-002' },
+        rerankModelList: [],
+        retrievalConfig: {
+          search_method: RETRIEVE_METHOD.semantic,
+          reranking_enable: false,
+          reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+          top_k: 3,
+          score_threshold_enabled: false,
+          score_threshold: 0,
+        },
+      })
+      expect(isValid).toBe(false)
+    })
+
+    it('should validate params: maxChunkLength must not exceed limit', () => {
+      const { result } = renderHook(() =>
+        useDocumentCreation({
+          dataSourceType: DataSourceType.FILE,
+          files: [createMockFile()],
+          notionPages: [],
+          notionCredentialId: '',
+          websitePages: [],
+        }),
+      )
+
+      const isValid = result.current.validateParams({
+        segmentationType: 'general',
+        maxChunkLength: 5000,
+        limitMaxChunkLength: 4000, // limit < maxChunkLength
+        overlap: 50,
+        indexType: IndexingType.QUALIFIED,
+        embeddingModel: { provider: 'openai', model: 'text-embedding-ada-002' },
+        rerankModelList: [],
+        retrievalConfig: {
+          search_method: RETRIEVE_METHOD.semantic,
+          reranking_enable: false,
+          reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+          top_k: 3,
+          score_threshold_enabled: false,
+          score_threshold: 0,
+        },
+      })
+      expect(isValid).toBe(false)
+    })
+  })
+
+  describe('Full Flow: Segmentation State → Process Rule → Creation Params Consistency', () => {
+    it('should keep segmentation values consistent across getProcessRule and buildCreationParams', () => {
+      const files = [createMockFile()]
+      const { result: segResult } = renderHook(() => useSegmentationState())
+      const { result: creationResult } = renderHook(() =>
+        useDocumentCreation({
+          dataSourceType: DataSourceType.FILE,
+          files,
+          notionPages: [],
+          notionCredentialId: '',
+          websitePages: [],
+        }),
+      )
+
+      // Change segmentation settings
+      act(() => {
+        segResult.current.setMaxChunkLength(2048)
+        segResult.current.setOverlap(100)
+      })
+
+      const processRule = segResult.current.getProcessRule(ChunkingMode.text)
+      expect(processRule.rules.segmentation.max_tokens).toBe(2048)
+      expect(processRule.rules.segmentation.chunk_overlap).toBe(100)
+
+      const params = creationResult.current.buildCreationParams(
+        ChunkingMode.text,
+        'Chinese',
+        processRule,
+        {
+          search_method: RETRIEVE_METHOD.semantic,
+          reranking_enable: false,
+          reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+          top_k: 3,
+          score_threshold_enabled: false,
+          score_threshold: 0,
+        },
+        { provider: 'openai', model: 'text-embedding-ada-002' },
+        IndexingType.QUALIFIED,
+      )
+
+      expect(params).not.toBeNull()
+      expect(params!.process_rule.rules.segmentation.max_tokens).toBe(2048)
+      expect(params!.process_rule.rules.segmentation.chunk_overlap).toBe(100)
+      expect(params!.doc_language).toBe('Chinese')
+    })
+
+    it('should support parent-child mode through the full pipeline', () => {
+      const files = [createMockFile()]
+      const { result: segResult } = renderHook(() => useSegmentationState())
+      const { result: creationResult } = renderHook(() =>
+        useDocumentCreation({
+          dataSourceType: DataSourceType.FILE,
+          files,
+          notionPages: [],
+          notionCredentialId: '',
+          websitePages: [],
+        }),
+      )
+
+      const processRule = segResult.current.getProcessRule(ChunkingMode.parentChild)
+      const params = creationResult.current.buildCreationParams(
+        ChunkingMode.parentChild,
+        'English',
+        processRule,
+        {
+          search_method: RETRIEVE_METHOD.semantic,
+          reranking_enable: false,
+          reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+          top_k: 3,
+          score_threshold_enabled: false,
+          score_threshold: 0,
+        },
+        { provider: 'openai', model: 'text-embedding-ada-002' },
+        IndexingType.QUALIFIED,
+      )
+
+      expect(params).not.toBeNull()
+      expect(params!.doc_form).toBe(ChunkingMode.parentChild)
+      expect(params!.process_rule.mode).toBe('hierarchical')
+      expect(params!.process_rule.rules.parent_mode).toBe('paragraph')
+      expect(params!.process_rule.rules.subchunk_segmentation).toBeDefined()
+    })
+  })
+})

web/__tests__/datasets/dataset-settings-flow.test.tsx

@@ -0,0 +1,451 @@
+/**
+ * Integration Test: Dataset Settings Flow
+ *
+ * Tests cross-module data contracts in the dataset settings form:
+ *   useFormState hook ↔ index method config ↔ retrieval config ↔ permission state.
+ *
+ * The unit-level use-form-state.spec.ts validates the hook in isolation.
+ * This integration test verifies that changing one configuration dimension
+ * correctly cascades to dependent parts (index method → retrieval config,
+ * permission → member list visibility, embedding model → embedding available state).
+ */
+
+import type { DataSet } from '@/models/datasets'
+import type { RetrievalConfig } from '@/types/app'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { IndexingType } from '@/app/components/datasets/create/step-two'
+import { ChunkingMode, DatasetPermission, DataSourceType, WeightedScoreEnum } from '@/models/datasets'
+import { RETRIEVE_METHOD } from '@/types/app'
+
+// --- Mocks ---
+
+const mockMutateDatasets = vi.fn()
+const mockInvalidDatasetList = vi.fn()
+const mockUpdateDatasetSetting = vi.fn().mockResolvedValue({})
+
+vi.mock('@/context/app-context', () => ({
+  useSelector: () => false,
+}))
+
+vi.mock('@/service/datasets', () => ({
+  updateDatasetSetting: (...args: unknown[]) => mockUpdateDatasetSetting(...args),
+}))
+
+vi.mock('@/service/knowledge/use-dataset', () => ({
+  useInvalidDatasetList: () => mockInvalidDatasetList,
+}))
+
+vi.mock('@/service/use-common', () => ({
+  useMembers: () => ({
+    data: {
+      accounts: [
+        { id: 'user-1', name: 'Alice', email: 'alice@example.com', role: 'owner', avatar: '', avatar_url: '', last_login_at: '', created_at: '', status: 'active' },
+        { id: 'user-2', name: 'Bob', email: 'bob@example.com', role: 'admin', avatar: '', avatar_url: '', last_login_at: '', created_at: '', status: 'active' },
+        { id: 'user-3', name: 'Charlie', email: 'charlie@example.com', role: 'normal', avatar: '', avatar_url: '', last_login_at: '', created_at: '', status: 'active' },
+      ],
+    },
+  }),
+}))
+
+vi.mock('@/app/components/header/account-setting/model-provider-page/hooks', () => ({
+  useModelList: () => ({ data: [] }),
+}))
+
+vi.mock('@/app/components/datasets/common/check-rerank-model', () => ({
+  isReRankModelSelected: () => true,
+}))
+
+vi.mock('@/app/components/base/toast', () => ({
+  default: { notify: vi.fn() },
+}))
+
+// --- Dataset factory ---
+
+const createMockDataset = (overrides?: Partial<DataSet>): DataSet => ({
+  id: 'ds-settings-1',
+  name: 'Settings Test Dataset',
+  description: 'Integration test dataset',
+  permission: DatasetPermission.onlyMe,
+  icon_info: {
+    icon_type: 'emoji',
+    icon: '📙',
+    icon_background: '#FFF4ED',
+    icon_url: '',
+  },
+  indexing_technique: 'high_quality',
+  indexing_status: 'completed',
+  data_source_type: DataSourceType.FILE,
+  doc_form: ChunkingMode.text,
+  embedding_model: 'text-embedding-ada-002',
+  embedding_model_provider: 'openai',
+  embedding_available: true,
+  app_count: 2,
+  document_count: 10,
+  total_document_count: 10,
+  word_count: 5000,
+  provider: 'vendor',
+  tags: [],
+  partial_member_list: [],
+  external_knowledge_info: {
+    external_knowledge_id: '',
+    external_knowledge_api_id: '',
+    external_knowledge_api_name: '',
+    external_knowledge_api_endpoint: '',
+  },
+  external_retrieval_model: {
+    top_k: 2,
+    score_threshold: 0.5,
+    score_threshold_enabled: false,
+  },
+  retrieval_model_dict: {
+    search_method: RETRIEVE_METHOD.semantic,
+    reranking_enable: false,
+    reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+    top_k: 3,
+    score_threshold_enabled: false,
+    score_threshold: 0,
+  } as RetrievalConfig,
+  retrieval_model: {
+    search_method: RETRIEVE_METHOD.semantic,
+    reranking_enable: false,
+    reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+    top_k: 3,
+    score_threshold_enabled: false,
+    score_threshold: 0,
+  } as RetrievalConfig,
+  built_in_field_enabled: false,
+  keyword_number: 10,
+  created_by: 'user-1',
+  updated_by: 'user-1',
+  updated_at: Date.now(),
+  runtime_mode: 'general',
+  enable_api: true,
+  is_multimodal: false,
+  ...overrides,
+} as DataSet)
+
+let mockDataset: DataSet = createMockDataset()
+
+vi.mock('@/context/dataset-detail', () => ({
+  useDatasetDetailContextWithSelector: (
+    selector: (state: { dataset: DataSet | null, mutateDatasetRes: () => void }) => unknown,
+  ) => selector({ dataset: mockDataset, mutateDatasetRes: mockMutateDatasets }),
+}))
+
+// Import after mocks are registered
+const { useFormState } = await import(
+  '@/app/components/datasets/settings/form/hooks/use-form-state',
+)
+
+describe('Dataset Settings Flow - Cross-Module Configuration Cascade', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockUpdateDatasetSetting.mockResolvedValue({})
+    mockDataset = createMockDataset()
+  })
+
+  describe('Form State Initialization from Dataset → Index Method → Retrieval Config Chain', () => {
+    it('should initialise all form dimensions from a QUALIFIED dataset', () => {
+      const { result } = renderHook(() => useFormState())
+
+      expect(result.current.name).toBe('Settings Test Dataset')
+      expect(result.current.description).toBe('Integration test dataset')
+      expect(result.current.indexMethod).toBe('high_quality')
+      expect(result.current.embeddingModel).toEqual({
+        provider: 'openai',
+        model: 'text-embedding-ada-002',
+      })
+      expect(result.current.retrievalConfig.search_method).toBe(RETRIEVE_METHOD.semantic)
+    })
+
+    it('should initialise from an ECONOMICAL dataset with keyword retrieval', () => {
+      mockDataset = createMockDataset({
+        indexing_technique: IndexingType.ECONOMICAL,
+        embedding_model: '',
+        embedding_model_provider: '',
+        retrieval_model_dict: {
+          search_method: RETRIEVE_METHOD.keywordSearch,
+          reranking_enable: false,
+          reranking_model: { reranking_provider_name: '', reranking_model_name: '' },
+          top_k: 5,
+          score_threshold_enabled: false,
+          score_threshold: 0,
+        } as RetrievalConfig,
+      })
+
+      const { result } = renderHook(() => useFormState())
+
+      expect(result.current.indexMethod).toBe(IndexingType.ECONOMICAL)
+      expect(result.current.embeddingModel).toEqual({ provider: '', model: '' })
+      expect(result.current.retrievalConfig.search_method).toBe(RETRIEVE_METHOD.keywordSearch)
+    })
+  })
+
+  describe('Index Method Change → Retrieval Config Sync', () => {
+    it('should allow switching index method from QUALIFIED to ECONOMICAL', () => {
+      const { result } = renderHook(() => useFormState())
+
+      expect(result.current.indexMethod).toBe('high_quality')
+
+      act(() => {
+        result.current.setIndexMethod(IndexingType.ECONOMICAL)
+      })
+
+      expect(result.current.indexMethod).toBe(IndexingType.ECONOMICAL)
+    })
+
+    it('should allow updating retrieval config after index method switch', () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setIndexMethod(IndexingType.ECONOMICAL)
+      })
+
+      act(() => {
+        result.current.setRetrievalConfig({
+          ...result.current.retrievalConfig,
+          search_method: RETRIEVE_METHOD.keywordSearch,
+          reranking_enable: false,
+        })
+      })
+
+      expect(result.current.indexMethod).toBe(IndexingType.ECONOMICAL)
+      expect(result.current.retrievalConfig.search_method).toBe(RETRIEVE_METHOD.keywordSearch)
+      expect(result.current.retrievalConfig.reranking_enable).toBe(false)
+    })
+
+    it('should preserve retrieval config when switching back to QUALIFIED', () => {
+      const { result } = renderHook(() => useFormState())
+
+      const originalConfig = { ...result.current.retrievalConfig }
+
+      act(() => {
+        result.current.setIndexMethod(IndexingType.ECONOMICAL)
+      })
+      act(() => {
+        result.current.setIndexMethod(IndexingType.QUALIFIED)
+      })
+
+      expect(result.current.indexMethod).toBe('high_quality')
+      expect(result.current.retrievalConfig.search_method).toBe(originalConfig.search_method)
+    })
+  })
+
+  describe('Permission Change → Member List Visibility Logic', () => {
+    it('should start with onlyMe permission and empty member selection', () => {
+      const { result } = renderHook(() => useFormState())
+
+      expect(result.current.permission).toBe(DatasetPermission.onlyMe)
+      expect(result.current.selectedMemberIDs).toEqual([])
+    })
+
+    it('should enable member selection when switching to partialMembers', () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.partialMembers)
+      })
+
+      expect(result.current.permission).toBe(DatasetPermission.partialMembers)
+      expect(result.current.memberList).toHaveLength(3)
+      expect(result.current.memberList.map(m => m.id)).toEqual(['user-1', 'user-2', 'user-3'])
+    })
+
+    it('should persist member selection through permission toggle', () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.partialMembers)
+        result.current.setSelectedMemberIDs(['user-1', 'user-3'])
+      })
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.allTeamMembers)
+      })
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.partialMembers)
+      })
+
+      expect(result.current.selectedMemberIDs).toEqual(['user-1', 'user-3'])
+    })
+
+    it('should include partial_member_list in save payload only for partialMembers', async () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.partialMembers)
+        result.current.setSelectedMemberIDs(['user-2'])
+      })
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      expect(mockUpdateDatasetSetting).toHaveBeenCalledWith({
+        datasetId: 'ds-settings-1',
+        body: expect.objectContaining({
+          permission: DatasetPermission.partialMembers,
+          partial_member_list: [
+            expect.objectContaining({ user_id: 'user-2', role: 'admin' }),
+          ],
+        }),
+      })
+    })
+
+    it('should not include partial_member_list for allTeamMembers permission', async () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setPermission(DatasetPermission.allTeamMembers)
+      })
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      const savedBody = mockUpdateDatasetSetting.mock.calls[0][0].body as Record<string, unknown>
+      expect(savedBody).not.toHaveProperty('partial_member_list')
+    })
+  })
+
+  describe('Form Submission Validation → All Fields Together', () => {
+    it('should reject empty name on save', async () => {
+      const Toast = await import('@/app/components/base/toast')
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setName('')
+      })
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      expect(Toast.default.notify).toHaveBeenCalledWith({
+        type: 'error',
+        message: expect.any(String),
+      })
+      expect(mockUpdateDatasetSetting).not.toHaveBeenCalled()
+    })
+
+    it('should include all configuration dimensions in a successful save', async () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setName('Updated Name')
+        result.current.setDescription('Updated Description')
+        result.current.setIndexMethod(IndexingType.ECONOMICAL)
+        result.current.setKeywordNumber(15)
+      })
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      expect(mockUpdateDatasetSetting).toHaveBeenCalledWith({
+        datasetId: 'ds-settings-1',
+        body: expect.objectContaining({
+          name: 'Updated Name',
+          description: 'Updated Description',
+          indexing_technique: 'economy',
+          keyword_number: 15,
+          embedding_model: 'text-embedding-ada-002',
+          embedding_model_provider: 'openai',
+        }),
+      })
+    })
+
+    it('should call mutateDatasets and invalidDatasetList after successful save', async () => {
+      const { result } = renderHook(() => useFormState())
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      await waitFor(() => {
+        expect(mockMutateDatasets).toHaveBeenCalled()
+        expect(mockInvalidDatasetList).toHaveBeenCalled()
+      })
+    })
+  })
+
+  describe('Embedding Model Change → Retrieval Config Cascade', () => {
+    it('should update embedding model independently of retrieval config', () => {
+      const { result } = renderHook(() => useFormState())
+
+      const originalRetrievalConfig = { ...result.current.retrievalConfig }
+
+      act(() => {
+        result.current.setEmbeddingModel({ provider: 'cohere', model: 'embed-english-v3.0' })
+      })
+
+      expect(result.current.embeddingModel).toEqual({
+        provider: 'cohere',
+        model: 'embed-english-v3.0',
+      })
+      expect(result.current.retrievalConfig.search_method).toBe(originalRetrievalConfig.search_method)
+    })
+
+    it('should propagate embedding model into weighted retrieval config on save', async () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setEmbeddingModel({ provider: 'cohere', model: 'embed-v3' })
+        result.current.setRetrievalConfig({
+          ...result.current.retrievalConfig,
+          search_method: RETRIEVE_METHOD.hybrid,
+          weights: {
+            weight_type: WeightedScoreEnum.Customized,
+            vector_setting: {
+              vector_weight: 0.6,
+              embedding_provider_name: '',
+              embedding_model_name: '',
+            },
+            keyword_setting: { keyword_weight: 0.4 },
+          },
+        })
+      })
+
+      await act(async () => {
+        await result.current.handleSave()
+      })
+
+      expect(mockUpdateDatasetSetting).toHaveBeenCalledWith({
+        datasetId: 'ds-settings-1',
+        body: expect.objectContaining({
+          embedding_model: 'embed-v3',
+          embedding_model_provider: 'cohere',
+          retrieval_model: expect.objectContaining({
+            weights: expect.objectContaining({
+              vector_setting: expect.objectContaining({
+                embedding_provider_name: 'cohere',
+                embedding_model_name: 'embed-v3',
+              }),
+            }),
+          }),
+        }),
+      })
+    })
+
+    it('should handle switching from semantic to hybrid search with embedding model', () => {
+      const { result } = renderHook(() => useFormState())
+
+      act(() => {
+        result.current.setRetrievalConfig({
+          ...result.current.retrievalConfig,
+          search_method: RETRIEVE_METHOD.hybrid,
+          reranking_enable: true,
+          reranking_model: {
+            reranking_provider_name: 'cohere',
+            reranking_model_name: 'rerank-english-v3.0',
+          },
+        })
+      })
+
+      expect(result.current.retrievalConfig.search_method).toBe(RETRIEVE_METHOD.hybrid)
+      expect(result.current.retrievalConfig.reranking_enable).toBe(true)
+      expect(result.current.embeddingModel.model).toBe('text-embedding-ada-002')
+    })
+  })
+})

web/__tests__/datasets/document-management.test.tsx

@@ -0,0 +1,335 @@
+/**
+ * Integration Test: Document Management Flow
+ *
+ * Tests cross-module interactions: query state (URL-based) → document list sorting →
+ * document selection → status filter utilities.
+ * Validates the data contract between documents page hooks and list component hooks.
+ */
+
+import type { SimpleDocumentDetail } from '@/models/datasets'
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DataSourceType } from '@/models/datasets'
+
+const mockPush = vi.fn()
+vi.mock('next/navigation', () => ({
+  useSearchParams: () => new URLSearchParams(''),
+  useRouter: () => ({ push: mockPush }),
+  usePathname: () => '/datasets/ds-1/documents',
+}))
+
+const { sanitizeStatusValue, normalizeStatusForQuery } = await import(
+  '@/app/components/datasets/documents/status-filter',
+)
+
+const { useDocumentSort } = await import(
+  '@/app/components/datasets/documents/components/document-list/hooks/use-document-sort',
+)
+const { useDocumentSelection } = await import(
+  '@/app/components/datasets/documents/components/document-list/hooks/use-document-selection',
+)
+const { default: useDocumentListQueryState } = await import(
+  '@/app/components/datasets/documents/hooks/use-document-list-query-state',
+)
+
+type LocalDoc = SimpleDocumentDetail & { percent?: number }
+
+const createDoc = (overrides?: Partial<LocalDoc>): LocalDoc => ({
+  id: `doc-${Math.random().toString(36).slice(2, 8)}`,
+  name: 'test-doc.txt',
+  word_count: 500,
+  hit_count: 10,
+  created_at: Date.now() / 1000,
+  data_source_type: DataSourceType.FILE,
+  display_status: 'available',
+  indexing_status: 'completed',
+  enabled: true,
+  archived: false,
+  doc_type: null,
+  doc_metadata: null,
+  position: 1,
+  dataset_process_rule_id: 'rule-1',
+  ...overrides,
+} as LocalDoc)
+
+describe('Document Management Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Status Filter Utilities', () => {
+    it('should sanitize valid status values', () => {
+      expect(sanitizeStatusValue('all')).toBe('all')
+      expect(sanitizeStatusValue('available')).toBe('available')
+      expect(sanitizeStatusValue('error')).toBe('error')
+    })
+
+    it('should fallback to "all" for invalid values', () => {
+      expect(sanitizeStatusValue(null)).toBe('all')
+      expect(sanitizeStatusValue(undefined)).toBe('all')
+      expect(sanitizeStatusValue('')).toBe('all')
+      expect(sanitizeStatusValue('nonexistent')).toBe('all')
+    })
+
+    it('should handle URL aliases', () => {
+      // 'active' is aliased to 'available'
+      expect(sanitizeStatusValue('active')).toBe('available')
+    })
+
+    it('should normalize status for API query', () => {
+      expect(normalizeStatusForQuery('all')).toBe('all')
+      // 'enabled' normalized to 'available' for query
+      expect(normalizeStatusForQuery('enabled')).toBe('available')
+    })
+  })
+
+  describe('URL-based Query State', () => {
+    it('should parse default query from empty URL params', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query).toEqual({
+        page: 1,
+        limit: 10,
+        keyword: '',
+        status: 'all',
+        sort: '-created_at',
+      })
+    })
+
+    it('should update query and push to router', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ keyword: 'test', page: 2 })
+      })
+
+      expect(mockPush).toHaveBeenCalled()
+      // The push call should contain the updated query params
+      const pushUrl = mockPush.mock.calls[0][0] as string
+      expect(pushUrl).toContain('keyword=test')
+      expect(pushUrl).toContain('page=2')
+    })
+
+    it('should reset query to defaults', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.resetQuery()
+      })
+
+      expect(mockPush).toHaveBeenCalled()
+      // Default query omits default values from URL
+      const pushUrl = mockPush.mock.calls[0][0] as string
+      expect(pushUrl).toBe('/datasets/ds-1/documents')
+    })
+  })
+
+  describe('Document Sort Integration', () => {
+    it('should return documents unsorted when no sort field set', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'Banana.txt', word_count: 300 }),
+        createDoc({ id: 'doc-2', name: 'Apple.txt', word_count: 100 }),
+        createDoc({ id: 'doc-3', name: 'Cherry.txt', word_count: 200 }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
+        remoteSortValue: '-created_at',
+      }))
+
+      expect(result.current.sortField).toBeNull()
+      expect(result.current.sortedDocuments).toHaveLength(3)
+    })
+
+    it('should sort by name descending', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'Banana.txt' }),
+        createDoc({ id: 'doc-2', name: 'Apple.txt' }),
+        createDoc({ id: 'doc-3', name: 'Cherry.txt' }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
+        remoteSortValue: '-created_at',
+      }))
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+
+      expect(result.current.sortField).toBe('name')
+      expect(result.current.sortOrder).toBe('desc')
+      const names = result.current.sortedDocuments.map(d => d.name)
+      expect(names).toEqual(['Cherry.txt', 'Banana.txt', 'Apple.txt'])
+    })
+
+    it('should toggle sort order on same field click', () => {
+      const docs = [createDoc({ id: 'doc-1', name: 'A.txt' }), createDoc({ id: 'doc-2', name: 'B.txt' })]
+
+      const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
+        remoteSortValue: '-created_at',
+      }))
+
+      act(() => result.current.handleSort('name'))
+      expect(result.current.sortOrder).toBe('desc')
+
+      act(() => result.current.handleSort('name'))
+      expect(result.current.sortOrder).toBe('asc')
+    })
+
+    it('should filter by status before sorting', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'A.txt', display_status: 'available' }),
+        createDoc({ id: 'doc-2', name: 'B.txt', display_status: 'error' }),
+        createDoc({ id: 'doc-3', name: 'C.txt', display_status: 'available' }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: 'available',
+        remoteSortValue: '-created_at',
+      }))
+
+      // Only 'available' documents should remain
+      expect(result.current.sortedDocuments).toHaveLength(2)
+      expect(result.current.sortedDocuments.every(d => d.display_status === 'available')).toBe(true)
+    })
+  })
+
+  describe('Document Selection Integration', () => {
+    it('should manage selection state externally', () => {
+      const docs = [
+        createDoc({ id: 'doc-1' }),
+        createDoc({ id: 'doc-2' }),
+        createDoc({ id: 'doc-3' }),
+      ]
+      const onSelectedIdChange = vi.fn()
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: [],
+        onSelectedIdChange,
+      }))
+
+      expect(result.current.isAllSelected).toBe(false)
+      expect(result.current.isSomeSelected).toBe(false)
+    })
+
+    it('should select all documents', () => {
+      const docs = [
+        createDoc({ id: 'doc-1' }),
+        createDoc({ id: 'doc-2' }),
+      ]
+      const onSelectedIdChange = vi.fn()
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: [],
+        onSelectedIdChange,
+      }))
+
+      act(() => {
+        result.current.onSelectAll()
+      })
+
+      expect(onSelectedIdChange).toHaveBeenCalledWith(
+        expect.arrayContaining(['doc-1', 'doc-2']),
+      )
+    })
+
+    it('should detect all-selected state', () => {
+      const docs = [
+        createDoc({ id: 'doc-1' }),
+        createDoc({ id: 'doc-2' }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: ['doc-1', 'doc-2'],
+        onSelectedIdChange: vi.fn(),
+      }))
+
+      expect(result.current.isAllSelected).toBe(true)
+    })
+
+    it('should detect partial selection', () => {
+      const docs = [
+        createDoc({ id: 'doc-1' }),
+        createDoc({ id: 'doc-2' }),
+        createDoc({ id: 'doc-3' }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: ['doc-1'],
+        onSelectedIdChange: vi.fn(),
+      }))
+
+      expect(result.current.isSomeSelected).toBe(true)
+      expect(result.current.isAllSelected).toBe(false)
+    })
+
+    it('should identify downloadable selected documents (FILE type only)', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', data_source_type: DataSourceType.FILE }),
+        createDoc({ id: 'doc-2', data_source_type: DataSourceType.NOTION }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: ['doc-1', 'doc-2'],
+        onSelectedIdChange: vi.fn(),
+      }))
+
+      expect(result.current.downloadableSelectedIds).toEqual(['doc-1'])
+    })
+
+    it('should clear selection', () => {
+      const onSelectedIdChange = vi.fn()
+      const docs = [createDoc({ id: 'doc-1' })]
+
+      const { result } = renderHook(() => useDocumentSelection({
+        documents: docs,
+        selectedIds: ['doc-1'],
+        onSelectedIdChange,
+      }))
+
+      act(() => {
+        result.current.clearSelection()
+      })
+
+      expect(onSelectedIdChange).toHaveBeenCalledWith([])
+    })
+  })
+
+  describe('Cross-Module: Query State → Sort → Selection Pipeline', () => {
+    it('should maintain consistent default state across all hooks', () => {
+      const docs = [createDoc({ id: 'doc-1' })]
+      const { result: queryResult } = renderHook(() => useDocumentListQueryState())
+      const { result: sortResult } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: queryResult.current.query.status,
+        remoteSortValue: queryResult.current.query.sort,
+      }))
+      const { result: selResult } = renderHook(() => useDocumentSelection({
+        documents: sortResult.current.sortedDocuments,
+        selectedIds: [],
+        onSelectedIdChange: vi.fn(),
+      }))
+
+      // Query defaults
+      expect(queryResult.current.query.sort).toBe('-created_at')
+      expect(queryResult.current.query.status).toBe('all')
+
+      // Sort inherits 'all' status → no filtering applied
+      expect(sortResult.current.sortedDocuments).toHaveLength(1)
+
+      // Selection starts empty
+      expect(selResult.current.isAllSelected).toBe(false)
+    })
+  })
+})

web/__tests__/datasets/external-knowledge-base.test.tsx

@@ -0,0 +1,215 @@
+/**
+ * Integration Test: External Knowledge Base Creation Flow
+ *
+ * Tests the data contract, validation logic, and API interaction
+ * for external knowledge base creation.
+ */
+
+import type { CreateKnowledgeBaseReq } from '@/app/components/datasets/external-knowledge-base/create/declarations'
+import { describe, expect, it } from 'vitest'
+
+// --- Factory ---
+const createFormData = (overrides?: Partial<CreateKnowledgeBaseReq>): CreateKnowledgeBaseReq => ({
+  name: 'My External KB',
+  description: 'A test external knowledge base',
+  external_knowledge_api_id: 'api-1',
+  external_knowledge_id: 'ext-kb-123',
+  external_retrieval_model: {
+    top_k: 4,
+    score_threshold: 0.5,
+    score_threshold_enabled: false,
+  },
+  provider: 'external',
+  ...overrides,
+})
+
+describe('External Knowledge Base Creation Flow', () => {
+  describe('Data Contract: CreateKnowledgeBaseReq', () => {
+    it('should define a complete form structure', () => {
+      const form = createFormData()
+
+      expect(form).toHaveProperty('name')
+      expect(form).toHaveProperty('external_knowledge_api_id')
+      expect(form).toHaveProperty('external_knowledge_id')
+      expect(form).toHaveProperty('external_retrieval_model')
+      expect(form).toHaveProperty('provider')
+      expect(form.provider).toBe('external')
+    })
+
+    it('should include retrieval model settings', () => {
+      const form = createFormData()
+
+      expect(form.external_retrieval_model).toEqual({
+        top_k: 4,
+        score_threshold: 0.5,
+        score_threshold_enabled: false,
+      })
+    })
+
+    it('should allow partial overrides', () => {
+      const form = createFormData({
+        name: 'Custom Name',
+        external_retrieval_model: {
+          top_k: 10,
+          score_threshold: 0.8,
+          score_threshold_enabled: true,
+        },
+      })
+
+      expect(form.name).toBe('Custom Name')
+      expect(form.external_retrieval_model.top_k).toBe(10)
+      expect(form.external_retrieval_model.score_threshold_enabled).toBe(true)
+    })
+  })
+
+  describe('Form Validation Logic', () => {
+    const isFormValid = (form: CreateKnowledgeBaseReq): boolean => {
+      return (
+        form.name.trim() !== ''
+        && form.external_knowledge_api_id !== ''
+        && form.external_knowledge_id !== ''
+        && form.external_retrieval_model.top_k !== undefined
+        && form.external_retrieval_model.score_threshold !== undefined
+      )
+    }
+
+    it('should validate a complete form', () => {
+      const form = createFormData()
+      expect(isFormValid(form)).toBe(true)
+    })
+
+    it('should reject empty name', () => {
+      const form = createFormData({ name: '' })
+      expect(isFormValid(form)).toBe(false)
+    })
+
+    it('should reject whitespace-only name', () => {
+      const form = createFormData({ name: '   ' })
+      expect(isFormValid(form)).toBe(false)
+    })
+
+    it('should reject empty external_knowledge_api_id', () => {
+      const form = createFormData({ external_knowledge_api_id: '' })
+      expect(isFormValid(form)).toBe(false)
+    })
+
+    it('should reject empty external_knowledge_id', () => {
+      const form = createFormData({ external_knowledge_id: '' })
+      expect(isFormValid(form)).toBe(false)
+    })
+  })
+
+  describe('Form State Transitions', () => {
+    it('should start with empty default state', () => {
+      const defaultForm: CreateKnowledgeBaseReq = {
+        name: '',
+        description: '',
+        external_knowledge_api_id: '',
+        external_knowledge_id: '',
+        external_retrieval_model: {
+          top_k: 4,
+          score_threshold: 0.5,
+          score_threshold_enabled: false,
+        },
+        provider: 'external',
+      }
+
+      // Verify default state matches component's initial useState
+      expect(defaultForm.name).toBe('')
+      expect(defaultForm.external_knowledge_api_id).toBe('')
+      expect(defaultForm.external_knowledge_id).toBe('')
+      expect(defaultForm.provider).toBe('external')
+    })
+
+    it('should support immutable form updates', () => {
+      const form = createFormData({ name: '' })
+      const updated = { ...form, name: 'Updated Name' }
+
+      expect(form.name).toBe('')
+      expect(updated.name).toBe('Updated Name')
+      // Other fields should remain unchanged
+      expect(updated.external_knowledge_api_id).toBe(form.external_knowledge_api_id)
+    })
+
+    it('should support retrieval model updates', () => {
+      const form = createFormData()
+      const updated = {
+        ...form,
+        external_retrieval_model: {
+          ...form.external_retrieval_model,
+          top_k: 10,
+          score_threshold_enabled: true,
+        },
+      }
+
+      expect(updated.external_retrieval_model.top_k).toBe(10)
+      expect(updated.external_retrieval_model.score_threshold_enabled).toBe(true)
+      // Unchanged field
+      expect(updated.external_retrieval_model.score_threshold).toBe(0.5)
+    })
+  })
+
+  describe('API Call Data Contract', () => {
+    it('should produce a valid API payload from form data', () => {
+      const form = createFormData()
+
+      // The API expects the full CreateKnowledgeBaseReq
+      expect(form.name).toBeTruthy()
+      expect(form.external_knowledge_api_id).toBeTruthy()
+      expect(form.external_knowledge_id).toBeTruthy()
+      expect(form.provider).toBe('external')
+      expect(typeof form.external_retrieval_model.top_k).toBe('number')
+      expect(typeof form.external_retrieval_model.score_threshold).toBe('number')
+      expect(typeof form.external_retrieval_model.score_threshold_enabled).toBe('boolean')
+    })
+
+    it('should support optional description', () => {
+      const formWithDesc = createFormData({ description: 'Some description' })
+      const formWithoutDesc = createFormData({ description: '' })
+
+      expect(formWithDesc.description).toBe('Some description')
+      expect(formWithoutDesc.description).toBe('')
+    })
+
+    it('should validate retrieval model bounds', () => {
+      const form = createFormData({
+        external_retrieval_model: {
+          top_k: 0,
+          score_threshold: 0,
+          score_threshold_enabled: false,
+        },
+      })
+
+      expect(form.external_retrieval_model.top_k).toBe(0)
+      expect(form.external_retrieval_model.score_threshold).toBe(0)
+    })
+  })
+
+  describe('External API List Integration', () => {
+    it('should validate API item structure', () => {
+      const apiItem = {
+        id: 'api-1',
+        name: 'Production API',
+        settings: {
+          endpoint: 'https://api.example.com',
+          api_key: 'key-123',
+        },
+      }
+
+      expect(apiItem).toHaveProperty('id')
+      expect(apiItem).toHaveProperty('name')
+      expect(apiItem).toHaveProperty('settings')
+      expect(apiItem.settings).toHaveProperty('endpoint')
+      expect(apiItem.settings).toHaveProperty('api_key')
+    })
+
+    it('should link API selection to form data', () => {
+      const selectedApi = { id: 'api-2', name: 'Staging API' }
+      const form = createFormData({
+        external_knowledge_api_id: selectedApi.id,
+      })
+
+      expect(form.external_knowledge_api_id).toBe('api-2')
+    })
+  })
+})

web/__tests__/datasets/hit-testing-flow.test.tsx

@@ -0,0 +1,404 @@
+/**
+ * Integration Test: Hit Testing Flow
+ *
+ * Tests the query submission → API response → callback chain flow
+ * by rendering the actual QueryInput component and triggering user interactions.
+ * Validates that the production onSubmit logic correctly constructs payloads
+ * and invokes callbacks on success/failure.
+ */
+
+import type {
+  HitTestingResponse,
+  Query,
+} from '@/models/datasets'
+import type { RetrievalConfig } from '@/types/app'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import QueryInput from '@/app/components/datasets/hit-testing/components/query-input'
+import { RETRIEVE_METHOD } from '@/types/app'
+
+// --- Mocks ---
+
+vi.mock('@/context/dataset-detail', () => ({
+  default: {},
+  useDatasetDetailContext: vi.fn(() => ({ dataset: undefined })),
+  useDatasetDetailContextWithSelector: vi.fn(() => false),
+}))
+
+vi.mock('use-context-selector', () => ({
+  useContext: vi.fn(() => ({})),
+  useContextSelector: vi.fn(() => false),
+  createContext: vi.fn(() => ({})),
+}))
+
+vi.mock('@/app/components/datasets/common/image-uploader/image-uploader-in-retrieval-testing', () => ({
+  default: ({ textArea, actionButton }: { textArea: React.ReactNode, actionButton: React.ReactNode }) => (
+    <div data-testid="image-uploader-mock">
+      {textArea}
+      {actionButton}
+    </div>
+  ),
+}))
+
+// --- Factories ---
+
+const createRetrievalConfig = (overrides = {}): RetrievalConfig => ({
+  search_method: RETRIEVE_METHOD.semantic,
+  reranking_enable: false,
+  reranking_mode: undefined,
+  reranking_model: {
+    reranking_provider_name: '',
+    reranking_model_name: '',
+  },
+  weights: undefined,
+  top_k: 3,
+  score_threshold_enabled: false,
+  score_threshold: 0.5,
+  ...overrides,
+} as RetrievalConfig)
+
+const createHitTestingResponse = (numResults: number): HitTestingResponse => ({
+  query: {
+    content: 'What is Dify?',
+    tsne_position: { x: 0, y: 0 },
+  },
+  records: Array.from({ length: numResults }, (_, i) => ({
+    segment: {
+      id: `seg-${i}`,
+      document: {
+        id: `doc-${i}`,
+        data_source_type: 'upload_file',
+        name: `document-${i}.txt`,
+        doc_type: null as unknown as import('@/models/datasets').DocType,
+      },
+      content: `Result content ${i}`,
+      sign_content: `Result content ${i}`,
+      position: i + 1,
+      word_count: 100 + i * 50,
+      tokens: 50 + i * 25,
+      keywords: ['test', 'dify'],
+      hit_count: i * 5,
+      index_node_hash: `hash-${i}`,
+      answer: '',
+    },
+    content: {
+      id: `seg-${i}`,
+      document: {
+        id: `doc-${i}`,
+        data_source_type: 'upload_file',
+        name: `document-${i}.txt`,
+        doc_type: null as unknown as import('@/models/datasets').DocType,
+      },
+      content: `Result content ${i}`,
+      sign_content: `Result content ${i}`,
+      position: i + 1,
+      word_count: 100 + i * 50,
+      tokens: 50 + i * 25,
+      keywords: ['test', 'dify'],
+      hit_count: i * 5,
+      index_node_hash: `hash-${i}`,
+      answer: '',
+    },
+    score: 0.95 - i * 0.1,
+    tsne_position: { x: 0, y: 0 },
+    child_chunks: null,
+    files: [],
+  })),
+})
+
+const createTextQuery = (content: string): Query[] => [
+  { content, content_type: 'text_query', file_info: null },
+]
+
+// --- Helpers ---
+
+const findSubmitButton = () => {
+  const buttons = screen.getAllByRole('button')
+  const submitButton = buttons.find(btn => btn.classList.contains('w-[88px]'))
+  expect(submitButton).toBeTruthy()
+  return submitButton!
+}
+
+// --- Tests ---
+
+describe('Hit Testing Flow', () => {
+  const mockHitTestingMutation = vi.fn()
+  const mockExternalMutation = vi.fn()
+  const mockSetHitResult = vi.fn()
+  const mockSetExternalHitResult = vi.fn()
+  const mockOnUpdateList = vi.fn()
+  const mockSetQueries = vi.fn()
+  const mockOnClickRetrievalMethod = vi.fn()
+  const mockOnSubmit = vi.fn()
+
+  const createDefaultProps = (overrides: Record<string, unknown> = {}) => ({
+    onUpdateList: mockOnUpdateList,
+    setHitResult: mockSetHitResult,
+    setExternalHitResult: mockSetExternalHitResult,
+    loading: false,
+    queries: [] as Query[],
+    setQueries: mockSetQueries,
+    isExternal: false,
+    onClickRetrievalMethod: mockOnClickRetrievalMethod,
+    retrievalConfig: createRetrievalConfig(),
+    isEconomy: false,
+    onSubmit: mockOnSubmit,
+    hitTestingMutation: mockHitTestingMutation,
+    externalKnowledgeBaseHitTestingMutation: mockExternalMutation,
+    ...overrides,
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Query Submission → API Call', () => {
+    it('should call hitTestingMutation with correct payload including retrieval model', async () => {
+      const retrievalConfig = createRetrievalConfig({
+        search_method: RETRIEVE_METHOD.semantic,
+        top_k: 3,
+        score_threshold_enabled: false,
+      })
+      mockHitTestingMutation.mockResolvedValue(createHitTestingResponse(3))
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('How does RAG work?'),
+          retrievalConfig,
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockHitTestingMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            query: 'How does RAG work?',
+            attachment_ids: [],
+            retrieval_model: expect.objectContaining({
+              search_method: RETRIEVE_METHOD.semantic,
+              top_k: 3,
+              score_threshold_enabled: false,
+            }),
+          }),
+          expect.objectContaining({
+            onSuccess: expect.any(Function),
+          }),
+        )
+      })
+    })
+
+    it('should override search_method to keywordSearch when isEconomy is true', async () => {
+      const retrievalConfig = createRetrievalConfig({ search_method: RETRIEVE_METHOD.semantic })
+      mockHitTestingMutation.mockResolvedValue(createHitTestingResponse(1))
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('test query'),
+          retrievalConfig,
+          isEconomy: true,
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockHitTestingMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            retrieval_model: expect.objectContaining({
+              search_method: RETRIEVE_METHOD.keywordSearch,
+            }),
+          }),
+          expect.anything(),
+        )
+      })
+    })
+
+    it('should handle empty results by calling setHitResult with empty records', async () => {
+      const emptyResponse = createHitTestingResponse(0)
+      mockHitTestingMutation.mockImplementation(async (_params: unknown, options?: { onSuccess?: (data: HitTestingResponse) => void }) => {
+        options?.onSuccess?.(emptyResponse)
+        return emptyResponse
+      })
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('nonexistent topic'),
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockSetHitResult).toHaveBeenCalledWith(
+          expect.objectContaining({ records: [] }),
+        )
+      })
+    })
+
+    it('should not call success callbacks when mutation resolves without onSuccess', async () => {
+      // Simulate a mutation that resolves but does not invoke the onSuccess callback
+      mockHitTestingMutation.mockResolvedValue(undefined)
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('test'),
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockHitTestingMutation).toHaveBeenCalled()
+      })
+      // Success callbacks should not fire when onSuccess is not invoked
+      expect(mockSetHitResult).not.toHaveBeenCalled()
+      expect(mockOnUpdateList).not.toHaveBeenCalled()
+      expect(mockOnSubmit).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('API Response → Results Data Contract', () => {
+    it('should produce results with required segment fields for rendering', () => {
+      const response = createHitTestingResponse(3)
+
+      // Validate each result has the fields needed by ResultItem component
+      response.records.forEach((record) => {
+        expect(record.segment).toHaveProperty('id')
+        expect(record.segment).toHaveProperty('content')
+        expect(record.segment).toHaveProperty('position')
+        expect(record.segment).toHaveProperty('word_count')
+        expect(record.segment).toHaveProperty('document')
+        expect(record.segment.document).toHaveProperty('name')
+        expect(record.score).toBeGreaterThanOrEqual(0)
+        expect(record.score).toBeLessThanOrEqual(1)
+      })
+    })
+
+    it('should maintain correct score ordering', () => {
+      const response = createHitTestingResponse(5)
+
+      for (let i = 1; i < response.records.length; i++) {
+        expect(response.records[i - 1].score).toBeGreaterThanOrEqual(response.records[i].score)
+      }
+    })
+
+    it('should include document metadata for result item display', () => {
+      const response = createHitTestingResponse(1)
+      const record = response.records[0]
+
+      expect(record.segment.document.name).toBeTruthy()
+      expect(record.segment.document.data_source_type).toBeTruthy()
+    })
+  })
+
+  describe('Successful Submission → Callback Chain', () => {
+    it('should call setHitResult, onUpdateList, and onSubmit after successful submission', async () => {
+      const response = createHitTestingResponse(3)
+      mockHitTestingMutation.mockImplementation(async (_params: unknown, options?: { onSuccess?: (data: HitTestingResponse) => void }) => {
+        options?.onSuccess?.(response)
+        return response
+      })
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('Test query'),
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockSetHitResult).toHaveBeenCalledWith(response)
+        expect(mockOnUpdateList).toHaveBeenCalledTimes(1)
+        expect(mockOnSubmit).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('should trigger records list refresh via onUpdateList after query', async () => {
+      const response = createHitTestingResponse(1)
+      mockHitTestingMutation.mockImplementation(async (_params: unknown, options?: { onSuccess?: (data: HitTestingResponse) => void }) => {
+        options?.onSuccess?.(response)
+        return response
+      })
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('new query'),
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockOnUpdateList).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+
+  describe('External KB Hit Testing', () => {
+    it('should use external mutation with correct payload for external datasets', async () => {
+      mockExternalMutation.mockImplementation(async (_params: unknown, options?: { onSuccess?: (data: { records: never[] }) => void }) => {
+        const response = { records: [] }
+        options?.onSuccess?.(response)
+        return response
+      })
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('test'),
+          isExternal: true,
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockExternalMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            query: 'test',
+            external_retrieval_model: expect.objectContaining({
+              top_k: 4,
+              score_threshold: 0.5,
+              score_threshold_enabled: false,
+            }),
+          }),
+          expect.objectContaining({
+            onSuccess: expect.any(Function),
+          }),
+        )
+        // Internal mutation should NOT be called
+        expect(mockHitTestingMutation).not.toHaveBeenCalled()
+      })
+    })
+
+    it('should call setExternalHitResult and onUpdateList on successful external submission', async () => {
+      const externalResponse = { records: [] }
+      mockExternalMutation.mockImplementation(async (_params: unknown, options?: { onSuccess?: (data: { records: never[] }) => void }) => {
+        options?.onSuccess?.(externalResponse)
+        return externalResponse
+      })
+
+      render(
+        <QueryInput {...createDefaultProps({
+          queries: createTextQuery('external query'),
+          isExternal: true,
+        })}
+        />,
+      )
+
+      fireEvent.click(findSubmitButton())
+
+      await waitFor(() => {
+        expect(mockSetExternalHitResult).toHaveBeenCalledWith(externalResponse)
+        expect(mockOnUpdateList).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+})

web/__tests__/datasets/metadata-management-flow.test.tsx

@@ -0,0 +1,337 @@
+/**
+ * Integration Test: Metadata Management Flow
+ *
+ * Tests the cross-module composition of metadata name validation, type constraints,
+ * and duplicate detection across the metadata management hooks.
+ *
+ * The unit-level use-check-metadata-name.spec.ts tests the validation hook alone.
+ * This integration test verifies:
+ *   - Name validation combined with existing metadata list (duplicate detection)
+ *   - Metadata type enum constraints matching expected data model
+ *   - Full add/rename workflow: validate name → check duplicates → allow or reject
+ *   - Name uniqueness logic: existing metadata keeps its own name, cannot take another's
+ */
+
+import type { MetadataItemWithValueLength } from '@/app/components/datasets/metadata/types'
+import { renderHook } from '@testing-library/react'
+import { DataType } from '@/app/components/datasets/metadata/types'
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+const { default: useCheckMetadataName } = await import(
+  '@/app/components/datasets/metadata/hooks/use-check-metadata-name',
+)
+
+// --- Factory functions ---
+
+const createMetadataItem = (
+  id: string,
+  name: string,
+  type = DataType.string,
+  count = 0,
+): MetadataItemWithValueLength => ({
+  id,
+  name,
+  type,
+  count,
+})
+
+const createMetadataList = (): MetadataItemWithValueLength[] => [
+  createMetadataItem('meta-1', 'author', DataType.string, 5),
+  createMetadataItem('meta-2', 'created_date', DataType.time, 10),
+  createMetadataItem('meta-3', 'page_count', DataType.number, 3),
+  createMetadataItem('meta-4', 'source_url', DataType.string, 8),
+  createMetadataItem('meta-5', 'version', DataType.number, 2),
+]
+
+describe('Metadata Management Flow - Cross-Module Validation Composition', () => {
+  describe('Name Validation Flow: Format Rules', () => {
+    it('should accept valid lowercase names with underscores', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      expect(result.current.checkName('valid_name').errorMsg).toBe('')
+      expect(result.current.checkName('author').errorMsg).toBe('')
+      expect(result.current.checkName('page_count').errorMsg).toBe('')
+      expect(result.current.checkName('v2_field').errorMsg).toBe('')
+    })
+
+    it('should reject empty names', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      expect(result.current.checkName('').errorMsg).toBeTruthy()
+    })
+
+    it('should reject names with invalid characters', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      expect(result.current.checkName('Author').errorMsg).toBeTruthy()
+      expect(result.current.checkName('my-field').errorMsg).toBeTruthy()
+      expect(result.current.checkName('field name').errorMsg).toBeTruthy()
+      expect(result.current.checkName('1field').errorMsg).toBeTruthy()
+      expect(result.current.checkName('_private').errorMsg).toBeTruthy()
+    })
+
+    it('should reject names exceeding 255 characters', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      const longName = 'a'.repeat(256)
+      expect(result.current.checkName(longName).errorMsg).toBeTruthy()
+
+      const maxName = 'a'.repeat(255)
+      expect(result.current.checkName(maxName).errorMsg).toBe('')
+    })
+  })
+
+  describe('Metadata Type Constraints: Enum Values Match Expected Set', () => {
+    it('should define exactly three data types', () => {
+      const typeValues = Object.values(DataType)
+      expect(typeValues).toHaveLength(3)
+    })
+
+    it('should include string, number, and time types', () => {
+      expect(DataType.string).toBe('string')
+      expect(DataType.number).toBe('number')
+      expect(DataType.time).toBe('time')
+    })
+
+    it('should use consistent types in metadata items', () => {
+      const metadataList = createMetadataList()
+
+      const stringItems = metadataList.filter(m => m.type === DataType.string)
+      const numberItems = metadataList.filter(m => m.type === DataType.number)
+      const timeItems = metadataList.filter(m => m.type === DataType.time)
+
+      expect(stringItems).toHaveLength(2)
+      expect(numberItems).toHaveLength(2)
+      expect(timeItems).toHaveLength(1)
+    })
+
+    it('should enforce type-safe metadata item construction', () => {
+      const item = createMetadataItem('test-1', 'test_field', DataType.number, 0)
+
+      expect(item.id).toBe('test-1')
+      expect(item.name).toBe('test_field')
+      expect(item.type).toBe(DataType.number)
+      expect(item.count).toBe(0)
+    })
+  })
+
+  describe('Duplicate Name Detection: Add Metadata → Check Name → Detect Duplicates', () => {
+    it('should detect duplicate names against an existing metadata list', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const checkDuplicate = (newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        return existingMetadata.some(m => m.name === newName)
+      }
+
+      expect(checkDuplicate('author')).toBe(true)
+      expect(checkDuplicate('created_date')).toBe(true)
+      expect(checkDuplicate('page_count')).toBe(true)
+    })
+
+    it('should allow names that do not conflict with existing metadata', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const isNameAvailable = (newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        return !existingMetadata.some(m => m.name === newName)
+      }
+
+      expect(isNameAvailable('category')).toBe(true)
+      expect(isNameAvailable('file_size')).toBe(true)
+      expect(isNameAvailable('language')).toBe(true)
+    })
+
+    it('should reject names that fail format validation before duplicate check', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      const validateAndCheckDuplicate = (newName: string): { valid: boolean, reason: string } => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return { valid: false, reason: 'format' }
+        return { valid: true, reason: '' }
+      }
+
+      expect(validateAndCheckDuplicate('Author').reason).toBe('format')
+      expect(validateAndCheckDuplicate('').reason).toBe('format')
+      expect(validateAndCheckDuplicate('valid_name').valid).toBe(true)
+    })
+  })
+
+  describe('Name Uniqueness Across Edits: Rename Workflow', () => {
+    it('should allow an existing metadata item to keep its own name', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const isRenameValid = (itemId: string, newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        // Allow keeping the same name (skip self in duplicate check)
+        return !existingMetadata.some(m => m.name === newName && m.id !== itemId)
+      }
+
+      // Author keeping its own name should be valid
+      expect(isRenameValid('meta-1', 'author')).toBe(true)
+      // page_count keeping its own name should be valid
+      expect(isRenameValid('meta-3', 'page_count')).toBe(true)
+    })
+
+    it('should reject renaming to another existing metadata name', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const isRenameValid = (itemId: string, newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        return !existingMetadata.some(m => m.name === newName && m.id !== itemId)
+      }
+
+      // Author trying to rename to "page_count" (taken by meta-3)
+      expect(isRenameValid('meta-1', 'page_count')).toBe(false)
+      // version trying to rename to "source_url" (taken by meta-4)
+      expect(isRenameValid('meta-5', 'source_url')).toBe(false)
+    })
+
+    it('should allow renaming to a completely new valid name', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const isRenameValid = (itemId: string, newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        return !existingMetadata.some(m => m.name === newName && m.id !== itemId)
+      }
+
+      expect(isRenameValid('meta-1', 'document_author')).toBe(true)
+      expect(isRenameValid('meta-2', 'publish_date')).toBe(true)
+      expect(isRenameValid('meta-3', 'total_pages')).toBe(true)
+    })
+
+    it('should reject renaming with an invalid format even if name is unique', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const isRenameValid = (itemId: string, newName: string): boolean => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return false
+        return !existingMetadata.some(m => m.name === newName && m.id !== itemId)
+      }
+
+      expect(isRenameValid('meta-1', 'New Author')).toBe(false)
+      expect(isRenameValid('meta-2', '2024_date')).toBe(false)
+      expect(isRenameValid('meta-3', '')).toBe(false)
+    })
+  })
+
+  describe('Full Metadata Management Workflow', () => {
+    it('should support a complete add-validate-check-duplicate cycle', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const addMetadataField = (
+        name: string,
+        type: DataType,
+      ): { success: boolean, error?: string } => {
+        const formatCheck = result.current.checkName(name)
+        if (formatCheck.errorMsg)
+          return { success: false, error: 'invalid_format' }
+
+        if (existingMetadata.some(m => m.name === name))
+          return { success: false, error: 'duplicate_name' }
+
+        existingMetadata.push(createMetadataItem(`meta-${existingMetadata.length + 1}`, name, type))
+        return { success: true }
+      }
+
+      // Add a valid new field
+      const result1 = addMetadataField('department', DataType.string)
+      expect(result1.success).toBe(true)
+      expect(existingMetadata).toHaveLength(6)
+
+      // Try to add a duplicate
+      const result2 = addMetadataField('author', DataType.string)
+      expect(result2.success).toBe(false)
+      expect(result2.error).toBe('duplicate_name')
+      expect(existingMetadata).toHaveLength(6)
+
+      // Try to add an invalid name
+      const result3 = addMetadataField('Invalid Name', DataType.string)
+      expect(result3.success).toBe(false)
+      expect(result3.error).toBe('invalid_format')
+      expect(existingMetadata).toHaveLength(6)
+
+      // Add another valid field
+      const result4 = addMetadataField('priority_level', DataType.number)
+      expect(result4.success).toBe(true)
+      expect(existingMetadata).toHaveLength(7)
+    })
+
+    it('should support a complete rename workflow with validation chain', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+      const existingMetadata = createMetadataList()
+
+      const renameMetadataField = (
+        itemId: string,
+        newName: string,
+      ): { success: boolean, error?: string } => {
+        const formatCheck = result.current.checkName(newName)
+        if (formatCheck.errorMsg)
+          return { success: false, error: 'invalid_format' }
+
+        if (existingMetadata.some(m => m.name === newName && m.id !== itemId))
+          return { success: false, error: 'duplicate_name' }
+
+        const item = existingMetadata.find(m => m.id === itemId)
+        if (!item)
+          return { success: false, error: 'not_found' }
+
+        // Simulate the rename in-place
+        const index = existingMetadata.indexOf(item)
+        existingMetadata[index] = { ...item, name: newName }
+        return { success: true }
+      }
+
+      // Rename author to document_author
+      expect(renameMetadataField('meta-1', 'document_author').success).toBe(true)
+      expect(existingMetadata.find(m => m.id === 'meta-1')?.name).toBe('document_author')
+
+      // Try renaming created_date to page_count (already taken)
+      expect(renameMetadataField('meta-2', 'page_count').error).toBe('duplicate_name')
+
+      // Rename to invalid format
+      expect(renameMetadataField('meta-3', 'Page Count').error).toBe('invalid_format')
+
+      // Rename non-existent item
+      expect(renameMetadataField('meta-999', 'something').error).toBe('not_found')
+    })
+
+    it('should maintain validation consistency across multiple operations', () => {
+      const { result } = renderHook(() => useCheckMetadataName())
+
+      // Validate the same name multiple times for consistency
+      const name = 'consistent_field'
+      const results = Array.from({ length: 5 }, () => result.current.checkName(name))
+
+      expect(results.every(r => r.errorMsg === '')).toBe(true)
+
+      // Validate an invalid name multiple times
+      const invalidResults = Array.from({ length: 5 }, () => result.current.checkName('Invalid'))
+      expect(invalidResults.every(r => r.errorMsg !== '')).toBe(true)
+    })
+  })
+})

web/__tests__/datasets/pipeline-datasource-flow.test.tsx

@@ -0,0 +1,477 @@
+/**
+ * Integration Test: Pipeline Data Source Store Composition
+ *
+ * Tests cross-slice interactions in the pipeline data source Zustand store.
+ * The unit-level slice specs test each slice in isolation.
+ * This integration test verifies:
+ *   - Store initialization produces correct defaults across all slices
+ *   - Cross-slice coordination (e.g. credential shared across slices)
+ *   - State isolation: changes in one slice do not affect others
+ *   - Full workflow simulation through credential → source → data path
+ */
+
+import type { NotionPage } from '@/models/common'
+import type { CrawlResultItem, FileItem } from '@/models/datasets'
+import type { OnlineDriveFile } from '@/models/pipeline'
+import { createDataSourceStore } from '@/app/components/datasets/documents/create-from-pipeline/data-source/store'
+import { CrawlStep } from '@/models/datasets'
+import { OnlineDriveFileType } from '@/models/pipeline'
+
+// --- Factory functions ---
+
+const createFileItem = (id: string): FileItem => ({
+  fileID: id,
+  file: { id, name: `${id}.txt`, size: 1024 } as FileItem['file'],
+  progress: 100,
+})
+
+const createCrawlResultItem = (url: string, title?: string): CrawlResultItem => ({
+  title: title ?? `Page: ${url}`,
+  markdown: `# ${title ?? url}\n\nContent for ${url}`,
+  description: `Description for ${url}`,
+  source_url: url,
+})
+
+const createOnlineDriveFile = (id: string, name: string, type = OnlineDriveFileType.file): OnlineDriveFile => ({
+  id,
+  name,
+  size: 2048,
+  type,
+})
+
+const createNotionPage = (pageId: string): NotionPage => ({
+  page_id: pageId,
+  page_name: `Page ${pageId}`,
+  page_icon: null,
+  is_bound: true,
+  parent_id: 'parent-1',
+  type: 'page',
+  workspace_id: 'ws-1',
+})
+
+describe('Pipeline Data Source Store Composition - Cross-Slice Integration', () => {
+  describe('Store Initialization → All Slices Have Correct Defaults', () => {
+    it('should create a store with all five slices combined', () => {
+      const store = createDataSourceStore()
+      const state = store.getState()
+
+      // Common slice defaults
+      expect(state.currentCredentialId).toBe('')
+      expect(state.currentNodeIdRef.current).toBe('')
+
+      // Local file slice defaults
+      expect(state.localFileList).toEqual([])
+      expect(state.currentLocalFile).toBeUndefined()
+
+      // Online document slice defaults
+      expect(state.documentsData).toEqual([])
+      expect(state.onlineDocuments).toEqual([])
+      expect(state.searchValue).toBe('')
+      expect(state.selectedPagesId).toEqual(new Set())
+
+      // Website crawl slice defaults
+      expect(state.websitePages).toEqual([])
+      expect(state.step).toBe(CrawlStep.init)
+      expect(state.previewIndex).toBe(-1)
+
+      // Online drive slice defaults
+      expect(state.breadcrumbs).toEqual([])
+      expect(state.prefix).toEqual([])
+      expect(state.keywords).toBe('')
+      expect(state.selectedFileIds).toEqual([])
+      expect(state.onlineDriveFileList).toEqual([])
+      expect(state.bucket).toBe('')
+      expect(state.hasBucket).toBe(false)
+    })
+  })
+
+  describe('Cross-Slice Coordination: Shared Credential', () => {
+    it('should set credential that is accessible from the common slice', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setCurrentCredentialId('cred-abc-123')
+
+      expect(store.getState().currentCredentialId).toBe('cred-abc-123')
+    })
+
+    it('should allow credential update independently of all other slices', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setLocalFileList([createFileItem('f1')])
+      store.getState().setCurrentCredentialId('cred-xyz')
+
+      expect(store.getState().currentCredentialId).toBe('cred-xyz')
+      expect(store.getState().localFileList).toHaveLength(1)
+    })
+  })
+
+  describe('Local File Workflow: Set Files → Verify List → Clear', () => {
+    it('should set and retrieve local file list', () => {
+      const store = createDataSourceStore()
+      const files = [createFileItem('f1'), createFileItem('f2'), createFileItem('f3')]
+
+      store.getState().setLocalFileList(files)
+
+      expect(store.getState().localFileList).toHaveLength(3)
+      expect(store.getState().localFileList[0].fileID).toBe('f1')
+      expect(store.getState().localFileList[2].fileID).toBe('f3')
+    })
+
+    it('should update preview ref when setting file list', () => {
+      const store = createDataSourceStore()
+      const files = [createFileItem('f-preview')]
+
+      store.getState().setLocalFileList(files)
+
+      expect(store.getState().previewLocalFileRef.current).toBeDefined()
+    })
+
+    it('should clear files by setting empty list', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setLocalFileList([createFileItem('f1')])
+      expect(store.getState().localFileList).toHaveLength(1)
+
+      store.getState().setLocalFileList([])
+      expect(store.getState().localFileList).toHaveLength(0)
+    })
+
+    it('should set and clear current local file selection', () => {
+      const store = createDataSourceStore()
+      const file = { id: 'current-file', name: 'current.txt' } as FileItem['file']
+
+      store.getState().setCurrentLocalFile(file)
+      expect(store.getState().currentLocalFile).toBeDefined()
+      expect(store.getState().currentLocalFile?.id).toBe('current-file')
+
+      store.getState().setCurrentLocalFile(undefined)
+      expect(store.getState().currentLocalFile).toBeUndefined()
+    })
+  })
+
+  describe('Online Document Workflow: Set Documents → Select Pages → Verify', () => {
+    it('should set documents data and online documents', () => {
+      const store = createDataSourceStore()
+      const pages = [createNotionPage('page-1'), createNotionPage('page-2')]
+
+      store.getState().setOnlineDocuments(pages)
+
+      expect(store.getState().onlineDocuments).toHaveLength(2)
+      expect(store.getState().onlineDocuments[0].page_id).toBe('page-1')
+    })
+
+    it('should update preview ref when setting online documents', () => {
+      const store = createDataSourceStore()
+      const pages = [createNotionPage('page-preview')]
+
+      store.getState().setOnlineDocuments(pages)
+
+      expect(store.getState().previewOnlineDocumentRef.current).toBeDefined()
+      expect(store.getState().previewOnlineDocumentRef.current?.page_id).toBe('page-preview')
+    })
+
+    it('should track selected page IDs', () => {
+      const store = createDataSourceStore()
+      const pages = [createNotionPage('p1'), createNotionPage('p2'), createNotionPage('p3')]
+
+      store.getState().setOnlineDocuments(pages)
+      store.getState().setSelectedPagesId(new Set(['p1', 'p3']))
+
+      expect(store.getState().selectedPagesId.size).toBe(2)
+      expect(store.getState().selectedPagesId.has('p1')).toBe(true)
+      expect(store.getState().selectedPagesId.has('p2')).toBe(false)
+      expect(store.getState().selectedPagesId.has('p3')).toBe(true)
+    })
+
+    it('should manage search value for filtering documents', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setSearchValue('meeting notes')
+
+      expect(store.getState().searchValue).toBe('meeting notes')
+    })
+
+    it('should set and clear current document selection', () => {
+      const store = createDataSourceStore()
+      const page = createNotionPage('current-page')
+
+      store.getState().setCurrentDocument(page)
+      expect(store.getState().currentDocument?.page_id).toBe('current-page')
+
+      store.getState().setCurrentDocument(undefined)
+      expect(store.getState().currentDocument).toBeUndefined()
+    })
+  })
+
+  describe('Website Crawl Workflow: Set Pages → Track Step → Preview', () => {
+    it('should set website pages and update preview ref', () => {
+      const store = createDataSourceStore()
+      const pages = [
+        createCrawlResultItem('https://example.com'),
+        createCrawlResultItem('https://example.com/about'),
+      ]
+
+      store.getState().setWebsitePages(pages)
+
+      expect(store.getState().websitePages).toHaveLength(2)
+      expect(store.getState().previewWebsitePageRef.current?.source_url).toBe('https://example.com')
+    })
+
+    it('should manage crawl step transitions', () => {
+      const store = createDataSourceStore()
+
+      expect(store.getState().step).toBe(CrawlStep.init)
+
+      store.getState().setStep(CrawlStep.running)
+      expect(store.getState().step).toBe(CrawlStep.running)
+
+      store.getState().setStep(CrawlStep.finished)
+      expect(store.getState().step).toBe(CrawlStep.finished)
+    })
+
+    it('should set crawl result with data and timing', () => {
+      const store = createDataSourceStore()
+      const result = {
+        data: [createCrawlResultItem('https://test.com')],
+        time_consuming: 3.5,
+      }
+
+      store.getState().setCrawlResult(result)
+
+      expect(store.getState().crawlResult?.data).toHaveLength(1)
+      expect(store.getState().crawlResult?.time_consuming).toBe(3.5)
+    })
+
+    it('should manage preview index for page navigation', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setPreviewIndex(2)
+      expect(store.getState().previewIndex).toBe(2)
+
+      store.getState().setPreviewIndex(-1)
+      expect(store.getState().previewIndex).toBe(-1)
+    })
+
+    it('should set and clear current website selection', () => {
+      const store = createDataSourceStore()
+      const page = createCrawlResultItem('https://current.com')
+
+      store.getState().setCurrentWebsite(page)
+      expect(store.getState().currentWebsite?.source_url).toBe('https://current.com')
+
+      store.getState().setCurrentWebsite(undefined)
+      expect(store.getState().currentWebsite).toBeUndefined()
+    })
+  })
+
+  describe('Online Drive Workflow: Breadcrumbs → File Selection → Navigation', () => {
+    it('should manage breadcrumb navigation', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setBreadcrumbs(['root', 'folder-a', 'subfolder'])
+
+      expect(store.getState().breadcrumbs).toEqual(['root', 'folder-a', 'subfolder'])
+    })
+
+    it('should support breadcrumb push/pop pattern', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setBreadcrumbs(['root'])
+      store.getState().setBreadcrumbs([...store.getState().breadcrumbs, 'level-1'])
+      store.getState().setBreadcrumbs([...store.getState().breadcrumbs, 'level-2'])
+
+      expect(store.getState().breadcrumbs).toEqual(['root', 'level-1', 'level-2'])
+
+      // Pop back one level
+      store.getState().setBreadcrumbs(store.getState().breadcrumbs.slice(0, -1))
+      expect(store.getState().breadcrumbs).toEqual(['root', 'level-1'])
+    })
+
+    it('should manage file list and selection', () => {
+      const store = createDataSourceStore()
+      const files = [
+        createOnlineDriveFile('drive-1', 'report.pdf'),
+        createOnlineDriveFile('drive-2', 'data.csv'),
+        createOnlineDriveFile('drive-3', 'images', OnlineDriveFileType.folder),
+      ]
+
+      store.getState().setOnlineDriveFileList(files)
+      expect(store.getState().onlineDriveFileList).toHaveLength(3)
+
+      store.getState().setSelectedFileIds(['drive-1', 'drive-2'])
+      expect(store.getState().selectedFileIds).toEqual(['drive-1', 'drive-2'])
+    })
+
+    it('should update preview ref when selecting files', () => {
+      const store = createDataSourceStore()
+      const files = [
+        createOnlineDriveFile('drive-a', 'file-a.txt'),
+        createOnlineDriveFile('drive-b', 'file-b.txt'),
+      ]
+
+      store.getState().setOnlineDriveFileList(files)
+      store.getState().setSelectedFileIds(['drive-b'])
+
+      expect(store.getState().previewOnlineDriveFileRef.current?.id).toBe('drive-b')
+    })
+
+    it('should manage bucket and prefix for S3-like navigation', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setBucket('my-data-bucket')
+      store.getState().setPrefix(['data', '2024'])
+      store.getState().setHasBucket(true)
+
+      expect(store.getState().bucket).toBe('my-data-bucket')
+      expect(store.getState().prefix).toEqual(['data', '2024'])
+      expect(store.getState().hasBucket).toBe(true)
+    })
+
+    it('should manage keywords for search filtering', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setKeywords('quarterly report')
+      expect(store.getState().keywords).toBe('quarterly report')
+    })
+  })
+
+  describe('State Isolation: Changes to One Slice Do Not Affect Others', () => {
+    it('should keep local file state independent from online document state', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setLocalFileList([createFileItem('local-1')])
+      store.getState().setOnlineDocuments([createNotionPage('notion-1')])
+
+      expect(store.getState().localFileList).toHaveLength(1)
+      expect(store.getState().onlineDocuments).toHaveLength(1)
+
+      // Clearing local files should not affect online documents
+      store.getState().setLocalFileList([])
+      expect(store.getState().localFileList).toHaveLength(0)
+      expect(store.getState().onlineDocuments).toHaveLength(1)
+    })
+
+    it('should keep website crawl state independent from online drive state', () => {
+      const store = createDataSourceStore()
+
+      store.getState().setWebsitePages([createCrawlResultItem('https://site.com')])
+      store.getState().setOnlineDriveFileList([createOnlineDriveFile('d1', 'file.txt')])
+
+      expect(store.getState().websitePages).toHaveLength(1)
+      expect(store.getState().onlineDriveFileList).toHaveLength(1)
+
+      // Clearing website pages should not affect drive files
+      store.getState().setWebsitePages([])
+      expect(store.getState().websitePages).toHaveLength(0)
+      expect(store.getState().onlineDriveFileList).toHaveLength(1)
+    })
+
+    it('should create fully independent store instances', () => {
+      const storeA = createDataSourceStore()
+      const storeB = createDataSourceStore()
+
+      storeA.getState().setCurrentCredentialId('cred-A')
+      storeA.getState().setLocalFileList([createFileItem('fa-1')])
+
+      expect(storeA.getState().currentCredentialId).toBe('cred-A')
+      expect(storeB.getState().currentCredentialId).toBe('')
+      expect(storeB.getState().localFileList).toEqual([])
+    })
+  })
+
+  describe('Full Workflow Simulation: Credential → Source → Data → Verify', () => {
+    it('should support a complete local file upload workflow', () => {
+      const store = createDataSourceStore()
+
+      // Step 1: Set credential
+      store.getState().setCurrentCredentialId('upload-cred-1')
+
+      // Step 2: Set file list
+      const files = [createFileItem('upload-1'), createFileItem('upload-2')]
+      store.getState().setLocalFileList(files)
+
+      // Step 3: Select current file for preview
+      store.getState().setCurrentLocalFile(files[0].file)
+
+      // Verify all state is consistent
+      expect(store.getState().currentCredentialId).toBe('upload-cred-1')
+      expect(store.getState().localFileList).toHaveLength(2)
+      expect(store.getState().currentLocalFile?.id).toBe('upload-1')
+      expect(store.getState().previewLocalFileRef.current).toBeDefined()
+    })
+
+    it('should support a complete website crawl workflow', () => {
+      const store = createDataSourceStore()
+
+      // Step 1: Set credential
+      store.getState().setCurrentCredentialId('crawl-cred-1')
+
+      // Step 2: Init crawl
+      store.getState().setStep(CrawlStep.running)
+
+      // Step 3: Crawl completes with results
+      const crawledPages = [
+        createCrawlResultItem('https://docs.example.com/guide'),
+        createCrawlResultItem('https://docs.example.com/api'),
+        createCrawlResultItem('https://docs.example.com/faq'),
+      ]
+      store.getState().setCrawlResult({ data: crawledPages, time_consuming: 12.5 })
+      store.getState().setStep(CrawlStep.finished)
+
+      // Step 4: Set website pages from results
+      store.getState().setWebsitePages(crawledPages)
+
+      // Step 5: Set preview
+      store.getState().setPreviewIndex(1)
+
+      // Verify all state
+      expect(store.getState().currentCredentialId).toBe('crawl-cred-1')
+      expect(store.getState().step).toBe(CrawlStep.finished)
+      expect(store.getState().websitePages).toHaveLength(3)
+      expect(store.getState().crawlResult?.time_consuming).toBe(12.5)
+      expect(store.getState().previewIndex).toBe(1)
+      expect(store.getState().previewWebsitePageRef.current?.source_url).toBe('https://docs.example.com/guide')
+    })
+
+    it('should support a complete online drive navigation workflow', () => {
+      const store = createDataSourceStore()
+
+      // Step 1: Set credential
+      store.getState().setCurrentCredentialId('drive-cred-1')
+
+      // Step 2: Set bucket
+      store.getState().setBucket('company-docs')
+      store.getState().setHasBucket(true)
+
+      // Step 3: Navigate into folders
+      store.getState().setBreadcrumbs(['company-docs'])
+      store.getState().setPrefix(['projects'])
+      const folderFiles = [
+        createOnlineDriveFile('proj-1', 'project-alpha', OnlineDriveFileType.folder),
+        createOnlineDriveFile('proj-2', 'project-beta', OnlineDriveFileType.folder),
+        createOnlineDriveFile('readme', 'README.md', OnlineDriveFileType.file),
+      ]
+      store.getState().setOnlineDriveFileList(folderFiles)
+
+      // Step 4: Navigate deeper
+      store.getState().setBreadcrumbs([...store.getState().breadcrumbs, 'project-alpha'])
+      store.getState().setPrefix([...store.getState().prefix, 'project-alpha'])
+
+      // Step 5: Select files
+      store.getState().setOnlineDriveFileList([
+        createOnlineDriveFile('doc-1', 'spec.pdf'),
+        createOnlineDriveFile('doc-2', 'design.fig'),
+      ])
+      store.getState().setSelectedFileIds(['doc-1'])
+
+      // Verify full state
+      expect(store.getState().currentCredentialId).toBe('drive-cred-1')
+      expect(store.getState().bucket).toBe('company-docs')
+      expect(store.getState().breadcrumbs).toEqual(['company-docs', 'project-alpha'])
+      expect(store.getState().prefix).toEqual(['projects', 'project-alpha'])
+      expect(store.getState().onlineDriveFileList).toHaveLength(2)
+      expect(store.getState().selectedFileIds).toEqual(['doc-1'])
+      expect(store.getState().previewOnlineDriveFileRef.current?.name).toBe('spec.pdf')
+    })
+  })
+})

web/__tests__/datasets/segment-crud.test.tsx

@@ -0,0 +1,301 @@
+/**
+ * Integration Test: Segment CRUD Flow
+ *
+ * Tests segment selection, search/filter, and modal state management across hooks.
+ * Validates cross-hook data contracts in the completed segment module.
+ */
+
+import type { SegmentDetailModel } from '@/models/datasets'
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useModalState } from '@/app/components/datasets/documents/detail/completed/hooks/use-modal-state'
+import { useSearchFilter } from '@/app/components/datasets/documents/detail/completed/hooks/use-search-filter'
+import { useSegmentSelection } from '@/app/components/datasets/documents/detail/completed/hooks/use-segment-selection'
+
+const createSegment = (id: string, content = 'Test segment content'): SegmentDetailModel => ({
+  id,
+  position: 1,
+  document_id: 'doc-1',
+  content,
+  sign_content: content,
+  answer: '',
+  word_count: 50,
+  tokens: 25,
+  keywords: ['test'],
+  index_node_id: 'idx-1',
+  index_node_hash: 'hash-1',
+  hit_count: 0,
+  enabled: true,
+  disabled_at: 0,
+  disabled_by: '',
+  status: 'completed',
+  created_by: 'user-1',
+  created_at: Date.now(),
+  indexing_at: Date.now(),
+  completed_at: Date.now(),
+  error: null,
+  stopped_at: 0,
+  updated_at: Date.now(),
+  attachments: [],
+} as SegmentDetailModel)
+
+describe('Segment CRUD Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Search and Filter → Segment List Query', () => {
+    it('should manage search input with debounce', () => {
+      vi.useFakeTimers()
+      const onPageChange = vi.fn()
+      const { result } = renderHook(() => useSearchFilter({ onPageChange }))
+
+      act(() => {
+        result.current.handleInputChange('keyword')
+      })
+
+      expect(result.current.inputValue).toBe('keyword')
+      expect(result.current.searchValue).toBe('')
+
+      act(() => {
+        vi.advanceTimersByTime(500)
+      })
+      expect(result.current.searchValue).toBe('keyword')
+      expect(onPageChange).toHaveBeenCalledWith(1)
+
+      vi.useRealTimers()
+    })
+
+    it('should manage status filter state', () => {
+      const onPageChange = vi.fn()
+      const { result } = renderHook(() => useSearchFilter({ onPageChange }))
+
+      // status value 1 maps to !!1 = true (enabled)
+      act(() => {
+        result.current.onChangeStatus({ value: 1, name: 'enabled' })
+      })
+      // onChangeStatus converts: value === 'all' ? 'all' : !!value
+      expect(result.current.selectedStatus).toBe(true)
+
+      act(() => {
+        result.current.onClearFilter()
+      })
+      expect(result.current.selectedStatus).toBe('all')
+      expect(result.current.inputValue).toBe('')
+    })
+
+    it('should provide status list for filter dropdown', () => {
+      const { result } = renderHook(() => useSearchFilter({ onPageChange: vi.fn() }))
+      expect(result.current.statusList).toBeInstanceOf(Array)
+      expect(result.current.statusList.length).toBe(3) // all, disabled, enabled
+    })
+
+    it('should compute selectDefaultValue based on selectedStatus', () => {
+      const { result } = renderHook(() => useSearchFilter({ onPageChange: vi.fn() }))
+
+      // Initial state: 'all'
+      expect(result.current.selectDefaultValue).toBe('all')
+
+      // Set to enabled (true)
+      act(() => {
+        result.current.onChangeStatus({ value: 1, name: 'enabled' })
+      })
+      expect(result.current.selectDefaultValue).toBe(1)
+
+      // Set to disabled (false)
+      act(() => {
+        result.current.onChangeStatus({ value: 0, name: 'disabled' })
+      })
+      expect(result.current.selectDefaultValue).toBe(0)
+    })
+  })
+
+  describe('Segment Selection → Batch Operations', () => {
+    const segments = [
+      createSegment('seg-1'),
+      createSegment('seg-2'),
+      createSegment('seg-3'),
+    ]
+
+    it('should manage individual segment selection', () => {
+      const { result } = renderHook(() => useSegmentSelection(segments))
+
+      act(() => {
+        result.current.onSelected('seg-1')
+      })
+      expect(result.current.selectedSegmentIds).toContain('seg-1')
+
+      act(() => {
+        result.current.onSelected('seg-2')
+      })
+      expect(result.current.selectedSegmentIds).toContain('seg-1')
+      expect(result.current.selectedSegmentIds).toContain('seg-2')
+      expect(result.current.selectedSegmentIds).toHaveLength(2)
+    })
+
+    it('should toggle selection on repeated click', () => {
+      const { result } = renderHook(() => useSegmentSelection(segments))
+
+      act(() => {
+        result.current.onSelected('seg-1')
+      })
+      expect(result.current.selectedSegmentIds).toContain('seg-1')
+
+      act(() => {
+        result.current.onSelected('seg-1')
+      })
+      expect(result.current.selectedSegmentIds).not.toContain('seg-1')
+    })
+
+    it('should support select all toggle', () => {
+      const { result } = renderHook(() => useSegmentSelection(segments))
+
+      act(() => {
+        result.current.onSelectedAll()
+      })
+      expect(result.current.selectedSegmentIds).toHaveLength(3)
+      expect(result.current.isAllSelected).toBe(true)
+
+      act(() => {
+        result.current.onSelectedAll()
+      })
+      expect(result.current.selectedSegmentIds).toHaveLength(0)
+      expect(result.current.isAllSelected).toBe(false)
+    })
+
+    it('should detect partial selection via isSomeSelected', () => {
+      const { result } = renderHook(() => useSegmentSelection(segments))
+
+      act(() => {
+        result.current.onSelected('seg-1')
+      })
+
+      // After selecting one of three, isSomeSelected should be true
+      expect(result.current.selectedSegmentIds).toEqual(['seg-1'])
+      expect(result.current.isSomeSelected).toBe(true)
+      expect(result.current.isAllSelected).toBe(false)
+    })
+
+    it('should clear selection via onCancelBatchOperation', () => {
+      const { result } = renderHook(() => useSegmentSelection(segments))
+
+      act(() => {
+        result.current.onSelected('seg-1')
+        result.current.onSelected('seg-2')
+      })
+      expect(result.current.selectedSegmentIds).toHaveLength(2)
+
+      act(() => {
+        result.current.onCancelBatchOperation()
+      })
+      expect(result.current.selectedSegmentIds).toHaveLength(0)
+    })
+  })
+
+  describe('Modal State Management', () => {
+    const onNewSegmentModalChange = vi.fn()
+
+    it('should open segment detail modal on card click', () => {
+      const { result } = renderHook(() => useModalState({ onNewSegmentModalChange }))
+
+      const segment = createSegment('seg-detail-1', 'Detail content')
+      act(() => {
+        result.current.onClickCard(segment)
+      })
+      expect(result.current.currSegment.showModal).toBe(true)
+      expect(result.current.currSegment.segInfo).toBeDefined()
+      expect(result.current.currSegment.segInfo!.id).toBe('seg-detail-1')
+    })
+
+    it('should close segment detail modal', () => {
+      const { result } = renderHook(() => useModalState({ onNewSegmentModalChange }))
+
+      const segment = createSegment('seg-1')
+      act(() => {
+        result.current.onClickCard(segment)
+      })
+      expect(result.current.currSegment.showModal).toBe(true)
+
+      act(() => {
+        result.current.onCloseSegmentDetail()
+      })
+      expect(result.current.currSegment.showModal).toBe(false)
+    })
+
+    it('should manage full screen toggle', () => {
+      const { result } = renderHook(() => useModalState({ onNewSegmentModalChange }))
+
+      expect(result.current.fullScreen).toBe(false)
+      act(() => {
+        result.current.toggleFullScreen()
+      })
+      expect(result.current.fullScreen).toBe(true)
+      act(() => {
+        result.current.toggleFullScreen()
+      })
+      expect(result.current.fullScreen).toBe(false)
+    })
+
+    it('should manage collapsed state', () => {
+      const { result } = renderHook(() => useModalState({ onNewSegmentModalChange }))
+
+      expect(result.current.isCollapsed).toBe(true)
+      act(() => {
+        result.current.toggleCollapsed()
+      })
+      expect(result.current.isCollapsed).toBe(false)
+    })
+
+    it('should manage new child segment modal', () => {
+      const { result } = renderHook(() => useModalState({ onNewSegmentModalChange }))
+
+      expect(result.current.showNewChildSegmentModal).toBe(false)
+      act(() => {
+        result.current.handleAddNewChildChunk('chunk-parent-1')
+      })
+      expect(result.current.showNewChildSegmentModal).toBe(true)
+      expect(result.current.currChunkId).toBe('chunk-parent-1')
+
+      act(() => {
+        result.current.onCloseNewChildChunkModal()
+      })
+      expect(result.current.showNewChildSegmentModal).toBe(false)
+    })
+  })
+
+  describe('Cross-Hook Data Flow: Search → Selection → Modal', () => {
+    it('should maintain independent state across all three hooks', () => {
+      const segments = [createSegment('seg-1'), createSegment('seg-2')]
+
+      const { result: filterResult } = renderHook(() =>
+        useSearchFilter({ onPageChange: vi.fn() }),
+      )
+      const { result: selectionResult } = renderHook(() =>
+        useSegmentSelection(segments),
+      )
+      const { result: modalResult } = renderHook(() =>
+        useModalState({ onNewSegmentModalChange: vi.fn() }),
+      )
+
+      // Set search filter to enabled
+      act(() => {
+        filterResult.current.onChangeStatus({ value: 1, name: 'enabled' })
+      })
+
+      // Select a segment
+      act(() => {
+        selectionResult.current.onSelected('seg-1')
+      })
+
+      // Open detail modal
+      act(() => {
+        modalResult.current.onClickCard(segments[0])
+      })
+
+      // All states should be independent
+      expect(filterResult.current.selectedStatus).toBe(true) // !!1
+      expect(selectionResult.current.selectedSegmentIds).toContain('seg-1')
+      expect(modalResult.current.currSegment.showModal).toBe(true)
+    })
+  })
+})

web/__tests__/develop/api-key-management-flow.test.tsx

@@ -0,0 +1,192 @@
+/**
+ * Integration test: API Key management flow
+ *
+ * Tests the cross-component interaction:
+ *   ApiServer → SecretKeyButton → SecretKeyModal
+ *
+ * Renders real ApiServer, SecretKeyButton, and SecretKeyModal together
+ * with only service-layer mocks. Deep modal interactions (create/delete)
+ * are covered by unit tests in secret-key-modal.spec.tsx.
+ */
+import { act, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import ApiServer from '@/app/components/develop/ApiServer'
+
+// ---------- fake timers (HeadlessUI Dialog transitions) ----------
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+
+afterEach(() => {
+  vi.runOnlyPendingTimers()
+  vi.useRealTimers()
+})
+
+async function flushUI() {
+  await act(async () => {
+    vi.runAllTimers()
+  })
+}
+
+// ---------- mocks ----------
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    currentWorkspace: { id: 'ws-1', name: 'Workspace' },
+    isCurrentWorkspaceManager: true,
+    isCurrentWorkspaceEditor: true,
+  }),
+}))
+
+vi.mock('@/hooks/use-timestamp', () => ({
+  default: () => ({
+    formatTime: vi.fn((val: number) => `Time:${val}`),
+    formatDate: vi.fn((val: string) => `Date:${val}`),
+  }),
+}))
+
+vi.mock('@/service/apps', () => ({
+  createApikey: vi.fn().mockResolvedValue({ token: 'sk-new-token-1234567890abcdef' }),
+  delApikey: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('@/service/datasets', () => ({
+  createApikey: vi.fn().mockResolvedValue({ token: 'dk-new' }),
+  delApikey: vi.fn().mockResolvedValue({}),
+}))
+
+const mockApiKeys = vi.fn().mockReturnValue({ data: [] })
+const mockIsLoading = vi.fn().mockReturnValue(false)
+
+vi.mock('@/service/use-apps', () => ({
+  useAppApiKeys: () => ({
+    data: mockApiKeys(),
+    isLoading: mockIsLoading(),
+  }),
+  useInvalidateAppApiKeys: () => vi.fn(),
+}))
+
+vi.mock('@/service/knowledge/use-dataset', () => ({
+  useDatasetApiKeys: () => ({ data: null, isLoading: false }),
+  useInvalidateDatasetApiKeys: () => vi.fn(),
+}))
+
+// ---------- tests ----------
+
+describe('API Key management flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockApiKeys.mockReturnValue({ data: [] })
+    mockIsLoading.mockReturnValue(false)
+  })
+
+  it('ApiServer renders URL, status badge, and API Key button', () => {
+    render(<ApiServer apiBaseUrl="https://api.dify.ai/v1" appId="app-1" />)
+
+    expect(screen.getByText('https://api.dify.ai/v1')).toBeInTheDocument()
+    expect(screen.getByText('appApi.ok')).toBeInTheDocument()
+    expect(screen.getByText('appApi.apiKey')).toBeInTheDocument()
+  })
+
+  it('clicking API Key button opens SecretKeyModal with real modal content', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+
+    render(<ApiServer apiBaseUrl="https://api.dify.ai/v1" appId="app-1" />)
+
+    // Click API Key button (rendered by SecretKeyButton)
+    await act(async () => {
+      await user.click(screen.getByText('appApi.apiKey'))
+    })
+    await flushUI()
+
+    // SecretKeyModal should render with real HeadlessUI Dialog
+    await waitFor(() => {
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKey')).toBeInTheDocument()
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKeyTips')).toBeInTheDocument()
+      expect(screen.getByText('appApi.apiKeyModal.createNewSecretKey')).toBeInTheDocument()
+    })
+  })
+
+  it('modal shows loading state when API keys are being fetched', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    mockIsLoading.mockReturnValue(true)
+
+    render(<ApiServer apiBaseUrl="https://api.dify.ai/v1" appId="app-1" />)
+
+    await act(async () => {
+      await user.click(screen.getByText('appApi.apiKey'))
+    })
+    await flushUI()
+
+    await waitFor(() => {
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKey')).toBeInTheDocument()
+    })
+
+    // Loading indicator should be present
+    expect(document.body.querySelector('[role="status"]')).toBeInTheDocument()
+  })
+
+  it('modal can be closed by clicking X icon', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+
+    render(<ApiServer apiBaseUrl="https://api.dify.ai/v1" appId="app-1" />)
+
+    // Open modal
+    await act(async () => {
+      await user.click(screen.getByText('appApi.apiKey'))
+    })
+    await flushUI()
+
+    await waitFor(() => {
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKey')).toBeInTheDocument()
+    })
+
+    // Click X icon to close
+    const closeIcon = document.body.querySelector('svg.cursor-pointer')
+    expect(closeIcon).toBeInTheDocument()
+
+    await act(async () => {
+      await user.click(closeIcon!)
+    })
+    await flushUI()
+
+    // Modal should close
+    await waitFor(() => {
+      expect(screen.queryByText('appApi.apiKeyModal.apiSecretKeyTips')).not.toBeInTheDocument()
+    })
+  })
+
+  it('renders correctly with different API URLs', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+
+    const { rerender } = render(
+      <ApiServer apiBaseUrl="http://localhost:5001/v1" appId="app-dev" />,
+    )
+
+    expect(screen.getByText('http://localhost:5001/v1')).toBeInTheDocument()
+
+    // Open modal and verify it works with the same appId
+    await act(async () => {
+      await user.click(screen.getByText('appApi.apiKey'))
+    })
+    await flushUI()
+
+    await waitFor(() => {
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKey')).toBeInTheDocument()
+    })
+
+    // Close modal, update URL and re-verify
+    const xIcon = document.body.querySelector('svg.cursor-pointer')
+    await act(async () => {
+      await user.click(xIcon!)
+    })
+    await flushUI()
+
+    rerender(
+      <ApiServer apiBaseUrl="https://api.production.com/v1" appId="app-prod" />,
+    )
+
+    expect(screen.getByText('https://api.production.com/v1')).toBeInTheDocument()
+  })
+})

web/__tests__/develop/develop-page-flow.test.tsx

@@ -0,0 +1,237 @@
+/**
+ * Integration test: DevelopMain page flow
+ *
+ * Tests the full page lifecycle:
+ *   Loading state → App loaded → Header (ApiServer) + Content (Doc) rendered
+ *
+ * Uses real DevelopMain, ApiServer, and Doc components with minimal mocks.
+ */
+import { act, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import DevelopMain from '@/app/components/develop'
+import { AppModeEnum, Theme } from '@/types/app'
+
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+
+afterEach(() => {
+  vi.runOnlyPendingTimers()
+  vi.useRealTimers()
+})
+
+async function flushUI() {
+  await act(async () => {
+    vi.runAllTimers()
+  })
+}
+
+let storeAppDetail: unknown
+
+vi.mock('@/app/components/app/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    return selector({ appDetail: storeAppDetail })
+  },
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useLocale: () => 'en-US',
+}))
+
+vi.mock('@/hooks/use-theme', () => ({
+  default: () => ({ theme: Theme.light }),
+}))
+
+vi.mock('@/i18n-config/language', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/i18n-config/language')>()
+  return {
+    ...actual,
+  }
+})
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    currentWorkspace: { id: 'ws-1', name: 'Workspace' },
+    isCurrentWorkspaceManager: true,
+    isCurrentWorkspaceEditor: true,
+  }),
+}))
+
+vi.mock('@/hooks/use-timestamp', () => ({
+  default: () => ({
+    formatTime: vi.fn((val: number) => `Time:${val}`),
+    formatDate: vi.fn((val: string) => `Date:${val}`),
+  }),
+}))
+
+vi.mock('@/service/apps', () => ({
+  createApikey: vi.fn().mockResolvedValue({ token: 'sk-new-1234567890' }),
+  delApikey: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('@/service/datasets', () => ({
+  createApikey: vi.fn().mockResolvedValue({ token: 'dk-new' }),
+  delApikey: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('@/service/use-apps', () => ({
+  useAppApiKeys: () => ({ data: { data: [] }, isLoading: false }),
+  useInvalidateAppApiKeys: () => vi.fn(),
+}))
+
+vi.mock('@/service/knowledge/use-dataset', () => ({
+  useDatasetApiKeys: () => ({ data: null, isLoading: false }),
+  useInvalidateDatasetApiKeys: () => vi.fn(),
+}))
+
+// ---------- tests ----------
+
+describe('DevelopMain page flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    storeAppDetail = undefined
+  })
+
+  it('should show loading indicator when appDetail is not available', () => {
+    storeAppDetail = undefined
+    render(<DevelopMain appId="app-1" />)
+
+    expect(screen.getByRole('status')).toBeInTheDocument()
+    // No content should be visible
+    expect(screen.queryByText('appApi.apiServer')).not.toBeInTheDocument()
+  })
+
+  it('should render full page when appDetail is loaded', () => {
+    storeAppDetail = {
+      id: 'app-1',
+      name: 'Test App',
+      api_base_url: 'https://api.test.com/v1',
+      mode: AppModeEnum.CHAT,
+    }
+
+    render(<DevelopMain appId="app-1" />)
+
+    // ApiServer section should be visible
+    expect(screen.getByText('appApi.apiServer')).toBeInTheDocument()
+    expect(screen.getByText('https://api.test.com/v1')).toBeInTheDocument()
+    expect(screen.getByText('appApi.ok')).toBeInTheDocument()
+    expect(screen.getByText('appApi.apiKey')).toBeInTheDocument()
+
+    // Loading should NOT be visible
+    expect(screen.queryByRole('status')).not.toBeInTheDocument()
+  })
+
+  it('should render Doc component with correct app mode template', () => {
+    storeAppDetail = {
+      id: 'app-1',
+      name: 'Chat App',
+      api_base_url: 'https://api.test.com/v1',
+      mode: AppModeEnum.CHAT,
+    }
+
+    const { container } = render(<DevelopMain appId="app-1" />)
+
+    // Doc renders an article element with prose classes
+    const article = container.querySelector('article')
+    expect(article).toBeInTheDocument()
+    expect(article?.className).toContain('prose')
+  })
+
+  it('should transition from loading to content when appDetail becomes available', () => {
+    // Start with no data
+    storeAppDetail = undefined
+    const { rerender } = render(<DevelopMain appId="app-1" />)
+    expect(screen.getByRole('status')).toBeInTheDocument()
+
+    // Simulate store update
+    storeAppDetail = {
+      id: 'app-1',
+      name: 'My App',
+      api_base_url: 'https://api.example.com/v1',
+      mode: AppModeEnum.COMPLETION,
+    }
+    rerender(<DevelopMain appId="app-1" />)
+
+    // Content should now be visible
+    expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    expect(screen.getByText('https://api.example.com/v1')).toBeInTheDocument()
+  })
+
+  it('should open API key modal from the page', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+
+    storeAppDetail = {
+      id: 'app-1',
+      name: 'Test App',
+      api_base_url: 'https://api.test.com/v1',
+      mode: AppModeEnum.WORKFLOW,
+    }
+
+    render(<DevelopMain appId="app-1" />)
+
+    // Click API Key button in the header
+    await act(async () => {
+      await user.click(screen.getByText('appApi.apiKey'))
+    })
+    await flushUI()
+
+    // SecretKeyModal should open
+    await waitFor(() => {
+      expect(screen.getByText('appApi.apiKeyModal.apiSecretKey')).toBeInTheDocument()
+    })
+  })
+
+  it('should render correctly for different app modes', () => {
+    const modes = [
+      AppModeEnum.CHAT,
+      AppModeEnum.COMPLETION,
+      AppModeEnum.ADVANCED_CHAT,
+      AppModeEnum.WORKFLOW,
+    ]
+
+    for (const mode of modes) {
+      storeAppDetail = {
+        id: 'app-1',
+        name: `${mode} App`,
+        api_base_url: 'https://api.test.com/v1',
+        mode,
+      }
+
+      const { container, unmount } = render(<DevelopMain appId="app-1" />)
+
+      // ApiServer should always be present
+      expect(screen.getByText('appApi.apiServer')).toBeInTheDocument()
+
+      // Doc should render an article
+      expect(container.querySelector('article')).toBeInTheDocument()
+
+      unmount()
+    }
+  })
+
+  it('should have correct page layout structure', () => {
+    storeAppDetail = {
+      id: 'app-1',
+      name: 'Test App',
+      api_base_url: 'https://api.test.com/v1',
+      mode: AppModeEnum.CHAT,
+    }
+
+    render(<DevelopMain appId="app-1" />)
+
+    // Main container: flex column with full height
+    const mainDiv = screen.getByTestId('develop-main')
+    expect(mainDiv.className).toContain('flex')
+    expect(mainDiv.className).toContain('flex-col')
+    expect(mainDiv.className).toContain('h-full')
+
+    // Header section with border
+    const header = mainDiv.querySelector('.border-b')
+    expect(header).toBeInTheDocument()
+
+    // Content section with overflow scroll
+    const content = mainDiv.querySelector('.overflow-auto')
+    expect(content).toBeInTheDocument()
+  })
+})

web/__tests__/explore/explore-app-list-flow.test.tsx

@@ -1,18 +1,23 @@
+/**
+ * Integration test: Explore App List Flow
+ *
+ * Tests the end-to-end user flow of browsing, filtering, searching,
+ * and adding apps to workspace from the explore page.
+ */
 import type { Mock } from 'vitest'
 import type { CreateAppModalProps } from '@/app/components/explore/create-app-modal'
 import type { App } from '@/models/explore'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import AppList from '@/app/components/explore/app-list'
 import ExploreContext from '@/context/explore-context'
 import { fetchAppDetail } from '@/service/explore'
 import { AppModeEnum } from '@/types/app'
-import AppList from './index'
 
 const allCategoriesEn = 'explore.apps.allCategories:{"lng":"en"}'
 let mockTabValue = allCategoriesEn
 const mockSetTab = vi.fn()
-let mockExploreData: { categories: string[], allList: App[] } | undefined = { categories: [], allList: [] }
+let mockExploreData: { categories: string[], allList: App[] } | undefined
 let mockIsLoading = false
-let mockIsError = false
 const mockHandleImportDSL = vi.fn()
 const mockHandleImportDSLConfirm = vi.fn()
 
@@ -43,7 +48,7 @@ vi.mock('@/service/use-explore', () => ({
   useExploreAppList: () => ({
     data: mockExploreData,
     isLoading: mockIsLoading,
-    isError: mockIsError,
+    isError: false,
   }),
 }))
 
@@ -96,7 +101,7 @@ vi.mock('@/app/components/app/create-from-dsl-modal/dsl-confirm-modal', () => ({
 
 const createApp = (overrides: Partial<App> = {}): App => ({
   app: {
-    id: overrides.app?.id ?? 'app-basic-id',
+    id: overrides.app?.id ?? 'app-id',
     mode: overrides.app?.mode ?? AppModeEnum.CHAT,
     icon_type: overrides.app?.icon_type ?? 'emoji',
     icon: overrides.app?.icon ?? '😀',
@@ -121,113 +126,80 @@ const createApp = (overrides: Partial<App> = {}): App => ({
   is_agent: overrides.is_agent ?? false,
 })
 
-const renderWithContext = (hasEditPermission = false, onSuccess?: () => void) => {
-  return render(
-    <ExploreContext.Provider
-      value={{
-        controlUpdateInstalledApps: 0,
-        setControlUpdateInstalledApps: vi.fn(),
-        hasEditPermission,
-        installedApps: [],
-        setInstalledApps: vi.fn(),
-        isFetchingInstalledApps: false,
-        setIsFetchingInstalledApps: vi.fn(),
-        isShowTryAppPanel: false,
-        setShowTryAppPanel: vi.fn(),
-      }}
-    >
-      <AppList onSuccess={onSuccess} />
-    </ExploreContext.Provider>,
-  )
+const createContextValue = (hasEditPermission = true) => ({
+  controlUpdateInstalledApps: 0,
+  setControlUpdateInstalledApps: vi.fn(),
+  hasEditPermission,
+  installedApps: [] as never[],
+  setInstalledApps: vi.fn(),
+  isFetchingInstalledApps: false,
+  setIsFetchingInstalledApps: vi.fn(),
+  isShowTryAppPanel: false,
+  setShowTryAppPanel: vi.fn(),
+})
+
+const wrapWithContext = (hasEditPermission = true, onSuccess?: () => void) => (
+  <ExploreContext.Provider value={createContextValue(hasEditPermission)}>
+    <AppList onSuccess={onSuccess} />
+  </ExploreContext.Provider>
+)
+
+const renderWithContext = (hasEditPermission = true, onSuccess?: () => void) => {
+  return render(wrapWithContext(hasEditPermission, onSuccess))
 }
 
-describe('AppList', () => {
+describe('Explore App List Flow', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     mockTabValue = allCategoriesEn
-    mockExploreData = { categories: [], allList: [] }
     mockIsLoading = false
-    mockIsError = false
+    mockExploreData = {
+      categories: ['Writing', 'Translate', 'Programming'],
+      allList: [
+        createApp({ app_id: 'app-1', app: { ...createApp().app, name: 'Writer Bot' }, category: 'Writing' }),
+        createApp({ app_id: 'app-2', app: { ...createApp().app, id: 'app-id-2', name: 'Translator' }, category: 'Translate' }),
+        createApp({ app_id: 'app-3', app: { ...createApp().app, id: 'app-id-3', name: 'Code Helper' }, category: 'Programming' }),
+      ],
+    }
   })
 
-  // Rendering: show loading when categories are not ready.
-  describe('Rendering', () => {
-    it('should render loading when the query is loading', () => {
-      // Arrange
-      mockExploreData = undefined
-      mockIsLoading = true
-
-      // Act
+  describe('Browse and Filter Flow', () => {
+    it('should display all apps when no category filter is applied', () => {
       renderWithContext()
 
-      // Assert
-      expect(screen.getByRole('status')).toBeInTheDocument()
+      expect(screen.getByText('Writer Bot')).toBeInTheDocument()
+      expect(screen.getByText('Translator')).toBeInTheDocument()
+      expect(screen.getByText('Code Helper')).toBeInTheDocument()
     })
 
-    it('should render app cards when data is available', () => {
-      // Arrange
-      mockExploreData = {
-        categories: ['Writing', 'Translate'],
-        allList: [createApp(), createApp({ app_id: 'app-2', app: { ...createApp().app, name: 'Beta' }, category: 'Translate' })],
-      }
-
-      // Act
-      renderWithContext()
-
-      // Assert
-      expect(screen.getByText('Alpha')).toBeInTheDocument()
-      expect(screen.getByText('Beta')).toBeInTheDocument()
-    })
-  })
-
-  // Props: category selection filters the list.
-  describe('Props', () => {
     it('should filter apps by selected category', () => {
-      // Arrange
       mockTabValue = 'Writing'
-      mockExploreData = {
-        categories: ['Writing', 'Translate'],
-        allList: [createApp(), createApp({ app_id: 'app-2', app: { ...createApp().app, name: 'Beta' }, category: 'Translate' })],
-      }
-
-      // Act
       renderWithContext()
 
-      // Assert
-      expect(screen.getByText('Alpha')).toBeInTheDocument()
-      expect(screen.queryByText('Beta')).not.toBeInTheDocument()
+      expect(screen.getByText('Writer Bot')).toBeInTheDocument()
+      expect(screen.queryByText('Translator')).not.toBeInTheDocument()
+      expect(screen.queryByText('Code Helper')).not.toBeInTheDocument()
     })
-  })
 
-  // User interactions: search and create flow.
-  describe('User Interactions', () => {
-    it('should filter apps by search keywords', async () => {
-      // Arrange
-      mockExploreData = {
-        categories: ['Writing'],
-        allList: [createApp(), createApp({ app_id: 'app-2', app: { ...createApp().app, name: 'Gamma' } })],
-      }
+    it('should filter apps by search keyword', async () => {
       renderWithContext()
 
-      // Act
       const input = screen.getByPlaceholderText('common.operation.search')
-      fireEvent.change(input, { target: { value: 'gam' } })
+      fireEvent.change(input, { target: { value: 'trans' } })
 
-      // Assert
       await waitFor(() => {
-        expect(screen.queryByText('Alpha')).not.toBeInTheDocument()
-        expect(screen.getByText('Gamma')).toBeInTheDocument()
+        expect(screen.getByText('Translator')).toBeInTheDocument()
+        expect(screen.queryByText('Writer Bot')).not.toBeInTheDocument()
+        expect(screen.queryByText('Code Helper')).not.toBeInTheDocument()
       })
     })
+  })
 
-    it('should handle create flow and confirm DSL when pending', async () => {
-      // Arrange
+  describe('Add to Workspace Flow', () => {
+    it('should complete the full add-to-workspace flow with DSL confirmation', async () => {
+      // Step 1: User clicks "Add to Workspace" on an app card
       const onSuccess = vi.fn()
-      mockExploreData = {
-        categories: ['Writing'],
-        allList: [createApp()],
-      };
-      (fetchAppDetail as unknown as Mock).mockResolvedValue({ export_data: 'yaml-content' })
+      ;(fetchAppDetail as unknown as Mock).mockResolvedValue({ export_data: 'yaml-content' })
       mockHandleImportDSL.mockImplementation(async (_payload: unknown, options: { onSuccess?: () => void, onPending?: () => void }) => {
         options.onPending?.()
       })
@@ -235,19 +207,27 @@ describe('AppList', () => {
         options.onSuccess?.()
       })
 
-      // Act
       renderWithContext(true, onSuccess)
-      fireEvent.click(screen.getByText('explore.appCard.addToWorkspace'))
+
+      // Step 2: Click add to workspace button - opens create modal
+      fireEvent.click(screen.getAllByText('explore.appCard.addToWorkspace')[0])
+
+      // Step 3: Confirm creation in modal
       fireEvent.click(await screen.findByTestId('confirm-create'))
 
-      // Assert
+      // Step 4: API fetches app detail
       await waitFor(() => {
-        expect(fetchAppDetail).toHaveBeenCalledWith('app-basic-id')
+        expect(fetchAppDetail).toHaveBeenCalledWith('app-id')
       })
-      expect(mockHandleImportDSL).toHaveBeenCalledTimes(1)
-      expect(await screen.findByTestId('dsl-confirm-modal')).toBeInTheDocument()
 
+      // Step 5: DSL import triggers pending confirmation
+      expect(mockHandleImportDSL).toHaveBeenCalledTimes(1)
+
+      // Step 6: DSL confirm modal appears and user confirms
+      expect(await screen.findByTestId('dsl-confirm-modal')).toBeInTheDocument()
       fireEvent.click(screen.getByTestId('dsl-confirm'))
+
+      // Step 7: Flow completes successfully
       await waitFor(() => {
         expect(mockHandleImportDSLConfirm).toHaveBeenCalledTimes(1)
         expect(onSuccess).toHaveBeenCalledTimes(1)
@@ -255,30 +235,39 @@ describe('AppList', () => {
     })
   })
 
-  // Edge cases: handle clearing search keywords.
-  describe('Edge Cases', () => {
-    it('should reset search results when clear icon is clicked', async () => {
-      // Arrange
+  describe('Loading and Empty States', () => {
+    it('should transition from loading to content', () => {
+      // Step 1: Loading state
+      mockIsLoading = true
+      mockExploreData = undefined
+      const { rerender } = render(wrapWithContext())
+
+      expect(screen.getByRole('status')).toBeInTheDocument()
+
+      // Step 2: Data loads
+      mockIsLoading = false
       mockExploreData = {
         categories: ['Writing'],
-        allList: [createApp(), createApp({ app_id: 'app-2', app: { ...createApp().app, name: 'Gamma' } })],
+        allList: [createApp()],
       }
-      renderWithContext()
+      rerender(wrapWithContext())
 
-      // Act
-      const input = screen.getByPlaceholderText('common.operation.search')
-      fireEvent.change(input, { target: { value: 'gam' } })
-      await waitFor(() => {
-        expect(screen.queryByText('Alpha')).not.toBeInTheDocument()
-      })
+      expect(screen.queryByRole('status')).not.toBeInTheDocument()
+      expect(screen.getByText('Alpha')).toBeInTheDocument()
+    })
+  })
 
-      fireEvent.click(screen.getByTestId('input-clear'))
+  describe('Permission-Based Behavior', () => {
+    it('should hide add-to-workspace button when user has no edit permission', () => {
+      renderWithContext(false)
 
-      // Assert
-      await waitFor(() => {
-        expect(screen.getByText('Alpha')).toBeInTheDocument()
-        expect(screen.getByText('Gamma')).toBeInTheDocument()
-      })
+      expect(screen.queryByText('explore.appCard.addToWorkspace')).not.toBeInTheDocument()
+    })
+
+    it('should show add-to-workspace button when user has edit permission', () => {
+      renderWithContext(true)
+
+      expect(screen.getAllByText('explore.appCard.addToWorkspace').length).toBeGreaterThan(0)
     })
   })
 })

web/__tests__/explore/installed-app-flow.test.tsx

@@ -0,0 +1,260 @@
+/**
+ * Integration test: Installed App Flow
+ *
+ * Tests the end-to-end user flow of installed apps: sidebar navigation,
+ * mode-based routing (Chat / Completion / Workflow), and lifecycle
+ * operations (pin/unpin, delete).
+ */
+import type { Mock } from 'vitest'
+import type { InstalledApp as InstalledAppModel } from '@/models/explore'
+import { render, screen, waitFor } from '@testing-library/react'
+import { useContext } from 'use-context-selector'
+import InstalledApp from '@/app/components/explore/installed-app'
+import { useWebAppStore } from '@/context/web-app-context'
+import { AccessMode } from '@/models/access-control'
+import { useGetUserCanAccessApp } from '@/service/access-control'
+import { useGetInstalledAppAccessModeByAppId, useGetInstalledAppMeta, useGetInstalledAppParams } from '@/service/use-explore'
+import { AppModeEnum } from '@/types/app'
+
+// Mock external dependencies
+vi.mock('use-context-selector', () => ({
+  useContext: vi.fn(),
+  createContext: vi.fn(() => ({})),
+}))
+
+vi.mock('@/context/web-app-context', () => ({
+  useWebAppStore: vi.fn(),
+}))
+
+vi.mock('@/service/access-control', () => ({
+  useGetUserCanAccessApp: vi.fn(),
+}))
+
+vi.mock('@/service/use-explore', () => ({
+  useGetInstalledAppAccessModeByAppId: vi.fn(),
+  useGetInstalledAppParams: vi.fn(),
+  useGetInstalledAppMeta: vi.fn(),
+}))
+
+vi.mock('@/app/components/share/text-generation', () => ({
+  default: ({ isWorkflow }: { isWorkflow?: boolean }) => (
+    <div data-testid="text-generation-app">
+      Text Generation
+      {isWorkflow && ' (Workflow)'}
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/base/chat/chat-with-history', () => ({
+  default: ({ installedAppInfo }: { installedAppInfo?: InstalledAppModel }) => (
+    <div data-testid="chat-with-history">
+      Chat -
+      {' '}
+      {installedAppInfo?.app.name}
+    </div>
+  ),
+}))
+
+describe('Installed App Flow', () => {
+  const mockUpdateAppInfo = vi.fn()
+  const mockUpdateWebAppAccessMode = vi.fn()
+  const mockUpdateAppParams = vi.fn()
+  const mockUpdateWebAppMeta = vi.fn()
+  const mockUpdateUserCanAccessApp = vi.fn()
+
+  const createInstalledApp = (mode: AppModeEnum = AppModeEnum.CHAT): InstalledAppModel => ({
+    id: 'installed-app-1',
+    app: {
+      id: 'real-app-id',
+      name: 'Integration Test App',
+      mode,
+      icon_type: 'emoji',
+      icon: '🧪',
+      icon_background: '#FFFFFF',
+      icon_url: '',
+      description: 'Test app for integration',
+      use_icon_as_answer_icon: false,
+    },
+    uninstallable: true,
+    is_pinned: false,
+  })
+
+  const mockAppParams = {
+    user_input_form: [],
+    file_upload: { image: { enabled: false, number_limits: 0, transfer_methods: [] } },
+    system_parameters: {},
+  }
+
+  type MockOverrides = {
+    context?: { installedApps?: InstalledAppModel[], isFetchingInstalledApps?: boolean }
+    accessMode?: { isFetching?: boolean, data?: unknown, error?: unknown }
+    params?: { isFetching?: boolean, data?: unknown, error?: unknown }
+    meta?: { isFetching?: boolean, data?: unknown, error?: unknown }
+    userAccess?: { data?: unknown, error?: unknown }
+  }
+
+  const setupDefaultMocks = (app?: InstalledAppModel, overrides: MockOverrides = {}) => {
+    ;(useContext as Mock).mockReturnValue({
+      installedApps: app ? [app] : [],
+      isFetchingInstalledApps: false,
+      ...overrides.context,
+    })
+
+    ;(useWebAppStore as unknown as Mock).mockImplementation((selector: (state: Record<string, Mock>) => unknown) => {
+      return selector({
+        updateAppInfo: mockUpdateAppInfo,
+        updateWebAppAccessMode: mockUpdateWebAppAccessMode,
+        updateAppParams: mockUpdateAppParams,
+        updateWebAppMeta: mockUpdateWebAppMeta,
+        updateUserCanAccessApp: mockUpdateUserCanAccessApp,
+      })
+    })
+
+    ;(useGetInstalledAppAccessModeByAppId as Mock).mockReturnValue({
+      isFetching: false,
+      data: { accessMode: AccessMode.PUBLIC },
+      error: null,
+      ...overrides.accessMode,
+    })
+
+    ;(useGetInstalledAppParams as Mock).mockReturnValue({
+      isFetching: false,
+      data: mockAppParams,
+      error: null,
+      ...overrides.params,
+    })
+
+    ;(useGetInstalledAppMeta as Mock).mockReturnValue({
+      isFetching: false,
+      data: { tool_icons: {} },
+      error: null,
+      ...overrides.meta,
+    })
+
+    ;(useGetUserCanAccessApp as Mock).mockReturnValue({
+      data: { result: true },
+      error: null,
+      ...overrides.userAccess,
+    })
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Mode-Based Routing', () => {
+    it.each([
+      [AppModeEnum.CHAT, 'chat-with-history'],
+      [AppModeEnum.ADVANCED_CHAT, 'chat-with-history'],
+      [AppModeEnum.AGENT_CHAT, 'chat-with-history'],
+    ])('should render ChatWithHistory for %s mode', (mode, testId) => {
+      const app = createInstalledApp(mode)
+      setupDefaultMocks(app)
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByTestId(testId)).toBeInTheDocument()
+      expect(screen.getByText(/Integration Test App/)).toBeInTheDocument()
+    })
+
+    it('should render TextGenerationApp for COMPLETION mode', () => {
+      const app = createInstalledApp(AppModeEnum.COMPLETION)
+      setupDefaultMocks(app)
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByTestId('text-generation-app')).toBeInTheDocument()
+      expect(screen.getByText('Text Generation')).toBeInTheDocument()
+      expect(screen.queryByText(/Workflow/)).not.toBeInTheDocument()
+    })
+
+    it('should render TextGenerationApp with workflow flag for WORKFLOW mode', () => {
+      const app = createInstalledApp(AppModeEnum.WORKFLOW)
+      setupDefaultMocks(app)
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByTestId('text-generation-app')).toBeInTheDocument()
+      expect(screen.getByText(/Workflow/)).toBeInTheDocument()
+    })
+  })
+
+  describe('Data Loading Flow', () => {
+    it('should show loading spinner when params are being fetched', () => {
+      const app = createInstalledApp()
+      setupDefaultMocks(app, { params: { isFetching: true, data: null } })
+
+      const { container } = render(<InstalledApp id="installed-app-1" />)
+
+      expect(container.querySelector('svg.spin-animation')).toBeInTheDocument()
+      expect(screen.queryByTestId('chat-with-history')).not.toBeInTheDocument()
+    })
+
+    it('should render content when all data is available', () => {
+      const app = createInstalledApp()
+      setupDefaultMocks(app)
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByTestId('chat-with-history')).toBeInTheDocument()
+    })
+  })
+
+  describe('Error Handling Flow', () => {
+    it('should show error state when API fails', () => {
+      const app = createInstalledApp()
+      setupDefaultMocks(app, { params: { data: null, error: new Error('Network error') } })
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByText(/Network error/)).toBeInTheDocument()
+    })
+
+    it('should show 404 when app is not found', () => {
+      setupDefaultMocks(undefined, {
+        accessMode: { data: null },
+        params: { data: null },
+        meta: { data: null },
+        userAccess: { data: null },
+      })
+
+      render(<InstalledApp id="nonexistent" />)
+
+      expect(screen.getByText(/404/)).toBeInTheDocument()
+    })
+
+    it('should show 403 when user has no permission', () => {
+      const app = createInstalledApp()
+      setupDefaultMocks(app, { userAccess: { data: { result: false } } })
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      expect(screen.getByText(/403/)).toBeInTheDocument()
+    })
+  })
+
+  describe('State Synchronization', () => {
+    it('should update all stores when app data is loaded', async () => {
+      const app = createInstalledApp()
+      setupDefaultMocks(app)
+
+      render(<InstalledApp id="installed-app-1" />)
+
+      await waitFor(() => {
+        expect(mockUpdateAppInfo).toHaveBeenCalledWith(
+          expect.objectContaining({
+            app_id: 'installed-app-1',
+            site: expect.objectContaining({
+              title: 'Integration Test App',
+              icon: '🧪',
+            }),
+          }),
+        )
+        expect(mockUpdateAppParams).toHaveBeenCalledWith(mockAppParams)
+        expect(mockUpdateWebAppMeta).toHaveBeenCalledWith({ tool_icons: {} })
+        expect(mockUpdateWebAppAccessMode).toHaveBeenCalledWith(AccessMode.PUBLIC)
+        expect(mockUpdateUserCanAccessApp).toHaveBeenCalledWith(true)
+      })
+    })
+  })
+})

web/__tests__/explore/sidebar-lifecycle-flow.test.tsx

@@ -0,0 +1,225 @@
+import type { IExplore } from '@/context/explore-context'
+/**
+ * Integration test: Sidebar Lifecycle Flow
+ *
+ * Tests the sidebar interactions for installed apps lifecycle:
+ * navigation, pin/unpin ordering, delete confirmation, and
+ * fold/unfold behavior.
+ */
+import type { InstalledApp } from '@/models/explore'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import Toast from '@/app/components/base/toast'
+import SideBar from '@/app/components/explore/sidebar'
+import ExploreContext from '@/context/explore-context'
+import { MediaType } from '@/hooks/use-breakpoints'
+import { AppModeEnum } from '@/types/app'
+
+let mockMediaType: string = MediaType.pc
+const mockSegments = ['apps']
+const mockPush = vi.fn()
+const mockRefetch = vi.fn()
+const mockUninstall = vi.fn()
+const mockUpdatePinStatus = vi.fn()
+let mockInstalledApps: InstalledApp[] = []
+
+vi.mock('next/navigation', () => ({
+  useSelectedLayoutSegments: () => mockSegments,
+  useRouter: () => ({
+    push: mockPush,
+  }),
+}))
+
+vi.mock('@/hooks/use-breakpoints', () => ({
+  default: () => mockMediaType,
+  MediaType: {
+    mobile: 'mobile',
+    tablet: 'tablet',
+    pc: 'pc',
+  },
+}))
+
+vi.mock('@/service/use-explore', () => ({
+  useGetInstalledApps: () => ({
+    isFetching: false,
+    data: { installed_apps: mockInstalledApps },
+    refetch: mockRefetch,
+  }),
+  useUninstallApp: () => ({
+    mutateAsync: mockUninstall,
+  }),
+  useUpdateAppPinStatus: () => ({
+    mutateAsync: mockUpdatePinStatus,
+  }),
+}))
+
+const createInstalledApp = (overrides: Partial<InstalledApp> = {}): InstalledApp => ({
+  id: overrides.id ?? 'app-1',
+  uninstallable: overrides.uninstallable ?? false,
+  is_pinned: overrides.is_pinned ?? false,
+  app: {
+    id: overrides.app?.id ?? 'app-basic-id',
+    mode: overrides.app?.mode ?? AppModeEnum.CHAT,
+    icon_type: overrides.app?.icon_type ?? 'emoji',
+    icon: overrides.app?.icon ?? '🤖',
+    icon_background: overrides.app?.icon_background ?? '#fff',
+    icon_url: overrides.app?.icon_url ?? '',
+    name: overrides.app?.name ?? 'App One',
+    description: overrides.app?.description ?? 'desc',
+    use_icon_as_answer_icon: overrides.app?.use_icon_as_answer_icon ?? false,
+  },
+})
+
+const createContextValue = (installedApps: InstalledApp[] = []): IExplore => ({
+  controlUpdateInstalledApps: 0,
+  setControlUpdateInstalledApps: vi.fn(),
+  hasEditPermission: true,
+  installedApps,
+  setInstalledApps: vi.fn(),
+  isFetchingInstalledApps: false,
+  setIsFetchingInstalledApps: vi.fn(),
+  isShowTryAppPanel: false,
+  setShowTryAppPanel: vi.fn(),
+})
+
+const renderSidebar = (installedApps: InstalledApp[] = []) => {
+  return render(
+    <ExploreContext.Provider value={createContextValue(installedApps)}>
+      <SideBar controlUpdateInstalledApps={0} />
+    </ExploreContext.Provider>,
+  )
+}
+
+describe('Sidebar Lifecycle Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockMediaType = MediaType.pc
+    mockInstalledApps = []
+    vi.spyOn(Toast, 'notify').mockImplementation(() => ({ clear: vi.fn() }))
+  })
+
+  describe('Pin / Unpin / Delete Flow', () => {
+    it('should complete pin → unpin cycle for an app', async () => {
+      mockUpdatePinStatus.mockResolvedValue(undefined)
+
+      // Step 1: Start with an unpinned app and pin it
+      const unpinnedApp = createInstalledApp({ is_pinned: false })
+      mockInstalledApps = [unpinnedApp]
+      const { unmount } = renderSidebar(mockInstalledApps)
+
+      fireEvent.click(screen.getByTestId('item-operation-trigger'))
+      fireEvent.click(await screen.findByText('explore.sidebar.action.pin'))
+
+      await waitFor(() => {
+        expect(mockUpdatePinStatus).toHaveBeenCalledWith({ appId: 'app-1', isPinned: true })
+        expect(Toast.notify).toHaveBeenCalledWith(expect.objectContaining({
+          type: 'success',
+        }))
+      })
+
+      // Step 2: Simulate refetch returning pinned state, then unpin
+      unmount()
+      vi.clearAllMocks()
+      mockUpdatePinStatus.mockResolvedValue(undefined)
+
+      const pinnedApp = createInstalledApp({ is_pinned: true })
+      mockInstalledApps = [pinnedApp]
+      renderSidebar(mockInstalledApps)
+
+      fireEvent.click(screen.getByTestId('item-operation-trigger'))
+      fireEvent.click(await screen.findByText('explore.sidebar.action.unpin'))
+
+      await waitFor(() => {
+        expect(mockUpdatePinStatus).toHaveBeenCalledWith({ appId: 'app-1', isPinned: false })
+        expect(Toast.notify).toHaveBeenCalledWith(expect.objectContaining({
+          type: 'success',
+        }))
+      })
+    })
+
+    it('should complete the delete flow with confirmation', async () => {
+      const app = createInstalledApp()
+      mockInstalledApps = [app]
+      mockUninstall.mockResolvedValue(undefined)
+
+      renderSidebar(mockInstalledApps)
+
+      // Step 1: Open operation menu and click delete
+      fireEvent.click(screen.getByTestId('item-operation-trigger'))
+      fireEvent.click(await screen.findByText('explore.sidebar.action.delete'))
+
+      // Step 2: Confirm dialog appears
+      expect(await screen.findByText('explore.sidebar.delete.title')).toBeInTheDocument()
+
+      // Step 3: Confirm deletion
+      fireEvent.click(screen.getByText('common.operation.confirm'))
+
+      // Step 4: Uninstall API called and success toast shown
+      await waitFor(() => {
+        expect(mockUninstall).toHaveBeenCalledWith('app-1')
+        expect(Toast.notify).toHaveBeenCalledWith(expect.objectContaining({
+          type: 'success',
+          message: 'common.api.remove',
+        }))
+      })
+    })
+
+    it('should cancel deletion when user clicks cancel', async () => {
+      const app = createInstalledApp()
+      mockInstalledApps = [app]
+
+      renderSidebar(mockInstalledApps)
+
+      // Open delete flow
+      fireEvent.click(screen.getByTestId('item-operation-trigger'))
+      fireEvent.click(await screen.findByText('explore.sidebar.action.delete'))
+
+      // Cancel the deletion
+      fireEvent.click(await screen.findByText('common.operation.cancel'))
+
+      // Uninstall should not be called
+      expect(mockUninstall).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Multi-App Ordering', () => {
+    it('should display pinned apps before unpinned apps with divider', () => {
+      mockInstalledApps = [
+        createInstalledApp({ id: 'pinned-1', is_pinned: true, app: { ...createInstalledApp().app, name: 'Pinned App' } }),
+        createInstalledApp({ id: 'unpinned-1', is_pinned: false, app: { ...createInstalledApp().app, name: 'Regular App' } }),
+      ]
+
+      const { container } = renderSidebar(mockInstalledApps)
+
+      // Both apps are rendered
+      const pinnedApp = screen.getByText('Pinned App')
+      const regularApp = screen.getByText('Regular App')
+      expect(pinnedApp).toBeInTheDocument()
+      expect(regularApp).toBeInTheDocument()
+
+      // Pinned app appears before unpinned app in the DOM
+      const pinnedItem = pinnedApp.closest('[class*="rounded-lg"]')!
+      const regularItem = regularApp.closest('[class*="rounded-lg"]')!
+      expect(pinnedItem.compareDocumentPosition(regularItem) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+
+      // Divider is rendered between pinned and unpinned sections
+      const divider = container.querySelector('[class*="bg-divider-regular"]')
+      expect(divider).toBeInTheDocument()
+    })
+  })
+
+  describe('Empty State', () => {
+    it('should show NoApps component when no apps are installed on desktop', () => {
+      mockMediaType = MediaType.pc
+      renderSidebar([])
+
+      expect(screen.getByText('explore.sidebar.noApps.title')).toBeInTheDocument()
+    })
+
+    it('should hide NoApps on mobile', () => {
+      mockMediaType = MediaType.mobile
+      renderSidebar([])
+
+      expect(screen.queryByText('explore.sidebar.noApps.title')).not.toBeInTheDocument()
+    })
+  })
+})

web/__tests__/goto-anything/slash-command-modes.test.tsx

@@ -49,14 +49,14 @@ describe('Slash Command Dual-Mode System', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
-    ;(slashCommandRegistry as any).findCommand = vi.fn((name: string) => {
+    vi.mocked(slashCommandRegistry.findCommand).mockImplementation((name: string) => {
       if (name === 'docs')
         return mockDirectCommand
       if (name === 'theme')
         return mockSubmenuCommand
-      return null
+      return undefined
     })
-    ;(slashCommandRegistry as any).getAllCommands = vi.fn(() => [
+    vi.mocked(slashCommandRegistry.getAllCommands).mockReturnValue([
       mockDirectCommand,
       mockSubmenuCommand,
     ])
@@ -147,7 +147,7 @@ describe('Slash Command Dual-Mode System', () => {
         unregister: vi.fn(),
       }
 
-      ;(slashCommandRegistry as any).findCommand = vi.fn(() => commandWithoutMode)
+      vi.mocked(slashCommandRegistry.findCommand).mockReturnValue(commandWithoutMode)
 
       const handler = slashCommandRegistry.findCommand('test')
       // Default behavior should be submenu when mode is not specified

web/__tests__/plugins/plugin-auth-flow.test.tsx

@@ -0,0 +1,271 @@
+/**
+ * Integration Test: Plugin Authentication Flow
+ *
+ * Tests the integration between PluginAuth, usePluginAuth hook,
+ * Authorize/Authorized components, and credential management.
+ * Verifies the complete auth flow from checking authorization status
+ * to rendering the correct UI state.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { AuthCategory, CredentialTypeEnum } from '@/app/components/plugins/plugin-auth/types'
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        'plugin.auth.setUpTip': 'Set up your credentials',
+        'plugin.auth.authorized': 'Authorized',
+        'plugin.auth.apiKey': 'API Key',
+        'plugin.auth.oauth': 'OAuth',
+      }
+      return map[key] ?? key
+    },
+  }),
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceManager: true,
+  }),
+}))
+
+vi.mock('@/utils/classnames', () => ({
+  cn: (...args: unknown[]) => args.filter(Boolean).join(' '),
+}))
+
+const mockUsePluginAuth = vi.fn()
+vi.mock('@/app/components/plugins/plugin-auth/hooks/use-plugin-auth', () => ({
+  usePluginAuth: (...args: unknown[]) => mockUsePluginAuth(...args),
+}))
+
+vi.mock('@/app/components/plugins/plugin-auth/authorize', () => ({
+  default: ({ pluginPayload, canOAuth, canApiKey }: {
+    pluginPayload: { provider: string }
+    canOAuth: boolean
+    canApiKey: boolean
+  }) => (
+    <div data-testid="authorize-component">
+      <span data-testid="auth-provider">{pluginPayload.provider}</span>
+      {canOAuth && <span data-testid="auth-oauth">OAuth available</span>}
+      {canApiKey && <span data-testid="auth-apikey">API Key available</span>}
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/plugin-auth/authorized', () => ({
+  default: ({ pluginPayload, credentials }: {
+    pluginPayload: { provider: string }
+    credentials: Array<{ id: string, name: string }>
+  }) => (
+    <div data-testid="authorized-component">
+      <span data-testid="auth-provider">{pluginPayload.provider}</span>
+      <span data-testid="auth-credential-count">
+        {credentials.length}
+        {' '}
+        credentials
+      </span>
+    </div>
+  ),
+}))
+
+const { default: PluginAuth } = await import('@/app/components/plugins/plugin-auth/plugin-auth')
+
+describe('Plugin Authentication Flow Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    cleanup()
+  })
+
+  const basePayload = {
+    category: AuthCategory.tool,
+    provider: 'test-provider',
+  }
+
+  describe('Unauthorized State', () => {
+    it('renders Authorize component when not authorized', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: false,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      render(<PluginAuth pluginPayload={basePayload} />)
+
+      expect(screen.getByTestId('authorize-component')).toBeInTheDocument()
+      expect(screen.queryByTestId('authorized-component')).not.toBeInTheDocument()
+      expect(screen.getByTestId('auth-apikey')).toBeInTheDocument()
+    })
+
+    it('shows OAuth option when plugin supports it', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: false,
+        canOAuth: true,
+        canApiKey: true,
+        credentials: [],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      render(<PluginAuth pluginPayload={basePayload} />)
+
+      expect(screen.getByTestId('auth-oauth')).toBeInTheDocument()
+      expect(screen.getByTestId('auth-apikey')).toBeInTheDocument()
+    })
+
+    it('applies className to wrapper when not authorized', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: false,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      const { container } = render(
+        <PluginAuth pluginPayload={basePayload} className="custom-class" />,
+      )
+
+      expect(container.firstChild).toHaveClass('custom-class')
+    })
+  })
+
+  describe('Authorized State', () => {
+    it('renders Authorized component when authorized and no children', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: true,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [
+          { id: 'cred-1', name: 'My API Key', is_default: true },
+        ],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      render(<PluginAuth pluginPayload={basePayload} />)
+
+      expect(screen.queryByTestId('authorize-component')).not.toBeInTheDocument()
+      expect(screen.getByTestId('authorized-component')).toBeInTheDocument()
+      expect(screen.getByTestId('auth-credential-count')).toHaveTextContent('1 credentials')
+    })
+
+    it('renders children instead of Authorized when authorized and children provided', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: true,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [{ id: 'cred-1', name: 'Key', is_default: true }],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      render(
+        <PluginAuth pluginPayload={basePayload}>
+          <div data-testid="custom-children">Custom authorized view</div>
+        </PluginAuth>,
+      )
+
+      expect(screen.queryByTestId('authorize-component')).not.toBeInTheDocument()
+      expect(screen.queryByTestId('authorized-component')).not.toBeInTheDocument()
+      expect(screen.getByTestId('custom-children')).toBeInTheDocument()
+    })
+
+    it('does not apply className when authorized', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: true,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [{ id: 'cred-1', name: 'Key', is_default: true }],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      const { container } = render(
+        <PluginAuth pluginPayload={basePayload} className="custom-class" />,
+      )
+
+      expect(container.firstChild).not.toHaveClass('custom-class')
+    })
+  })
+
+  describe('Auth Category Integration', () => {
+    it('passes correct provider to usePluginAuth for tool category', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: false,
+        canOAuth: false,
+        canApiKey: true,
+        credentials: [],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      const toolPayload = {
+        category: AuthCategory.tool,
+        provider: 'google-search-provider',
+      }
+
+      render(<PluginAuth pluginPayload={toolPayload} />)
+
+      expect(mockUsePluginAuth).toHaveBeenCalledWith(toolPayload, true)
+      expect(screen.getByTestId('auth-provider')).toHaveTextContent('google-search-provider')
+    })
+
+    it('passes correct provider to usePluginAuth for datasource category', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: false,
+        canOAuth: true,
+        canApiKey: false,
+        credentials: [],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      const dsPayload = {
+        category: AuthCategory.datasource,
+        provider: 'notion-datasource',
+      }
+
+      render(<PluginAuth pluginPayload={dsPayload} />)
+
+      expect(mockUsePluginAuth).toHaveBeenCalledWith(dsPayload, true)
+      expect(screen.getByTestId('auth-oauth')).toBeInTheDocument()
+      expect(screen.queryByTestId('auth-apikey')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Multiple Credentials', () => {
+    it('shows credential count when multiple credentials exist', () => {
+      mockUsePluginAuth.mockReturnValue({
+        isAuthorized: true,
+        canOAuth: true,
+        canApiKey: true,
+        credentials: [
+          { id: 'cred-1', name: 'API Key 1', is_default: true },
+          { id: 'cred-2', name: 'API Key 2', is_default: false },
+          { id: 'cred-3', name: 'OAuth Token', is_default: false, credential_type: CredentialTypeEnum.OAUTH2 },
+        ],
+        disabled: false,
+        invalidPluginCredentialInfo: vi.fn(),
+        notAllowCustomCredential: false,
+      })
+
+      render(<PluginAuth pluginPayload={basePayload} />)
+
+      expect(screen.getByTestId('auth-credential-count')).toHaveTextContent('3 credentials')
+    })
+  })
+})

web/__tests__/plugins/plugin-card-rendering.test.tsx

@@ -0,0 +1,224 @@
+/**
+ * Integration Test: Plugin Card Rendering Pipeline
+ *
+ * Tests the integration between Card, Icon, Title, Description,
+ * OrgInfo, CornerMark, and CardMoreInfo components. Verifies that
+ * plugin data flows correctly through the card rendering pipeline.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('#i18n', () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+vi.mock('@/context/i18n', () => ({
+  useGetLanguage: () => 'en_US',
+}))
+
+vi.mock('@/hooks/use-theme', () => ({
+  default: () => ({ theme: 'light' }),
+}))
+
+vi.mock('@/i18n-config', () => ({
+  renderI18nObject: (obj: Record<string, string>, locale: string) => obj[locale] || obj.en_US || '',
+}))
+
+vi.mock('@/types/app', () => ({
+  Theme: { dark: 'dark', light: 'light' },
+}))
+
+vi.mock('@/utils/classnames', () => ({
+  cn: (...args: unknown[]) => args.filter(a => typeof a === 'string' && a).join(' '),
+}))
+
+vi.mock('@/app/components/plugins/hooks', () => ({
+  useCategories: () => ({
+    categoriesMap: {
+      tool: { label: 'Tool' },
+      model: { label: 'Model' },
+      extension: { label: 'Extension' },
+    },
+  }),
+}))
+
+vi.mock('@/app/components/plugins/base/badges/partner', () => ({
+  default: () => <span data-testid="partner-badge">Partner</span>,
+}))
+
+vi.mock('@/app/components/plugins/base/badges/verified', () => ({
+  default: () => <span data-testid="verified-badge">Verified</span>,
+}))
+
+vi.mock('@/app/components/plugins/card/base/card-icon', () => ({
+  default: ({ src, installed, installFailed }: { src: string | object, installed?: boolean, installFailed?: boolean }) => (
+    <div data-testid="card-icon" data-installed={installed} data-install-failed={installFailed}>
+      {typeof src === 'string' ? src : 'emoji-icon'}
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/card/base/corner-mark', () => ({
+  default: ({ text }: { text: string }) => (
+    <div data-testid="corner-mark">{text}</div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/card/base/description', () => ({
+  default: ({ text, descriptionLineRows }: { text: string, descriptionLineRows?: number }) => (
+    <div data-testid="description" data-rows={descriptionLineRows}>{text}</div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/card/base/org-info', () => ({
+  default: ({ orgName, packageName }: { orgName: string, packageName: string }) => (
+    <div data-testid="org-info">
+      {orgName}
+      /
+      {packageName}
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/card/base/placeholder', () => ({
+  default: ({ text }: { text: string }) => (
+    <div data-testid="placeholder">{text}</div>
+  ),
+}))
+
+vi.mock('@/app/components/plugins/card/base/title', () => ({
+  default: ({ title }: { title: string }) => (
+    <div data-testid="title">{title}</div>
+  ),
+}))
+
+const { default: Card } = await import('@/app/components/plugins/card/index')
+type CardPayload = Parameters<typeof Card>[0]['payload']
+
+describe('Plugin Card Rendering Integration', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  const makePayload = (overrides = {}) => ({
+    category: 'tool',
+    type: 'plugin',
+    name: 'google-search',
+    org: 'langgenius',
+    label: { en_US: 'Google Search', zh_Hans: 'Google搜索' },
+    brief: { en_US: 'Search the web using Google', zh_Hans: '使用Google搜索网页' },
+    icon: 'https://example.com/icon.png',
+    verified: true,
+    badges: [] as string[],
+    ...overrides,
+  }) as CardPayload
+
+  it('renders a complete plugin card with all subcomponents', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} />)
+
+    expect(screen.getByTestId('card-icon')).toBeInTheDocument()
+    expect(screen.getByTestId('title')).toHaveTextContent('Google Search')
+    expect(screen.getByTestId('org-info')).toHaveTextContent('langgenius/google-search')
+    expect(screen.getByTestId('description')).toHaveTextContent('Search the web using Google')
+  })
+
+  it('shows corner mark with category label when not hidden', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} />)
+
+    expect(screen.getByTestId('corner-mark')).toBeInTheDocument()
+  })
+
+  it('hides corner mark when hideCornerMark is true', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} hideCornerMark />)
+
+    expect(screen.queryByTestId('corner-mark')).not.toBeInTheDocument()
+  })
+
+  it('shows installed status on icon', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} installed />)
+
+    const icon = screen.getByTestId('card-icon')
+    expect(icon).toHaveAttribute('data-installed', 'true')
+  })
+
+  it('shows install failed status on icon', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} installFailed />)
+
+    const icon = screen.getByTestId('card-icon')
+    expect(icon).toHaveAttribute('data-install-failed', 'true')
+  })
+
+  it('renders verified badge when plugin is verified', () => {
+    const payload = makePayload({ verified: true })
+    render(<Card payload={payload} />)
+
+    expect(screen.getByTestId('verified-badge')).toBeInTheDocument()
+  })
+
+  it('renders partner badge when plugin has partner badge', () => {
+    const payload = makePayload({ badges: ['partner'] })
+    render(<Card payload={payload} />)
+
+    expect(screen.getByTestId('partner-badge')).toBeInTheDocument()
+  })
+
+  it('renders footer content when provided', () => {
+    const payload = makePayload()
+    render(
+      <Card
+        payload={payload}
+        footer={<div data-testid="custom-footer">Custom footer</div>}
+      />,
+    )
+
+    expect(screen.getByTestId('custom-footer')).toBeInTheDocument()
+  })
+
+  it('renders titleLeft content when provided', () => {
+    const payload = makePayload()
+    render(
+      <Card
+        payload={payload}
+        titleLeft={<span data-testid="title-left-content">New</span>}
+      />,
+    )
+
+    expect(screen.getByTestId('title-left-content')).toBeInTheDocument()
+  })
+
+  it('uses dark icon when theme is dark and icon_dark is provided', () => {
+    vi.doMock('@/hooks/use-theme', () => ({
+      default: () => ({ theme: 'dark' }),
+    }))
+
+    const payload = makePayload({
+      icon: 'https://example.com/icon-light.png',
+      icon_dark: 'https://example.com/icon-dark.png',
+    })
+
+    render(<Card payload={payload} />)
+    expect(screen.getByTestId('card-icon')).toBeInTheDocument()
+  })
+
+  it('shows loading placeholder when isLoading is true', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} isLoading loadingFileName="uploading.difypkg" />)
+
+    expect(screen.getByTestId('placeholder')).toBeInTheDocument()
+  })
+
+  it('renders description with custom line rows', () => {
+    const payload = makePayload()
+    render(<Card payload={payload} descriptionLineRows={3} />)
+
+    const description = screen.getByTestId('description')
+    expect(description).toHaveAttribute('data-rows', '3')
+  })
+})

web/__tests__/plugins/plugin-data-utilities.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Integration Test: Plugin Data Utilities
+ *
+ * Tests the integration between plugin utility functions, including
+ * tag/category validation, form schema transformation, and
+ * credential data processing. Verifies that these utilities work
+ * correctly together in processing plugin metadata.
+ */
+import { describe, expect, it } from 'vitest'
+
+import { transformFormSchemasSecretInput } from '@/app/components/plugins/plugin-auth/utils'
+import { getValidCategoryKeys, getValidTagKeys } from '@/app/components/plugins/utils'
+
+type TagInput = Parameters<typeof getValidTagKeys>[0]
+
+describe('Plugin Data Utilities Integration', () => {
+  describe('Tag and Category Validation Pipeline', () => {
+    it('validates tags and categories in a metadata processing flow', () => {
+      const pluginMetadata = {
+        tags: ['search', 'productivity', 'invalid-tag', 'media-generate'],
+        category: 'tool',
+      }
+
+      const validTags = getValidTagKeys(pluginMetadata.tags as TagInput)
+      expect(validTags.length).toBeGreaterThan(0)
+      expect(validTags.length).toBeLessThanOrEqual(pluginMetadata.tags.length)
+
+      const validCategory = getValidCategoryKeys(pluginMetadata.category)
+      expect(validCategory).toBeDefined()
+    })
+
+    it('handles completely invalid metadata gracefully', () => {
+      const invalidMetadata = {
+        tags: ['nonexistent-1', 'nonexistent-2'],
+        category: 'nonexistent-category',
+      }
+
+      const validTags = getValidTagKeys(invalidMetadata.tags as TagInput)
+      expect(validTags).toHaveLength(0)
+
+      const validCategory = getValidCategoryKeys(invalidMetadata.category)
+      expect(validCategory).toBeUndefined()
+    })
+
+    it('handles undefined and empty inputs', () => {
+      expect(getValidTagKeys([] as TagInput)).toHaveLength(0)
+      expect(getValidCategoryKeys(undefined)).toBeUndefined()
+      expect(getValidCategoryKeys('')).toBeUndefined()
+    })
+  })
+
+  describe('Credential Secret Masking Pipeline', () => {
+    it('masks secrets when displaying credential form data', () => {
+      const credentialValues = {
+        api_key: 'sk-abc123456789',
+        api_endpoint: 'https://api.example.com',
+        secret_token: 'secret-token-value',
+        description: 'My credential set',
+      }
+
+      const secretFields = ['api_key', 'secret_token']
+
+      const displayValues = transformFormSchemasSecretInput(secretFields, credentialValues)
+
+      expect(displayValues.api_key).toBe('[__HIDDEN__]')
+      expect(displayValues.secret_token).toBe('[__HIDDEN__]')
+      expect(displayValues.api_endpoint).toBe('https://api.example.com')
+      expect(displayValues.description).toBe('My credential set')
+    })
+
+    it('preserves original values when no secret fields', () => {
+      const values = {
+        name: 'test',
+        endpoint: 'https://api.example.com',
+      }
+
+      const result = transformFormSchemasSecretInput([], values)
+      expect(result).toEqual(values)
+    })
+
+    it('handles falsy secret values without masking', () => {
+      const values = {
+        api_key: '',
+        secret: null as unknown as string,
+        other: 'visible',
+      }
+
+      const result = transformFormSchemasSecretInput(['api_key', 'secret'], values)
+      expect(result.api_key).toBe('')
+      expect(result.secret).toBeNull()
+      expect(result.other).toBe('visible')
+    })
+
+    it('does not mutate the original values object', () => {
+      const original = {
+        api_key: 'my-secret-key',
+        name: 'test',
+      }
+      const originalCopy = { ...original }
+
+      transformFormSchemasSecretInput(['api_key'], original)
+
+      expect(original).toEqual(originalCopy)
+    })
+  })
+
+  describe('Combined Plugin Metadata Validation', () => {
+    it('processes a complete plugin entry with tags and credentials', () => {
+      const pluginEntry = {
+        name: 'test-plugin',
+        category: 'tool',
+        tags: ['search', 'invalid-tag'],
+        credentials: {
+          api_key: 'sk-test-key-123',
+          base_url: 'https://api.test.com',
+        },
+        secretFields: ['api_key'],
+      }
+
+      const validCategory = getValidCategoryKeys(pluginEntry.category)
+      expect(validCategory).toBe('tool')
+
+      const validTags = getValidTagKeys(pluginEntry.tags as TagInput)
+      expect(validTags).toContain('search')
+
+      const displayCredentials = transformFormSchemasSecretInput(
+        pluginEntry.secretFields,
+        pluginEntry.credentials,
+      )
+      expect(displayCredentials.api_key).toBe('[__HIDDEN__]')
+      expect(displayCredentials.base_url).toBe('https://api.test.com')
+
+      expect(pluginEntry.credentials.api_key).toBe('sk-test-key-123')
+    })
+
+    it('handles multiple plugins in batch processing', () => {
+      const plugins = [
+        { tags: ['search', 'productivity'], category: 'tool' },
+        { tags: ['image', 'design'], category: 'model' },
+        { tags: ['invalid'], category: 'extension' },
+      ]
+
+      const results = plugins.map(p => ({
+        validTags: getValidTagKeys(p.tags as TagInput),
+        validCategory: getValidCategoryKeys(p.category),
+      }))
+
+      expect(results[0].validTags.length).toBeGreaterThan(0)
+      expect(results[0].validCategory).toBe('tool')
+
+      expect(results[1].validTags).toContain('image')
+      expect(results[1].validTags).toContain('design')
+      expect(results[1].validCategory).toBe('model')
+
+      expect(results[2].validTags).toHaveLength(0)
+      expect(results[2].validCategory).toBe('extension')
+    })
+  })
+})

web/__tests__/plugins/plugin-install-flow.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Integration Test: Plugin Installation Flow
+ *
+ * Tests the integration between GitHub release fetching, version comparison,
+ * upload handling, and task status polling. Verifies the complete plugin
+ * installation pipeline from source discovery to completion.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/config', () => ({
+  GITHUB_ACCESS_TOKEN: '',
+}))
+
+const mockToastNotify = vi.fn()
+vi.mock('@/app/components/base/toast', () => ({
+  default: { notify: (...args: unknown[]) => mockToastNotify(...args) },
+}))
+
+const mockUploadGitHub = vi.fn()
+vi.mock('@/service/plugins', () => ({
+  uploadGitHub: (...args: unknown[]) => mockUploadGitHub(...args),
+  checkTaskStatus: vi.fn(),
+}))
+
+vi.mock('@/utils/semver', () => ({
+  compareVersion: (a: string, b: string) => {
+    const parse = (v: string) => v.replace(/^v/, '').split('.').map(Number)
+    const [aMajor, aMinor = 0, aPatch = 0] = parse(a)
+    const [bMajor, bMinor = 0, bPatch = 0] = parse(b)
+    if (aMajor !== bMajor)
+      return aMajor > bMajor ? 1 : -1
+    if (aMinor !== bMinor)
+      return aMinor > bMinor ? 1 : -1
+    if (aPatch !== bPatch)
+      return aPatch > bPatch ? 1 : -1
+    return 0
+  },
+  getLatestVersion: (versions: string[]) => {
+    return versions.sort((a, b) => {
+      const parse = (v: string) => v.replace(/^v/, '').split('.').map(Number)
+      const [aMaj, aMin = 0, aPat = 0] = parse(a)
+      const [bMaj, bMin = 0, bPat = 0] = parse(b)
+      if (aMaj !== bMaj)
+        return bMaj - aMaj
+      if (aMin !== bMin)
+        return bMin - aMin
+      return bPat - aPat
+    })[0]
+  },
+}))
+
+const { useGitHubReleases, useGitHubUpload } = await import(
+  '@/app/components/plugins/install-plugin/hooks',
+)
+
+describe('Plugin Installation Flow Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    globalThis.fetch = vi.fn()
+  })
+
+  describe('GitHub Release Discovery → Version Check → Upload Pipeline', () => {
+    it('fetches releases, checks for updates, and uploads the new version', async () => {
+      const mockReleases = [
+        {
+          tag_name: 'v2.0.0',
+          assets: [{ browser_download_url: 'https://github.com/test/v2.difypkg', name: 'plugin-v2.difypkg' }],
+        },
+        {
+          tag_name: 'v1.5.0',
+          assets: [{ browser_download_url: 'https://github.com/test/v1.5.difypkg', name: 'plugin-v1.5.difypkg' }],
+        },
+        {
+          tag_name: 'v1.0.0',
+          assets: [{ browser_download_url: 'https://github.com/test/v1.difypkg', name: 'plugin-v1.difypkg' }],
+        },
+      ]
+
+      ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockReleases),
+      })
+
+      mockUploadGitHub.mockResolvedValue({
+        manifest: { name: 'test-plugin', version: '2.0.0' },
+        unique_identifier: 'test-plugin:2.0.0',
+      })
+
+      const { fetchReleases, checkForUpdates } = useGitHubReleases()
+
+      const releases = await fetchReleases('test-org', 'test-repo')
+      expect(releases).toHaveLength(3)
+      expect(releases[0].tag_name).toBe('v2.0.0')
+
+      const { needUpdate, toastProps } = checkForUpdates(releases, 'v1.0.0')
+      expect(needUpdate).toBe(true)
+      expect(toastProps.message).toContain('v2.0.0')
+
+      const { handleUpload } = useGitHubUpload()
+      const onSuccess = vi.fn()
+      const result = await handleUpload(
+        'https://github.com/test-org/test-repo',
+        'v2.0.0',
+        'plugin-v2.difypkg',
+        onSuccess,
+      )
+
+      expect(mockUploadGitHub).toHaveBeenCalledWith(
+        'https://github.com/test-org/test-repo',
+        'v2.0.0',
+        'plugin-v2.difypkg',
+      )
+      expect(onSuccess).toHaveBeenCalledWith({
+        manifest: { name: 'test-plugin', version: '2.0.0' },
+        unique_identifier: 'test-plugin:2.0.0',
+      })
+      expect(result).toEqual({
+        manifest: { name: 'test-plugin', version: '2.0.0' },
+        unique_identifier: 'test-plugin:2.0.0',
+      })
+    })
+
+    it('handles no new version available', async () => {
+      const mockReleases = [
+        {
+          tag_name: 'v1.0.0',
+          assets: [{ browser_download_url: 'https://github.com/test/v1.difypkg', name: 'plugin-v1.difypkg' }],
+        },
+      ]
+
+      ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockReleases),
+      })
+
+      const { fetchReleases, checkForUpdates } = useGitHubReleases()
+
+      const releases = await fetchReleases('test-org', 'test-repo')
+      const { needUpdate, toastProps } = checkForUpdates(releases, 'v1.0.0')
+
+      expect(needUpdate).toBe(false)
+      expect(toastProps.type).toBe('info')
+      expect(toastProps.message).toBe('No new version available')
+    })
+
+    it('handles empty releases', async () => {
+      ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve([]),
+      })
+
+      const { fetchReleases, checkForUpdates } = useGitHubReleases()
+
+      const releases = await fetchReleases('test-org', 'test-repo')
+      expect(releases).toHaveLength(0)
+
+      const { needUpdate, toastProps } = checkForUpdates(releases, 'v1.0.0')
+      expect(needUpdate).toBe(false)
+      expect(toastProps.type).toBe('error')
+      expect(toastProps.message).toBe('Input releases is empty')
+    })
+
+    it('handles fetch failure gracefully', async () => {
+      ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+        ok: false,
+        status: 404,
+      })
+
+      const { fetchReleases } = useGitHubReleases()
+      const releases = await fetchReleases('nonexistent-org', 'nonexistent-repo')
+
+      expect(releases).toEqual([])
+      expect(mockToastNotify).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'error' }),
+      )
+    })
+
+    it('handles upload failure gracefully', async () => {
+      mockUploadGitHub.mockRejectedValue(new Error('Upload failed'))
+
+      const { handleUpload } = useGitHubUpload()
+      const onSuccess = vi.fn()
+
+      await expect(
+        handleUpload('https://github.com/test/repo', 'v1.0.0', 'plugin.difypkg', onSuccess),
+      ).rejects.toThrow('Upload failed')
+
+      expect(onSuccess).not.toHaveBeenCalled()
+      expect(mockToastNotify).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'error', message: 'Error uploading package' }),
+      )
+    })
+  })
+
+  describe('Task Status Polling Integration', () => {
+    it('polls until plugin installation succeeds', async () => {
+      const mockCheckTaskStatus = vi.fn()
+        .mockResolvedValueOnce({
+          task: {
+            plugins: [{ plugin_unique_identifier: 'test:1.0.0', status: 'running' }],
+          },
+        })
+        .mockResolvedValueOnce({
+          task: {
+            plugins: [{ plugin_unique_identifier: 'test:1.0.0', status: 'success' }],
+          },
+        })
+
+      const { checkTaskStatus: fetchCheckTaskStatus } = await import('@/service/plugins')
+      ;(fetchCheckTaskStatus as ReturnType<typeof vi.fn>).mockImplementation(mockCheckTaskStatus)
+
+      await vi.doMock('@/utils', () => ({
+        sleep: () => Promise.resolve(),
+      }))
+
+      const { default: checkTaskStatus } = await import(
+        '@/app/components/plugins/install-plugin/base/check-task-status',
+      )
+
+      const checker = checkTaskStatus()
+      const result = await checker.check({
+        taskId: 'task-123',
+        pluginUniqueIdentifier: 'test:1.0.0',
+      })
+
+      expect(result.status).toBe('success')
+    })
+
+    it('returns failure when plugin not found in task', async () => {
+      const mockCheckTaskStatus = vi.fn().mockResolvedValue({
+        task: {
+          plugins: [{ plugin_unique_identifier: 'other:1.0.0', status: 'success' }],
+        },
+      })
+
+      const { checkTaskStatus: fetchCheckTaskStatus } = await import('@/service/plugins')
+      ;(fetchCheckTaskStatus as ReturnType<typeof vi.fn>).mockImplementation(mockCheckTaskStatus)
+
+      const { default: checkTaskStatus } = await import(
+        '@/app/components/plugins/install-plugin/base/check-task-status',
+      )
+
+      const checker = checkTaskStatus()
+      const result = await checker.check({
+        taskId: 'task-123',
+        pluginUniqueIdentifier: 'test:1.0.0',
+      })
+
+      expect(result.status).toBe('failed')
+      expect(result.error).toBe('Plugin package not found')
+    })
+
+    it('stops polling when stop() is called', async () => {
+      const { default: checkTaskStatus } = await import(
+        '@/app/components/plugins/install-plugin/base/check-task-status',
+      )
+
+      const checker = checkTaskStatus()
+      checker.stop()
+
+      const result = await checker.check({
+        taskId: 'task-123',
+        pluginUniqueIdentifier: 'test:1.0.0',
+      })
+
+      expect(result.status).toBe('success')
+    })
+  })
+})

web/__tests__/plugins/plugin-marketplace-to-install.test.tsx

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest'
+import { pluginInstallLimit } from '@/app/components/plugins/install-plugin/hooks/use-install-plugin-limit'
+import { InstallationScope } from '@/types/feature'
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: () => ({
+    plugin_installation_permission: {
+      restrict_to_marketplace_only: false,
+      plugin_installation_scope: InstallationScope.ALL,
+    },
+  }),
+}))
+
+describe('Plugin Marketplace to Install Flow', () => {
+  describe('install permission validation pipeline', () => {
+    const systemFeaturesAll = {
+      plugin_installation_permission: {
+        restrict_to_marketplace_only: false,
+        plugin_installation_scope: InstallationScope.ALL,
+      },
+    }
+
+    const systemFeaturesMarketplaceOnly = {
+      plugin_installation_permission: {
+        restrict_to_marketplace_only: true,
+        plugin_installation_scope: InstallationScope.ALL,
+      },
+    }
+
+    const systemFeaturesOfficialOnly = {
+      plugin_installation_permission: {
+        restrict_to_marketplace_only: false,
+        plugin_installation_scope: InstallationScope.OFFICIAL_ONLY,
+      },
+    }
+
+    it('should allow marketplace plugin when all sources allowed', () => {
+      const plugin = { from: 'marketplace' as const, verification: { authorized_category: 'langgenius' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesAll as never)
+      expect(result.canInstall).toBe(true)
+    })
+
+    it('should allow github plugin when all sources allowed', () => {
+      const plugin = { from: 'github' as const, verification: { authorized_category: 'langgenius' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesAll as never)
+      expect(result.canInstall).toBe(true)
+    })
+
+    it('should block github plugin when marketplace only', () => {
+      const plugin = { from: 'github' as const, verification: { authorized_category: 'langgenius' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesMarketplaceOnly as never)
+      expect(result.canInstall).toBe(false)
+    })
+
+    it('should allow marketplace plugin when marketplace only', () => {
+      const plugin = { from: 'marketplace' as const, verification: { authorized_category: 'partner' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesMarketplaceOnly as never)
+      expect(result.canInstall).toBe(true)
+    })
+
+    it('should allow official plugin when official only', () => {
+      const plugin = { from: 'marketplace' as const, verification: { authorized_category: 'langgenius' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesOfficialOnly as never)
+      expect(result.canInstall).toBe(true)
+    })
+
+    it('should block community plugin when official only', () => {
+      const plugin = { from: 'marketplace' as const, verification: { authorized_category: 'community' } }
+      const result = pluginInstallLimit(plugin as never, systemFeaturesOfficialOnly as never)
+      expect(result.canInstall).toBe(false)
+    })
+  })
+
+  describe('plugin source classification', () => {
+    it('should correctly classify plugin install sources', () => {
+      const sources = ['marketplace', 'github', 'package'] as const
+      const features = {
+        plugin_installation_permission: {
+          restrict_to_marketplace_only: true,
+          plugin_installation_scope: InstallationScope.ALL,
+        },
+      }
+
+      const results = sources.map(source => ({
+        source,
+        canInstall: pluginInstallLimit(
+          { from: source, verification: { authorized_category: 'langgenius' } } as never,
+          features as never,
+        ).canInstall,
+      }))
+
+      expect(results.find(r => r.source === 'marketplace')?.canInstall).toBe(true)
+      expect(results.find(r => r.source === 'github')?.canInstall).toBe(false)
+      expect(results.find(r => r.source === 'package')?.canInstall).toBe(false)
+    })
+  })
+})

web/__tests__/plugins/plugin-page-filter-management.test.tsx

@@ -0,0 +1,120 @@
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { useStore } from '@/app/components/plugins/plugin-page/filter-management/store'
+
+describe('Plugin Page Filter Management Integration', () => {
+  beforeEach(() => {
+    const { result } = renderHook(() => useStore())
+    act(() => {
+      result.current.setTagList([])
+      result.current.setCategoryList([])
+      result.current.setShowTagManagementModal(false)
+      result.current.setShowCategoryManagementModal(false)
+    })
+  })
+
+  describe('tag and category filter lifecycle', () => {
+    it('should manage full tag lifecycle: add -> update -> clear', () => {
+      const { result } = renderHook(() => useStore())
+
+      const initialTags = [
+        { name: 'search', label: { en_US: 'Search' } },
+        { name: 'productivity', label: { en_US: 'Productivity' } },
+      ]
+
+      act(() => {
+        result.current.setTagList(initialTags as never[])
+      })
+      expect(result.current.tagList).toHaveLength(2)
+
+      const updatedTags = [
+        ...initialTags,
+        { name: 'image', label: { en_US: 'Image' } },
+      ]
+
+      act(() => {
+        result.current.setTagList(updatedTags as never[])
+      })
+      expect(result.current.tagList).toHaveLength(3)
+
+      act(() => {
+        result.current.setTagList([])
+      })
+      expect(result.current.tagList).toHaveLength(0)
+    })
+
+    it('should manage full category lifecycle: add -> update -> clear', () => {
+      const { result } = renderHook(() => useStore())
+
+      const categories = [
+        { name: 'tool', label: { en_US: 'Tool' } },
+        { name: 'model', label: { en_US: 'Model' } },
+      ]
+
+      act(() => {
+        result.current.setCategoryList(categories as never[])
+      })
+      expect(result.current.categoryList).toHaveLength(2)
+
+      act(() => {
+        result.current.setCategoryList([])
+      })
+      expect(result.current.categoryList).toHaveLength(0)
+    })
+  })
+
+  describe('modal state management', () => {
+    it('should manage tag management modal independently', () => {
+      const { result } = renderHook(() => useStore())
+
+      act(() => {
+        result.current.setShowTagManagementModal(true)
+      })
+      expect(result.current.showTagManagementModal).toBe(true)
+      expect(result.current.showCategoryManagementModal).toBe(false)
+
+      act(() => {
+        result.current.setShowTagManagementModal(false)
+      })
+      expect(result.current.showTagManagementModal).toBe(false)
+    })
+
+    it('should manage category management modal independently', () => {
+      const { result } = renderHook(() => useStore())
+
+      act(() => {
+        result.current.setShowCategoryManagementModal(true)
+      })
+      expect(result.current.showCategoryManagementModal).toBe(true)
+      expect(result.current.showTagManagementModal).toBe(false)
+    })
+
+    it('should support both modals open simultaneously', () => {
+      const { result } = renderHook(() => useStore())
+
+      act(() => {
+        result.current.setShowTagManagementModal(true)
+        result.current.setShowCategoryManagementModal(true)
+      })
+
+      expect(result.current.showTagManagementModal).toBe(true)
+      expect(result.current.showCategoryManagementModal).toBe(true)
+    })
+  })
+
+  describe('state persistence across renders', () => {
+    it('should maintain filter state when re-rendered', () => {
+      const { result, rerender } = renderHook(() => useStore())
+
+      act(() => {
+        result.current.setTagList([{ name: 'search' }] as never[])
+        result.current.setCategoryList([{ name: 'tool' }] as never[])
+      })
+
+      rerender()
+
+      expect(result.current.tagList).toHaveLength(1)
+      expect(result.current.categoryList).toHaveLength(1)
+    })
+  })
+})

web/__tests__/rag-pipeline/chunk-preview-formatting.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Integration test: Chunk preview formatting pipeline
+ *
+ * Tests the formatPreviewChunks utility across all chunking modes
+ * (text, parentChild, QA) with real data structures.
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/config', () => ({
+  RAG_PIPELINE_PREVIEW_CHUNK_NUM: 3,
+}))
+
+vi.mock('@/models/datasets', () => ({
+  ChunkingMode: {
+    text: 'text',
+    parentChild: 'parent-child',
+    qa: 'qa',
+  },
+}))
+
+const { formatPreviewChunks } = await import(
+  '@/app/components/rag-pipeline/components/panel/test-run/result/result-preview/utils',
+)
+
+describe('Chunk Preview Formatting', () => {
+  describe('general text chunks', () => {
+    it('should format text chunks correctly', () => {
+      const outputs = {
+        chunk_structure: 'text',
+        preview: [
+          { content: 'Chunk 1 content', summary: 'Summary 1' },
+          { content: 'Chunk 2 content' },
+        ],
+      }
+
+      const result = formatPreviewChunks(outputs)
+
+      expect(Array.isArray(result)).toBe(true)
+      const chunks = result as Array<{ content: string, summary?: string }>
+      expect(chunks).toHaveLength(2)
+      expect(chunks[0].content).toBe('Chunk 1 content')
+      expect(chunks[0].summary).toBe('Summary 1')
+      expect(chunks[1].content).toBe('Chunk 2 content')
+    })
+
+    it('should limit chunks to RAG_PIPELINE_PREVIEW_CHUNK_NUM', () => {
+      const outputs = {
+        chunk_structure: 'text',
+        preview: Array.from({ length: 10 }, (_, i) => ({
+          content: `Chunk ${i + 1}`,
+        })),
+      }
+
+      const result = formatPreviewChunks(outputs)
+      const chunks = result as Array<{ content: string }>
+
+      expect(chunks).toHaveLength(3) // Mocked limit
+    })
+  })
+
+  describe('parent-child chunks — paragraph mode', () => {
+    it('should format paragraph parent-child chunks', () => {
+      const outputs = {
+        chunk_structure: 'parent-child',
+        parent_mode: 'paragraph',
+        preview: [
+          {
+            content: 'Parent paragraph',
+            child_chunks: ['Child 1', 'Child 2'],
+            summary: 'Parent summary',
+          },
+        ],
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        parent_child_chunks: Array<{
+          parent_content: string
+          parent_summary?: string
+          child_contents: string[]
+          parent_mode: string
+        }>
+        parent_mode: string
+      }
+
+      expect(result.parent_mode).toBe('paragraph')
+      expect(result.parent_child_chunks).toHaveLength(1)
+      expect(result.parent_child_chunks[0].parent_content).toBe('Parent paragraph')
+      expect(result.parent_child_chunks[0].parent_summary).toBe('Parent summary')
+      expect(result.parent_child_chunks[0].child_contents).toEqual(['Child 1', 'Child 2'])
+    })
+
+    it('should limit parent chunks in paragraph mode', () => {
+      const outputs = {
+        chunk_structure: 'parent-child',
+        parent_mode: 'paragraph',
+        preview: Array.from({ length: 10 }, (_, i) => ({
+          content: `Parent ${i + 1}`,
+          child_chunks: [`Child of ${i + 1}`],
+        })),
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        parent_child_chunks: unknown[]
+      }
+
+      expect(result.parent_child_chunks).toHaveLength(3) // Mocked limit
+    })
+  })
+
+  describe('parent-child chunks — full-doc mode', () => {
+    it('should format full-doc parent-child chunks', () => {
+      const outputs = {
+        chunk_structure: 'parent-child',
+        parent_mode: 'full-doc',
+        preview: [
+          {
+            content: 'Full document content',
+            child_chunks: ['Section 1', 'Section 2', 'Section 3'],
+          },
+        ],
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        parent_child_chunks: Array<{
+          parent_content: string
+          child_contents: string[]
+          parent_mode: string
+        }>
+      }
+
+      expect(result.parent_child_chunks).toHaveLength(1)
+      expect(result.parent_child_chunks[0].parent_content).toBe('Full document content')
+      expect(result.parent_child_chunks[0].parent_mode).toBe('full-doc')
+    })
+
+    it('should limit child chunks in full-doc mode', () => {
+      const outputs = {
+        chunk_structure: 'parent-child',
+        parent_mode: 'full-doc',
+        preview: [
+          {
+            content: 'Document',
+            child_chunks: Array.from({ length: 20 }, (_, i) => `Section ${i + 1}`),
+          },
+        ],
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        parent_child_chunks: Array<{ child_contents: string[] }>
+      }
+
+      expect(result.parent_child_chunks[0].child_contents).toHaveLength(3) // Mocked limit
+    })
+  })
+
+  describe('QA chunks', () => {
+    it('should format QA chunks correctly', () => {
+      const outputs = {
+        chunk_structure: 'qa',
+        qa_preview: [
+          { question: 'What is AI?', answer: 'Artificial Intelligence is...' },
+          { question: 'What is ML?', answer: 'Machine Learning is...' },
+        ],
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        qa_chunks: Array<{ question: string, answer: string }>
+      }
+
+      expect(result.qa_chunks).toHaveLength(2)
+      expect(result.qa_chunks[0].question).toBe('What is AI?')
+      expect(result.qa_chunks[0].answer).toBe('Artificial Intelligence is...')
+    })
+
+    it('should limit QA chunks', () => {
+      const outputs = {
+        chunk_structure: 'qa',
+        qa_preview: Array.from({ length: 10 }, (_, i) => ({
+          question: `Q${i + 1}`,
+          answer: `A${i + 1}`,
+        })),
+      }
+
+      const result = formatPreviewChunks(outputs) as {
+        qa_chunks: unknown[]
+      }
+
+      expect(result.qa_chunks).toHaveLength(3) // Mocked limit
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should return undefined for null outputs', () => {
+      expect(formatPreviewChunks(null)).toBeUndefined()
+    })
+
+    it('should return undefined for undefined outputs', () => {
+      expect(formatPreviewChunks(undefined)).toBeUndefined()
+    })
+
+    it('should return undefined for unknown chunk_structure', () => {
+      const outputs = {
+        chunk_structure: 'unknown-type',
+        preview: [],
+      }
+
+      expect(formatPreviewChunks(outputs)).toBeUndefined()
+    })
+  })
+})

web/__tests__/rag-pipeline/dsl-export-import-flow.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Integration test: DSL export/import flow
+ *
+ * Validates DSL export logic (sync draft → check secrets → download)
+ * and DSL import modal state management.
+ */
+import { act, renderHook } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+const mockDoSyncWorkflowDraft = vi.fn().mockResolvedValue(undefined)
+const mockExportPipelineConfig = vi.fn().mockResolvedValue({ data: 'yaml-content' })
+const mockNotify = vi.fn()
+const mockEventEmitter = { emit: vi.fn() }
+const mockDownloadBlob = vi.fn()
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+vi.mock('@/app/components/base/toast', () => ({
+  useToastContext: () => ({ notify: mockNotify }),
+}))
+
+vi.mock('@/app/components/workflow/constants', () => ({
+  DSL_EXPORT_CHECK: 'DSL_EXPORT_CHECK',
+}))
+
+vi.mock('@/app/components/workflow/store', () => ({
+  useWorkflowStore: () => ({
+    getState: () => ({
+      pipelineId: 'pipeline-abc',
+      knowledgeName: 'My Pipeline',
+    }),
+  }),
+}))
+
+vi.mock('@/context/event-emitter', () => ({
+  useEventEmitterContextContext: () => ({
+    eventEmitter: mockEventEmitter,
+  }),
+}))
+
+vi.mock('@/service/use-pipeline', () => ({
+  useExportPipelineDSL: () => ({
+    mutateAsync: mockExportPipelineConfig,
+  }),
+}))
+
+vi.mock('@/service/workflow', () => ({
+  fetchWorkflowDraft: vi.fn(),
+}))
+
+vi.mock('@/utils/download', () => ({
+  downloadBlob: (...args: unknown[]) => mockDownloadBlob(...args),
+}))
+
+vi.mock('@/app/components/rag-pipeline/hooks/use-nodes-sync-draft', () => ({
+  useNodesSyncDraft: () => ({
+    doSyncWorkflowDraft: mockDoSyncWorkflowDraft,
+  }),
+}))
+
+describe('DSL Export/Import Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Export Flow', () => {
+    it('should sync draft then export then download', async () => {
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.handleExportDSL()
+      })
+
+      expect(mockDoSyncWorkflowDraft).toHaveBeenCalled()
+      expect(mockExportPipelineConfig).toHaveBeenCalledWith({
+        pipelineId: 'pipeline-abc',
+        include: false,
+      })
+      expect(mockDownloadBlob).toHaveBeenCalledWith(expect.objectContaining({
+        fileName: 'My Pipeline.pipeline',
+      }))
+    })
+
+    it('should export with include flag when specified', async () => {
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.handleExportDSL(true)
+      })
+
+      expect(mockExportPipelineConfig).toHaveBeenCalledWith({
+        pipelineId: 'pipeline-abc',
+        include: true,
+      })
+    })
+
+    it('should notify on export error', async () => {
+      mockDoSyncWorkflowDraft.mockRejectedValueOnce(new Error('sync failed'))
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.handleExportDSL()
+      })
+
+      expect(mockNotify).toHaveBeenCalledWith(expect.objectContaining({
+        type: 'error',
+      }))
+    })
+  })
+
+  describe('Export Check Flow', () => {
+    it('should export directly when no secret environment variables', async () => {
+      const { fetchWorkflowDraft } = await import('@/service/workflow')
+      vi.mocked(fetchWorkflowDraft).mockResolvedValueOnce({
+        environment_variables: [
+          { value_type: 'string', key: 'API_URL', value: 'https://api.example.com' },
+        ],
+      } as unknown as Awaited<ReturnType<typeof fetchWorkflowDraft>>)
+
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.exportCheck()
+      })
+
+      // Should proceed to export directly (no secret vars)
+      expect(mockDoSyncWorkflowDraft).toHaveBeenCalled()
+    })
+
+    it('should emit DSL_EXPORT_CHECK event when secret variables exist', async () => {
+      const { fetchWorkflowDraft } = await import('@/service/workflow')
+      vi.mocked(fetchWorkflowDraft).mockResolvedValueOnce({
+        environment_variables: [
+          { value_type: 'secret', key: 'API_KEY', value: '***' },
+        ],
+      } as unknown as Awaited<ReturnType<typeof fetchWorkflowDraft>>)
+
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.exportCheck()
+      })
+
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(expect.objectContaining({
+        type: 'DSL_EXPORT_CHECK',
+        payload: expect.objectContaining({
+          data: expect.arrayContaining([
+            expect.objectContaining({ value_type: 'secret' }),
+          ]),
+        }),
+      }))
+    })
+
+    it('should notify on export check error', async () => {
+      const { fetchWorkflowDraft } = await import('@/service/workflow')
+      vi.mocked(fetchWorkflowDraft).mockRejectedValueOnce(new Error('fetch failed'))
+
+      const { useDSL } = await import('@/app/components/rag-pipeline/hooks/use-DSL')
+      const { result } = renderHook(() => useDSL())
+
+      await act(async () => {
+        await result.current.exportCheck()
+      })
+
+      expect(mockNotify).toHaveBeenCalledWith(expect.objectContaining({
+        type: 'error',
+      }))
+    })
+  })
+})

web/__tests__/rag-pipeline/input-field-crud-flow.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Integration test: Input field CRUD complete flow
+ *
+ * Validates the full lifecycle of input fields:
+ * creation, editing, renaming, removal, and data conversion round-trip.
+ */
+import type { FormData } from '@/app/components/rag-pipeline/components/panel/input-field/editor/form/types'
+import type { InputVar } from '@/models/pipeline'
+import { describe, expect, it, vi } from 'vitest'
+import { SupportUploadFileTypes } from '@/app/components/workflow/types'
+import { PipelineInputVarType } from '@/models/pipeline'
+import { TransferMethod } from '@/types/app'
+
+vi.mock('@/config', () => ({
+  VAR_ITEM_TEMPLATE_IN_PIPELINE: {
+    type: 'text-input',
+    label: '',
+    variable: '',
+    max_length: 48,
+    default_value: undefined,
+    required: true,
+    tooltips: undefined,
+    options: [],
+    placeholder: undefined,
+    unit: undefined,
+    allowed_file_upload_methods: undefined,
+    allowed_file_types: undefined,
+    allowed_file_extensions: undefined,
+  },
+}))
+
+describe('Input Field CRUD Flow', () => {
+  describe('Create → Edit → Convert Round-trip', () => {
+    it('should create a text field and roundtrip through form data', async () => {
+      const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      // Create new field from template (no data passed)
+      const newFormData = convertToInputFieldFormData()
+      expect(newFormData.type).toBe('text-input')
+      expect(newFormData.variable).toBe('')
+      expect(newFormData.label).toBe('')
+      expect(newFormData.required).toBe(true)
+
+      // Simulate user editing form data
+      const editedFormData: FormData = {
+        ...newFormData,
+        variable: 'user_name',
+        label: 'User Name',
+        maxLength: 100,
+        default: 'John',
+        tooltips: 'Enter your name',
+        placeholder: 'Type here...',
+        allowedTypesAndExtensions: {},
+      }
+
+      // Convert back to InputVar
+      const inputVar = convertFormDataToINputField(editedFormData)
+
+      expect(inputVar.variable).toBe('user_name')
+      expect(inputVar.label).toBe('User Name')
+      expect(inputVar.max_length).toBe(100)
+      expect(inputVar.default_value).toBe('John')
+      expect(inputVar.tooltips).toBe('Enter your name')
+      expect(inputVar.placeholder).toBe('Type here...')
+      expect(inputVar.required).toBe(true)
+    })
+
+    it('should handle file field with upload settings', async () => {
+      const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const fileInputVar: InputVar = {
+        type: PipelineInputVarType.singleFile,
+        label: 'Upload Document',
+        variable: 'doc_file',
+        max_length: 1,
+        default_value: undefined,
+        required: true,
+        tooltips: 'Upload a PDF',
+        options: [],
+        placeholder: undefined,
+        unit: undefined,
+        allowed_file_upload_methods: [TransferMethod.local_file, TransferMethod.remote_url],
+        allowed_file_types: [SupportUploadFileTypes.document],
+        allowed_file_extensions: ['.pdf', '.docx'],
+      }
+
+      // Convert to form data
+      const formData = convertToInputFieldFormData(fileInputVar)
+      expect(formData.allowedFileUploadMethods).toEqual([TransferMethod.local_file, TransferMethod.remote_url])
+      expect(formData.allowedTypesAndExtensions).toEqual({
+        allowedFileTypes: [SupportUploadFileTypes.document],
+        allowedFileExtensions: ['.pdf', '.docx'],
+      })
+
+      // Round-trip back
+      const restored = convertFormDataToINputField(formData)
+      expect(restored.allowed_file_upload_methods).toEqual([TransferMethod.local_file, TransferMethod.remote_url])
+      expect(restored.allowed_file_types).toEqual([SupportUploadFileTypes.document])
+      expect(restored.allowed_file_extensions).toEqual(['.pdf', '.docx'])
+    })
+
+    it('should handle select field with options', async () => {
+      const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const selectVar: InputVar = {
+        type: PipelineInputVarType.select,
+        label: 'Priority',
+        variable: 'priority',
+        max_length: 0,
+        default_value: 'medium',
+        required: false,
+        tooltips: 'Select priority level',
+        options: ['low', 'medium', 'high'],
+        placeholder: 'Choose...',
+        unit: undefined,
+        allowed_file_upload_methods: undefined,
+        allowed_file_types: undefined,
+        allowed_file_extensions: undefined,
+      }
+
+      const formData = convertToInputFieldFormData(selectVar)
+      expect(formData.options).toEqual(['low', 'medium', 'high'])
+      expect(formData.default).toBe('medium')
+
+      const restored = convertFormDataToINputField(formData)
+      expect(restored.options).toEqual(['low', 'medium', 'high'])
+      expect(restored.default_value).toBe('medium')
+    })
+
+    it('should handle number field with unit', async () => {
+      const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const numberVar: InputVar = {
+        type: PipelineInputVarType.number,
+        label: 'Max Tokens',
+        variable: 'max_tokens',
+        max_length: 0,
+        default_value: '1024',
+        required: true,
+        tooltips: undefined,
+        options: [],
+        placeholder: undefined,
+        unit: 'tokens',
+        allowed_file_upload_methods: undefined,
+        allowed_file_types: undefined,
+        allowed_file_extensions: undefined,
+      }
+
+      const formData = convertToInputFieldFormData(numberVar)
+      expect(formData.unit).toBe('tokens')
+      expect(formData.default).toBe('1024')
+
+      const restored = convertFormDataToINputField(formData)
+      expect(restored.unit).toBe('tokens')
+      expect(restored.default_value).toBe('1024')
+    })
+  })
+
+  describe('Omit optional fields', () => {
+    it('should not include tooltips when undefined', async () => {
+      const { convertToInputFieldFormData } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const inputVar: InputVar = {
+        type: PipelineInputVarType.textInput,
+        label: 'Test',
+        variable: 'test',
+        max_length: 48,
+        default_value: undefined,
+        required: true,
+        tooltips: undefined,
+        options: [],
+        placeholder: undefined,
+        unit: undefined,
+        allowed_file_upload_methods: undefined,
+        allowed_file_types: undefined,
+        allowed_file_extensions: undefined,
+      }
+
+      const formData = convertToInputFieldFormData(inputVar)
+
+      // Optional fields should not be present
+      expect('tooltips' in formData).toBe(false)
+      expect('placeholder' in formData).toBe(false)
+      expect('unit' in formData).toBe(false)
+      expect('default' in formData).toBe(false)
+    })
+
+    it('should include optional fields when explicitly set to empty string', async () => {
+      const { convertToInputFieldFormData } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const inputVar: InputVar = {
+        type: PipelineInputVarType.textInput,
+        label: 'Test',
+        variable: 'test',
+        max_length: 48,
+        default_value: '',
+        required: true,
+        tooltips: '',
+        options: [],
+        placeholder: '',
+        unit: '',
+        allowed_file_upload_methods: undefined,
+        allowed_file_types: undefined,
+        allowed_file_extensions: undefined,
+      }
+
+      const formData = convertToInputFieldFormData(inputVar)
+
+      expect(formData.default).toBe('')
+      expect(formData.tooltips).toBe('')
+      expect(formData.placeholder).toBe('')
+      expect(formData.unit).toBe('')
+    })
+  })
+
+  describe('Multiple fields workflow', () => {
+    it('should process multiple fields independently', async () => {
+      const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+        '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+      )
+
+      const fields: InputVar[] = [
+        {
+          type: PipelineInputVarType.textInput,
+          label: 'Name',
+          variable: 'name',
+          max_length: 48,
+          default_value: 'Alice',
+          required: true,
+          tooltips: undefined,
+          options: [],
+          placeholder: undefined,
+          unit: undefined,
+          allowed_file_upload_methods: undefined,
+          allowed_file_types: undefined,
+          allowed_file_extensions: undefined,
+        },
+        {
+          type: PipelineInputVarType.number,
+          label: 'Count',
+          variable: 'count',
+          max_length: 0,
+          default_value: '10',
+          required: false,
+          tooltips: undefined,
+          options: [],
+          placeholder: undefined,
+          unit: 'items',
+          allowed_file_upload_methods: undefined,
+          allowed_file_types: undefined,
+          allowed_file_extensions: undefined,
+        },
+      ]
+
+      const formDataList = fields.map(f => convertToInputFieldFormData(f))
+      const restoredFields = formDataList.map(fd => convertFormDataToINputField(fd))
+
+      expect(restoredFields).toHaveLength(2)
+      expect(restoredFields[0].variable).toBe('name')
+      expect(restoredFields[0].default_value).toBe('Alice')
+      expect(restoredFields[1].variable).toBe('count')
+      expect(restoredFields[1].default_value).toBe('10')
+      expect(restoredFields[1].unit).toBe('items')
+    })
+  })
+})

web/__tests__/rag-pipeline/input-field-editor-flow.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Integration test: Input field editor data conversion flow
+ *
+ * Tests the full pipeline: InputVar -> FormData -> InputVar roundtrip
+ * and schema validation for various input types.
+ */
+import type { InputVar } from '@/models/pipeline'
+import { describe, expect, it, vi } from 'vitest'
+import { PipelineInputVarType } from '@/models/pipeline'
+
+// Mock the config module for VAR_ITEM_TEMPLATE_IN_PIPELINE
+vi.mock('@/config', () => ({
+  VAR_ITEM_TEMPLATE_IN_PIPELINE: {
+    type: 'text-input',
+    label: '',
+    variable: '',
+    max_length: 48,
+    required: false,
+    options: [],
+    allowed_file_upload_methods: [],
+    allowed_file_types: [],
+    allowed_file_extensions: [],
+  },
+  MAX_VAR_KEY_LENGTH: 30,
+  RAG_PIPELINE_PREVIEW_CHUNK_NUM: 10,
+}))
+
+// Import real functions (not mocked)
+const { convertToInputFieldFormData, convertFormDataToINputField } = await import(
+  '@/app/components/rag-pipeline/components/panel/input-field/editor/utils',
+)
+
+describe('Input Field Editor Data Flow', () => {
+  describe('convertToInputFieldFormData', () => {
+    it('should convert a text input InputVar to FormData', () => {
+      const inputVar: InputVar = {
+        type: 'text-input',
+        label: 'Name',
+        variable: 'user_name',
+        max_length: 100,
+        required: true,
+        default_value: 'John',
+        tooltips: 'Enter your name',
+        placeholder: 'Type here...',
+        options: [],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(inputVar)
+
+      expect(formData.type).toBe('text-input')
+      expect(formData.label).toBe('Name')
+      expect(formData.variable).toBe('user_name')
+      expect(formData.maxLength).toBe(100)
+      expect(formData.required).toBe(true)
+      expect(formData.default).toBe('John')
+      expect(formData.tooltips).toBe('Enter your name')
+      expect(formData.placeholder).toBe('Type here...')
+    })
+
+    it('should handle file input with upload settings', () => {
+      const inputVar: InputVar = {
+        type: 'file',
+        label: 'Document',
+        variable: 'doc',
+        required: false,
+        allowed_file_upload_methods: ['local_file', 'remote_url'],
+        allowed_file_types: ['document', 'image'],
+        allowed_file_extensions: ['.pdf', '.jpg'],
+        options: [],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(inputVar)
+
+      expect(formData.allowedFileUploadMethods).toEqual(['local_file', 'remote_url'])
+      expect(formData.allowedTypesAndExtensions).toEqual({
+        allowedFileTypes: ['document', 'image'],
+        allowedFileExtensions: ['.pdf', '.jpg'],
+      })
+    })
+
+    it('should use template defaults when no data provided', () => {
+      const formData = convertToInputFieldFormData(undefined)
+
+      expect(formData.type).toBe('text-input')
+      expect(formData.maxLength).toBe(48)
+      expect(formData.required).toBe(false)
+    })
+
+    it('should omit undefined/null optional fields', () => {
+      const inputVar: InputVar = {
+        type: 'text-input',
+        label: 'Simple',
+        variable: 'simple_var',
+        max_length: 50,
+        required: false,
+        options: [],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(inputVar)
+
+      expect(formData.default).toBeUndefined()
+      expect(formData.tooltips).toBeUndefined()
+      expect(formData.placeholder).toBeUndefined()
+      expect(formData.unit).toBeUndefined()
+    })
+  })
+
+  describe('convertFormDataToINputField', () => {
+    it('should convert FormData back to InputVar', () => {
+      const formData = {
+        type: PipelineInputVarType.textInput,
+        label: 'Name',
+        variable: 'user_name',
+        maxLength: 100,
+        required: true,
+        default: 'John',
+        tooltips: 'Enter your name',
+        options: [],
+        placeholder: 'Type here...',
+        allowedTypesAndExtensions: {
+          allowedFileTypes: undefined,
+          allowedFileExtensions: undefined,
+        },
+      }
+
+      const inputVar = convertFormDataToINputField(formData)
+
+      expect(inputVar.type).toBe('text-input')
+      expect(inputVar.label).toBe('Name')
+      expect(inputVar.variable).toBe('user_name')
+      expect(inputVar.max_length).toBe(100)
+      expect(inputVar.required).toBe(true)
+      expect(inputVar.default_value).toBe('John')
+      expect(inputVar.tooltips).toBe('Enter your name')
+    })
+  })
+
+  describe('roundtrip conversion', () => {
+    it('should preserve text input data through roundtrip', () => {
+      const original: InputVar = {
+        type: 'text-input',
+        label: 'Question',
+        variable: 'question',
+        max_length: 200,
+        required: true,
+        default_value: 'What is AI?',
+        tooltips: 'Enter your question',
+        placeholder: 'Ask something...',
+        options: [],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(original)
+      const restored = convertFormDataToINputField(formData)
+
+      expect(restored.type).toBe(original.type)
+      expect(restored.label).toBe(original.label)
+      expect(restored.variable).toBe(original.variable)
+      expect(restored.max_length).toBe(original.max_length)
+      expect(restored.required).toBe(original.required)
+      expect(restored.default_value).toBe(original.default_value)
+      expect(restored.tooltips).toBe(original.tooltips)
+      expect(restored.placeholder).toBe(original.placeholder)
+    })
+
+    it('should preserve number input data through roundtrip', () => {
+      const original = {
+        type: 'number',
+        label: 'Temperature',
+        variable: 'temp',
+        required: false,
+        default_value: '0.7',
+        unit: '°C',
+        options: [],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(original)
+      const restored = convertFormDataToINputField(formData)
+
+      expect(restored.type).toBe('number')
+      expect(restored.unit).toBe('°C')
+      expect(restored.default_value).toBe('0.7')
+    })
+
+    it('should preserve select options through roundtrip', () => {
+      const original: InputVar = {
+        type: 'select',
+        label: 'Mode',
+        variable: 'mode',
+        required: true,
+        options: ['fast', 'balanced', 'quality'],
+      } as InputVar
+
+      const formData = convertToInputFieldFormData(original)
+      const restored = convertFormDataToINputField(formData)
+
+      expect(restored.options).toEqual(['fast', 'balanced', 'quality'])
+    })
+  })
+})

web/__tests__/rag-pipeline/test-run-flow.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Integration test: Test run end-to-end flow
+ *
+ * Validates the data flow through test-run preparation hooks:
+ * step navigation, datasource filtering, and data clearing.
+ */
+import { act, renderHook } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { BlockEnum } from '@/app/components/workflow/types'
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}))
+
+// Mutable holder so mock data can reference BlockEnum after imports
+const mockNodesHolder = vi.hoisted(() => ({ value: [] as Record<string, unknown>[] }))
+
+vi.mock('reactflow', () => ({
+  useNodes: () => mockNodesHolder.value,
+}))
+
+mockNodesHolder.value = [
+  {
+    id: 'ds-1',
+    data: {
+      type: BlockEnum.DataSource,
+      title: 'Local Files',
+      datasource_type: 'upload_file',
+      datasource_configurations: { datasource_label: 'Upload', upload_file_config: {} },
+    },
+  },
+  {
+    id: 'ds-2',
+    data: {
+      type: BlockEnum.DataSource,
+      title: 'Web Crawl',
+      datasource_type: 'website_crawl',
+      datasource_configurations: { datasource_label: 'Crawl' },
+    },
+  },
+  {
+    id: 'kb-1',
+    data: {
+      type: BlockEnum.KnowledgeBase,
+      title: 'Knowledge Base',
+    },
+  },
+]
+
+// Mock the Zustand store used by the hooks
+const mockSetDocumentsData = vi.fn()
+const mockSetSearchValue = vi.fn()
+const mockSetSelectedPagesId = vi.fn()
+const mockSetOnlineDocuments = vi.fn()
+const mockSetCurrentDocument = vi.fn()
+const mockSetStep = vi.fn()
+const mockSetCrawlResult = vi.fn()
+const mockSetWebsitePages = vi.fn()
+const mockSetPreviewIndex = vi.fn()
+const mockSetCurrentWebsite = vi.fn()
+const mockSetOnlineDriveFileList = vi.fn()
+const mockSetBucket = vi.fn()
+const mockSetPrefix = vi.fn()
+const mockSetKeywords = vi.fn()
+const mockSetSelectedFileIds = vi.fn()
+
+vi.mock('@/app/components/datasets/documents/create-from-pipeline/data-source/store', () => ({
+  useDataSourceStore: () => ({
+    getState: () => ({
+      setDocumentsData: mockSetDocumentsData,
+      setSearchValue: mockSetSearchValue,
+      setSelectedPagesId: mockSetSelectedPagesId,
+      setOnlineDocuments: mockSetOnlineDocuments,
+      setCurrentDocument: mockSetCurrentDocument,
+      setStep: mockSetStep,
+      setCrawlResult: mockSetCrawlResult,
+      setWebsitePages: mockSetWebsitePages,
+      setPreviewIndex: mockSetPreviewIndex,
+      setCurrentWebsite: mockSetCurrentWebsite,
+      setOnlineDriveFileList: mockSetOnlineDriveFileList,
+      setBucket: mockSetBucket,
+      setPrefix: mockSetPrefix,
+      setKeywords: mockSetKeywords,
+      setSelectedFileIds: mockSetSelectedFileIds,
+    }),
+  }),
+}))
+
+vi.mock('@/models/datasets', () => ({
+  CrawlStep: {
+    init: 'init',
+  },
+}))
+
+describe('Test Run Flow Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Step Navigation', () => {
+    it('should start at step 1 and navigate forward', async () => {
+      const { useTestRunSteps } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useTestRunSteps())
+
+      expect(result.current.currentStep).toBe(1)
+
+      act(() => {
+        result.current.handleNextStep()
+      })
+
+      expect(result.current.currentStep).toBe(2)
+    })
+
+    it('should navigate back from step 2 to step 1', async () => {
+      const { useTestRunSteps } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useTestRunSteps())
+
+      act(() => {
+        result.current.handleNextStep()
+      })
+      expect(result.current.currentStep).toBe(2)
+
+      act(() => {
+        result.current.handleBackStep()
+      })
+      expect(result.current.currentStep).toBe(1)
+    })
+
+    it('should provide labeled steps', async () => {
+      const { useTestRunSteps } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useTestRunSteps())
+
+      expect(result.current.steps).toHaveLength(2)
+      expect(result.current.steps[0].value).toBe('dataSource')
+      expect(result.current.steps[1].value).toBe('documentProcessing')
+    })
+  })
+
+  describe('Datasource Options', () => {
+    it('should filter nodes to only DataSource type', async () => {
+      const { useDatasourceOptions } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useDatasourceOptions())
+
+      // Should only include DataSource nodes, not KnowledgeBase
+      expect(result.current).toHaveLength(2)
+      expect(result.current[0].value).toBe('ds-1')
+      expect(result.current[1].value).toBe('ds-2')
+    })
+
+    it('should include node data in options', async () => {
+      const { useDatasourceOptions } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useDatasourceOptions())
+
+      expect(result.current[0].label).toBe('Local Files')
+      expect(result.current[0].data.type).toBe(BlockEnum.DataSource)
+    })
+  })
+
+  describe('Data Clearing Flow', () => {
+    it('should clear online document data', async () => {
+      const { useOnlineDocument } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useOnlineDocument())
+
+      act(() => {
+        result.current.clearOnlineDocumentData()
+      })
+
+      expect(mockSetDocumentsData).toHaveBeenCalledWith([])
+      expect(mockSetSearchValue).toHaveBeenCalledWith('')
+      expect(mockSetSelectedPagesId).toHaveBeenCalledWith(expect.any(Set))
+      expect(mockSetOnlineDocuments).toHaveBeenCalledWith([])
+      expect(mockSetCurrentDocument).toHaveBeenCalledWith(undefined)
+    })
+
+    it('should clear website crawl data', async () => {
+      const { useWebsiteCrawl } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useWebsiteCrawl())
+
+      act(() => {
+        result.current.clearWebsiteCrawlData()
+      })
+
+      expect(mockSetStep).toHaveBeenCalledWith('init')
+      expect(mockSetCrawlResult).toHaveBeenCalledWith(undefined)
+      expect(mockSetCurrentWebsite).toHaveBeenCalledWith(undefined)
+      expect(mockSetWebsitePages).toHaveBeenCalledWith([])
+      expect(mockSetPreviewIndex).toHaveBeenCalledWith(-1)
+    })
+
+    it('should clear online drive data', async () => {
+      const { useOnlineDrive } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useOnlineDrive())
+
+      act(() => {
+        result.current.clearOnlineDriveData()
+      })
+
+      expect(mockSetOnlineDriveFileList).toHaveBeenCalledWith([])
+      expect(mockSetBucket).toHaveBeenCalledWith('')
+      expect(mockSetPrefix).toHaveBeenCalledWith([])
+      expect(mockSetKeywords).toHaveBeenCalledWith('')
+      expect(mockSetSelectedFileIds).toHaveBeenCalledWith([])
+    })
+  })
+
+  describe('Full Flow Simulation', () => {
+    it('should support complete step navigation cycle', async () => {
+      const { useTestRunSteps } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result } = renderHook(() => useTestRunSteps())
+
+      // Start at step 1
+      expect(result.current.currentStep).toBe(1)
+
+      // Move to step 2
+      act(() => {
+        result.current.handleNextStep()
+      })
+      expect(result.current.currentStep).toBe(2)
+
+      // Go back to step 1
+      act(() => {
+        result.current.handleBackStep()
+      })
+      expect(result.current.currentStep).toBe(1)
+
+      // Move forward again
+      act(() => {
+        result.current.handleNextStep()
+      })
+      expect(result.current.currentStep).toBe(2)
+    })
+
+    it('should not regress when clearing all data sources in sequence', async () => {
+      const {
+        useOnlineDocument,
+        useWebsiteCrawl,
+        useOnlineDrive,
+      } = await import(
+        '@/app/components/rag-pipeline/components/panel/test-run/preparation/hooks',
+      )
+      const { result: docResult } = renderHook(() => useOnlineDocument())
+      const { result: crawlResult } = renderHook(() => useWebsiteCrawl())
+      const { result: driveResult } = renderHook(() => useOnlineDrive())
+
+      // Clear all data sources
+      act(() => {
+        docResult.current.clearOnlineDocumentData()
+        crawlResult.current.clearWebsiteCrawlData()
+        driveResult.current.clearOnlineDriveData()
+      })
+
+      expect(mockSetDocumentsData).toHaveBeenCalledWith([])
+      expect(mockSetStep).toHaveBeenCalledWith('init')
+      expect(mockSetOnlineDriveFileList).toHaveBeenCalledWith([])
+    })
+  })
+})