feat: v3.5 - Multi-language acoustic algorithm scheduler
- 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
这个提交包含在：
@@ -0,0 +1,172 @@
|
||||
# 水声算法全协议集成与调度平台 - 需求规格说明书
|
||||
文档信息
|
||||
项目 内容
|
||||
文档版本 V1.0
|
||||
编写日期 2026.01
|
||||
适用范围 软件研发、测试、交付、客户使用指导
|
||||
目标客户 高校水声实验室、水声领域研究所、海试现场测试团队
|
||||
一、项目背景与目标
|
||||
1.1 项目背景
|
||||
当前水声算法研发场景中，存在多语言算法混用（Python/MATLAB/C/C++）、接口定义混乱、算法迭代频繁、跨语言调用复杂等问题，高校 / 研究所科研人员需投入大量精力解决工程适配问题，而非聚焦算法本身；海试现场则面临设备轻量化、操作零门槛、离线处理、快速出结果的核心诉求，现有工具无法同时满足科研试错与工程应用的双重需求。
|
||||
本公司作为 2-3 人规模的水声算法科技企业，依托 Python 核心技术栈，打造一款轻量化、高适配、零门槛的水声算法智能调度处理软件，解决行业核心痛点。
|
||||
1.2 项目目标
|
||||
功能目标：实现多语言算法统一纳管、复杂接口零代码适配、跨语言算法自由组合调度、全流程自动化处理与容错溯源，支持海试数据质量检测专属场景。
|
||||
性能目标：轻量化离线部署，客户侧零硬件成本，支持大体积水声数据分块处理，跨语言算法调用性能与原生调用持平，整体容错率≥95%。
|
||||
体验目标：Web 界面可视化操作，全程零代码 / 极简代码，客户无需掌握工程开发知识，10 分钟即可上手，错误可自主快速修复。
|
||||
商业目标：贴合微型企业研发节奏，快速落地商业化，同时预留工业级拓展接口，支撑长远业务发展。
|
||||
二、核心需求
|
||||
2.1 总体功能需求
|
||||
软件整体分为算法库管理模块、接口配置模块、算法调度模块、数据处理模块、容错溯源模块、客户扩展模块、海试专属模块七大核心模块，所有功能均通过 Web 界面实现，支持本地离线运行，无网络依赖。
|
||||
2.2 详细功能需求
|
||||
2.2.1 算法库管理模块
|
||||
双仓库管理
|
||||
内置官方标准算法库：包含水声通用算法（降噪、特征提取、频谱分析、数据清洗、质量检测等），支持一键调用、免费迭代更新。
|
||||
开放客户自定义算法库：支持客户上传自研算法，兼容 Python/MATLAB/C/C++ 多语言，算法按 “语言 - 名称 - 版本” 分类展示，支持搜索、筛选。
|
||||
黑盒化封装
|
||||
所有算法（标准 / 自研、任意语言）均封装为标准化黑盒插件，对内保留完整算法逻辑，对外仅暴露基于标准化中间数据的输入输出接口。
|
||||
系统自动完成算法的黑盒化处理，客户无需做任何封装、编译、转换操作。
|
||||
版本化管理
|
||||
支持算法多版本保存，自动按 “V + 数字” 打标版本号，也支持客户自定义版本号与版本备注。
|
||||
支持算法版本一键切换、回滚，可选择任意版本作为当前调用版本，无需重新配置接口。
|
||||
支持两个版本算法的效果对比：用同一组测试数据运行，自动生成维度、核心指标、可视化结果的对比报告。
|
||||
保留所有版本的修改日志（修改人、修改时间、备注），支持版本溯源与无用版本轻量删除。
|
||||
2.2.2 接口配置模块
|
||||
双接口模式
|
||||
通用接口模式：预设水声行业标准输入输出字段（如输入：清洗后数据 + 采样率；输出：特征数组 + 信噪比），一键调用，无需配置，适配 80% 常规场景。
|
||||
自定义接口模式：支持复杂接口零代码配置，适配科研试错的个性化需求。
|
||||
零代码配置能力
|
||||
支持通过下拉选择、字段拖拽、多字段组合完成输入 / 输出接口与标准化中间数据的映射。
|
||||
支持为映射字段添加轻量预处理，内置预处理算子库（维度展平 / 取维 / 切片、类型转换、归一化 / 标准化、空值过滤、平滑滤波等），一键选择即可应用。
|
||||
支持预处理规则保存为个人模板，后续配置可直接复用。
|
||||
实时强制校验
|
||||
配置过程中实时完成5 类核心校验，配错即时弹窗提示 + 红色高亮错误位置，错误配置无法保存：
|
||||
① 字段存在性校验：校验映射字段是否在标准化中间数据中存在 / 由前序算法生成；
|
||||
② 数据类型校验：校验字段类型与算法输入要求是否匹配；
|
||||
③ 数据维度校验：检测字段维度是否符合算法常规要求，不匹配则推荐预处理方案；
|
||||
④ 参数完整性校验：多参数映射时校验是否漏配，高亮未配置参数；
|
||||
⑤ 跨语言兼容性校验：配置非 Python 算法时，校验数据跨语言转换的兼容性。
|
||||
接口模板管理
|
||||
配置完成的通用 / 自定义接口均可保存为接口模板，标注模板名称与适用场景，后续调用算法可直接绑定模板，无需重新配置。
|
||||
2.2.3 算法调度模块
|
||||
可视化流程组合
|
||||
支持 Web 界面鼠标拖拽排序，自由组合官方标准算法与客户自研算法，支持 Python/MATLAB/C/C++ 跨语言混编。
|
||||
组合完成后系统自动做流程全局校验，校验前序算法输出与后序算法输入的接口衔接性，不匹配则即时提示并给出修复建议。
|
||||
文字指令智能调度
|
||||
支持客户输入自然语言指令（如 “检测海试声呐数据质量”“浅海低信噪比数据降噪 + STFT 特征提取”），系统自动解析意图、匹配场景算法，生成并执行调度流程。
|
||||
自动化调度执行
|
||||
按客户设定的顺序自动调度算法黑盒，全程完成标准化数据→语言专属数据→标准化数据的双向转换，客户无感知。
|
||||
支持非依赖型算法并行调度，提升大体积数据处理效率。
|
||||
执行过程中 Web 界面实时展示进度条 + 执行日志，显示当前执行算法、处理进度、耗时等信息。
|
||||
流程模板管理
|
||||
组合完成的算法调度流程可保存为流程模板（如 “海试数据质量检测流程”“浅海算法处理流程”），支持模板一键加载、修改、删除。
|
||||
2.2.4 数据处理模块
|
||||
标准化中间数据管理
|
||||
定义WaterSoundData为唯一数据交换标准，包含四大核心字段，支撑全流程数据流转：
|
||||
① 基础原始数据：原始声呐数据、采样率、采集时间、海洋环境参数等；
|
||||
② 处理过程数据：清洗后数据、降噪后数据、时频数据、特征数组等中间结果；
|
||||
③ 结果数据：最终处理结果、核心指标、可视化数据等；
|
||||
④ 元信息：数据状态、执行日志、错误信息、算法版本记录等。
|
||||
多语言数据转换
|
||||
由语言专属桥接插件完成无损数据转换，优先采用内存级传递（内存直接映射 / 指针传递）保证高性能，失败则采用文件级兜底（.npy/.mat/.bin 水声专属轻量化格式）。
|
||||
转换过程中自动完成数据类型、维度的适配，保证数据值与结构不丢失。
|
||||
大体积数据处理
|
||||
支持大体积水声数据自动分块处理，按水声数据特性拆分数据，逐块处理后自动合并结果，避免内存 / CPU 超限。
|
||||
分块规则可由客户在 Web 界面简单配置（如分块大小、合并方式），也可由系统自动适配。
|
||||
2.2.5 容错溯源模块
|
||||
三层递进容错体系
|
||||
配置阶段：实时校验 + 强制拦截，从根源拦截 90% 接口配置错误；
|
||||
转换阶段：自动兜底适配，对维度 / 类型不兼容、空值 / 无穷值、跨语言数据丢失等问题自动修复，修复过程记录日志；
|
||||
执行阶段：隔离式容错 + 降级执行，单个算法出错立即隔离，不影响整体流程；核心算法出错则自动调用同功能官方标准算法兜底执行，保证核心功能不丢失。
|
||||
可视化异常处理
|
||||
所有错误在 Web 界面异常中心集中展示，给出人话提示 + 一键修复建议，无需专业知识即可理解问题根源。
|
||||
支持异常快速定位，点击异常信息可直接跳转到对应的配置 / 执行页面，方便客户修改。
|
||||
全流程溯源
|
||||
自动生成结构化溯源日志，记录从接口配置→数据转换→算法执行→结果输出的每一步操作、数据变化、容错处理，按时间顺序排列，高亮异常步骤。
|
||||
自动生成接口配置校验报告，包含配置信息、校验结果、适配建议，支持日志与报告的在线查看、一键导出（JSON/Excel 格式）。
|
||||
错误修改便捷性
|
||||
接口配置与算法解耦，修改算法代码 / 参数无需重新配置接口，上传新文件即生效；
|
||||
所有修改操作均在原配置 / 执行界面完成，无需跳转其他页面，改完即保存、重新执行。
|
||||
2.2.6 客户扩展模块
|
||||
多语言算法上传
|
||||
支持客户上传各语言算法原始文件，操作极简，无需额外处理：
|
||||
① Python：上传.py 文件 / 直接粘贴函数代码；
|
||||
② MATLAB：上传.m 文件 / 直接粘贴函数代码；
|
||||
③ C/C++：上传单个.c/.cpp 文件 / 多文件压缩包，仅需填写核心函数名。
|
||||
系统自动完成 C/C++ 算法的编译（生成跨平台动态链接库）、所有语言算法的黑盒化封装，客户无感知。
|
||||
两种扩展方式
|
||||
零代码表单式（推荐，适配非开发岗）：全程 Web 界面选择、配置，无需写任何代码；
|
||||
极简代码式（适配开发岗）：提供封装好的扩展函数，5 行代码即可完成自研算法的注册与适配。
|
||||
轻量化环境适配
|
||||
若客户电脑无 C/C++ 编译器 / MATLAB 引擎，系统给出一键安装引导（轻量版 MinGW，50M 左右；oct2py 开源库），无需配置环境变量。
|
||||
技术支持入口
|
||||
Web 界面内置技术支持入口，客户可一键导出错误日志 + 配置报告，直接发送给厂家，方便快速定位问题。
|
||||
2.2.7 海试专属模块
|
||||
一键质量检测
|
||||
内置海试数据质量检测专属算法组合，支持客户上传海试原始数据，点击 “一键检测” 秒级出初步结果，几分钟内生成完整检测报告。
|
||||
简洁直观的检测报告
|
||||
报告包含核心检测指标（数据完整性、信噪比、数据噪声水平、有效数据占比）、异常点定位、检测结论（合格 / 不合格）、处理建议，支持报告导出（PDF/Excel 格式），适配现场汇报需求。
|
||||
轻量化操作优化
|
||||
海试模式下隐藏复杂配置功能，仅保留 “数据上传→一键检测→报告导出” 核心操作，界面简洁，非专业人员可快速上手。
|
||||
离线快速运行
|
||||
海试模式下系统自动优化资源占用，关闭非核心功能，保证在低配笔记本上也能快速、稳定运行，无卡顿、无崩溃。
|
||||
2.3 非功能需求
|
||||
2.3.1 性能需求
|
||||
部署性能：支持 Windows/Linux/macOS 跨平台运行，单实例运行内存占用≤4GB，CPU 占用可控；客户侧仅需 Python 运行环境，无需 GPU / 高端服务器，零硬件成本。
|
||||
执行性能：
|
||||
C/C++ 算法调用性能与原生编译执行持平，数据转换无额外损耗；
|
||||
海试数据质量检测秒级出初步结果，1GB 以内数据完整处理时间≤5 分钟；
|
||||
支持单文件≥10GB 的大体积数据分块处理，分块处理效率与单块处理持平。
|
||||
响应性能：Web 界面操作响应时间≤1s，接口配置实时校验响应时间≤0.5s，算法调度流程启动响应时间≤2s。
|
||||
2.3.2 稳定性与容错性需求
|
||||
整体容错率≥95%，其中接口配置准确率≥90%，执行异常处理率≥98%，结果准确性≥99%；
|
||||
支持 7×24h 连续运行，无卡死、无崩溃，可处理异常数据、复杂接口、跨语言混编等各类场景；
|
||||
任意算法 / 步骤执行失败，均有兜底方案，保证流程不中断、核心结果可输出；
|
||||
跨语言调用失败率≤1%，失败后自动切换兜底方案，无感知恢复。
|
||||
2.3.3 易用性需求
|
||||
全流程 Web 界面可视化操作，零代码 / 极简代码，科研人员 / 海试操作人员 10 分钟即可上手；
|
||||
错误提示为自然语言人话提示，避免专业技术术语，同时给出明确的修复建议；
|
||||
所有常用功能（算法上传、接口配置、流程组合）均有操作引导弹窗 / 图文帮助，支持一键关闭；
|
||||
界面布局简洁，按 “功能模块” 分栏，核心操作（如一键检测、一键执行）突出显示，适配客户操作习惯。
|
||||
2.3.4 安全性与兼容性需求
|
||||
离线安全性：全程本地离线运行，无网络传输，符合水声行业涉密数据管理要求，不收集、不存储客户任何算法与数据；
|
||||
数据安全性：客户算法与数据均存储在本地，系统仅做临时缓存，执行完成后可一键清理缓存，无数据泄露风险；
|
||||
环境兼容性：支持 Python3.8 及以上版本，兼容 MATLAB R2018 及以上版本，C/C++ 编译器兼容 MinGW/GCC/MSVC；
|
||||
格式兼容性：支持水声行业常用数据格式（.mat/.npy/.bin/.txt），输出结果可导出为 PDF/Excel/JSON 等通用格式。
|
||||
2.3.5 可维护性与可扩展性需求
|
||||
模块化设计：所有功能模块为可插拔式设计，开发、升级、维护互不影响；
|
||||
易开发维护：基于 Python 生态开发，代码简洁、可读性强，2-3 人团队可快速完成维护与迭代；
|
||||
易扩展：支持新增算法语言（如 Fortran/Julia）、新增预处理算子、新增容错规则，仅需开发对应轻量插件，无需重构核心代码；
|
||||
版本迭代：支持产品小版本热更新，客户无需重新安装，仅需替换插件 / 脚本即可完成升级。
|
||||
三、运行环境需求
|
||||
3.1 开发环境
|
||||
操作系统：Windows/Linux/macOS 均可；
|
||||
开发语言：Python3.8+，C/C++（仅用于跨语言桥接）；
|
||||
核心依赖：NumPy、SciPy、Streamlit、matlab.engine、oct2py、ctypes、cffi 等。
|
||||
3.2 客户运行环境
|
||||
3.2.1 基础环境
|
||||
操作系统：Windows 10/11、Linux（Ubuntu 18.04+）、macOS 10.15+；
|
||||
核心依赖：Python3.8+（一键安装，无需配置环境变量）；
|
||||
硬件配置：CPU≥4 核，内存≥8GB，硬盘剩余空间≥10GB（低配笔记本 / 办公电脑即可满足）。
|
||||
3.2.2 可选环境（按需自动安装）
|
||||
C/C++ 编译器：MinGW/GCC（轻量版，50M 左右，系统一键引导安装）；
|
||||
MATLAB 环境：MATLAB R2018+（可选，无则自动切换 oct2py 开源库兜底）。
|
||||
四、验收标准
|
||||
4.1 功能验收
|
||||
所有核心功能模块按需求实现，无功能缺失，操作流程与需求一致；
|
||||
多语言算法（Python/MATLAB/C/C++）均可正常上传、黑盒化、调用，跨语言混编组合流程可正常执行；
|
||||
复杂接口配置可完成所有个性化需求，实时校验准确，错误配置无法保存；
|
||||
容错体系有效，单个算法出错可隔离、核心算法可兜底，流程不中断；
|
||||
海试专属模块可实现一键检测，快速生成符合要求的检测报告。
|
||||
4.2 性能验收
|
||||
满足所有性能需求，部署在低配办公电脑上无明显卡顿，大体积数据可正常分块处理；
|
||||
C/C++ 算法调用性能与原生编译执行持平，数据转换无明显损耗；
|
||||
海试数据质量检测 1GB 以内数据完整处理时间≤5 分钟，秒级出初步结果；
|
||||
Web 界面操作响应时间≤1s，无延迟、无卡死。
|
||||
4.3 稳定性验收
|
||||
连续 72h 运行测试，无崩溃、无卡死，资源占用稳定；
|
||||
随机输入异常数据、配置复杂接口、进行跨语言混编，系统均可正常处理，容错率≥95%；
|
||||
任意算法执行失败，系统均可实现隔离或兜底，核心结果可正常输出。
|
||||
4.4 易用性验收
|
||||
非专业人员（无工程开发知识）按操作引导，10 分钟内可完成算法上传、接口配置、流程组合、执行的完整操作；
|
||||
错误提示清晰，修复建议明确，客户可自主完成 90% 以上的错误修改；
|
||||
所有常用功能均有操作引导，界面布局简洁，操作逻辑符合客户使用习惯。
|
||||
在新工单中引用
屏蔽一个用户