BakNRet/BakNRet/Public/Get-BaknretSecurityRecords.ps1

function Get-BakNRetSecurityRecords {
    <#
    .SYNOPSIS
        采集一组归档项的安全描述符，键是**归档内相对路径**（`<Slot>\…`）。

    .DESCRIPTION
        键用归档内路径而不是宿主机路径：目标机器上 `%UserProfile%` 会变、名录的前缀补全
        （legendary -> legendary_2.0.4）也会变，只有归档内相对路径在两端是同一个坐标系。

        遍历用显式栈，并且**跳过 reparse point**：PS 5.1 的 Get-ChildItem -Recurse 会
        跟着 junction 无限转；scoop 的 `apps\<app>\current` 就是 junction，正撞在这个坑上。

        $ScopeMap 由 Split-BakNRetPatternScope 产出（项下标 -> 该相对根的模式数组），
        所以这里的排除判定与真正交给 7z 的 -x! / -xr! 是同一套规则。

        Mode：
          * Roots —— 只存每个归档项的根（最省，适合"权限只在根上"的场景）
          * Smart —— 根 + 所有"继承复现不出来"的对象（默认；几万文件的树 sidecar 也只有几百 KB）
          * Full  —— 每一个对象都存（最保险，sidecar 会大到几 MB）

        返回 [pscustomobject]@{ Records; Scanned; Kept; Errors }。
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '',
        Justification = '同上：它采集一整棵树的记录，单数名是「读单个对象」的那个函数。')]
    param(
        [array]$Items = @(),
        [hashtable]$ScopeMap = @{},
        [ValidateSet('Roots', 'Smart', 'Full')][string]$Mode = 'Smart',
        [switch]$IncludeSacl
    )

    $records = New-Object System.Collections.Generic.List[object]
    $scanned = 0
    $errorCount = 0

    # 读安全描述符要 READ_CONTROL：系统目录里读不到是常态（C:\ProgramData 下就有
    # Get-Acl 直接报 "Attempted to perform an unauthorized operation" 的目录）。
    # SeBackupPrivilege 启用后系统会把读权限授予任何文件；连它都没有的账户，
    # 读不到的对象会带 e 字段落进 sidecar，而不是被静默当成"没有特殊权限"。
    $privileges = @('SeBackupPrivilege')
    if ($IncludeSacl) { $privileges += 'SeSecurityPrivilege' }
    Enable-BakNRetPrivilege -Name $privileges | Out-Null

    for ($index = 0; $index -lt $Items.Count; $index++) {
        $item = $Items[$index]
        if (-not $item) { continue }

        $archiveRoot = [string]$item.ArchivePath
        $real = [string]$item.RealPath
        if ([string]::IsNullOrWhiteSpace($archiveRoot) -or [string]::IsNullOrWhiteSpace($real)) { continue }
        if (-not (Test-Path -LiteralPath $real)) { continue }

        $patterns = @()
        if ($ScopeMap -and $ScopeMap.ContainsKey($index)) { $patterns = @($ScopeMap[$index]) }

        $rootItem = Get-Item -LiteralPath $real -Force -ErrorAction SilentlyContinue
        if (-not $rootItem) { continue }

        if (-not $rootItem.PSIsContainer) {
            $record = Get-BakNRetSecurityRecord -Path $real -Key $archiveRoot -Kind 'f' -IncludeSacl:$IncludeSacl
            $scanned++
            if ($record.e) { $errorCount++ }
            $records.Add($record)
            continue
        }

        $rootRecord = Get-BakNRetSecurityRecord -Path $real -Key $archiveRoot -Kind 'd' -IncludeSacl:$IncludeSacl
        $scanned++
        if ($rootRecord.e) { $errorCount++ }
        $records.Add($rootRecord)

        if ($Mode -eq 'Roots') { continue }

        $pending = New-Object System.Collections.Generic.Stack[object]
        $pending.Push(@{
                Dir         = $rootItem
                Rel         = ''
                Owner       = $rootRecord.o
                Group       = $rootRecord.g
                Inheritable = $rootRecord.Inheritable
                Signatures  = $rootRecord.AllSignatures
            })

        while ($pending.Count -gt 0) {
            $frame = $pending.Pop()
            foreach ($child in @(Get-ChildItem -LiteralPath $frame.Dir.FullName -Force -ErrorAction SilentlyContinue)) {
                if ($child.Attributes -band [IO.FileAttributes]::ReparsePoint) { continue }

                $childRel = if ($frame.Rel) { $frame.Rel + '\' + $child.Name } else { $child.Name }
                if (Test-BakNRetPathExcluded -RelativePath $childRel -Patterns $patterns) { continue }

                $kind = if ($child.PSIsContainer) { 'd' } else { 'f' }
                $record = Get-BakNRetSecurityRecord -Path $child.FullName -Key ($archiveRoot + '\' + $childRel) `
                    -Kind $kind -IncludeSacl:$IncludeSacl -ParentSignatures $frame.Signatures
                $scanned++
                if ($record.e) { $errorCount++ }

                if ($Mode -eq 'Full') {
                    $records.Add($record)
                }
                elseif (Test-BakNRetSecurityRecordNeeded -Record $record `
                        -ParentOwner $frame.Owner -ParentGroup $frame.Group `
                        -ParentInheritable $frame.Inheritable -ParentSignatures $frame.Signatures) {
                    $records.Add($record)
                }

                if ($child.PSIsContainer) {
                    $pending.Push(@{
                            Dir         = $child
                            Rel         = $childRel
                            Owner       = $record.o
                            Group       = $record.g
                            Inheritable = $record.Inheritable
                            Signatures  = $record.AllSignatures
                        })
                }
            }
        }
    }

    return [pscustomobject]@{
        Records = @($records.ToArray())
        Scanned = $scanned
        Kept    = $records.Count
        Errors  = $errorCount
    }
}