chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/legacy/worker.py

@@ -0,0 +1,352 @@
+"""在独立spawn进程按一条PULL许可推进一次冻结Sclicer公开函数链。
+
+静态只导入标准库和records；INIT校验后才核三份原样vendor哈希、导入真实依赖，
+原load_file一次并创建原iter_frames，不提前next。READY的单位来自同次db公开
+messages/signals；每PULL只next一次、对同msg/db原parse_frame一次，返当前ITEM
+后等待下一命令。STATUS/ACK不授予读取许可，STOP不取后继，正常EOF后退出。
+
+本进程只发送最大65536字节的严格JSON bytes，不使用Connection.send/recv的pickle。
+记录保原msg全部公开写出字段和全部原返回数值，不窥视generator frame、补decode、
+增加筛选或缩放。finally只关本连接和原生成器，不声称旧reader底层FD已确定关闭；
+父进程须等待本进程确实退出，OS才回收本进程旧FD。外部解释器/DBC/reader的RSS
+不受父共享账目保证。失败发送有限原错误事实并以非零退出，不伪称原异常对象跨进程。
+"""
+
+# spawn加载时不触及CAN库、原vendor或输入；这些依赖只在收到有效INIT后加载。
+from hashlib import sha256
+from importlib import metadata, util
+import os
+from pathlib import Path
+import platform
+import sys
+from .records import (LegacyCANRequest, LegacyDecodedFrame, LegacyRawFrame, MAX_WIRE_BYTES,
+    PROFILE_ID, decode_packet, decoded_to_dict, encode_packet, field_from_dict, field_to_dict)
+
+# vendor文件复制自历史Sclicer项目；以下哈希用于核对原始文件字节。
+VENDOR_SHA256 = {
+    'utils.py': 'cf3737ad5ab0a399dc7576585102339e0312b9babe690a1ba8decf543a71c2fd',
+    'file_processor.py': '5f37bd996ccd31eedd95bec5ed39289cd7f2fe3049110ebbe195db0cbefb1db6',
+    'can_processor.py': '3c96e67a1ec47ac181657b5bf5a9cabf7e35a1d5e2709577718c22d1293878e2',
+}
+
+
+def _send(connection, packet):
+    """通过bytes接口发送一个有界JSON包，不调用pickle通道。
+
+    参数: connection为本子进程Connection；packet为协议dict。返回: None。
+    异常: 原wire类型/限额或管道错误；不重试导致重复ITEM。
+    """
+    connection.send_bytes(encode_packet(packet))
+
+
+def _receive(connection):
+    """只接收一个不超过单包上限的bytes消息。
+
+    参数: connection为本子进程Connection。返回: 已校验dict。
+    异常: EOFError/OSError/协议错误传播，不把断管当正常来源EOF。
+    """
+    return decode_packet(connection.recv_bytes(MAX_WIRE_BYTES))
+
+
+def _exact(packet, names):
+    """限制每种控制包的精确字段，不让多余许可或版本字段静默生效。
+
+    参数: packet为已解析dict；names为允许键容器。返回: None。
+    异常: ValueError为字段缺失或多余。
+    """
+    if set(packet) != set(names):
+        raise ValueError('旧CAN控制包字段缺失或多余')
+
+
+def _request(packet):
+    """解析唯一INIT，只接受单个实际BLF和原DBC路径，不读取其内容摘要。
+
+    参数: packet为INIT dict。返回: LegacyCANRequest。
+    异常: 类型/形状/版本/路径错误；不调用旧reader或load_file。
+    """
+    _exact(packet, ('op', 'version', 'path', 'dbc_path', 'fields'))
+    if packet['op'] != 'init' or type(packet['version']) is not int or packet['version'] != 1:
+        raise ValueError('旧CAN需要init/version1')
+    if type(packet['path']) is not str or type(packet['dbc_path']) is not str or type(packet['fields']) is not list:
+        raise TypeError('旧CAN INIT需要文本路径与fields数组')
+    request = LegacyCANRequest(Path(packet['path']), Path(packet['dbc_path']),
+        tuple(field_from_dict(value) for value in packet['fields']))
+    # 只做stat和扩展名边界；不额外读取原CAN或预扫消息，不暗换另一种profile。
+    if request.input_path.suffix.lower() != '.blf' or not request.input_path.is_file():
+        raise ValueError('首版旧CAN仅支持单个现有BLF文件')
+    if not request.dbc_path.is_file():
+        raise FileNotFoundError(request.dbc_path)
+    return request
+
+
+def _load_vendor():
+    """核原样三模块字节后在独立child安装其原名称，保绝对utils导入。
+
+    参数: 无。返回: (file_processor模块,can_processor模块,实际哈希dict)。
+    异常: 哈希、同名模块污染或原模块依赖导入错误；不猴补函数、reader或计数器。
+    """
+    root = Path(__file__).resolve().parent / 'vendor' / 'sclicer_functions_v1'
+    actual = {}
+    for name, expected in VENDOR_SHA256.items():
+        actual[name] = sha256((root / name).read_bytes()).hexdigest()
+        if actual[name] != expected:
+            raise ValueError('旧CAN vendor哈希不匹配: ' + name)
+    # 原file_processor使用from utils导入；仅child内按原模块名加载，不碰父sys.modules。
+    modules = {}
+    sys.dont_write_bytecode = True
+    for name in ('utils', 'file_processor', 'can_processor'):
+        if name in sys.modules:
+            raise RuntimeError('隔离旧CAN进程存在同名模块: ' + name)
+        spec = util.spec_from_file_location(name, root / (name + '.py'))
+        if spec is None or spec.loader is None:
+            raise ImportError('无法加载原vendor模块: ' + name)
+        module = util.module_from_spec(spec)
+        sys.modules[name] = module
+        try:
+            spec.loader.exec_module(module)
+        except ModuleNotFoundError as error:
+            # 保持冻结模块原导入顺序，仅补充真实缺失依赖的可执行处理建议。
+            from ..can_dependencies import CANDependencyError
+            raise CANDependencyError(error.name or '未知模块') from error
+        modules[name] = module
+    return modules['file_processor'], modules['can_processor'], actual
+
+
+def _field_metadata(db, fields, *, cycle_fields=()):
+    """只读同次db公开messages/signals核定位唯一，并返回原单位。
+
+    参数: db为唯一原load_file结果；fields为原LegacyCANField tuple；
+        cycle_fields仅指定需要周期的字段，须在fields中。默认不访问cycle_time。
+    返回: 按请求顺序的字段事实；周期请求的字段另含正cycle_ns。
+        仅DBC为FD而定位为经典CAN时增加固定兼容提示。
+        channel保声明，不冒称DBC已测通道；不把DBC声明写回原帧。
+    异常: ValueError为ID/消息/帧型/信号歧义或不符，TypeError为单位不受支持。
+    """
+    if cycle_fields:
+        from .dbc_cycles import require_cycle_fields, cycle_time_ns
+        require_cycle_fields(cycle_fields)
+        if not set(cycle_fields).issubset(fields):
+            raise ValueError('周期字段须包含在本次DBC定位中')
+    from .binding import dbc_candidates
+    periods = {} if cycle_fields else None
+    result = []
+    for field in fields:
+        # 多定义允许由实际原帧决定；初始化所需的单位不能随候选改变。
+        candidates = dbc_candidates(db, field.frame_id, (field.signal,), field.is_extended, field.is_fd)
+        units = {signal.unit for message in candidates for signal in message.signals if signal.name == field.signal}
+        if len(units) != 1:
+            raise ValueError('候选DBC信号单位不同，请补充 is_extended 或 is_fd: ' + field.signal)
+        unit = next(iter(units))
+        compatible = field.is_fd is False and all(message.is_fd is True for message in candidates)
+        if unit is not None and type(unit) is not str:
+            raise TypeError('原DBC公开unit需要文本或None')
+        item = {'locator': field_to_dict(field), 'unit': unit}
+        if field.is_extended is None or field.is_fd is None:
+            # 父读取器据此跳过同ID但不含所需信号的帧，不伪造一次失效更新。
+            item['dbc_frames'] = [list(pair) for pair in dict.fromkeys(
+                (message.is_extended_frame, message.is_fd) for message in candidates)]
+        if compatible:
+            item['frame_format_compatibility'] = {'code': 'dbc_fd_classic_selector',
+                'dbc_is_fd': True, 'requested_is_fd': False}
+        if field in cycle_fields:
+            # 同一物理报文多个别名只取一次周期，后续记录不再访问DBC周期。
+            values = set()
+            for message in candidates:
+                # 多信号来自同一消息对象时只读一次周期，同ID不同定义不能相互覆盖。
+                identity = id(message)
+                if identity not in periods:
+                    periods[identity] = cycle_time_ns(message.cycle_time)
+                values.add(periods[identity])
+            if len(values) != 1:
+                raise ValueError('候选DBC周期不同，请补充帧类型、period 或 valid_for: ' + field.signal)
+            item['cycle_ns'] = next(iter(values))
+        result.append(item)
+    return result
+
+
+def _frame(msg):
+    """在一次原parse之后保存同次msg公开写出字段，不重建CAN消息。
+
+    参数: msg为本次原iter_frames刚yield的can.Message。返回: LegacyRawFrame。
+    异常: 新边界字段校验失败；data仅无损复制为bytes，不改timestamp/DLC/标志。
+    """
+    if len(msg.data) > 64:
+        raise ValueError('原报文data超过64字节，不能先复制再拒绝')
+    return LegacyRawFrame(timestamp=msg.timestamp, arbitration_id=msg.arbitration_id,
+        is_extended_id=msg.is_extended_id, is_remote_frame=msg.is_remote_frame,
+        is_error_frame=msg.is_error_frame, channel=msg.channel, dlc=msg.dlc, data=bytes(msg.data),
+        is_fd=msg.is_fd, is_rx=msg.is_rx, bitrate_switch=msg.bitrate_switch,
+        error_state_indicator=msg.error_state_indicator)
+
+
+def _argument_text(value, limit):
+    """只摘要原生异常参数，不执行任意对象str或先展开完整巨型消息。
+
+    参数: value为一个原args值；limit为最大字符数。返回: 有限str，短原str保持内容。
+    异常: 无主动异常；未知对象仅标明类型，不调用其自定义字符串方法。
+    """
+    if type(value) is str:
+        return value[:limit]
+    if value is None or type(value) in (bool, float):
+        return repr(value)[:limit]
+    if type(value) is int:
+        return str(value)[:limit] if value.bit_length() <= 128 else '<超过128位的整数参数>'
+    return '<参数类型:' + type(value).__name__[:64] + '>'
+
+
+def _error_packet(exc, phase, request_id):
+    """保存有限原错误事实，不把远端异常对象或任意类传给父进程。
+
+    参数: exc为本child原错；phase为有限阶段文本；request_id为当前许可或None。
+    返回: 有限ERROR dict；message是至多4个args摘要，traceback仅至多8个栈地点，
+        均不是完整str(exc)或完整traceback，截断有明确note，短单str参数保持原文本。
+    异常: 标准库字段访问/编码错误传播；调用方仍须确定退出，不伪报正常EOF。
+    """
+    # 不全量format_exception/str(exc)，仅读有限原参数及栈地点，绝不访问locals/gi_frame。
+    arguments = exc.args if type(exc.args) is tuple else ()
+    message = ', '.join(_argument_text(value, 1024) for value in arguments[:4])
+    if not arguments:
+        message = '远端异常无可安全摘要的原生args'
+    places, current = [], exc.__traceback__
+    for _ in range(8):
+        if current is None:
+            break
+        code = current.tb_frame.f_code
+        places.append(code.co_filename[:256] + ':' + str(current.tb_lineno) + ' ' + code.co_name[:128])
+        current = current.tb_next
+    trace = '\n'.join(places)
+    original_notes = getattr(exc, '__notes__', ())
+    notes = [note[:256] if type(note) is str else '<非文本note>' for note in
+        (original_notes[:8] if type(original_notes) in (tuple, list) else ())]
+    notes.append('远端message仅原args有限摘要；traceback仅有限栈地点，非完整str/trace。')
+    limit = 4096
+    while True:
+        packet = {'op': 'error', 'request_id': request_id, 'phase': phase,
+            'error': {'module': type(exc).__module__[:128], 'type': type(exc).__name__[:128],
+                'message': message[:limit], 'traceback': trace[:limit],
+                'notes': [note[:min(limit, 256)] for note in notes] + ['远端诊断有界；可能截断。']}}
+        try:
+            encode_packet(packet)
+            return packet
+        except ValueError:
+            # 每轮减半，固定包头的诊断不受输入长度放大；最短仍明确失败类型。
+            if limit <= 64:
+                return {'op': 'error', 'request_id': request_id, 'phase': phase,
+                    'error': {'module': type(exc).__module__[:32], 'type': type(exc).__name__[:32],
+                        'message': '远端错误诊断超过wire上限', 'traceback': '', 'notes': ['诊断已截断。']}}
+            limit //= 2
+
+
+def _report_error(connection, exc, phase, request_id):
+    """尽力发送原错误事实，断管不替代child原错或阻止退出。
+
+    参数: connection为本连接；exc/phase/request_id为原失败事实。返回: None。
+    异常: 不传播附加报告错误；原失败仍由worker最终非零退出表达。
+    """
+    try:
+        _send(connection, _error_packet(exc, phase, request_id))
+    except BaseException as diagnostic:
+        exc.add_note('旧CAN远端错误报告附加失败: ' + type(diagnostic).__name__)
+
+
+def worker_main(connection):
+    """作为spawn目标按INIT/PULL协议调用冻结旧公开链，等待许可时不预取。
+
+    参数: connection为父传来的独立duplex Connection。返回: 正常STOP或真实EOF时None。
+    异常: 原错误尽力发ERROR后以SystemExit(1)退出；连接/生成器附加关闭错误也非零。
+    副作用: 本child内一次load_file、一次iter_frames、每许可一次next/parse；不额外扫描。
+    """
+    iterator, failure, request_id = None, None, None
+    phase = 'init'
+    pulls_received = frames_returned = parse_calls = 0
+    try:
+        request = _request(_receive(connection))
+        phase = 'vendor'
+        files, processor, vendor = _load_vendor()
+        phase = 'dbc'
+        # 通过原模块实际导入的cantools执行唯一原load_file，不加选项或第二次解析。
+        db = processor.cantools.database.load_file(str(request.dbc_path))
+        phase = 'metadata'
+        from .binding import FrameBindingResolver
+        from .batch_worker import _parse_selected
+        from collections import Counter
+        resolver = FrameBindingResolver(db, request.fields)
+        duplicate_ids = {frame_id for frame_id, count in Counter(message.frame_id for message in db.messages).items()
+                         if count > 1}
+        phase = 'metadata'
+        fields = _field_metadata(db, request.fields)
+        iterator = files.iter_frames(str(request.input_path))
+        versions = {'python': platform.python_version(), 'python-can': metadata.version('python-can'),
+            'cantools': metadata.version('cantools'), 'natsort': metadata.version('natsort')}
+        _send(connection, {'op': 'ready', 'version': 1, 'profile': PROFILE_ID, 'worker_pid': os.getpid(),
+            'fields': fields, 'dependency_versions': versions, 'vendor_sha256': vendor})
+        # 只在收到下一条PULL时取原下一帧；STATUS/ACK/STOP均不授予此许可。
+        while True:
+            phase, request_id = 'control', None
+            packet = _receive(connection)
+            operation = packet.get('op')
+            if operation == 'stop':
+                _exact(packet, ('op',))
+                break
+            if operation == 'status':
+                _exact(packet, ('op',))
+                _send(connection, {'op': 'status', 'pulls_received': pulls_received,
+                    'frames_returned': frames_returned, 'parse_calls': parse_calls})
+                continue
+            if operation == 'ack':
+                expected = ('op', 'request_id') if 'request_id' in packet else ('op',)
+                _exact(packet, expected)
+                if 'request_id' in packet and (frames_returned == 0 or type(packet['request_id']) is not int
+                        or packet['request_id'] != frames_returned - 1):
+                    raise ValueError('ACK只允许确认最近返回ITEM')
+                _send(connection, packet)
+                continue
+            if operation != 'pull':
+                raise ValueError('未知旧CAN控制操作')
+            _exact(packet, ('op', 'request_id'))
+            candidate_id = packet['request_id']
+            request_id = candidate_id if type(candidate_id) is int and candidate_id >= 0 else None
+            if request_id is None or request_id != frames_returned:
+                raise ValueError('PULL许可必须从0严格连续')
+            pulls_received += 1
+            phase = 'next'
+            try:
+                msg = next(iterator)
+            except StopIteration:
+                # EOF需要实际多一次许可，候选发出后仍须父确认本child退出，不能靠断管猜EOF。
+                _send(connection, {'op': 'eof', 'request_id': request_id, 'frame_count': frames_returned})
+                break
+            phase = 'parse'
+            parse_calls += 1
+            fields_for_frame = resolver.fields_for(msg)
+            message = resolver.message_for(msg, fields_for_frame)
+            values = _parse_selected(processor, db, msg, message, duplicate_ids)
+            phase = 'item'
+            record = LegacyDecodedFrame(frames_returned, _frame(msg), values)
+            _send(connection, {'op': 'item', 'request_id': request_id, 'record': decoded_to_dict(record)})
+            frames_returned += 1
+            # 释放本层当前wire/记录引用，不给下一帧任何许可；旧generator内部状态不读取。
+            msg = values = record = None
+    except BaseException as exc:
+        failure = exc
+        _report_error(connection, exc, phase, request_id)
+    finally:
+        # 旧生成器close不是底层FD关闭证明；进程退出才由OS回收旧未公开reader资源。
+        if iterator is not None:
+            try:
+                iterator.close()
+            except BaseException as cleanup:
+                if failure is None:
+                    failure = cleanup
+                    _report_error(connection, cleanup, 'generator_close', request_id)
+                else:
+                    failure.add_note('旧生成器关闭附加失败: ' + type(cleanup).__name__)
+        try:
+            connection.close()
+        except BaseException as cleanup:
+            if failure is None:
+                failure = cleanup
+            else:
+                failure.add_note('旧CAN子连接关闭附加失败: ' + type(cleanup).__name__)
+    if failure is not None:
+        raise SystemExit(1)

chronaxis/migration/__init__.py

@@ -0,0 +1,11 @@
+"""公开安全旧配置导入及冻结迁移报告，不启动来源扫描或旧配置对象。
+
+输入为原INI bytes与显式mapping，或两个配置路径；输出完整静态AnalysisPlan
+和逐字段报告。当前模式能力以各入口返回的report为准；导入成功不是数据验收。
+"""
+
+from .api import import_legacy_ini, load_legacy_ini
+from .models import LegacyFieldMapping, LegacyImportIssue, LegacyImportReport, LegacyImportResult
+
+__all__ = ['import_legacy_ini', 'load_legacy_ini', 'LegacyImportResult', 'LegacyImportReport',
+           'LegacyImportIssue', 'LegacyFieldMapping']

chronaxis/migration/api.py

@@ -0,0 +1,270 @@
+"""提供纯字节旧INI导入与显式配置文件的加载入口，不读取分析数据。
+
+共享流程检查原生JSON mapping、保存身份、复制analysis并固定词法绝对路径，
+按模式转换后调用公开AnalysisPlan.from_dict/validate_analysis_plan。配置语义错误返回
+整份失败报告；API类型、文件I/O、内存与取消错误保持原生异常，不伪装成成功。
+支持Sclicer single/start_only、显式slope/start_end迁移和当前消息legacy_sum；不承诺旧完整缓存等价。
+"""
+
+import hashlib
+import json
+from dataclasses import replace
+from pathlib import Path
+
+from ..configuration import load_configuration, ConfigurationError, field_path_text
+from ..configuration.diagnostics import locate_error, field_path_parts
+from ..planning import AnalysisPlan, PlanValidationError, validate_analysis_plan
+from ..planning.checks import absolute_path, require_json_value
+from .ini import ImportProblem, parse_ini, problem
+from .models import LegacyImportIssue, LegacyImportReport, LegacyImportResult
+from .sclicer import convert_sclicer
+from .legacy_sum import convert_legacy_sum
+
+MODES = ('legacy_sum', 'sclicer_single', 'sclicer_start_only', 'sclicer_slope', 'sclicer_start_end')
+
+
+def _arguments(content, mapping, mode, base_dir, source_name, device_label):
+    """先核公开API类型，不把编程错误包成迁移拒绝。
+
+    参数: 原公开入口参数。返回: None。异常: TypeError为原生类型错误；ValueError为未知mode。
+    """
+    if type(content) is not bytes or type(mapping) is not dict:
+        raise TypeError('content需要bytes，mapping需要原生dict')
+    if type(mode) is not str or type(source_name) is not str or type(device_label) is not str:
+        raise TypeError('mode/source_name/device_label需要原生str')
+    if not isinstance(base_dir, (str, Path)):
+        raise TypeError('base_dir需要str或Path')
+    if mode not in MODES:
+        raise ValueError('未知导入mode：' + mode)
+
+
+def _report(content, mode, source_name, device_label, mapping_identity, fields, issues, plan):
+    """封装整份结果；参数: 本次原事实；返回: LegacyImportResult；异常: 资源错误原样传播。"""
+    report = LegacyImportReport('success' if plan is not None else 'failed', mode, source_name,
+        hashlib.sha256(content).hexdigest(), mapping_identity, device_label,
+        tuple(fields), tuple(issues), None if plan is None else plan.identity)
+    return LegacyImportResult(plan, report, content)
+
+
+def _prepare_mapping(mapping, base):
+    """检查完整mapping合同并复制为独立可修改分析配置。
+
+    参数: mapping原生对象；base词法绝对目录。返回: (独立mapping, identity)。
+    异常: ImportProblem/PlanValidationError为配置问题。目录输入会展开文件集合，缺省CAN声明会读取DBC。
+    """
+    require_json_value(mapping, '$')
+    required = {'mapping_version', 'analysis'}
+    if not required <= set(mapping) or set(mapping) - required - {'aliases', 'sections', 'path_base', 'io_policy'}:
+        problem('invalid_mapping_shape', 'mapping', '$', 'mapping需要版本、analysis；aliases、sections、路径与IO策略可选')
+    if type(mapping['mapping_version']) is not int or mapping['mapping_version'] != 1:
+        problem('invalid_mapping_version', 'mapping', '$.mapping_version', '仅支持原生整数1')
+    if mapping.get('path_base', 'mapping_directory') != 'mapping_directory' or mapping.get('io_policy', 'explicit_mapping') != 'explicit_mapping':
+        problem('invalid_mapping_policy', 'mapping', '$', '路径与IO策略只支持mapping_directory及explicit_mapping')
+    # 身份识别原mapping；路径固定和新节点仅发生于后续独立副本。
+    encoded = json.dumps(mapping, ensure_ascii=False, allow_nan=False, sort_keys=True, separators=(',', ':'))
+    identity = hashlib.sha256(encoded.encode('utf-8')).hexdigest()
+    copied = json.loads(encoded)
+    copied.setdefault('aliases',{})
+    copied.setdefault('sections',{})
+    analysis, aliases, sections = copied['analysis'], copied['aliases'], copied['sections']
+    if type(analysis) is not dict or type(aliases) is not dict or type(sections) is not dict:
+        problem('invalid_mapping_shape', 'mapping', '$', 'analysis/aliases/sections必须为对象')
+    if 'imports' in analysis:
+        problem('unresolved_imports','mapping','$.analysis.imports',
+                '纯字典映射不读取公共定义；请用load_legacy_ini加载映射文件或先config resolve')
+    from ..planning.config_groups import normalize_configuration
+    analysis=copied['analysis']=normalize_configuration(analysis)
+    for key in ('rules', 'windows', 'message_calculations', 'presets'):
+        if key in analysis and (type(analysis[key]) is not list or analysis[key]):
+            problem('nonempty_generated_nodes', 'mapping', '$.analysis.' + key, '导入前该数组必须缺省或为空')
+    signals = analysis.get('signals')
+    if type(signals) is not list:
+        problem('missing_signal_mapping', 'mapping', '$.analysis.signals', '必须显式声明signals数组')
+    from ..planning.signal_groups import signal_entries
+    signals=analysis['signals']=[dict(item) for item,_ in signal_entries(signals)]
+    names = set()
+    for index, signal in enumerate(signals):
+        if type(signal) is not dict:
+            problem('invalid_signal_mapping', 'mapping', f'$.analysis.signals[{index}]', 'signal必须为对象')
+        # 有效期可按用户周期或运行时DBC周期确定，由公共计划执行同一套检查。
+        for key in ('name',):
+            if key not in signal:
+                problem('missing_signal_metadata', 'mapping', f'$.analysis.signals[{index}].{key}', '不得猜测信号声明：' + key)
+        if type(signal['name']) is str:
+            names.add(signal['name'])
+    # 原字段只有一个候选才自动对应；明确aliases始终优先，不从表达式名称猜测。
+    candidates={}
+    for signal in signals:
+        field=signal.get('field')
+        original=field.get('signal') if type(field) is dict else field
+        if type(original) is str:candidates.setdefault(original,[]).append(signal['name'])
+    for original,choices in candidates.items():
+        if len(choices)==1:aliases.setdefault(original,choices[0])
+    for old, new in aliases.items():
+        if type(new) is not str or new not in names or not old.strip():
+            problem('invalid_alias', 'mapping', '$.aliases.' + old, '原名称须明确映射至analysis.signals别名')
+    # 不同旧Name可由用户显式指向同一新信号；每个旧键仍只有一个明确目标。
+    # JSON/YAML重复旧键由加载器拒绝，未知目标在上面拒绝，不能借此猜测字段关系。
+    # 只固定公开来源路径，不递归猜测任意metadata中的路径文本。
+    sources = analysis.get('sources')
+    if type(sources) is not list:
+        problem('missing_source_mapping', 'mapping', '$.analysis.sources', '必须显式声明sources数组')
+    for index, source in enumerate(sources):
+        if type(source) is not dict:
+            problem('invalid_source_mapping', 'mapping', f'$.analysis.sources[{index}]', 'source必须为对象')
+        # 导入与普通入口使用同一来源默认规则，不要求再次填写格式/时间/名称。
+        from ..planning.input_defaults import source_defaults
+        from ..planning.input_paths import FILE_SUFFIXES, expand_source_files
+        # 既有单文件声明保持原字段形态；只有集合声明才输出展开后的paths。
+        single_path = (type(source.get('path')) is str and Path(source['path']).suffix.lower() in FILE_SUFFIXES
+                       and not source['path'].endswith(('/', '\\')))
+        if source.get('source_type') != 'memory' and ('path' in source or 'paths' in source):
+            paths, shifts = expand_source_files(source,base,f'$.analysis.sources[{index}]')
+            source = dict(source, paths=[str(item) for item in paths])
+            source.pop('path',None)
+            if shifts is not None:
+                source['offsets'] = list(shifts)
+        source = source_defaults(source, index)
+        if single_path and 'paths' in source:
+            source['path'] = source.pop('paths')[0]
+        sources[index] = source
+        path = f'$.analysis.sources[{index}]'
+        if 'path' in source:
+            source['path'] = str(absolute_path(source['path'], base, path + '.path'))
+        if 'paths' in source:
+            if type(source['paths']) is not list:
+                problem('invalid_source_mapping', 'mapping', path + '.paths', 'paths必须为数组')
+            source['paths'] = [str(absolute_path(value, base, path + '.paths')) for value in source['paths']]
+        if 'dbc_by_channel' in source:
+            if type(source['dbc_by_channel']) is not dict:
+                problem('invalid_source_mapping', 'mapping', path + '.dbc_by_channel', 'dbc_by_channel必须为对象')
+            source['dbc_by_channel'] = {key: str(absolute_path(value, base, path + '.dbc_by_channel.' + key))
+                                        for key, value in source['dbc_by_channel'].items()}
+    # 仅缺省声明/定位才编译来源和信号；完整旧映射不新增DBC访问。
+    if any('dtype' not in item or 'unit' not in item or 'source' not in item
+           or type(item.get('field')) is dict and 'channel' not in item['field'] for item in signals):
+        from ..planning.inputs import parse_sources, parse_signals
+        source_models=parse_sources(sources,base)
+        typed=parse_signals(signals,source_models)
+        for raw,model in zip(signals,typed):
+            raw.setdefault('dtype',model.definition.dtype.value)
+            raw.setdefault('unit',model.definition.unit)
+            raw.setdefault('source',model.definition.source)
+            if model.definition.choices:raw.setdefault('choices',[list(pair) for pair in model.definition.choices])
+            if type(raw.get('field')) is dict:
+                source=next(s for s in source_models if s.name==model.definition.source)
+                raw['field'].setdefault('channel',source.config.channel + 1)
+    return copied, identity
+
+
+def import_legacy_ini(content: bytes, mapping: dict, *, mode, base_dir,
+                      source_name='input.ini', device_label='pending') -> LegacyImportResult:
+    """从原INI字节和显式mapping生成完整静态计划或整份拒绝报告。
+
+    参数: content为原bytes，mapping为JSON对象；mode选择合同模式；base_dir
+    为mapping目录；source_name/device_label只标识来源。返回: LegacyImportResult，
+    original_ini保同一bytes，失败plan为None。异常: API类型/未知mode、OSError、
+    MemoryError及取消保持原对象；配置语义与UTF-8错误进入report，不返回部分计划。
+    """
+    _arguments(content, mapping, mode, base_dir, source_name, device_label)
+    fields, issues, identity = [], [], None
+    try:
+        try:
+            text = content.decode('utf-8-sig')
+        except UnicodeDecodeError as error:
+            problem('invalid_ini_encoding', 'ini', '$', str(error))
+        base = Path(base_dir).absolute()
+        try:
+            copied, identity = _prepare_mapping(mapping, base)
+        except PlanValidationError as error:
+            problem(error.code, 'mapping', error.path,
+                error.message+('；修正：'+error.hint if error.hint else ''))
+        parser, headers = parse_ini(text, fields, preserve_case=mode == 'legacy_sum')
+        if 'sections' not in mapping:
+            if mode in ('sclicer_single','sclicer_start_only','sclicer_start_end'):
+                for number,section in enumerate((s for s in parser.sections() if s.startswith('TRIGGER_')),1):
+                    item=dict(name=f'trigger_{number}',window=f'window_{number}')
+                    if mode=='sclicer_start_end':item.update(semantics='start_end_timeout-v1',emit_initial=False)
+                    copied['sections'][section]=item
+            else:
+                problem('missing_section_parameters','mapping','$.sections','该模式仍需提供计算单位或slope参数，不能从段名猜测')
+        analysis = copied['analysis']
+        if mode == 'legacy_sum':
+            convert_legacy_sum(parser, headers, copied, analysis, fields, issues)
+        else:
+            convert_sclicer(parser, headers, copied, analysis, fields, issues, mode)
+        try:
+            from ..planning.config_groups import public_configuration
+            plan = AnalysisPlan.from_dict(public_configuration(analysis), base_dir=base)
+            validation = validate_analysis_plan(plan)
+        except PlanValidationError as error:
+            # 新条件错误仍回指原字段；其他计划配置错误明确归mapping，不制造INI行号。
+            original = next((item for item in fields if item.target == error.path), None)
+            problem(error.code, 'ini' if original else 'mapping', original.path if original else error.path,
+                    error.message+('；修正：'+error.hint if error.hint else ''),
+                    original.line if original else None, original.column if original else None)
+        if not validation.valid or not validation.execution_ready:
+            problem('plan_unavailable', 'plan', '$', '; '.join(validation.errors))
+        for warning in validation.warnings:
+            issues.append(LegacyImportIssue('static_unverified', 'plan', '$', warning, level='warning'))
+        return _report(content, mode, source_name, device_label, identity, fields, issues, plan)
+    except ImportProblem as error:
+        issues.append(error.issue)
+        return _report(content, mode, source_name, device_label, identity, fields, issues, None)
+
+
+
+def load_legacy_ini(ini_path, mapping_path, *, mode, device_label='pending') -> LegacyImportResult:
+    """只读INI、映射及显式一层公共定义，来源路径基准按实际声明文件确定。
+
+    参数: ini_path/mapping_path为str或Path；mode/device_label同字节API。
+    返回: LegacyImportResult，非法JSON/YAML给mapping定位。异常: API类型、未知mode、
+    文件读取OSError、MemoryError及取消原样传播；按声明展开目录及读取缺省信号所需DBC，不读取业务报文。
+    """
+    if not isinstance(ini_path, (str, Path)) or not isinstance(mapping_path, (str, Path)):
+        raise TypeError('配置路径需要str或Path')
+    # API参数先校验，不能在明显编程错误下先触发文件读取。
+    _arguments(b'', {}, mode, mapping_path, str(ini_path), device_label)
+    ini, mapping_file = Path(ini_path), Path(mapping_path).absolute()
+    content = ini.read_bytes()
+    try:
+        document = load_configuration(mapping_file)
+        from ..configuration.imports import expand_document_imports
+        document = expand_document_imports(document)
+        mapping = document.data
+    except PlanValidationError as error:
+        location=error.location
+        issue=LegacyImportIssue(error.code,'mapping',error.path,str(error),
+            None if location is None else location.line,None if location is None else location.column)
+        return _report(content,mode,str(ini),device_label,None,(),(issue,),None)
+    except ConfigurationError as error:
+        # 文件IO沿用导入API的原生异常合同；语法错误则进入可发布的迁移报告。
+        if error.code=='load_error' and isinstance(error.__cause__,OSError):
+            raise error.__cause__
+        syntax_code='invalid_mapping_yaml' if mapping_file.suffix.lower() in ('.yaml','.yml') else 'invalid_mapping_json'
+        code={'duplicate_key':'duplicate_mapping_key','nonfinite_number':'invalid_mapping_number',
+              'invalid_number':'invalid_mapping_number','unsupported_format':'unsupported_mapping_format'}.get(error.code,syntax_code)
+        location=error.location
+        issue=LegacyImportIssue(code,'mapping',field_path_text(error.field_path),str(error),
+            None if location is None else location.line,None if location is None else location.column)
+        return _report(content,mode,str(ini),device_label,None,(),(issue,),None)
+    if type(mapping) is not dict:
+        return _report(content, mode, str(ini), device_label, None, (),
+            (LegacyImportIssue('invalid_mapping_shape', 'mapping', '$', 'mapping配置根必须为对象'),), None)
+    result=import_legacy_ini(content, mapping, mode=mode, base_dir=mapping_file.parent,
+                             source_name=str(ini), device_label=device_label)
+    # 只补映射原文的错误位置。INI字段的行列已由迁移器确定，不能套映射位置。
+    issues=[]
+    for issue in result.report.issues:
+        parts=field_path_parts(issue.path)
+        if issue.origin!='mapping' or parts is None:
+            issues.append(issue)
+            continue
+        # 转换后计划路径从analysis内部开始，原mapping校验路径则已带前缀。
+        if parts and parts[0] not in mapping and ('analysis',*parts[:-1]) in document.locations:
+            parts=('analysis',*parts)
+        error=locate_error(PlanValidationError(field_path_text(parts),issue.message,issue.code),document)
+        location=error.location
+        issues.append(replace(issue,path=error.path,message=str(error),
+            line=None if location is None else location.line,column=None if location is None else location.column))
+    return replace(result,report=replace(result.report,issues=tuple(issues)))