acoustic_algo_scheduler/docs/ARCHITECTURE.md

HYD-SCHED 架构设计说明书

1. 总体设计思想

HYD-SCHED (海音达算法智能调度平台) 旨在解决水声算法研发中“多语言并存、数据接口不统一、环境耦合深”的问题。 其架构核心为：“元数据驱动、五维拦截校验、全协议桥接转发”。

---

2. 分层架构图

使用 Mermaid 描述的逻辑分层架构：

graph TD
    SubGraph_UI["<b>1. 表现层 (Streamlit UI)</b>"]
    SubGraph_Sched["<b>2. 调度执行层 (Scheduler Core)</b>"]
    SubGraph_Bridge["<b>3. 桥接协议层 (Polyglot Bridges)</b>"]
    SubGraph_Data["<b>4. 数据/领域层 (Core Data Model)</b>"]
    SubGraph_Infra["<b>5. 基础设施与检测 (Infra & Detect)</b>"]

    SubGraph_UI --> SubGraph_Sched
    SubGraph_Sched --> SubGraph_Bridge
    SubGraph_Bridge --> SubGraph_Data
    SubGraph_Bridge --> SubGraph_Infra

    style SubGraph_UI fill:#0077b6,color:#fff
    style SubGraph_Sched fill:#0096c7,color:#fff
    style SubGraph_Bridge fill:#00b4d8,color:#fff
    style SubGraph_Data fill:#90e0ef,color:#333
    style SubGraph_Infra fill:#caf0f8,color:#333

---

3. 核心领域模块说明

A. 展现层 (main.py)

• 英雄概览 (Hero Hub)：平台入口，展示核心能力与环境状态。
• 算法编排 (Scheduling)：图形化配置算法链路，支持拖拽语义（上下移动按钮）。
• 异常中心 (Exception Hub)：聚合静态校验（validator）与动态执行（runtime）日志，支持问题包导出。

B. 调度与编排 (src/scheduler.py | src/validator.py)

• 流式编排：负责管理桥接对象（Bridges）的执行顺序。
• 五维联合校验 (Validator)：
  1. 字段存在度：校验 input_mapping 中的字段是否在 WaterSoundData 中。
  2. 数据类型：校验输入输出是否匹配（NDArray vs Float 等）。
  3. 空间一致性：校验数组维度是否满足算法数学要求。
  4. 完整性（路径+哈希）：校验动态库 (.so) 或脚本 (.m) 路径是否存在，并可选启用 SHA256 完整性校验（src/integrity.py）。
  5. 跨环境兼容性：结合 env_detect 判断当前机器是否具备执行该类型算法的能力。

C. 全协议桥接层 (src/bridges.py)

桥接器	实现机制	优势
PythonBridge	动态 importlib 加载	原生性能，易于调试
CppBridge	ctypes 指针深度透传 / 可选子进程隔离（src/cpp_isolated_runner.py）	计算密集型算子首选，零拷贝；隔离模式可避免段错误拖垮主进程
MatlabBridge	三级降级 (Engine/Oct2py/CLI)	跨平台及离线环境的最大兼容

D. 数据模型层 (src/models.py)

• WaterSoundData (WSD)：系统唯一的标准数据交换格式（核心为 raw_data + meta）。
• 结果回写机制：无论算法类型为何，最终所有结果均通过桥接器标准化回写至 WSD 对象的特定字段。

E. 资产与管理 (src/algo_manager.py | data/algorithms.json)

• 元数据驱动：通过 JSON 配置文件定义算法的输入输出 Spec，实现算法资产的非侵入式入库。

---

4. 关键流程：一键调度执行

1. 扫描与构建：AlgorithmManager 加载元数据。
2. 链路实例化：UI 根据算法类型构造对应的 Bridge 实例。
3. 安全自检：FlowValidator 执行五维校验，若不通过则在异常中心报警。
4. 串联执行：CoreScheduler 遍历链路，依次更新 WaterSoundData 状态。
5. 日志闭环：每一步操作实时记录至 WSD 日志栈，供前端回显。