e2m2e.mbse package

MBSE (Model-Based Systems Engineering) 模型层

提供 SysML 风格的系统建模基础设施，包括：

• 需求模型 (requirements/): 形式化需求定义与追溯矩阵

• 架构模型 (architecture/): 组件登记与依赖关系

• 数据模型 (data/): Pydantic 统一数据结构

• 图表生成 (diagrams/): Mermaid 图表自动生成

所有模型均为 living artifacts，随实现代码同步更新。

e2m2e.mbse.data package

数据模型子包

提供基于 Pydantic 的统一数据结构。领域枚举见 e2m2e.data.templates.enums。

e2m2e.mbse.data.core_models module

核心数据模型

基于 Pydantic 的统一数据结构，替代现有分散的 dict/plain class/dataclass 混用模式。

所有模型支持 JSON 序列化/反序列化和运行时类型验证。

class e2m2e.mbse.data.core_models.NumpyArray(shape, dtype=None, buffer=None, offset=0, strides=None, order=None)

基类：ndarray

Pydantic 兼容的 numpy 数组类型标记

作为字段类型注解使用，实际的形状校验由各字段上的 @field_validator 完成，本类本身不包含 validator。

class e2m2e.mbse.data.core_models.OrbitProperties(*, period=None, amplitudes=None, extrema=None, mean_state=None, center=None, is_periodic=False, periodicity_error=None)

基类：_NumpyModel

轨道属性数据模型

从 Orbit 类中提取的计算属性组。

变量:

• period (float | None) -- 轨道周期（无量纲时间）

• amplitudes (dict[str, float] | None) -- 各方向振幅 {'x': float, 'y': float, 'z': float}

• extrema (dict[str, float] | None) -- 极值点 {'x_max': float, 'x_min': float, ...}

• mean_state (np.ndarray | None) -- 平均状态向量，形状 (6,)

• center (np.ndarray | None) -- 轨道中心点（位置分量均值），形状 (3,)

• is_periodic (bool) -- 是否为周期轨道

• periodicity_error (float | None) -- 周期性误差（首末状态欧氏距离）

参数:

• period (float | None)

• amplitudes (dict[str, float] | None)

• extrema (dict[str, float] | None)

• mean_state (ndarray | None)

• center (ndarray | None)

• is_periodic (bool)

• periodicity_error (float | None)

period: float | None

amplitudes: dict[str, float] | None

extrema: dict[str, float] | None

mean_state: np.ndarray | None

center: np.ndarray | None

is_periodic: bool

periodicity_error: float | None

classmethod validate_mean_state(value)

确保平均状态向量保持六维状态契约。

参数:

value (ndarray | None)

返回类型:

ndarray | None

classmethod validate_center(value)

确保轨道中心保持三维位置契约。

参数:

value (ndarray | None)

返回类型:

ndarray | None

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

e2m2e.mbse.architecture package

架构模型子包

提供组件模型（ADR 0001: Protocol 接缝已移除，多态通过 Dynamics 基类实现）。

e2m2e.mbse.architecture.components module

组件模型

将具体实现类关联为 SysML BDD 中的组件层次。

每个 Component 记录其源代码位置和依赖关系。

class e2m2e.mbse.architecture.components.Component(name, module_path, protocols=<factory>, dependencies=<factory>, layer='mbse', description='')

基类：object

系统组件定义

对应 SysML BDD 中的一个块（Block），记录其接口契约和依赖。

变量:

• name (str) -- 组件名称（如 "CR3BP_Dynamics"）

• module_path (str) -- 源代码模块路径（如 "e2m2e.algorithm.dynamics"）

• protocols (list[str]) -- 预留字段（ADR 0001 后为空列表）

• dependencies (list[str]) -- 该组件依赖的其他组件名称

• layer (str) -- 所属架构层（data/numerical/algorithm/api/tools/mbse）

• description (str) -- 组件功能简述

参数:

• name (str)

• module_path (str)

• protocols (list[str])

• dependencies (list[str])

• layer (str)

• description (str)

name: str

module_path: str

protocols: list[str]

dependencies: list[str]

layer: str = 'mbse'

description: str = ''

class e2m2e.mbse.architecture.components.ComponentRegistry

基类：object

组件注册表。

调用方持有注册表生命周期，避免模型装配和测试共享可变全局状态。

register(component)

注册一个组件

参数:

component (Component)

返回类型:

None

register_many(components)

批量注册组件

参数:

components (list[Component])

返回类型:

None

get(name)

按名称获取组件

参数:

name (str)

返回类型:

Component

all()

获取所有已注册组件

返回类型:

list[Component]

by_layer(layer)

按架构层筛选组件

参数:

layer (str)

返回类型:

list[Component]

by_protocol(protocol_name)

按接口名称筛选组件（ADR 0001 后 protocols 均为空，始终返回 []）

参数:

protocol_name (str)

返回类型:

list[Component]

dependency_graph()

构建组件依赖图

返回:

[dependency_names]}

返回类型:

{component_name

clear()

清空所有已注册组件（仅用于测试）

返回类型:

None

e2m2e.mbse.architecture.data_components module

数据层组件目录。

e2m2e.mbse.architecture.algorithm_components module

算法层组件目录。

e2m2e.mbse.architecture.numerical_components module

数值层组件目录。

e2m2e.mbse.architecture.api_components module

接口层组件目录。

e2m2e.mbse.architecture.tools_components module

工具层组件目录。

e2m2e.mbse.requirements package

需求模型子包

提供形式化的需求定义、注册和追溯能力。

e2m2e.mbse.requirements.base module

需求模型基础类

提供形式化的需求定义和注册机制，支持 SysML 需求图的自动生成。

每个需求具有唯一 ID、分类、优先级、验证方法，以及与代码和测试的追溯链接。

class e2m2e.mbse.requirements.base.RequirementCategory(*values)

基类：Enum

需求分类（对应 SysML 需求类型）

FUNCTIONAL = 'functional'

PERFORMANCE = 'performance'

INTERFACE = 'interface'

VERIFICATION = 'verification'

CONSTRAINT = 'constraint'

class e2m2e.mbse.requirements.base.RequirementPriority(*values)

基类：Enum

需求优先级（对应 SysML <<shall>>, <<should>>, <<may>>）

SHALL = 'shall'

SHOULD = 'should'

MAY = 'may'

class e2m2e.mbse.requirements.base.Requirement(id, title, category, description, priority=RequirementPriority.SHALL, verification_method='test', parent=None, linked_code=<factory>, linked_tests=<factory>)

基类：object

形式化需求定义

对应 SysML Requirement Diagram 中的需求元素。

变量:

• id (str) -- 唯一标识符，如 "REQ-001"

• title (str) -- 简短标题

• category (e2m2e.mbse.requirements.base.RequirementCategory) -- 需求分类

• description (str) -- 详细描述

• priority (e2m2e.mbse.requirements.base.RequirementPriority) -- 优先级（shall/should/may）

• verification_method (str) -- 验证方法（test/analysis/inspection）

• parent (str | None) -- 父需求 ID（用于需求分解层次）

• linked_code (list[str]) -- 关联的源代码模块路径

• linked_tests (list[str]) -- 关联的测试文件路径

参数:

• id (str)

• title (str)

• category (RequirementCategory)

• description (str)

• priority (RequirementPriority)

• verification_method (str)

• parent (str | None)

• linked_code (list[str])

• linked_tests (list[str])

id: str

title: str

category: RequirementCategory

description: str

priority: RequirementPriority = 'shall'

verification_method: str = 'test'

parent: str | None = None

linked_code: list[str]

linked_tests: list[str]

class e2m2e.mbse.requirements.base.RequirementRegistry

基类：object

需求注册表。

调用方持有注册表生命周期，支持按分类、层次和追溯关系查询。

register(requirement)

注册一个需求

参数:

requirement (Requirement)

返回类型:

None

register_many(requirements)

批量注册需求

参数:

requirements (list[Requirement])

返回类型:

None

get(req_id)

按 ID 获取需求

参数:

req_id (str)

返回类型:

Requirement

all()

获取所有已注册需求

返回类型:

list[Requirement]

by_category(category)

按分类筛选需求

参数:

category (RequirementCategory)

返回类型:

list[Requirement]

by_parent(parent_id)

获取指定父需求的子需求

参数:

parent_id (str)

返回类型:

list[Requirement]

children_of(req_id)

获取指定需求的所有子需求（递归）

参数:

req_id (str)

返回类型:

list[Requirement]

traceability_matrix()

构建需求追溯矩阵

返回:

{"requirement": Requirement, "code": [...],

"tests": [...], "has_coverage": bool}}

返回类型:

{req_id

coverage_report()

生成需求覆盖率报告

返回:

包含 total/covered/uncovered/coverage_rate/uncovered_ids 的字典

返回类型:

dict

clear()

清空所有已注册需求（仅用于测试）

返回类型:

None

e2m2e.mbse.requirements.core_requirements module

核心层需求定义。

定义 e2m2e 的系统建模、动力学传播、轨道数据和坐标变换等基础需求。 需求 ID 范围：REQ-001 ~ REQ-030。

e2m2e.mbse.requirements.algorithms_requirements module

Algorithms 层需求定义

定义 e2m2e 算法层（algorithms/）的系统需求，覆盖微分修正、延拓、 稳定性分析、多点射击法等核心数值算法。需求 ID 范围：REQ-100 ~ REQ-119。

e2m2e.mbse.diagrams package

图表生成子包

提供 SysML 风格的 Mermaid 图表自动生成。

e2m2e.mbse.diagrams.generator module

Mermaid 图表统一生成编排器

从 MBSE 模型定义自动生成 SysML 风格的 Mermaid 图表，嵌入 MkDocs 文档。

支持的图表类型： - BDD (Block Definition Diagram) → classDiagram - IBD (Internal Block Diagram) → graph - Activity Diagram → flowchart - Sequence Diagram → sequenceDiagram - State Machine → stateDiagram-v2 - Requirement Diagram → requirementDiagram

class e2m2e.mbse.diagrams.generator.DiagramGenerator(requirements=None, components=None)

基类：object

MBSE 图表生成编排器

从 RequirementRegistry 和 ComponentRegistry 生成 Mermaid 图表。

参数:

• requirements (RequirementRegistry | None)

• components (ComponentRegistry | None)

__init__(requirements=None, components=None)

初始化图表生成器

参数:

• requirements (RequirementRegistry | None) -- 需求注册表实例，默认使用全局单例

• components (ComponentRegistry | None) -- 组件注册表实例，默认使用全局单例

generate_bdd(layer=None)

生成 BDD (Block Definition Diagram) — Mermaid classDiagram

参数:

layer (str | None) -- 可选，仅生成指定层的组件图

返回:

Mermaid classDiagram 语法字符串

返回类型:

str

generate_requirement_diagram()

生成 Requirement Diagram — Mermaid requirementDiagram

返回:

Mermaid requirementDiagram 语法字符串

返回类型:

str

generate_traceability_matrix()

生成需求到代码和测试的 Markdown 追溯矩阵。

返回类型:

str

generate_state_machine(name, states, transitions)

生成 State Machine Diagram — Mermaid stateDiagram-v2

参数:

• name (str) -- 状态机名称

• states (list[str]) -- 状态列表

• transitions (list[tuple[str, str, str]]) -- 转换列表 [(from_state, to_state, trigger)]

返回:

Mermaid stateDiagram-v2 语法字符串

返回类型:

str

generate_activity(name, steps, decision_nodes=None)

生成 Activity Diagram — Mermaid flowchart

参数:

• name (str) -- 活动名称

• steps (list[dict]) -- 步骤列表 [{"id": str, "label": str, "type": "process|io|start|end"}]

• decision_nodes (list[dict] | None) -- 决策节点 [{"id": str, "label": str, "branches": [{"target": str, "condition": str}]}]

返回:

Mermaid flowchart 语法字符串

返回类型:

str

generate_sequence(participants, interactions)

生成 Sequence Diagram — Mermaid sequenceDiagram

参数:

• participants (list[str]) -- 参与者列表

• interactions (list[tuple[str, str, str]]) -- 交互列表 [(from, to, message)]

返回:

Mermaid sequenceDiagram 语法字符串

返回类型:

str

generate_ibd(component_name, attributes)

生成 IBD (Internal Block Diagram) — Mermaid graph

参数:

• component_name (str) -- 组件名称

• attributes (list[dict]) -- 属性列表 [{"name": str, "type": str, "direction": "input|output|internal"}]

返回:

Mermaid graph 语法字符串

返回类型:

str

write_document(title, content, output_path)

将受管 Markdown 文档写入指定位置。

参数:

• title (str)

• content (str)

• output_path (str)

返回类型:

None

write_diagram(title, content, output_path)

将 Mermaid 图表作为受管 Markdown 文档写入指定位置。

参数:

• title (str)

• content (str)

• output_path (str)

返回类型:

None

generate_all(output_dir)

生成默认模型的受管图表和追溯文档。

参数:

output_dir (str) -- 输出目录路径

返回:

生成的文件路径列表

返回类型:

list[str]