BakNRet/BakNRet/Public/Resolve-BackupEntry.ps1

function Resolve-BackupEntry {
    <#
    .SYNOPSIS
        把清单条目解析成"实际要打包什么、归档里长什么样"。

    .DESCRIPTION
        返回：

            IsName / BaseName / ArchiveFlavor / Direction
            CatalogEntry —— 名录条目（软件名写法才有）
            Items        —— 归档项数组（见 New-BaknretArchiveItem）
            Encrypt      —— 该归档是否加密
            ExcludePatterns / HasExcludeOverride —— 条目级 `:-` / `@ Exclude` 覆盖
            Includes / HasIncludeOverride        —— 条目级 `:+` / `@ Include` 覆盖
            Error        —— 可恢复的问题（例如名录里路径不存在）
            Blocking     —— 必须整条失败的问题（归档内路径冲突等）

        归档内部布局：
          * 软件名条目 -> `<Slot>\<Path 内容>`（文件 Slot 就是名为 `<Slot>` 的文件）；
          * 手写路径   -> `<末级名>\...`（与历史归档一致，不变）。

        名录里的 Slot 存在但路径当前不存在时**照样产出归档项**：源被删掉正是要恢复的场景，
        备份端按存在性跳过，恢复端靠它把内容还原回原位。
    #>
    param(
        $Entry,
        [string]$CatalogPath,
        [int]$MaxDepth = 5
    )

    $isName = -not (Test-LiteralPath -Path $Entry.Path)
    $forcePathFlavor = ($Entry.Flags -contains 'pathname')
    $baseName = Get-ItemArchiveName -Entry $Entry -CatalogPath $CatalogPath -MaxDepth $MaxDepth

    $overrides = $Entry.Overrides
    if (-not $overrides) { $overrides = @{} }
    $overridePath = if ($overrides.ContainsKey('Path')) { [string]$overrides['Path'] } else { $null }
    $hasExcludeOverride = $overrides.ContainsKey('Exclude')
    $entryExclude = if ($hasExcludeOverride) { @($overrides['Exclude']) } else { @() }
    $hasIncludeOverride = $overrides.ContainsKey('Include')
    $entryInclude = if ($hasIncludeOverride) { @($overrides['Include']) } else { @() }
    $hasEncryptOverride = $overrides.ContainsKey('Encrypt')

    $items = @()
    $catalogEntry = $null
    $errorText = $null
    $blocking = $null
    $archiveFlavor = if ($isName) { 'name' } else { 'path' }

    if (-not $isName) {
        # ---- 写法二：用户手写的目录 / 文件 ----
        $real = [string]$Entry.Path
        if ($overridePath) { $real = $overridePath }
        $real = [Environment]::ExpandEnvironmentVariables($real).Trim()

        $leaf = Split-Path -Path $real -Leaf
        if ($forcePathFlavor) { $archiveFlavor = 'path' }

        $exists = $false
        $isFile = $false
        if ($real) {
            $exists = Test-Path -LiteralPath $real
            if ($exists) {
                $item = Get-Item -LiteralPath $real -Force -ErrorAction SilentlyContinue
                if ($item) { $isFile = -not $item.PSIsContainer }
            }
        }

        if ([string]::IsNullOrWhiteSpace($leaf) -or [string]::IsNullOrWhiteSpace($real)) {
            $errorText = "无法从路径里拆出末级名：$real"
        }
        else {
            $items += New-BaknretArchiveItem -ArchivePath $leaf -RealPath $real -Kind 'path' `
                -Origin 'path' -Exists $exists -IsFile $isFile
        }
    }
    else {
        # ---- 写法一：软件名录里的软件名 ----
        $catalog = Get-SoftwareCatalog -Path $CatalogPath -MaxDepth $MaxDepth
        if (-not $catalog.ContainsKey($Entry.Path)) {
            $errorText = "软件名录里没有 '$($Entry.Path)'"
        }
        else {
            $catalogEntry = $catalog[$Entry.Path]
            # 名录条目自身有问题（Slot 缺 Path、前缀补全命中多个目录……）时整条失败：
            # 继续跑只会"少打包一块"或"任选一个目录"，那正是最该避免的静默错误。
            if ($catalogEntry.Error) {
                $errorText = $catalogEntry.Error
                if (-not $blocking) { $blocking = "软件名录里的 '$($Entry.Path)' 有问题：$($catalogEntry.Error)" }
            }

            $slots = @($catalogEntry.Slots)
            if ($overridePath -and $slots.Count -ne 1) {
                $blocking = ("'{0}' 有 {1} 个 Slot，不能用一个 `::` / `@ Path=` 覆盖路径；请写清楚是哪个 Slot" -f `
                        $Entry.Path, $slots.Count)
            }
            else {
                foreach ($slot in $slots) {
                    $resolvedPath = $slot.Resolved
                    $exists = $slot.Exists
                    $isFile = $slot.IsFile

                    if ($overridePath) {
                        $resolvedPath = [Environment]::ExpandEnvironmentVariables($overridePath).Trim()
                        $exists = Test-Path -LiteralPath $resolvedPath
                        $isFile = $false
                        if ($exists) {
                            $item = Get-Item -LiteralPath $resolvedPath -Force -ErrorAction SilentlyContinue
                            if ($item) { $isFile = -not $item.PSIsContainer }
                        }
                    }

                    $items += New-BaknretArchiveItem -ArchivePath $slot.Name -RealPath $resolvedPath -Kind 'slot' `
                        -Slot $slot.Name -Description $slot.Description -Origin 'catalog' `
                        -Exists $exists -IsFile $isFile -Exclude $slot.Exclude
                }
            }
        }
    }

    # ------------------------------------------------------------------
    # 包含项：`<归档内相对路径>:<宿主机绝对路径>`，把宿主机上的目录 / 文件放到包内指定位置。
    # 条目级写 `:+` / `@ Include=` 就覆盖名录里的 Include；没写就用名录里各 Slot 的。
    # ------------------------------------------------------------------
    $includeTexts = @()
    if ($hasIncludeOverride) {
        $includeTexts = @($entryInclude)
    }
    elseif ($catalogEntry) {
        foreach ($slot in @($catalogEntry.Slots)) { $includeTexts += @($slot.Include) }
    }

    foreach ($includeText in $includeTexts) {
        if ([string]::IsNullOrWhiteSpace($includeText)) { continue }
        $text = ([string]$includeText).Trim()

        $archivePart = ''
        $hostPart = $text
        $separator = $text.IndexOf(':')
        if ($separator -ge 0) {
            $archivePart = $text.Substring(0, $separator).Trim()
            $hostPart = $text.Substring($separator + 1).Trim()

            # 写成 `D:\extra\ps-modules:Modules`（宿主机在前）时纠正并告警。
            # 判据：第一个冒号前只有盘符那一个字母，而且紧跟着 `\` 或 `/`。
            # 这时按**最后一个**冒号切，才能把宿主机路径完整地拿回来。
            if ($archivePart -match '^[A-Za-z]$' -and ($hostPart.StartsWith('\') -or $hostPart.StartsWith('/'))) {
                $lastSeparator = $text.LastIndexOf(':')
                if ($lastSeparator -gt $separator) {
                    Write-Log ("包含项写得像'宿主机:归档内'：{0} —— 语法应为 <归档内相对路径>:<宿主机绝对路径>，已按后者解释" -f $text) -Level WARN
                    $hostPart = $text.Substring(0, $lastSeparator).Trim()
                    $archivePart = $text.Substring($lastSeparator + 1).Trim()
                }
            }
        }

        $hostPath = [Environment]::ExpandEnvironmentVariables($hostPart).Trim()
        if ([string]::IsNullOrWhiteSpace($hostPath)) {
            Write-Log "包含项 '$text' 里没有宿主机路径，已忽略" -Level WARN
            continue
        }

        $exists = Test-Path -LiteralPath $hostPath
        $isFile = $false
        if ($exists) {
            $item = Get-Item -LiteralPath $hostPath -Force -ErrorAction SilentlyContinue
            if ($item) { $isFile = -not $item.PSIsContainer }
        }

        $archivePath = $archivePart
        if ([string]::IsNullOrWhiteSpace($archivePath)) { $archivePath = Split-Path -Path $hostPath -Leaf }

        $items += New-BaknretArchiveItem -ArchivePath $archivePath -RealPath $hostPath -Kind 'include' `
            -Origin 'include' -Exists $exists -IsFile $isFile
    }

    # ------------------------------------------------------------------
    # 归档内路径冲突拦截
    # 一个目录 / 文件在包内只能有一个位置：重名会互相覆盖，祖宗关系会混成一棵树。
    # 宁可明确报错，也不要静默搅在一起。
    # ------------------------------------------------------------------
    $seen = @{}
    $collisions = @()
    foreach ($item in $items) {
        $key = ([string]$item.ArchivePath).ToLower()
        if (-not $key) { continue }
        if ($seen.ContainsKey($key)) {
            $collisions += ("'{0}'（{1} 与 {2}）" -f $item.ArchivePath, $seen[$key], $item.RealPath)
        }
        else {
            $seen[$key] = $item.RealPath
        }
    }
    foreach ($item in $items) {
        $key = ([string]$item.ArchivePath).ToLower()
        foreach ($other in $seen.Keys) {
            if ($other -eq $key) { continue }
            if ($other.StartsWith("$key\") -or $key.StartsWith("$other\")) {
                $collisions += ("'{0}' 与 '{1}' 是父子关系，包内会互相覆盖" -f $item.ArchivePath, $other)
            }
        }
    }
    $collisions = @($collisions | Select-Object -Unique)

    if ($collisions.Count -gt 0) {
        $blocking = ("归档内路径冲突：{0}。每个 Slot / 追加项在包内必须有唯一位置，" +
            "请改 Slot 名或归档内相对路径。") -f ($collisions -join '；')
    }

    # ------------------------------------------------------------------
    # 加密：清单覆盖优先，其次是名录里各 Slot 的 Encrypt 取或。
    # 一个软件一个归档，所以 Slot 之间不一致时按"加密"处理（宁可多加密，不可漏加密）。
    # ------------------------------------------------------------------
    $encrypt = $false
    if ($hasEncryptOverride) {
        $encrypt = [bool]$overrides['Encrypt']
    }
    elseif ($catalogEntry) {
        $slots = @($catalogEntry.Slots)
        $encryptedSlots = @($slots | Where-Object { $_.Encrypt })
        $encrypt = $encryptedSlots.Count -gt 0
        if ($encryptedSlots.Count -gt 0 -and $encryptedSlots.Count -lt $slots.Count) {
            Write-Log ("{0}：名录里各 Slot 的 Encrypt 不一致，整个归档按加密处理" -f $Entry.Path) -Level WARN
        }
    }

    return [pscustomobject]@{
        IsName             = [bool]$isName
        CatalogEntry       = $catalogEntry
        BaseName           = $baseName
        ArchiveFlavor      = $archiveFlavor
        Direction          = $Entry.Direction
        Items              = @($items)
        Encrypt            = [bool]$encrypt
        ExcludePatterns    = @($entryExclude)
        HasExcludeOverride = [bool]$hasExcludeOverride
        Includes           = @($entryInclude)
        HasIncludeOverride = [bool]$hasIncludeOverride
        Source             = $Entry.Path
        Error              = $errorText
        Blocking           = $blocking
    }
}