wangsli
11a2d4a4b9
- Core: Python/C++/MATLAB tri-protocol bridge architecture - Validation: 5-type real-time field, type, dimension, completeness, and compatibility checking - UI: Premium Deep Sea theme with visual pipeline preview - Modules: Sea Trial Exclusive + Exception Hub + Algorithm Management - Tests: Full coverage with 5 automated test cases
142 行
6.9 KiB
Markdown
142 行
6.9 KiB
Markdown
# 🌊 水声算法全协议集成与调度平台 项目审查报告
|
||
|
||
---
|
||
|
||
## 一、项目概况
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **项目名称** | 水声算法全协议集成与调度平台 |
|
||
| **目标客户** | 高校水声实验室、研究所、海试现场测试团队 |
|
||
| **团队规模** | 2-3 人，核心技术栈 Python |
|
||
| **当前状态** | Phase 1 已完成（核心框架），Phase 2-5 待开发 |
|
||
|
||
---
|
||
|
||
## 二、项目目标
|
||
|
||
| 目标类型 | 描述 |
|
||
|----------|------|
|
||
| **功能目标** | 多语言算法统一纳管、零代码接口适配、跨语言混编调度、全流程容错溯源、海试数据质量检测 |
|
||
| **性能目标** | 轻量化离线部署、1GB 数据 ≤5 分钟、容错率 ≥95%、C/C++ 原生性能 |
|
||
| **体验目标** | Web 可视化、10 分钟上手、人话错误提示、一键修复 |
|
||
| **商业目标** | 快速落地、预留工业级拓展接口 (C++/Qt) |
|
||
|
||
---
|
||
|
||
## 三、系统架构（五层设计）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户交互层 (Streamlit) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 核心调度层 (CoreScheduler) │
|
||
│ 流程调度 | 实时校验 | 容错处理 | 日志记录 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 桥接插件层 (Bridges) │
|
||
│ PythonBridge | MATLABBridge | CppBridge │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 算法层 (标准库 + 自定义库) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 数据层 (WaterSoundData) │
|
||
│ 原始数据 | 过程数据 | 结果数据 | 元信息 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 四、已完成模块 (Phase 1)
|
||
|
||
| 模块 | 文件 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| 数据标准 | `src/models.py` | ✅ 完成 | `WaterSoundData` 统一数据交换格式 |
|
||
| Python 桥接 | `src/bridges.py` | ✅ 完成 | `AlgorithmBridge` 抽象类 + `PythonBridge` 实现 |
|
||
| 核心调度 | `src/scheduler.py` | ✅ 完成 | `CoreScheduler` 流程执行与日志记录 |
|
||
| Web 界面 | `main.py` | ✅ 完成 | Streamlit 首页 + 算法调度演示页 |
|
||
| 集成测试 | `tests/test_core.py` | ✅ 通过 | 验证多算法链式调用 |
|
||
|
||
---
|
||
|
||
## 五、技术风险分析与应对策略
|
||
|
||
### 5.1 核心风险点
|
||
|
||
| 风险 | 级别 | 分析 | 应对策略 |
|
||
|------|------|------|----------|
|
||
| **C++ 编译器环境** | 🔴 高 | Windows 上 MinGW 路径配置是非开发人员的噩梦 | **优雅降级**：无编译器时禁用 C++ 上传功能，而非强行引导安装 |
|
||
| **Streamlit 拖拽限制** | 🟡 中 | 原生不支持复杂连线 | **列表式调度**：先用上下移动排序，跑通再考虑 Canvas 可视化 |
|
||
| **MATLAB Octave 差异** | 🟡 中 | oct2py 对复杂 Toolbox 支持有限 | **文档说明**：推荐 MATLAB，兼容模式注明精度差异 |
|
||
| **大数据内存** | 🟢 低 | 10GB 单文件场景少见，海试数据多分段采集 | **后期优化**：Phase 4 再引入 memmap |
|
||
|
||
### 5.2 设计原则
|
||
|
||
> **先让系统跑起来，再让系统跑得好。**
|
||
|
||
避免过早优化，聚焦最小可用版本 (MVP)。
|
||
|
||
---
|
||
|
||
## 六、修订后实施计划
|
||
|
||
### Phase 2：算法库与接口配置（预计 5 天）— **MVP 聚焦**
|
||
|
||
| 任务 | 描述 | 产出物 | 优先级 |
|
||
|------|------|--------|--------|
|
||
| 2.1 算法上传 | Python 文件上传、版本自动打标 | `src/algo_library.py` | P0 |
|
||
| 2.2 元数据存储 | JSON 持久化算法信息 | `data/algorithms.json` | P0 |
|
||
| 2.3 接口映射 | 下拉选择字段、简单预处理 | `src/interface_config.py` | P0 |
|
||
| 2.4 实时校验 | 5 类校验规则实现 | `src/validators.py` | P0 |
|
||
| 2.5 流程排序 | 列表式上下移动（不做拖拽） | 界面更新 | P1 |
|
||
|
||
### Phase 3：多语言桥接（预计 4 天）
|
||
|
||
| 任务 | 描述 | 产出物 | 优先级 |
|
||
|------|------|--------|--------|
|
||
| 3.1 MATLAB 桥接 | matlab.engine + oct2py 兜底 | `src/bridges_matlab.py` | P0 |
|
||
| 3.2 C++ 编译检测 | 检测 gcc，无则禁用 C++ 功能 | `src/cpp_compiler.py` | P1 |
|
||
| 3.3 C++ 桥接 | ctypes 加载（仅限有编译器环境） | `src/bridges_cpp.py` | P1 |
|
||
|
||
### Phase 4：容错与溯源（预计 3 天）
|
||
|
||
| 任务 | 描述 | 产出物 |
|
||
|------|------|--------|
|
||
| 4.1 三层容错 | 配置拦截、转换修复、执行兜底 | `src/fault_tolerance.py` |
|
||
| 4.2 溯源日志 | 结构化日志、时间轴展示 | `src/traceability.py` |
|
||
| 4.3 异常中心 | 错误列表、一键跳转修复 | 界面页 |
|
||
| 4.4 大数据优化 | memmap + 分块处理（可选） | 性能优化 |
|
||
|
||
### Phase 5：海试专属与打包（预计 3 天）
|
||
|
||
| 任务 | 描述 | 产出物 |
|
||
|------|------|--------|
|
||
| 5.1 海试模式 | 简化界面、内置质量检测流程 | `src/seatrial_mode.py` |
|
||
| 5.2 报告生成 | PDF/Excel 导出 | `src/report_generator.py` |
|
||
| 5.3 产品打包 | PyInstaller 生成可执行文件 | 交付包 |
|
||
|
||
---
|
||
|
||
## 七、里程碑时间线（总计 15 天 — 海音·智调 1.0 版本）
|
||
|
||
```
|
||
Week 1: Phase 2 (算法库 + 接口配置) — MVP 核心
|
||
Week 2: Phase 3 (MATLAB + C++ 桥接) — 多语言支持
|
||
Week 3: Phase 4 + 5 (容错 + 海试 + 打包) — 产品化
|
||
```
|
||
|
||
---
|
||
|
||
## 八、关键决策记录
|
||
|
||
| 决策 | 理由 | 日期 |
|
||
|------|------|------|
|
||
| 暂定全称为：水声算法全协议集成与调度平台 | 回归技术本质，强调“全协议”兼容性，品牌名称推迟至发布前确定 | 2026-01-20 |
|
||
| 采用列表式调度而非拖拽连线 | Streamlit 原生限制 + 开发成本 | 2026-01-20 |
|
||
| C++ 环境采用"优雅降级"策略 | 避免非开发人员配置编译器的门槛 | 2026-01-20 |
|
||
| 大数据 memmap 优化推迟至 Phase 4 | 目标场景以分段数据为主，10GB 单文件少见 | 2026-01-20 |
|
||
| 算法能力标签系统简化为"类型下拉" | 降低上传门槛，后期再细化 | 2026-01-20 |
|
||
|
||
---
|
||
|
||
*报告生成时间：2026-01-20*
|
||
*最后更新：2026-01-20 20:19*
|