872 lines
23 KiB
Markdown
872 lines
23 KiB
Markdown
# MIL SDK 文档
|
||
|
||
MIL SDK 是一个用于处理 MIL（Model-In-the-Loop）仿真数据的 Python 工具包，主要提供 Excel 数据文件的读取、解析、生成和更新功能。
|
||
|
||
## 目录
|
||
|
||
- [概述](#概述)
|
||
- [项目架构](#项目架构)
|
||
- [快速开始](#快速开始)
|
||
- [数据模型](#数据模型)
|
||
- [异常体系](#异常体系)
|
||
- [日志模块](#日志模块)
|
||
- [Excel 读取模块](#excel-读取模块)
|
||
- [Excel 生成模块](#excel-生成模块)
|
||
- [Excel 更新模块](#excel-更新模块)
|
||
- [API 参考](#api-参考)
|
||
- [使用示例](#使用示例)
|
||
- [Excel 文件格式约定](#excel-文件格式约定)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
### 项目简介
|
||
|
||
MIL SDK 专为 MIL 仿真数据处理场景设计，提供以下核心能力：
|
||
|
||
- **数据读取** - 从特定格式的 Excel 文件中解析仿真信号数据
|
||
- **用例管理** - 读取和解析测试用例模板
|
||
- **用例生成** - 根据数据和模板生成测试用例 Excel 文件
|
||
- **数据对比** - 比较新旧仿真数据差异，自动更新信号列
|
||
|
||
### 技术栈
|
||
|
||
| 类别 | 技术选型 |
|
||
|------|----------|
|
||
| 语言 | Python 3.10+ |
|
||
| 主要依赖 | openpyxl >= 3.0.0 |
|
||
| 测试框架 | pytest >= 7.0.0 |
|
||
| 类型检查 | mypy >= 1.0.0 |
|
||
| 代码规范 | ruff >= 0.1.0 |
|
||
|
||
### 版本信息
|
||
|
||
- 当前版本：0.1.0
|
||
- 许可证：MIT
|
||
|
||
---
|
||
|
||
## 项目架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
mil_sdk/
|
||
├── src/
|
||
│ └── core/ # 核心模块
|
||
│ ├── __init__.py # 公共 API 导出
|
||
│ ├── base.py # 核心数据模型
|
||
│ ├── exceptions.py # 自定义异常
|
||
│ ├── logging_config.py # 日志配置
|
||
│ ├── mil_read_data_excel.py # 读取仿真数据 Excel
|
||
│ ├── mil_read_case_excel.py # 读取测试用例 Excel
|
||
│ ├── mil_create_data_excel.py # 生成测试用例 Excel
|
||
│ └── mil_update_excel.py # 更新用例 Excel
|
||
├── tests/ # 测试模块
|
||
│ ├── conftest.py # pytest 配置和 fixtures
|
||
│ ├── test_base.py # 基础数据模型测试
|
||
│ ├── test_mil_case_excel.py # 用例 Excel 测试
|
||
│ └── test_mil_data_excel.py # 数据 Excel 测试
|
||
├── main.py # 入口文件
|
||
├── pyproject.toml # 项目配置
|
||
├── requirements.txt # 依赖清单
|
||
└── SDK_DOCUMENTATION.md # 本文档
|
||
```
|
||
|
||
### 模块职责
|
||
|
||
| 模块 | 文件 | 职责 |
|
||
|------|------|------|
|
||
| 数据模型 | base.py | 定义 DataLog、SignalData、ExcelDataResult 等核心数据结构 |
|
||
| 异常体系 | exceptions.py | 定义 MILSDKError 及其子类，统一异常处理 |
|
||
| 日志模块 | logging_config.py | 提供日志配置和获取功能 |
|
||
| 数据读取 | mil_read_data_excel.py | 解析 MIL 仿真数据 Excel，提取信号数据 |
|
||
| 用例读取 | mil_read_case_excel.py | 解析测试用例模板 Excel |
|
||
| 用例生成 | mil_create_data_excel.py | 根据模板生成测试用例 Excel |
|
||
| 用例更新 | mil_update_excel.py | 比较新旧数据，更新信号列 |
|
||
|
||
### 依赖关系
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ main.py │
|
||
│ (入口文件，演示 SDK 使用) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ src/core/__init__.py │
|
||
│ (公共 API 统一导出模块) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│ │ │ │ │
|
||
▼ ▼ ▼ ▼ ▼
|
||
┌────────┐ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────┐
|
||
│ base │ │excep │ │logging│ │ mil_ │ │ mil_ │
|
||
│ │ │tions │ │_conf │ │read_ │ │create│
|
||
│ │ │ │ │ │ │data │ │_data │
|
||
└────────┘ └──────┘ └───────┘ └──────┘ └──────┘
|
||
│ │
|
||
▼ ▼
|
||
┌────────┐ ┌────────┐
|
||
│ mil_ │ │ mil_ │
|
||
│read_ │ │update_ │
|
||
│case │ │excel │
|
||
└────────┘ └────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
### 开发依赖安装
|
||
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 基础使用
|
||
|
||
```python
|
||
from src.core import setup_logging, read_excel_data, ExcelReaderConfig
|
||
|
||
# 初始化日志
|
||
setup_logging()
|
||
|
||
# 读取仿真数据
|
||
config = ExcelReaderConfig()
|
||
result = read_excel_data("simulation.xlsx", return_object=True, config=config)
|
||
|
||
# 获取信号数据
|
||
signal = result.get_signal("signal_name")
|
||
if signal:
|
||
for log in signal.datalog:
|
||
print(f"时间: {log.time}, 值: {log.value}")
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### DataLog
|
||
|
||
仿真数据日志记录，表示单个时间点的数据。
|
||
|
||
```python
|
||
@dataclass
|
||
class DataLog:
|
||
time: float = 0.0 # 时间戳（秒）
|
||
value: str = "" # 信号值
|
||
```
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| time | float | 0.0 | 时间戳，单位为秒 |
|
||
| value | str | "" | 信号值，可以是任意类型 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
log = DataLog(time=1.5, value="on")
|
||
print(f"时间: {log.time}, 值: {log.value}")
|
||
```
|
||
|
||
---
|
||
|
||
### SignalData
|
||
|
||
信号数据封装，包含信号的元数据和数据日志。
|
||
|
||
```python
|
||
@dataclass
|
||
class SignalData:
|
||
column: int = 0 # 列索引
|
||
attributes: dict[str, str] = field(default_factory=dict) # 信号属性
|
||
datalog: list[DataLog] = field(default_factory=list) # 数据日志列表
|
||
```
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| column | int | Excel 列索引 |
|
||
| attributes | dict[str, str] | 信号属性字典，键为行号，值为单元格值 |
|
||
| datalog | list[DataLog] | 数据日志列表 |
|
||
|
||
**方法说明**：
|
||
|
||
| 方法 | 返回值 | 说明 |
|
||
|------|--------|------|
|
||
| to_dict() | dict[str, Any] | 转换为字典格式 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
signal = SignalData(column=2, attributes={"type": "boolean"}, datalog=[DataLog(0.0, "off")])
|
||
data = signal.to_dict()
|
||
```
|
||
|
||
---
|
||
|
||
### ExcelDataResult
|
||
|
||
Excel 数据读取结果封装，提供对 Excel 数据的类型安全访问。
|
||
|
||
```python
|
||
@dataclass
|
||
class ExcelDataResult:
|
||
sheet_name: str = "Scenario1" # 工作表名称
|
||
source_row: int = 0 # Source: Input 所在行号
|
||
signals: dict[str, SignalData] = field(default_factory=dict) # 信号字典
|
||
```
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| sheet_name | str | 工作表名称，默认 "Scenario1" |
|
||
| source_row | int | "Source: Input" 标记所在行号 |
|
||
| signals | dict[str, SignalData] | 信号名称到信号数据的映射 |
|
||
|
||
**方法说明**：
|
||
|
||
| 方法 | 参数 | 返回值 | 说明 |
|
||
|------|------|--------|------|
|
||
| get_signal() | name: str | SignalData \| None | 获取指定信号的数据 |
|
||
| get_signal_names() | - | list[str] | 获取所有信号名称 |
|
||
| to_dict() | - | dict[str, Any] | 转换为字典格式 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
result = ExcelDataResult(sheet_name="Scenario1", source_row=3, signals={})
|
||
signal = result.get_signal("signal_name")
|
||
names = result.get_signal_names()
|
||
data = result.to_dict()
|
||
```
|
||
|
||
---
|
||
|
||
### ExcelReaderConfig
|
||
|
||
Excel 读取配置类，用于配置 Excel 文件的解析规则。
|
||
|
||
```python
|
||
@dataclass
|
||
class ExcelReaderConfig:
|
||
sheet_name: str = "Scenario1" # 工作表名称
|
||
source_header: str = "Source: Input" # 数据源标记行文本
|
||
time_column: int = 1 # 时间列索引（A 列）
|
||
header_row: int = 1 # 信号名称所在行号
|
||
type_row: int = 3 # 信号类型所在行号
|
||
interp_row: int = 6 # 插值类型所在行号
|
||
data_start_row_offset: int = 1 # 数据起始行偏移量
|
||
output_header: str = "Source: Output" # 输出标记行文本
|
||
block_path_row: int = 4 # 块路径所在行号
|
||
```
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| sheet_name | str | "Scenario1" | 工作表名称 |
|
||
| source_header | str | "Source: Input" | 数据源标记行文本 |
|
||
| time_column | int | 1 | 时间列索引（A 列） |
|
||
| header_row | int | 1 | 信号名称所在行号 |
|
||
| type_row | int | 3 | 信号类型所在行号 |
|
||
| interp_row | int | 6 | 插值类型所在行号 |
|
||
| data_start_row_offset | int | 1 | 相对于 source_row 的数据起始行偏移量 |
|
||
| output_header | str | "Source: Output" | 输出标记行文本 |
|
||
| block_path_row | int | 4 | 块路径所在行号 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
config = ExcelReaderConfig(
|
||
sheet_name="Scenario1",
|
||
source_header="Source: Input",
|
||
time_column=1
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 异常体系
|
||
|
||
异常模块位于 [exceptions.py](file:///f:/MyProject/mil_sdk/src/core/exceptions.py)。
|
||
|
||
### 异常层次
|
||
|
||
```
|
||
Exception
|
||
└── MILSDKError (基础异常)
|
||
├── ExcelReadError (文件读取错误)
|
||
├── ExcelFormatError (格式错误)
|
||
├── CaseDataError (用例数据错误)
|
||
└── ExcelWriteError (文件写入错误)
|
||
```
|
||
|
||
### MILSDKError
|
||
|
||
基础异常类，所有 SDK 自定义异常的基类。
|
||
|
||
```python
|
||
class MILSDKError(Exception):
|
||
pass
|
||
```
|
||
|
||
### ExcelReadError
|
||
|
||
Excel 文件读取错误，当文件不存在或读取失败时抛出。
|
||
|
||
```python
|
||
class ExcelReadError(MILSDKError):
|
||
"""Excel 文件读取错误（文件不存在、权限问题等）"""
|
||
pass
|
||
```
|
||
|
||
**触发场景**：
|
||
- 文件不存在
|
||
- 文件权限问题
|
||
- 文件格式损坏
|
||
|
||
### ExcelFormatError
|
||
|
||
Excel 格式错误，当 Excel 格式不符合预期时抛出。
|
||
|
||
```python
|
||
class ExcelFormatError(MILSDKError):
|
||
"""Excel 格式错误（缺少 Sheet、格式不匹配等）"""
|
||
pass
|
||
```
|
||
|
||
**触发场景**：
|
||
- 缺少指定的 Sheet
|
||
- 缺少 "Source: Input" 标记
|
||
- 缺少模板版本号
|
||
|
||
### CaseDataError
|
||
|
||
用例数据错误，当用例数据异常时抛出。
|
||
|
||
```python
|
||
class CaseDataError(MILSDKError):
|
||
"""用例数据错误（信号不存在、类型错误等）"""
|
||
pass
|
||
```
|
||
|
||
**触发场景**：
|
||
- 信号名称不存在
|
||
- 时间格式错误
|
||
- 缺少用例标题
|
||
|
||
### ExcelWriteError
|
||
|
||
Excel 文件写入错误，当文件写入失败时抛出。
|
||
|
||
```python
|
||
class ExcelWriteError(MILSDKError):
|
||
"""Excel 文件写入错误（权限问题、保存失败等）"""
|
||
pass
|
||
```
|
||
|
||
**触发场景**：
|
||
- 文件权限问题
|
||
- 磁盘空间不足
|
||
- 保存失败
|
||
|
||
**异常处理示例**：
|
||
|
||
```python
|
||
from src.core import (
|
||
MILSDKError,
|
||
ExcelReadError,
|
||
ExcelFormatError,
|
||
CaseDataError,
|
||
ExcelWriteError,
|
||
read_excel_data,
|
||
)
|
||
|
||
try:
|
||
result = read_excel_data("data.xlsx")
|
||
except ExcelReadError as e:
|
||
print(f"文件读取失败: {e}")
|
||
except ExcelFormatError as e:
|
||
print(f"格式错误: {e}")
|
||
except MILSDKError as e:
|
||
print(f"SDK 错误: {e}")
|
||
```
|
||
|
||
---
|
||
|
||
## 日志模块
|
||
|
||
日志模块位于 [logging_config.py](file:///f:/MyProject/mil_sdk/src/core/logging_config.py)。
|
||
|
||
### setup_logging
|
||
|
||
配置日志系统，设置日志级别、输出目标等。
|
||
|
||
```python
|
||
def setup_logging(
|
||
level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO",
|
||
log_file: str | Path | None = "logs/mil_sdk.log",
|
||
console_output: bool = True,
|
||
) -> logging.Logger
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| level | str | "INFO" | 日志级别，可选 "DEBUG"、"INFO"、"WARNING"、"ERROR" |
|
||
| log_file | str \| Path \| None | "logs/mil_sdk.log" | 日志文件路径，设为 None 则不写入文件 |
|
||
| console_output | bool | True | 是否输出到控制台 |
|
||
|
||
**返回值**：根日志记录器 (logging.Logger)
|
||
|
||
**日志格式**：`%(asctime)s [%(levelname)s] %(message)s`
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import setup_logging
|
||
|
||
logger = setup_logging(level="DEBUG", log_file="logs/mil_sdk.log")
|
||
```
|
||
|
||
### get_logger
|
||
|
||
获取指定名称的日志记录器。
|
||
|
||
```python
|
||
def get_logger(name: str) -> logging.Logger
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | str | 日志记录器名称，通常使用 `__name__` |
|
||
|
||
**返回值**：日志记录器实例
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import get_logger
|
||
|
||
logger = get_logger(__name__)
|
||
logger.info("This is an info message")
|
||
```
|
||
|
||
---
|
||
|
||
## Excel 读取模块
|
||
|
||
### read_excel_data
|
||
|
||
读取 MIL 仿真 Excel 文件并解析信号数据。
|
||
|
||
```python
|
||
def read_excel_data(
|
||
excel_path: str,
|
||
return_object: bool = False,
|
||
config: ExcelReaderConfig | None = None
|
||
) -> DataDict | ExcelDataResult
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| excel_path | str | - | Excel 文件路径 |
|
||
| return_object | bool | False | 是否返回 ExcelDataResult 对象（推荐），False 保持向后兼容 |
|
||
| config | ExcelReaderConfig \| None | None | Excel 读取配置，默认使用 ExcelReaderConfig() |
|
||
|
||
**返回值**：
|
||
|
||
`return_object=False` 时返回包含以下键的字典（向后兼容）：
|
||
- `wb`: Workbook 对象
|
||
- `sheet`: Worksheet 对象
|
||
- `source_row`: Source: Input 所在行号
|
||
- `<信号名>`: 信号元数据（type, column, datalog）
|
||
|
||
`return_object=True` 时返回 ExcelDataResult 对象（推荐）：
|
||
- `sheet_name`: 工作表名称
|
||
- `source_row`: Source: Input 所在行号
|
||
- `signals`: 信号名称到信号数据的映射
|
||
|
||
**异常**：
|
||
|
||
| 异常类型 | 触发条件 |
|
||
|----------|----------|
|
||
| ExcelReadError | 文件不存在或读取失败 |
|
||
| ExcelFormatError | Excel 格式不符合预期 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import read_excel_data
|
||
|
||
# 使用推荐的方式
|
||
result = read_excel_data("simulation.xlsx", return_object=True)
|
||
for name in result.get_signal_names():
|
||
signal = result.get_signal(name)
|
||
if signal:
|
||
print(f"信号: {name}, 数据点: {len(signal.datalog)}")
|
||
|
||
# 使用向后兼容的方式
|
||
data = read_excel_data("simulation.xlsx")
|
||
wb = data["wb"]
|
||
sheet = data["sheet"]
|
||
```
|
||
|
||
### read_excel_case
|
||
|
||
读取 Excel 用例模板。
|
||
|
||
```python
|
||
def read_excel_case(
|
||
excel_path: str,
|
||
data_dict: dict,
|
||
addTimeEn: bool,
|
||
) -> CaseDict
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| excel_path | str | Excel 模板文件路径 |
|
||
| data_dict | dict | 信号数据字典 |
|
||
| addTimeEn | bool | 是否累加时间 |
|
||
|
||
**返回值**：用例字典
|
||
|
||
**异常**：
|
||
|
||
| 异常类型 | 触发条件 |
|
||
|----------|----------|
|
||
| ExcelReadError | 文件读取失败 |
|
||
| ExcelFormatError | 格式错误 |
|
||
| CaseDataError | 用例数据错误 |
|
||
|
||
**用例字典结构**：
|
||
|
||
```python
|
||
{
|
||
"Sheet名称": {
|
||
"用例标题": {
|
||
"enable": bool, # 是否启用
|
||
"step": {
|
||
"step0": {
|
||
"name": str, # 步骤名称
|
||
"time": float, # 时间
|
||
"action": dict # 操作字典
|
||
},
|
||
"step1": {...}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import read_excel_case, read_excel_data
|
||
|
||
data_dict = read_excel_data("simulation.xlsx", return_object=False)
|
||
cases = read_excel_case("template.xlsx", data_dict, addTimeEn=True)
|
||
|
||
for sheet_name, sheet_cases in cases.items():
|
||
print(f"Sheet: {sheet_name}")
|
||
for case_name, case_data in sheet_cases.items():
|
||
print(f" 用例: {case_name}, 启用: {case_data['enable']}")
|
||
```
|
||
|
||
---
|
||
|
||
## Excel 生成模块
|
||
|
||
### create_excel_case
|
||
|
||
根据数据和用例模板生成测试用例 Excel 文件。
|
||
|
||
```python
|
||
def create_excel_case(
|
||
excel_path: str,
|
||
data_dict: dict,
|
||
sheets_dict: dict,
|
||
) -> None
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| excel_path | str | 输出目录路径 |
|
||
| data_dict | dict | 数据字典 |
|
||
| sheets_dict | dict | 工作表字典 |
|
||
|
||
**异常**：
|
||
|
||
| 异常类型 | 触发条件 |
|
||
|----------|----------|
|
||
| CaseDataError | 数据异常 |
|
||
| ExcelWriteError | 文件写入错误 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import read_excel_data, read_excel_case, create_excel_case
|
||
|
||
data_dict = read_excel_data("simulation.xlsx", return_object=False)
|
||
sheets_dict = read_excel_case("template.xlsx", data_dict, addTimeEn=True)
|
||
create_excel_case("output/", data_dict, sheets_dict)
|
||
```
|
||
|
||
---
|
||
|
||
## Excel 更新模块
|
||
|
||
### update_case_excel
|
||
|
||
比较新旧数据差异，更新 Excel 文件中的信号列。
|
||
|
||
```python
|
||
def update_case_excel(
|
||
filename: str,
|
||
old_data: dict,
|
||
new_data: dict,
|
||
) -> None
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| filename | str | Excel 文件路径 |
|
||
| old_data | dict | 旧数据字典 |
|
||
| new_data | dict | 新数据字典 |
|
||
|
||
**功能说明**：
|
||
- 比较新旧数据中的信号差异
|
||
- 在旧文件中添加新数据独有的信号列
|
||
- 从旧文件中删除新数据不存在的信号列
|
||
|
||
**异常**：
|
||
|
||
| 异常类型 | 触发条件 |
|
||
|----------|----------|
|
||
| CaseDataError | 数据类型错误 |
|
||
|
||
**示例**：
|
||
|
||
```python
|
||
from src.core import read_excel_data, update_case_excel
|
||
|
||
new_data = read_excel_data("new_data.xlsx", return_object=False)
|
||
old_data = read_excel_data("old_data.xlsx", return_object=False)
|
||
update_case_excel("updated.xlsx", old_data, new_data)
|
||
```
|
||
|
||
---
|
||
|
||
## API 参考
|
||
|
||
### 公共导入
|
||
|
||
所有公共 API 均可通过以下方式导入：
|
||
|
||
```python
|
||
from src.core import (
|
||
# 数据模型
|
||
DataLog,
|
||
SignalData,
|
||
ExcelDataResult,
|
||
ExcelReaderConfig,
|
||
# 核心函数
|
||
read_excel_data,
|
||
read_excel_case,
|
||
create_excel_case,
|
||
update_case_excel,
|
||
# 异常
|
||
MILSDKError,
|
||
ExcelReadError,
|
||
ExcelFormatError,
|
||
CaseDataError,
|
||
ExcelWriteError,
|
||
# 日志
|
||
setup_logging,
|
||
get_logger,
|
||
)
|
||
```
|
||
|
||
### 函数签名汇总
|
||
|
||
| 函数 | 签名 |
|
||
|------|------|
|
||
| DataLog | `DataLog(time: float = 0.0, value: str = "")` |
|
||
| SignalData | `SignalData(column: int = 0, attributes: dict = {}, datalog: list = [])` |
|
||
| ExcelDataResult | `ExcelDataResult(sheet_name: str = "Scenario1", source_row: int = 0, signals: dict = {})` |
|
||
| ExcelReaderConfig | `ExcelReaderConfig(...)` |
|
||
| read_excel_data | `read_excel_data(excel_path: str, return_object: bool = False, config: ExcelReaderConfig \| None = None) -> DataDict \| ExcelDataResult` |
|
||
| read_excel_case | `read_excel_case(excel_path: str, data_dict: dict, addTimeEn: bool) -> CaseDict` |
|
||
| create_excel_case | `create_excel_case(excel_path: str, data_dict: dict, sheets_dict: dict) -> None` |
|
||
| update_case_excel | `update_case_excel(filename: str, old_data: dict, new_data: dict) -> None` |
|
||
| setup_logging | `setup_logging(level: str = "INFO", log_file: str \| Path \| None = "logs/mil_sdk.log", console_output: bool = True) -> logging.Logger` |
|
||
| get_logger | `get_logger(name: str) -> logging.Logger` |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基础用法
|
||
|
||
```python
|
||
from src.core import setup_logging, read_excel_data
|
||
|
||
setup_logging()
|
||
result = read_excel_data("simulation.xlsx", return_object=True)
|
||
|
||
signal_names = result.get_signal_names()
|
||
print(f"共解析 {len(signal_names)} 个信号")
|
||
|
||
for name in signal_names:
|
||
signal = result.get_signal(name)
|
||
if signal:
|
||
print(f" {name}: {len(signal.datalog)} 个数据点")
|
||
```
|
||
|
||
### 完整工作流
|
||
|
||
```python
|
||
from pathlib import Path
|
||
from src.core import (
|
||
setup_logging,
|
||
read_excel_data,
|
||
read_excel_case,
|
||
create_excel_case,
|
||
update_case_excel,
|
||
)
|
||
|
||
def main() -> None:
|
||
setup_logging(level="INFO")
|
||
|
||
excel_path = Path(__file__).parent
|
||
|
||
data_dict = read_excel_data("new_data.xlsx", return_object=False)
|
||
old_data_dict = read_excel_data("old_data.xlsx", return_object=False)
|
||
|
||
update_case_excel("new_case.xlsx", old_data_dict, data_dict)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
```python
|
||
from src.core import (
|
||
ExcelReadError,
|
||
ExcelFormatError,
|
||
CaseDataError,
|
||
MILSDKError,
|
||
read_excel_data,
|
||
)
|
||
|
||
try:
|
||
result = read_excel_data("simulation.xlsx", return_object=True)
|
||
except ExcelReadError as e:
|
||
print(f"文件读取失败: {e}")
|
||
raise
|
||
except ExcelFormatError as e:
|
||
print(f"格式错误: {e}")
|
||
raise
|
||
except MILSDKError as e:
|
||
print(f"SDK 错误: {e}")
|
||
raise
|
||
```
|
||
|
||
---
|
||
|
||
## Excel 文件格式约定
|
||
|
||
### 仿真数据文件格式
|
||
|
||
Excel 仿真数据文件遵循以下格式约定：
|
||
|
||
| 行号 | 内容 |
|
||
|------|------|
|
||
| 1 | 信号名称（time, signal1, signal2...） |
|
||
| 2 | 预留行（通常为空） |
|
||
| 3 | "Source: Input" 标记行，标识数据列开始 |
|
||
| 4 | 信号类型信息 |
|
||
| 5 | 块路径信息 |
|
||
| 6 | 插值类型信息 |
|
||
| 7+ | 时间-值数据对 |
|
||
|
||
**示例结构**：
|
||
|
||
| A | B | C | D |
|
||
|---|---|---|---|
|
||
| time | signal1 | signal2 | signal3 |
|
||
| | | | |
|
||
| Source: Input | Source: Input | Source: Input | Source: Input |
|
||
| type | boolean | float | boolean |
|
||
| BlockPath | /model/signal1 | /model/signal2 | /model/signal3 |
|
||
| Interp | const | linear | zero-order hold |
|
||
| | off | 0.0 | true |
|
||
| 1.0 | on | 1.5 | false |
|
||
| 2.0 | off | 2.0 | true |
|
||
|
||
**要求**：
|
||
- Sheet 名称：`Scenario1`
|
||
- 时间列：必须存在且列名为 "time"
|
||
- 跳过列：列名为 "Parameter:"、"Value"、"BlockPath" 的列会被跳过
|
||
|
||
### 用例模板文件格式
|
||
|
||
用例模板 Excel 文件遵循以下格式约定：
|
||
|
||
| Sheet 名称 | 内容 |
|
||
|-----------|------|
|
||
| Atech-Hefei | 模板版本号 |
|
||
| 其他 Sheet | 测试用例数据 |
|
||
|
||
**用例数据格式**：
|
||
|
||
| 列号 | 列名 | 说明 |
|
||
|------|------|------|
|
||
| 1 | TITLE | 用例标题 |
|
||
| 2 | STATUS | 状态（完成测试/未完成） |
|
||
| 3 | ACTION | 操作描述（signal1=value1; signal2=value2） |
|
||
| 4 | NAME | 步骤名称 |
|
||
| 5 | TIME | 时间 |
|
||
|
||
**操作字符串格式**：
|
||
- 多条操作使用分号 `;` 分隔
|
||
- 操作格式：`信号名=值`
|
||
- 示例：`signal1=on; signal2=0.5`
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
### v0.1.0 (当前版本)
|
||
|
||
- 初始版本发布
|
||
- 支持 Excel 数据文件读取和解析
|
||
- 支持测试用例模板读取和生成
|
||
- 支持新旧数据对比和更新 |