CloudSearch/cloudsearch_transfer/adapter/quark/__init__.py

"""
CloudSearch Transfer — 夸克网盘适配器 v1.0.0

将 QuarkCredentialManager、QuarkTransfer、QuarkCleanup 组合为
BaseCloudDriveAdapter 的完整实现。

夸克网盘 7 步 API 转存流程：
 ① POST .../share/sharepage/token  → stoken
 ② GET  .../share/sharepage/detail → fid, share_fid_token, title
 ③ POST .../share/sharepage/save   → task_id (转存)
 ④ 轮询 GET .../task               → save_as_top_fids
 ⑤ POST .../share                  → task_id (创建分享)
 ⑥ 轮询 GET .../task               → share_id
 ⑦ POST .../share/password         → share_url, passcode

参考 cloud-auto-save 的 quark 实现 + netdisk 的 Pan 接口约定。
"""

from __future__ import annotations

import logging
import time
from typing import Any, Dict, List, Optional, Tuple

from ..base import BaseCloudDriveAdapter, FileInfo, TransferResult, VerifyResult
from ...config import PlatformConfig, TransferConfig
from ...errors import TransferError, TransferErrorCode

from .credential import QuarkCredentialManager
from .transfer import QuarkTransfer, SHARE_URL_PATTERN
from .cleanup import QuarkCleanup

logger = logging.getLogger(__name__)


class QuarkAdapter(BaseCloudDriveAdapter):
    """夸克网盘适配器。

    组合 credential / transfer / cleanup 三个模块，
    实现 BaseCloudDriveAdapter 定义的所有抽象方法。

    Attributes:
        PLATFORM_NAME: 展示用平台名称。
        PLATFORM_KEY: 内部平台标识。
        URL_PATTERNS: 夸克分享链接匹配正则列表。
    """

    # ─── 平台标识 ──────────────────────────────────────────────
    PLATFORM_NAME: str = "夸克网盘"
    PLATFORM_KEY: str = "quark"

    # ─── URL 匹配 ──────────────────────────────────────────────
    # 支持 pan.quark.cn/s/<share_id>
    URL_PATTERNS: List[str] = [
        r"pan\.quark\.cn/s/(\w+)",
    ]


    capabilities: Dict[str, bool] = {
        "ensure_dir": True,
        "save_files": True,
        "poll_task": True,
        "rename": True,
        "move_files": True,
        "delete_files": True,
        "cleanup_recycle": True,
        "share_staging_folder": False,
    }

    def __init__(self, config: PlatformConfig, transfer_config: TransferConfig) -> None:
        """初始化适配器。"""
        self._credential: QuarkCredentialManager = QuarkCredentialManager(cookie=config.cookie)
        self._transfer_engine: QuarkTransfer = QuarkTransfer(
            credential=self._credential,
            timeout=transfer_config.request_timeout,
            poll_interval=transfer_config.task_poll_interval,
            poll_max_attempts=transfer_config.task_poll_max_attempts,
        )
        self._cleanup: QuarkCleanup = QuarkCleanup(
            credential=self._credential,
            timeout=transfer_config.request_timeout,
        )
        super().__init__(config, transfer_config)

    # ═══════════════════════════════════════════════════════════════
    # 公开接口实现
    # ═══════════════════════════════════════════════════════════════

    def _setup_session(self) -> None:
        """将夸克 Cookie 注入 session 的默认 headers。"""
        headers = self._credential.get_headers()
        if headers:
            self.session.headers.update(headers)
            logger.debug("[QuarkAdapter] Session headers updated with Cookie")

    # ─── transfer() 使用基类模板，子类实现 _transfer ──────────

    def _transfer(self, share_url: str, save_dir: str = "",
                  share_password: str = "") -> TransferResult:
        """执行转存的核心逻辑（被基类 transfer() 调用）。

        通过 QuarkTransfer 引擎执行完整的 7 步流程。

        Args:
            share_url: 夸克分享链接。
            save_dir: 目标目录，空则使用配置的默认目录。
            share_password: 新分享的密码。

        Returns:
            TransferResult 包含转存结果。
        """
        start: float = time.time()

        # 凭证检查
        if not self._credential.validate():
            raise TransferError(
                TransferErrorCode.NOT_LOGIN,
                message="夸克 Cookie 无效或长度不足",
                platform=self.PLATFORM_KEY,
            )

        # 目标目录：支持 fid 或路径；路径会先创建/解析为 fid。
        requested_dir: str = save_dir or self.config.save_dir or "/"
        target_dir: str = requested_dir if requested_dir and not str(requested_dir).startswith("/") else self.ensure_dir(requested_dir)

        # 分享密码
        pwd: str = share_password or self.config.share_password or ""

        try:
            result: Dict[str, Any] = self._transfer_engine.transfer(
                share_url=share_url,
                save_dir=target_dir,
                share_password=pwd,
            )
        except ValueError as exc:
            raise TransferError(
                TransferErrorCode.URL_INVALID,
                message=str(exc),
                platform=self.PLATFORM_KEY,
            ) from exc
        except RuntimeError as exc:
            msg: str = str(exc)
            if "stoken" in msg or "status" in msg:
                raise TransferError(
                    TransferErrorCode.SHARE_NOT_EXIST,
                    message=msg,
                    platform=self.PLATFORM_KEY,
                ) from exc
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=msg,
                platform=self.PLATFORM_KEY,
            ) from exc

        elapsed: int = int((time.time() - start) * 1000)

        # 广告过滤：在转存完成后对 new_file_ids 进行过滤
        new_fids: List[str] = result.get("new_file_ids", [])
        if self.transfer_config.ad_filter_enabled and new_fids:
            new_fids = self._filter_ads(new_fids)
            if not new_fids:
                raise TransferError(
                    TransferErrorCode.RESOURCE_EMPTY,
                    platform=self.PLATFORM_KEY,
                )

        return TransferResult(
            success=True,
            platform=self.PLATFORM_KEY,
            new_file_id=",".join(new_fids),
            file_name=result.get("file_name", ""),
            share_url=result.get("share_url", ""),
            share_password=result.get("passcode", pwd),
            original_url=share_url,
            elapsed_ms=elapsed,
        )

    # ─── verify() 使用基类模板，子类实现 _verify ───────────────

    def _verify(self, share_url: str) -> VerifyResult:
        """验证夸克分享链接有效性。

        通过获取 stoken → 获取详情来验证链接。

        Args:
            share_url: 夸克分享链接。

        Returns:
            VerifyResult 包含验证结果。
        """
        try:
            pwd_id, passcode = self._parse_share_url(share_url)

            if not self._credential.validate():
                return VerifyResult(
                    valid=False,
                    platform=self.PLATFORM_KEY,
                    error=TransferError(
                        TransferErrorCode.NOT_LOGIN,
                        platform=self.PLATFORM_KEY,
                    ),
                )

            stoken: str = self._transfer_engine._get_stoken(pwd_id, passcode)
            detail: Dict[str, Any] = self._transfer_engine._get_detail(pwd_id, stoken)
            files: List[FileInfo] = self._extract_file_list(detail)

            return VerifyResult(
                valid=True,
                platform=self.PLATFORM_KEY,
                title=detail.get("title", ""),
                file_count=len(files),
                files=files,
            )

        except TransferError:
            raise
        except (ValueError, RuntimeError) as exc:
            return VerifyResult(
                valid=False,
                platform=self.PLATFORM_KEY,
                error=TransferError(
                    TransferErrorCode.SHARE_NOT_EXIST,
                    message=str(exc),
                    platform=self.PLATFORM_KEY,
                ),
            )
        except Exception as exc:
            return VerifyResult(
                valid=False,
                platform=self.PLATFORM_KEY,
                error=TransferError(
                    TransferErrorCode.NETWORK_ERROR,
                    message=str(exc),
                    platform=self.PLATFORM_KEY,
                ),
            )

    # ─── 核心抽象方法 ─────────────────────────────────────────

    def _get_share_detail(self, pwd_id: str, passcode: str = "") -> dict:
        """获取夸克分享详情（基类 transfer() 流程中的步骤②）。

        Args:
            pwd_id: 分享 ID。
            passcode: 提取码。

        Returns:
            分享详情字典，包含 title, fid, share_fid_token 等字段。
        """
        stoken: str = self._transfer_engine._get_stoken(pwd_id, passcode)
        return self._transfer_engine._get_detail(pwd_id, stoken)

    def _save_files(self, pwd_id: str, detail: dict, save_dir: str) -> List[str]:
        """转存文件到自己的夸克网盘（基类 transfer() 流程中的步骤③④）。

        save_dir 可传 fid 或路径；路径会先通过 ensure_dir 创建/解析为 fid。
        """
        # 需要 stoken，从 detail 间接获取（重新请求）
        stoken: str = self._transfer_engine._get_stoken(pwd_id)
        target_fid = save_dir if save_dir and not str(save_dir).startswith("/") else self.ensure_dir(save_dir or "/")
        task_id: str = self._transfer_engine._init_save(
            pwd_id, stoken, detail, to_pdir_fid=target_fid
        )
        return self._transfer_engine._poll_save_task(task_id)

    def _create_share(self, file_ids: List[str], title: str,
                      password: str = "") -> Tuple[str, str]:
        """创建夸克分享链接（基类 transfer() 流程中的步骤⑤⑥⑦）。

        Args:
            file_ids: 要分享的文件 ID 列表。
            title: 分享标题。
            password: 分享密码。

        Returns:
            (share_url, share_password) 元组。
        """
        task_id: str = self._transfer_engine._init_share(file_ids, title)
        share_id: str = self._transfer_engine._poll_share_task(task_id)
        return self._transfer_engine._set_password(share_id, password)

    def _extract_file_list(self, detail: dict) -> List[FileInfo]:
        """从夸克分享详情中提取文件列表。

        夸克的 sharepage/detail 返回格式：
        {
            "files": [
                {"fid": "...", "file_name": "...", "size": 123, "dir": false, ...},
            ]
        }

        Args:
            detail: 分享详情字典。

        Returns:
            FileInfo 对象列表。
        """
        files_data: List[Dict[str, Any]] = detail.get("files", [])
        result: List[FileInfo] = []

        for f in files_data:
            file_info = FileInfo(
                fid=str(f.get("fid", f.get("file_id", ""))),
                name=str(f.get("file_name", f.get("name", ""))),
                size=int(f.get("size", 0)),
                is_dir=bool(f.get("dir", f.get("is_dir", False))),
                ext=str(f.get("ext", f.get("file_extension", ""))),
            )
            result.append(file_info)

        # 如果 files 为空，尝试用 detail 顶层字段构造单个文件信息
        if not result and detail.get("fid"):
            result.append(FileInfo(
                fid=str(detail.get("fid", "")),
                name=str(detail.get("title", detail.get("file_name", ""))),
                size=0,
                is_dir=False,
            ))

        return result

    def _filter_ads(self, file_ids: List[str]) -> List[str]:
        """过滤广告文件。

        合并配置层和平台层的 banned_keywords，调用 QuarkCleanup 执行过滤。
        当前实现基于 file_ids 列表过滤（无文件名信息时保持原样）。

        Args:
            file_ids: 文件 ID 列表。

        Returns:
            过滤后的文件 ID 列表。
        """
        keywords: List[str] = list(
            set(self.config.banned_keywords)
            | set(self.transfer_config.default_banned_keywords)
        )
        if not keywords:
            return file_ids

        # 获取文件信息以进行名称匹配
        # 在基类 transfer() 流程中，此处 file_ids 已为转存后的新 IDs
        try:
            files: List[FileInfo] = self.get_files()
            file_names: List[str] = [f.name for f in files]
            return QuarkCleanup.filter_ad_ids(file_ids, file_names, keywords)
        except Exception:
            # 如果无法获取文件名列表，跳过广告过滤
            logger.warning("[QuarkAdapter] Cannot fetch file list for ad filtering, skipping")
            return file_ids


    # ─── Drive API capability helpers ─────────────────────────────

    @staticmethod
    def _normalize_dir_path(dir_path: str) -> str:
        path = "/" + str(dir_path or "").strip().strip("/")
        return "/" if path == "/" else path

    @staticmethod
    def _api_success(payload: Dict[str, Any]) -> bool:
        if not isinstance(payload, dict):
            return False
        code = payload.get("code")
        status = payload.get("status")
        return code == 0 or status in (0, 200)

    def ensure_dir(self, dir_path: str) -> str:
        normalized = self._normalize_dir_path(dir_path)
        if normalized == "/":
            return "0"

        parts = [part for part in normalized.strip("/").split("/") if part]
        prefixes = ["/" + "/".join(parts[:idx]) for idx in range(1, len(parts) + 1)]
        existing = {
            item.get("file_path"): str(item.get("fid"))
            for item in self.get_fids(prefixes)
            if item.get("file_path") and item.get("fid")
        }

        leaf_fid = existing.get(normalized)
        if leaf_fid:
            return leaf_fid

        for prefix in prefixes:
            if prefix in existing:
                continue
            result = self.mkdir(prefix)
            if self._api_success(result) and result.get("data", {}).get("fid"):
                existing[prefix] = str(result["data"]["fid"])
                continue
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=f"创建目录失败: {result.get('message', result)}",
                platform=self.PLATFORM_KEY,
            )
        return existing[normalized]

    def mkdir(self, dir_path: str) -> Dict[str, Any]:
        url = "https://drive-pc.quark.cn/1/clouddrive/file"
        params = {"pr": "ucpro", "fr": "pc", "uc_param_str": ""}
        payload = {
            "pdir_fid": "0",
            "file_name": "",
            "dir_path": self._normalize_dir_path(dir_path),
            "dir_init_lock": False,
        }
        return self._drive_api_json(self._post(url, json_data=payload, params=params, headers=self._credential.get_headers()), context="写入网盘目录")

    def rename(self, fid: str, file_name: str) -> Dict[str, Any]:
        url = "https://drive-pc.quark.cn/1/clouddrive/file/rename"
        params = {"pr": "ucpro", "fr": "pc", "uc_param_str": ""}
        payload = {"fid": fid, "file_name": file_name}
        return self._drive_api_json(self._post(url, json_data=payload, params=params, headers=self._credential.get_headers()), context="写入网盘目录")

    def get_fids(self, file_paths: List[str]) -> List[Dict[str, Any]]:
        pending = [self._normalize_dir_path(p) for p in file_paths]
        result: List[Dict[str, Any]] = []
        while pending:
            batch, pending = pending[:50], pending[50:]
            url = "https://drive-pc.quark.cn/1/clouddrive/file/info/path_list"
            params = {"pr": "ucpro", "fr": "pc"}
            payload = {"file_path": batch, "namespace": "0"}
            data = self._drive_api_json(self._post(url, json_data=payload, params=params, headers=self._credential.get_headers()), context="按路径获取文件ID")
            if not self._api_success(data):
                raise TransferError(
                    TransferErrorCode.NETWORK_ERROR,
                    message=f"获取目录ID失败: {data.get('message', data)}",
                    platform=self.PLATFORM_KEY,
                )
            result.extend(data.get("data", []))
        return result

    def move_files(self, fids: List[str], to_pdir_fid: str) -> Dict[str, Any]:
        if not fids:
            return {"code": 0, "message": "无文件需要移动"}
        last: Dict[str, Any] = {"code": 0, "message": "success"}
        for offset in range(0, len(fids), 100):
            batch = fids[offset:offset + 100]
            url = "https://drive-pc.quark.cn/1/clouddrive/file/move"
            params = {"uc_param_str": "", "fr": "pc", "pr": "ucpro"}
            payload = {"filelist": batch, "to_pdir_fid": to_pdir_fid, "exclude_fids": [], "action_type": 1}
            last = self._drive_api_json(self._post(url, json_data=payload, params=params, headers=self._credential.get_headers()), context="移动网盘文件")
            if not self._api_success(last):
                return last
            task_id = last.get("data", {}).get("task_id")
            if task_id:
                task = self.query_task(task_id)
                if not self._api_success(task) or task.get("data", {}).get("status") == -1:
                    return {"code": 1, "message": task.get("data", {}).get("message", task.get("message", "移动任务失败")), "data": task.get("data", {})}
        return {"code": 0, "message": "移动完成", "data": last.get("data", {})}

    def _task_query_params(self, retry_index: int = 0) -> Dict[str, Any]:
        now_ms = int(time.time() * 1000)
        return {
            "pr": "ucpro",
            "fr": "pc",
            "uc_param_str": "",
            "retry_index": retry_index,
            "__dt": 300,
            "__t": now_ms,
        }

    def delete_files(self, fids: List[str]) -> Dict[str, Any]:
        if not fids:
            return {"code": 0, "status": 200}
        if self.delete(fids):
            return {"code": 0, "status": 200}
        return {"code": 1, "status": 500, "message": "删除文件失败"}

    def query_task(self, task_id: str) -> Dict[str, Any]:
        url = "https://drive-pc.quark.cn/1/clouddrive/task"
        try:
            data = self._poll_task(url, task_id, query_params=self._task_query_params)
            return {"code": 0, "status": 200, "data": data}
        except TransferError as exc:
            return {"code": 1, "status": 500, "message": str(exc), "data": {"status": -1}}

    def recycle_list(self, page: int = 1, size: int = 30) -> List[Dict[str, Any]]:
        url = "https://drive-pc.quark.cn/1/clouddrive/file/recycle/list"
        params = {"_page": page, "_size": size, "pr": "ucpro", "fr": "pc", "uc_param_str": ""}
        data = self._drive_api_json(self._get(url, params=params, headers=self._credential.get_headers()), context="列出回收站")
        return data.get("data", {}).get("list", [])

    def recycle_remove(self, record_list: List[Dict[str, Any]]) -> Dict[str, Any]:
        url = "https://drive-pc.quark.cn/1/clouddrive/file/recycle/remove"
        params = {"uc_param_str": "", "fr": "pc", "pr": "ucpro"}
        payload = {"select_mode": 2, "record_list": record_list}
        return self._drive_api_json(self._post(url, json_data=payload, params=params, headers=self._credential.get_headers()), context="写入网盘目录")

    def cleanup_recycle(self, fids: List[str]) -> Dict[str, Any]:
        target_fids = {str(fid) for fid in fids if fid}
        if not target_fids:
            return {"code": 0, "message": "无回收站记录需要清理", "data": {"removed": 0}}
        records = [
            item for item in self.recycle_list()
            if str(item.get("fid") or item.get("file_id") or "") in target_fids
        ]
        if not records:
            return {"code": 0, "message": "未找到匹配的回收站记录", "data": {"removed": 0}}
        result = self.recycle_remove(records)
        if self._api_success(result):
            result.setdefault("data", {})["removed"] = len(records)
        return result

    # ─── get_files / delete ────────────────────────────────────

    def get_files(self, parent_fid: str = "0") -> List[FileInfo]:
        """列出夸克网盘指定目录下的文件。

        GET /1/clouddrive/file/sort?pdir_fid=<parent_fid>&_page=1&_size=100&_sort=updated_at:desc

        Args:
            parent_fid: 父目录 ID，默认 "0" 即根目录。

        Returns:
            FileInfo 列表。
        """
        url: str = "https://drive-pc.quark.cn/1/clouddrive/file/sort"
        params: Dict[str, str] = {
            "pdir_fid": parent_fid,
            "_page": "1",
            "_size": "100",
            "_sort": "updated_at:desc",
        }
        headers: Dict[str, str] = self._credential.get_headers()

        try:
            resp = self._get(url, params=params, headers=headers)
        except Exception as exc:
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=f"获取文件列表失败: {exc}",
                platform=self.PLATFORM_KEY,
            ) from exc

        data: Dict[str, Any] = resp.json()
        status: int = data.get("status", -1)
        if status != 0 and data.get("code") not in (0, None):
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=f"获取文件列表失败: {data.get('message')}",
                platform=self.PLATFORM_KEY,
            )

        files_data: List[Dict[str, Any]] = data.get("data", {}).get("list", [])
        result: List[FileInfo] = []
        for f in files_data:
            result.append(FileInfo(
                fid=str(f.get("fid", "")),
                name=str(f.get("file_name", f.get("name", ""))),
                size=int(f.get("size", 0)),
                is_dir=bool(f.get("dir", f.get("is_dir", False))),
                ext=str(f.get("file_extension", f.get("ext", ""))),
            ))

        logger.debug("[QuarkAdapter] Listed %d files in dir=%s", len(result), parent_fid)
        return result

    def delete(self, file_ids: List[str]) -> bool:
        """删除夸克网盘文件（移到回收站）。

        Args:
            file_ids: 要删除的文件 ID 列表。

        Returns:
            True 表示删除成功。
        """
        if not self._credential.validate():
            raise TransferError(
                TransferErrorCode.NOT_LOGIN,
                platform=self.PLATFORM_KEY,
            )

        try:
            return self._cleanup.delete_files(file_ids)
        except RuntimeError as exc:
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=str(exc),
                platform=self.PLATFORM_KEY,
            ) from exc

    def delete_permanent(self, file_ids: List[str]) -> bool:
        """彻底删除夸克网盘文件（不可恢复）。

        Args:
            file_ids: 要彻底删除的文件 ID 列表。

        Returns:
            True 表示删除成功。
        """
        if not self._credential.validate():
            raise TransferError(
                TransferErrorCode.NOT_LOGIN,
                platform=self.PLATFORM_KEY,
            )

        try:
            return self._cleanup.delete_files_permanent(file_ids)
        except RuntimeError as exc:
            raise TransferError(
                TransferErrorCode.NETWORK_ERROR,
                message=str(exc),
                platform=self.PLATFORM_KEY,
            ) from exc

    # ─── 工具方法 ─────────────────────────────────────────────

    def _parse_share_url(self, url: str) -> Tuple[str, str]:
        """解析夸克分享 URL 提取 (pwd_id, passcode)。

        夸克链接格式：https://pan.quark.cn/s/<pwd_id> 或带 ?pwd=xxxx

        Args:
            url: 夸克分享链接。

        Returns:
            (pwd_id, passcode) 元组。

        Raises:
            TransferError: URL 格式无法识别。
        """
        pwd_id: Optional[str] = QuarkTransfer.parse_share_url(url)
        if not pwd_id:
            raise TransferError(
                TransferErrorCode.URL_INVALID,
                message=f"无法解析夸克链接: {url}",
                platform=self.PLATFORM_KEY,
            )

        # 提取密码参数
        from urllib.parse import urlparse, parse_qs
        parsed = urlparse(url)
        params = parse_qs(parsed.query)
        passcode: str = params.get("pwd", params.get("code", [""]))[0]

        return pwd_id, passcode

    def update_cookie(self, cookie: str) -> None:
        """动态更新 Cookie 并同步到 session headers。

        Args:
            cookie: 新的 Cookie 字符串。
        """
        self._credential.update_cookie(cookie)
        self._setup_session()
        logger.info("[QuarkAdapter] Cookie updated, new length=%d", len(cookie))

    def close(self) -> None:
        """关闭所有子模块的 HTTP 会话。"""
        self._transfer_engine.close()
        self._cleanup.close()
        self.session.close()

    def __repr__(self) -> str:
        return (
            f"QuarkAdapter(name={self.PLATFORM_NAME}, "
            f"account={self.config.account_name}, "
            f"credential_valid={self._credential.validate()})"
        )