402 lines
20 KiB
Python
402 lines
20 KiB
Python
"""Checkpointed CBB mutations with native evidence and no automatic replay."""
|
|
from dataclasses import asdict, dataclass, field, replace
|
|
from datetime import datetime, timezone
|
|
import json
|
|
from pathlib import Path, PureWindowsPath
|
|
import re
|
|
from uuid import uuid4
|
|
|
|
from .library_lock import LibraryLock, LibraryBusy
|
|
from .scoped_manifest import (ManifestScope, build_manifest, build_exclusive_library_manifest,
|
|
copy_verified, hash_file, scan_tree)
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Capability:
|
|
supported: bool
|
|
reason: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ManagementRequest:
|
|
operation: str
|
|
library: Path
|
|
name: str
|
|
partition: str = 'Logical-Physical'
|
|
source: Path | None = None
|
|
auto_verify: bool = True
|
|
evidence_dir: Path = Path('management-evidence')
|
|
top_level_block: str = ''
|
|
timeout_seconds: float = 180
|
|
mapped_drive: str = ''
|
|
mapped_remote_root: str = ''
|
|
transaction_token: str = ''
|
|
check_previous_release: bool = False
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class CatalogEntry:
|
|
name: str
|
|
partition: str
|
|
engineering_identity: dict = field(default_factory=dict)
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Catalog:
|
|
library: Path
|
|
flow: int
|
|
entries: tuple[CatalogEntry, ...]
|
|
safe_to_continue: bool = True
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class NativeOutcome:
|
|
success: bool
|
|
safe_to_continue: bool
|
|
detail: str
|
|
identity_matches: bool | None = None
|
|
evidence_path: Path | None = None
|
|
identity_proof: dict | None = None
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ManagementResult:
|
|
operation: str
|
|
library: Path
|
|
name: str
|
|
partition: str
|
|
source: Path | None
|
|
auto_verify: bool
|
|
stage: str
|
|
status: str
|
|
safe_to_continue: bool
|
|
detail: str = ''
|
|
evidence_path: Path | None = None
|
|
release_proof: dict | None = None
|
|
|
|
|
|
def validate_name(value):
|
|
if (not value or value != value.strip() or value.endswith('.') or value in ('.', '..')
|
|
or any(ord(c) < 32 or c in '<>:"/\\|?*' for c in value)
|
|
or value.split('.')[0].upper() in {'CON', 'PRN', 'AUX', 'NUL',
|
|
*(f'COM{i}' for i in range(1, 10)), *(f'LPT{i}' for i in range(1, 10))}):
|
|
raise ValueError('CBB 名称/分区不是有效单一名称,禁止路径、控制字符或保留名称。')
|
|
|
|
|
|
def source_project(source, top_level_block=''):
|
|
"""Require complete PRJ/PCB and self-contained engineering references."""
|
|
from .backup_recovery import _project_text
|
|
source = Path(source).resolve(strict=True)
|
|
if source.suffix.casefold() != '.prj' or not source.is_file():
|
|
raise ValueError('请选择完整工程的 PRJ 文件。')
|
|
scan_tree(source.parent) # Reject reparse points, including file links.
|
|
text = _project_text(source)
|
|
roots = re.findall(r'^KEY RootBlock "([^"]+)"', text, re.M)
|
|
if len(roots) != 1 or top_level_block and roots[0] != top_level_block:
|
|
raise ValueError('工程顶层块不唯一或与输入不一致。')
|
|
validate_name(roots[0])
|
|
def reference(path, key):
|
|
values = re.findall(r'^KEY ' + re.escape(key) + r' "([^"]+)"', _project_text(path), re.M)
|
|
if len(values) != 1 or PureWindowsPath(values[0]).is_absolute() or PureWindowsPath(values[0]).drive:
|
|
raise ValueError(f'{key} 必须为唯一工程内相对引用。')
|
|
resolved = (path.parent/values[0]).resolve()
|
|
if not resolved.is_relative_to(source.parent):
|
|
raise ValueError(f'{key} 越出来源工程。')
|
|
return resolved
|
|
pcb = reference(source, 'PCBDesignPath')
|
|
if not pcb.is_file() or reference(pcb, 'ProjectFile') != source:
|
|
raise ValueError('PCB 未引用所选来源工程。')
|
|
from .maintenance_entry import maintenance_project_files
|
|
for path in maintenance_project_files(source, pcb):
|
|
if not path.is_file():
|
|
raise ValueError('工程缺少 PCB 工程配置。')
|
|
# Healthy Expedition PCB projects can use Layout/LayoutDB.lyt without
|
|
# declaring an independent iCDBDir. The schematic DB stays mandatory;
|
|
# an explicitly declared PCB DB must still pass every reference check.
|
|
if path != source and not re.search(r'^KEY iCDBDir\b', _project_text(path), re.M):
|
|
continue
|
|
db = reference(path, 'iCDBDir')
|
|
if not (db/'icdb.dat').is_file():
|
|
raise ValueError('工程缺少原理图/PCB 数据库。')
|
|
if not (pcb.parent/'Layout/LayoutDB.lyt').is_file():
|
|
raise ValueError('工程缺少布局数据库。')
|
|
return source, pcb, roots[0]
|
|
|
|
|
|
def engineering_identity(source):
|
|
"""Compare actual registered engineering bytes, not a name-only acknowledgment.
|
|
|
|
Conservative until native normalization has an independently proven semantic
|
|
comparison: changed database bytes cannot be claimed to match the source.
|
|
"""
|
|
source, pcb, top = source_project(source)
|
|
from .backup_recovery import _project_text
|
|
db = re.findall(r'^KEY iCDBDir "([^"]+)"', _project_text(source), re.M)[0]
|
|
return {'top_level_block': top, 'schematic_sha256': hash_file(source.parent/db/'icdb.dat'),
|
|
'layout_sha256': hash_file(pcb.parent/'Layout/LayoutDB.lyt')}
|
|
|
|
|
|
def _write_json(path, value):
|
|
path = Path(path)
|
|
pending = path.with_suffix('.pending')
|
|
with pending.open('w', encoding='utf-8') as stream:
|
|
json.dump(value, stream, ensure_ascii=False, default=str, indent=2)
|
|
stream.flush()
|
|
import os
|
|
os.fsync(stream.fileno())
|
|
pending.replace(path)
|
|
|
|
|
|
def unfinished_operations(root):
|
|
results = []
|
|
for path in sorted(Path(root).glob('*/checkpoint.json')):
|
|
try:
|
|
record = json.loads(path.read_text(encoding='utf-8'))
|
|
if (record.get('stage') != 'complete' or record.get('safe_to_continue') is False
|
|
or record.get('status') == 'RECOVERY_REQUIRED'):
|
|
results.append({**record, 'evidence_path': str(path)})
|
|
except (OSError, ValueError):
|
|
results.append({'status': 'CHECKPOINT_UNREADABLE', 'evidence_path': str(path)})
|
|
return results
|
|
|
|
|
|
def _may_have_mutated(record):
|
|
prewrite = {'preflight', 'release_check', 'catalog_before', 'baseline', 'stage_source', 'prepare_identity'}
|
|
history = record.get('history')
|
|
return (record.get('stage') not in prewrite | {'complete'} or record.get('status') == 'RECOVERY_REQUIRED'
|
|
or not isinstance(history, list) or not history
|
|
or any(not isinstance(item, dict) or item.get('stage') not in prewrite for item in history))
|
|
|
|
|
|
def run_management(request, *, adapter=None, verifier=None, idle_check=None, progress=None):
|
|
from .verify_runner import VerifyRequest, run_verify
|
|
from .backup_recovery import _idle_check
|
|
import win32con, win32event
|
|
import pythoncom
|
|
if adapter is None:
|
|
from .native_management import NativeManagementAdapter
|
|
adapter = NativeManagementAdapter()
|
|
verifier = verifier or run_verify
|
|
idle_check = idle_check or _idle_check
|
|
root = report = None
|
|
stage = 'preflight'
|
|
history = []
|
|
mutated = uploaded = removed = False
|
|
owner_safe = True
|
|
mutex = None
|
|
acquired = False
|
|
release_proof = None
|
|
def invoke(callback, *args):
|
|
nonlocal owner_safe
|
|
owner_safe = False
|
|
try:
|
|
result = callback(*args)
|
|
except Exception as error:
|
|
owner_safe = getattr(error, 'safe_to_continue', False) is True
|
|
raise
|
|
owner_safe = result.safe_to_continue
|
|
return result
|
|
def checkpoint(next_stage, **details):
|
|
nonlocal stage
|
|
stage = next_stage
|
|
history.append({'stage': stage, 'time': datetime.now(timezone.utc).isoformat(), **details})
|
|
if report:
|
|
_write_json(report, {**asdict(request), 'stage': stage, 'status': 'RUNNING',
|
|
'safe_to_continue': False, 'history': history, 'backup_policy': 'manual'})
|
|
if progress:
|
|
progress({'stage': stage, 'block': request.name, 'operation': request.operation, **details})
|
|
def finish(status, detail='', safe=True):
|
|
result = ManagementResult(request.operation, request.library, request.name, request.partition,
|
|
request.source, request.auto_verify, 'complete', status, safe, detail, report, release_proof)
|
|
if report:
|
|
try:
|
|
_write_json(report, {**asdict(result), 'history': history, 'backup_policy': 'manual'})
|
|
except OSError as error:
|
|
result = replace(result, detail=f'{detail}\n操作记录写入失败:{error}'.strip())
|
|
return result
|
|
from .com_runtime import initialize_com, uninitialize_com
|
|
initialized = initialize_com()
|
|
try:
|
|
if request.operation not in ('add', 'update', 'remove'):
|
|
raise ValueError('不支持的管理操作。')
|
|
validate_name(request.name); validate_name(request.partition)
|
|
from .network_path import absolute_preserving_drive
|
|
library = absolute_preserving_drive(request.library)
|
|
canonical_library = library.resolve(strict=True)
|
|
library_root = canonical_library.parent
|
|
if library.suffix.casefold() != '.lmc' or not library.is_file():
|
|
raise ValueError('中心库必须为现有 LMC 文件。')
|
|
evidence = Path(request.evidence_dir).resolve()
|
|
if evidence.is_relative_to(library_root) or library_root.is_relative_to(evidence):
|
|
raise ValueError('操作记录与暂存目录必须位于目标中心库之外,且不能包含目标库。')
|
|
capability = adapter.capabilities().get(request.operation, Capability(False, '未验证的原生接口'))
|
|
if not capability.supported:
|
|
return finish('UNSUPPORTED', capability.reason)
|
|
unfinished_target = None
|
|
for unfinished in unfinished_operations(evidence):
|
|
if (unfinished.get('library') and Path(unfinished['library']).resolve() == canonical_library
|
|
and _may_have_mutated(unfinished) and (not unfinished.get('name')
|
|
or str(unfinished['name']).casefold() == request.name.casefold())):
|
|
unfinished_target = unfinished
|
|
break
|
|
source = pcb = None
|
|
if request.operation in ('add', 'update'):
|
|
if request.source is None:
|
|
raise ValueError('新增/更新需要完整来源工程。')
|
|
source, pcb, top = source_project(request.source, request.top_level_block)
|
|
if (source.parent.is_relative_to(library_root) or library_root.is_relative_to(source.parent)
|
|
or evidence.is_relative_to(source.parent)
|
|
or source.parent.is_relative_to(evidence)):
|
|
raise ValueError('来源工程、目标库与操作证据必须使用独立目录。')
|
|
root = evidence/('management-' + uuid4().hex)
|
|
root.mkdir(parents=True, exist_ok=False)
|
|
report = root/'checkpoint.json'
|
|
checkpoint('release_check')
|
|
mutex = win32event.CreateMutex(None, False, r'Local\CbbRefreshVerify795')
|
|
acquired = win32event.WaitForSingleObject(mutex, 0) in (win32con.WAIT_OBJECT_0, win32con.WAIT_ABANDONED)
|
|
if not acquired:
|
|
return finish('BLOCKED', '已有 CBB 校验/管理/恢复任务运行;本次未启动。')
|
|
from .library_lock import has_blocker, has_retained_library, release_retained_library
|
|
if (has_blocker(library) or has_retained_library(library) or request.check_previous_release
|
|
or unfinished_target and unfinished_target.get('safe_to_continue') is not True):
|
|
release_proof = release_retained_library(library, root/'previous-release')
|
|
if unfinished_target:
|
|
return finish('BLOCKED', f'存在未完成/需恢复任务,禁止自动重放:{unfinished_target["evidence_path"]}')
|
|
if hasattr(adapter, 'bind_library_mapping'):
|
|
adapter.bind_library_mapping(request.mapped_drive, request.mapped_remote_root)
|
|
with LibraryLock(library, block_name=request.name, safe_to_release=lambda: owner_safe or (
|
|
callable(getattr(adapter, 'release_confirmed', None)) and adapter.release_confirmed(library))):
|
|
work = library.parent/'ReusableBlocksLP'/request.name/'Work'
|
|
target_project, target_pcb = work/(request.name+'.prj'), work/'PCB/pcb.pcb'
|
|
if request.operation != 'add':
|
|
# Read actual engineering references when available; fallback
|
|
# paths still permit removal of catalog entries missing Work.
|
|
from .verify_runner import preflight
|
|
try:
|
|
target_project, target_pcb = preflight(VerifyRequest(library, request.name, root))
|
|
except ValueError:
|
|
pass
|
|
idle_check(library, target_project, target_pcb)
|
|
if source:
|
|
idle_check(library, source, pcb)
|
|
checkpoint('catalog_before')
|
|
owner_safe = False
|
|
before = invoke(adapter.catalog, library, root/'before')
|
|
owner_safe = before.safe_to_continue
|
|
if not owner_safe or Path(before.library).resolve() != canonical_library or before.flow != 1:
|
|
return finish('BLOCKED', '原生目录身份/流程或所有者释放未确认。仅支持已验证 DxDesigner 流程。', owner_safe)
|
|
same_name = [entry for entry in before.entries if entry.name.casefold() == request.name.casefold()]
|
|
matches = [entry for entry in same_name if entry.partition == request.partition and entry.name == request.name]
|
|
if request.operation == 'add' and same_name:
|
|
return finish('UPLOAD_FAILED', '同名 CBB 已存在;新增禁止覆盖,请使用明确的同名更新。')
|
|
if request.operation != 'add' and len(matches) != 1:
|
|
return finish('BLOCKED', '目标名称和分区必须与原生目录唯一匹配。')
|
|
if hasattr(adapter, 'preflight'):
|
|
adapter.preflight(request, before)
|
|
# Native/project owners must be idle before snapshot or mutation.
|
|
idle_check(library, target_project, target_pcb)
|
|
scope = ManifestScope.library(request.name, library.name)
|
|
checkpoint('baseline')
|
|
original = build_exclusive_library_manifest(library_root, scope=scope, progress=progress)
|
|
_write_json(root/'library-baseline-manifest.json', original)
|
|
staged = request
|
|
identity = None
|
|
if source:
|
|
checkpoint('stage_source')
|
|
source_manifest = copy_verified(source.parent, root/'source', progress=progress)
|
|
_write_json(root/'source-manifest.json', source_manifest)
|
|
staged = replace(request, source=root/'source'/source.name, top_level_block=top)
|
|
identity = engineering_identity(staged.source)
|
|
if build_manifest(source.parent) != source_manifest:
|
|
raise OSError('来源工程在暂存期间变化。')
|
|
if source and hasattr(adapter, 'prepare_add_transaction'):
|
|
checkpoint('prepare_identity')
|
|
owner_safe = False
|
|
staged, proof = adapter.prepare_add_transaction(staged, root, original_source=source)
|
|
owner_safe = proof.safe_to_continue
|
|
if not owner_safe or proof.identity is None:
|
|
return finish('UPLOAD_FAILED', proof.detail, owner_safe)
|
|
identity = proof.identity
|
|
if build_exclusive_library_manifest(library_root, scope=scope, progress=progress) != original:
|
|
raise OSError('内容基线记录后中心库发生变化,停止写入。')
|
|
if request.operation in ('remove', 'update'):
|
|
checkpoint('native_remove')
|
|
mutated = True; owner_safe = False
|
|
native = invoke(adapter.remove, request, root/'remove')
|
|
owner_safe = native.safe_to_continue
|
|
if not owner_safe or not native.success:
|
|
return finish('RECOVERY_REQUIRED', native.detail, owner_safe)
|
|
idle_check(library, target_project, target_pcb)
|
|
after = invoke(adapter.catalog, library, root/'after-remove')
|
|
owner_safe = after.safe_to_continue
|
|
if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1
|
|
or any(e.name == request.name and e.partition == request.partition for e in after.entries)):
|
|
return finish('RECOVERY_REQUIRED', '原生移除后目录未确认目标缺失。', owner_safe)
|
|
removed = True
|
|
checkpoint('removed')
|
|
if request.operation == 'remove':
|
|
return finish('REMOVED', '已由原生操作移除,重新读取目录确认不存在;应用未创建备份。')
|
|
checkpoint('native_add')
|
|
mutated = True; owner_safe = False
|
|
native = invoke(adapter.add, staged, root/'add')
|
|
owner_safe = native.safe_to_continue
|
|
if not owner_safe or not native.success:
|
|
return finish('RECOVERY_REQUIRED' if removed or not owner_safe else 'UPLOAD_FAILED',
|
|
native.detail, owner_safe)
|
|
idle_check(library, target_project, target_pcb)
|
|
after = invoke(adapter.catalog, library, root/'after-add')
|
|
owner_safe = after.safe_to_continue
|
|
matches = [entry for entry in after.entries if entry.name == request.name
|
|
and entry.partition == request.partition]
|
|
proof_matches = (native.identity_matches is True and native.identity_proof == identity
|
|
if hasattr(adapter, 'prepare_add_transaction') else
|
|
len(matches) == 1 and matches[0].engineering_identity == identity)
|
|
if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1
|
|
or len(matches) != 1 or not proof_matches):
|
|
return finish('RECOVERY_REQUIRED', '原生新增后名称、分区或来源工程内容未确认一致。', owner_safe)
|
|
uploaded = True
|
|
checkpoint('uploaded')
|
|
if not request.auto_verify:
|
|
return finish('UPLOADED', '上传已确认;本批次未启用自动校验。')
|
|
# Adapter catalog cannot return until its exact native owner exits.
|
|
checkpoint('verify')
|
|
owner_safe = False
|
|
verified = verifier(VerifyRequest(library, request.name, root/'verify',
|
|
mapped_drive=request.mapped_drive, mapped_remote_root=request.mapped_remote_root), progress=progress)
|
|
owner_safe = verified.safe_to_continue
|
|
checkpoint('verified', verification=asdict(verified))
|
|
good = verified.status == 'PASS' and verified.library_flag == 'GREEN' and owner_safe
|
|
return finish('UPLOADED_VERIFIED' if good else 'UPLOADED_VERIFY_FAILED',
|
|
verified.stderr or verified.library_flag_detail, owner_safe)
|
|
except Exception as error:
|
|
if uploaded:
|
|
return finish('UPLOADED_VERIFY_FAILED', str(error), owner_safe)
|
|
status = 'RECOVERY_REQUIRED' if mutated else ('UPLOAD_FAILED' if request.operation in ('add', 'update') else 'BLOCKED')
|
|
# Bad input is never described as a native upload attempt.
|
|
if root is None and isinstance(error, ValueError):
|
|
status = 'BLOCKED'
|
|
if stage == 'release_check' and not mutated:
|
|
status = 'BLOCKED'
|
|
return finish(status, str(error), owner_safe)
|
|
finally:
|
|
if mutex is not None:
|
|
if acquired:
|
|
win32event.ReleaseMutex(mutex)
|
|
mutex.Close()
|
|
uninitialize_com(initialized)
|
|
|
|
|
|
def run_management_batch(requests, *, stop=None, progress=None, **kwargs):
|
|
results = []
|
|
for request in requests:
|
|
if stop is not None and stop.is_set():
|
|
break
|
|
result = run_management(request, progress=progress, **kwargs)
|
|
results.append(result)
|
|
if progress:
|
|
progress({'stage': result.status, 'block': result.name, 'detail': result.detail,
|
|
'evidence_path': str(result.evidence_path or '')})
|
|
if not result.safe_to_continue:
|
|
break
|
|
return results
|