document-management/backend/tests/dms/test_openapi_storage.py

from __future__ import annotations

from pathlib import Path
import re

import pytest
import yaml

from dms.storage.paths import (
    STORAGE_SUBDIRECTORIES,
    UnsafeStoragePathError,
    ensure_storage_directories,
    resolve_storage_path,
)


BACKEND_ROOT = Path(__file__).resolve().parents[2]
OPENAPI_ROOT = BACKEND_ROOT / "openapi"


def test_all_openapi_yaml_files_parse():
    for path in OPENAPI_ROOT.rglob("*.yaml"):
        with path.open("r", encoding="utf-8") as stream:
            assert isinstance(yaml.safe_load(stream), dict)


def test_all_openapi_external_refs_resolve():
    def walk(value, source_path: Path):
        if isinstance(value, dict):
            reference = value.get("$ref")
            if isinstance(reference, str) and not reference.startswith("#"):
                target, _, fragment = reference.partition("#")
                target_path = (source_path.parent / target).resolve()
                assert target_path.is_file(), reference
                target_document = yaml.safe_load(
                    target_path.read_text(encoding="utf-8")
                )
                current = target_document
                if fragment:
                    for part in fragment.lstrip("/").split("/"):
                        assert part in current, reference
                        current = current[part]
            for child in value.values():
                walk(child, source_path)
        elif isinstance(value, list):
            for child in value:
                walk(child, source_path)

    for path in OPENAPI_ROOT.rglob("*.yaml"):
        walk(yaml.safe_load(path.read_text(encoding="utf-8")), path)


def test_flask_methods_match_openapi_exactly(flask_app):
    document = yaml.safe_load(
        (OPENAPI_ROOT / "openapi.yaml").read_text(encoding="utf-8")
    )
    # 契约1.25：proxy-verify 仅Java版实现（Python版请求返回404、前端静默回落），不计入Flask路由精确对齐
    java_only_paths = {"/api/v1/auth/portal/proxy-verify"}
    openapi_methods = set()
    operation_ids = []
    for path, item in document["paths"].items():
        if path in java_only_paths:
            continue
        if "$ref" in item:
            target, _, fragment = item["$ref"].partition("#")
            referenced = yaml.safe_load(
                (OPENAPI_ROOT / target).read_text(encoding="utf-8")
            )
            item = referenced[fragment.lstrip("/")]
        for method, operation in item.items():
            if method.lower() in {"get", "post", "put", "delete", "patch"}:
                openapi_methods.add((method.upper(), path))
                operation_ids.append(operation["operationId"])
    flask_methods = set()
    for rule in flask_app.url_map.iter_rules():
        if not rule.rule.startswith("/api/v1"):
            continue
        path = re.sub(r"<(?:[^:>]+:)?([^>]+)>", r"{\1}", rule.rule)
        for method in rule.methods - {"HEAD", "OPTIONS"}:
            flask_methods.add((method, path))
    assert flask_methods == openapi_methods
    assert len(operation_ids) == len(set(operation_ids))


def test_openapi_contains_only_q2b_paths():
    document = yaml.safe_load(
        (OPENAPI_ROOT / "openapi.yaml").read_text(encoding="utf-8")
    )
    assert set(document["paths"]) == {
        "/api/v1/health",
        "/api/v1/auth/captcha",
        "/api/v1/auth/login",
        "/api/v1/auth/logout",
        "/api/v1/auth/reauth",
        "/api/v1/auth/portal/verify",
        "/api/v1/auth/portal/proxy-verify",
        "/api/v1/auth/portal/setup-password",
        "/api/v1/users/me",
        "/api/v1/users/me/ui-theme",
        "/api/v1/organizations/tree",
        "/api/v1/organizations",
        "/api/v1/organizations/{id}",
        "/api/v1/organizations/{id}/ip-assignments",
        "/api/v1/organizations/reorder",
        "/api/v1/ip-entries",
        "/api/v1/ip-entries/{id}",
        "/api/v1/users",
        "/api/v1/users/{id}",
        "/api/v1/users/{id}/reset-password",
        "/api/v1/users/reorder",
        "/api/v1/roles",
        "/api/v1/roles/{id}",
        "/api/v1/roles/{id}/permissions",
        "/api/v1/roles/{id}/users",
        "/api/v1/roles/reorder",
        "/api/v1/config/ui-dictionaries",
        "/api/v1/config/login-background",
        "/api/v1/categories/tree",
        "/api/v1/categories",
        "/api/v1/categories/reorder",
        "/api/v1/categories/{id}",
        "/api/v1/documents",
        "/api/v1/documents/tags",
        "/api/v1/documents/reorder",
        "/api/v1/documents/{id}",
        "/api/v1/documents/batch-import",
        "/api/v1/documents/{id}/preview",
        "/api/v1/documents/{id}/re-extract",
        "/api/v1/documents/{id}/move",
        "/api/v1/documents/{id}/download",
        "/api/v1/main-plans/{id}/sub-plans",
        "/api/v1/main-plans/{id}/sub-plans/bind",
        "/api/v1/main-plans/{id}/sub-plans/{subPlanId}",
        "/api/v1/attachments",
        "/api/v1/attachments/{id}",
        "/api/v1/attachments/batch-import",
        "/api/v1/attachments/{id}/main-plans",
        "/api/v1/main-plans/{id}/attachments",
        "/api/v1/main-plans/{id}/attachments/bind",
        "/api/v1/main-plans/{id}/attachments/reorder",
        "/api/v1/main-plans/{id}/attachments/{attachmentId}",
        "/api/v1/main-plans/{id}/attachments/{bindingId}/move",
        "/api/v1/documents/{id}/description",
        "/api/v1/documents/{id}/permissions",
        "/api/v1/documents/{id}/permissions/entries/{entryId}/voucher",
        "/api/v1/documents/{id}/password",
        "/api/v1/documents/relation-presets",
        "/api/v1/documents/{id}/relations",
        "/api/v1/audit/logs",
        "/api/v1/statistics/documents",
        "/api/v1/audit/statistics/trend",
        "/api/v1/audit/statistics/actions",
        "/api/v1/audit/statistics/users",
        "/api/v1/recycle-bin/documents",
        "/api/v1/recycle-bin/documents/{id}/restore",
        "/api/v1/backup/config",
        "/api/v1/backup/jobs",
        "/api/v1/backup/jobs/current",
        "/api/v1/backup/jobs/current/cancel",
        "/api/v1/backup/test-target",
        "/api/v1/system/metrics/current",
        "/api/v1/system/metrics/history",
        "/api/v1/system/process",
        "/api/v1/system/storage-usage",
        "/api/v1/system/converter",
        "/api/v1/system/health",
        "/api/v1/system/info",
        "/api/v1/system/runtime-config",
        "/api/v1/system/logs",
        "/api/v1/system/logs/download",
        "/api/v1/system/maintenance/preview-cache",
        "/api/v1/system/users/{user_id}/force-offline",
    }
    assert document["info"]["version"] == "1.33.0"
    assert "/api/v1/documents/{id}/restore" not in document["paths"]
    assert document["paths"]["/api/v1/health"]["get"]["security"] == []
    login_path = yaml.safe_load(
        (OPENAPI_ROOT / "paths" / "auth.yaml").read_text(encoding="utf-8")
    )
    assert login_path["Login"]["post"]["security"] == []


def test_openapi_string_id_component():
    schemas = yaml.safe_load(
        (OPENAPI_ROOT / "components" / "schemas.yaml").read_text(encoding="utf-8")
    )
    assert schemas["StringId"] == {
        "type": "string",
        "pattern": "^[0-9]+$",
        "description": "数据库BIGINT在JSON中的安全十进制字符串表达。",
    }


def test_openapi_health_response_matches_contract():
    schemas = yaml.safe_load(
        (OPENAPI_ROOT / "components" / "schemas.yaml").read_text(encoding="utf-8")
    )
    health = schemas["HealthResponse"]
    assert set(health["required"]) == {"code", "message", "data", "requestId"}
    assert "timestamp" not in health["properties"]


def test_openapi_has_all_fixed_enum_groups():
    schemas = yaml.safe_load(
        (OPENAPI_ROOT / "components" / "schemas.yaml").read_text(encoding="utf-8")
    )
    expected = {
        "RoleCode",
        "AllowedModule",
        "DocumentType",
        "DocumentStatus",
        "SecurityLevel",
        "AttachmentType",
        "AllowedAction",
        "CategoryType",
        "EnabledStatus",
        "AuditResult",
        "AuditAction",
        "AuditTarget",
    }
    assert expected <= set(schemas)


def test_storage_directory_skeleton(tmp_path: Path):
    root = ensure_storage_directories(tmp_path / "storage")
    assert {path.name for path in root.iterdir()} == set(STORAGE_SUBDIRECTORIES)


@pytest.mark.parametrize(
    "unsafe_path",
    [
        "../outside.pdf",
        "original/../../outside.pdf",
        "/absolute/file.pdf",
        "C:\\Windows\\system.ini",
        "",
    ],
)
def test_storage_path_cannot_escape_root(tmp_path: Path, unsafe_path: str):
    with pytest.raises(UnsafeStoragePathError):
        resolve_storage_path(unsafe_path, tmp_path)


def test_storage_path_resolves_safe_relative_path(tmp_path: Path):
    resolved = resolve_storage_path(
        "original/2026/07/1/file.pdf",
        tmp_path,
    )
    assert resolved == (tmp_path / "original/2026/07/1/file.pdf").resolve()