ForcePilot/backend/server/routers/external_systems/trash_router.py

"""Trash 子域 Router。

外部系统限界上下文的回收站管理 API，覆盖回收站列表查询 / 恢复软删除资源 /
物理删除 / 清理过期回收站。所有端点通过 ``create_use_cases_from_db`` 装配
use_cases，经 ``trash_service`` 端口调用用例。

鉴权分层（与前端权限保持一致）：
- 查询（``list_trash``）与恢复（``restore``）使用 ``get_admin_user``（admin + superadmin）
- 物理删除（``hard_delete``）与清理（``purge``）使用 ``get_superadmin_user``（仅 superadmin），
  因物理删除不可恢复，前端同样仅对 superadmin 开放物理删除按钮

Request Schema 与 Input DTO 不共享类，Router 内显式构造 DTO，操作者字段
（``restored_by`` / ``deleted_by`` / ``purged_by``）由 ``current_user.uid`` 填充。
Router 内不 try/except 领域异常，由全局异常处理器统一处理。

路径顺序（关键，来自 FastAPI 路由匹配规则）：静态路径端点（``GET ""`` /
``POST "/purge"``）必须在动态路径端点（``POST "/{resource_type}/{resource_id}/restore"``
/ ``DELETE "/{resource_type}/{resource_id}"``）之前声明。

``ResourceType`` 枚举值与 ``TrashService._RESOURCE_REPO_MAP`` 的 key 对齐，
在边界层拦截非法资源类型（FastAPI 自动返回 422），同时在 OpenAPI 文档中
暴露支持的资源类型列表。
"""

from __future__ import annotations

from enum import StrEnum
from typing import Any

from fastapi import APIRouter, Depends, Path, Query
from pydantic import BaseModel, ConfigDict, Field
from yuxi.external_systems.infrastructure.container import UseCases
from yuxi.external_systems.use_cases.dto.trash import (
    BatchHardDeleteInput,
    BatchItemInput,
    BatchRestoreInput,
    HardDeleteInput,
    ListTrashInput,
    PurgeTrashInput,
    RestoreInput,
)
from yuxi.storage.postgres.models_business import User

from server.routers.external_systems import get_use_cases, parse_and_naive, validate_time_range
from server.utils.auth_middleware import get_admin_user, get_superadmin_user

trash_router = APIRouter(
    prefix="/trash",
    tags=["external-systems-trash"],
)


# ---------------- 边界层校验枚举（与 TrashService._RESOURCE_REPO_MAP 对齐） ----------------


class ResourceType(StrEnum):
    """回收站支持的资源类型。

    值与 ``TrashService._RESOURCE_REPO_MAP`` 的 key 一一对应，
    新增资源类型时需同步更新此处与 service 层映射。
    """

    SYSTEM = "system"
    ENVIRONMENT = "environment"
    TOOL = "tool"
    TOKEN = "token"
    ASSET = "asset"
    WEBHOOK_SUBSCRIPTION = "webhook_subscription"
    QUOTA = "quota"
    NOTIFICATION_CHANNEL = "notification_channel"
    SECRET_ROTATION_POLICY = "secret_rotation_policy"
    ACCESS_RULE = "access_rule"
    TEST_CASE = "test_case"


# ---------------- Request Schemas ----------------


class PurgeTrashRequest(BaseModel):
    """清理过期回收站请求体。字段对齐 ``PurgeTrashInput``。"""

    model_config = ConfigDict(frozen=True)

    older_than_days: int = Field(default=30, ge=1)


class BatchItemRequest(BaseModel):
    """批量操作的单条资源项请求体。"""

    model_config = ConfigDict(frozen=True)

    resource_type: ResourceType
    resource_id: int = Field(ge=1)


class BatchOperationRequest(BaseModel):
    """批量操作请求体。字段对齐 ``BatchRestoreInput`` / ``BatchHardDeleteInput``。"""

    model_config = ConfigDict(frozen=True)

    items: list[BatchItemRequest] = Field(min_length=1, max_length=100)


# ---------------- Endpoints ----------------


@trash_router.get("", response_model=dict)
async def list_trash(
    resource_type: ResourceType | None = Query(None, description="资源类型过滤；不传时返回各类型计数摘要"),
    limit: int = Query(50, ge=1, le=200),
    offset: int = Query(0, ge=0),
    start_time: str | None = Query(
        None, description="仅明细模式生效（需传 resource_type），按 deleted_at 过滤下界（ISO 8601）"
    ),
    end_time: str | None = Query(
        None, description="仅明细模式生效（需传 resource_type），按 deleted_at 过滤上界（ISO 8601）"
    ),
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """查询回收站列表。

    - 不传 ``resource_type``：返回各类型计数摘要（``by_type``），``items`` 为空
    - 传 ``resource_type``：返回指定类型的软删除记录明细，``start_time``/``end_time`` 生效
    """
    start_dt = parse_and_naive("start_time", start_time)
    end_dt = parse_and_naive("end_time", end_time)
    validate_time_range(start_dt, end_dt)
    input_dto = ListTrashInput(
        resource_type=resource_type.value if resource_type is not None else None,
        limit=limit,
        offset=offset,
        start_time=start_dt,
        end_time=end_dt,
    )
    output = await use_cases.trash_service.list_trash(input_dto)
    return {"success": True, "data": output.model_dump()}


@trash_router.post("/purge", response_model=dict)
async def purge_trash(
    payload: PurgeTrashRequest,
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_superadmin_user),
) -> dict[str, Any]:
    """清理过期回收站（物理删除超过保留期的软删除资源）。

    ``purged_by`` 由当前管理员填充。物理删除不可恢复，仅 superadmin 可执行。
    """
    input_dto = PurgeTrashInput(
        older_than_days=payload.older_than_days,
        purged_by=current_user.uid,
    )
    output = await use_cases.trash_service.purge(input_dto)
    return {"success": True, "data": output.model_dump()}


@trash_router.post("/batch/restore", response_model=dict)
async def batch_restore_resources(
    payload: BatchOperationRequest,
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """批量恢复软删除资源。

    每条独立事务，已知领域异常记录为失败项，未预期异常冒泡。
    ``restored_by`` 由当前管理员填充。
    """
    input_dto = BatchRestoreInput(
        items=[
            BatchItemInput(resource_type=item.resource_type.value, resource_id=item.resource_id)
            for item in payload.items
        ],
        restored_by=current_user.uid,
    )
    output = await use_cases.trash_service.batch_restore(input_dto)
    return {"success": True, "data": output.model_dump()}


@trash_router.post("/batch/hard-delete", response_model=dict)
async def batch_hard_delete_resources(
    payload: BatchOperationRequest,
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_superadmin_user),
) -> dict[str, Any]:
    """批量物理删除资源（不可恢复，仅 superadmin）。

    每条独立事务，已知领域异常记录为失败项，未预期异常冒泡。
    ``deleted_by`` 由当前管理员填充。
    """
    input_dto = BatchHardDeleteInput(
        items=[
            BatchItemInput(resource_type=item.resource_type.value, resource_id=item.resource_id)
            for item in payload.items
        ],
        deleted_by=current_user.uid,
    )
    output = await use_cases.trash_service.batch_hard_delete(input_dto)
    return {"success": True, "data": output.model_dump()}


@trash_router.post("/{resource_type}/{resource_id}/restore", response_model=dict)
async def restore_resource(
    resource_type: ResourceType,
    resource_id: int = Path(..., ge=1),
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """恢复软删除资源。

    ``restored_by`` 由当前管理员填充。
    """
    input_dto = RestoreInput(
        resource_type=resource_type.value,
        resource_id=resource_id,
        restored_by=current_user.uid,
    )
    output = await use_cases.trash_service.restore(input_dto)
    return {"success": True, "data": output.model_dump()}


@trash_router.delete("/{resource_type}/{resource_id}", response_model=dict)
async def hard_delete_resource(
    resource_type: ResourceType,
    resource_id: int = Path(..., ge=1),
    use_cases: UseCases = Depends(get_use_cases),
    current_user: User = Depends(get_superadmin_user),
) -> dict[str, Any]:
    """物理删除回收站中的资源（不可恢复）。

    ``deleted_by`` 由当前管理员填充。物理删除不可恢复，仅 superadmin 可执行。
    """
    input_dto = HardDeleteInput(
        resource_type=resource_type.value,
        resource_id=resource_id,
        deleted_by=current_user.uid,
    )
    output = await use_cases.trash_service.hard_delete(input_dto)
    return {"success": True, "data": output.model_dump()}