# HYD-SCHED 架构设计说明书

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

---

## 2. 分层架构图
使用 Mermaid 描述的逻辑分层架构：

```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 日志栈，供前端回显。