# 项目架构

## 整体架构图

```
arxml_sdk/
├── src/                           # 源代码
│   ├── __init__.py               # 包入口，导出全部公共API
│   ├── core/                      # 核心基础设施层
│   │   ├── __init__.py
│   │   ├── base.py               # Base 基类
│   │   ├── constants.py          # ARXML 标签常量
│   │   └── enums.py              # AUTOSAR 枚举类型
│   ├── types/                     # 数据类型层
│   │   ├── __init__.py
│   │   ├── base_type.py          # 基础数据类型
│   │   ├── unit.py               # 单位类型
│   │   ├── data_constraint.py    # 数据约束
│   │   ├── compu_method.py       # 计算方法
│   │   ├── application_types.py # 应用数据类型
│   │   ├── implementation_types.py # 实现数据类型
│   │   ├── sw_addr_method.py     # 软件地址方法
│   │   ├── data_mapping.py       # 数据类型映射
│   │   ├── sw_component_type.py  # 软件组件类型
│   │   ├── interface.py          # 接口定义
│   │   ├── package.py            # 包管理
│   │   └── swc_internal_behavior.py # SWC内部行为
│   └── utils/                     # 工具层
│       ├── __init__.py
│       └── arxml_writer.py       # ARXML文档写入
└── tests/                         # 测试
```

## 模块职责

### core 模块 - 核心基础设施层

提供 SDK 运行所需的基础组件，不依赖其他业务模块。

| 文件 | 职责 | 关键类/函数 |
|------|------|-------------|
| base.py | 定义所有类型的基础类 | `Base` (dataclass), `create_uuid()`, `create_text_element()` |
| constants.py | ARXML 标签常量统一管理 | 约140个XML标签常量定义 |
| enums.py | AUTOSAR 枚举类型定义 | `Category`, `Encoding`, `PortDirection` 等12个枚举 |

**Base 类核心属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| name | str | 元素名称 |
| id | Optional[int] | 元素标识符 |
| parent | Optional[Base] | 父元素引用 |
| description | Optional[str] | 元素描述 |
| package_path | str | 完整包路径 (如 `/Pkg1/Pkg2/Name`) |

**Base 类核心方法：**

| 方法 | 说明 |
|------|------|
| to_arxml(doc) | 抽象方法，将对象序列化为 ARXML DOM 元素 |
| class_name | 属性，获取类型名称 |
| parent_id | 属性，获取父类 ID |

### types 模块 - 数据类型层

实现 AUTOSAR 数据模型的各个类型，依赖 core 模块。

| 文件 | 职责 | 主要类 |
|------|------|--------|
| base_type.py | 基础数据类型 (SW-BASE-TYPE) | `BaseType` |
| unit.py | 数据单位 | `Unit` |
| data_constraint.py | 数据约束范围 | `DataConstraint` |
| compu_method.py | 计算方法 (线性转换/文本表) | `Linear`, `TextTable`, `CompuMethod` |
| application_types.py | 应用层数据类型 | `ApplicationBooleanDataType`, `ApplicationValueDataType`, `ApplicationStructureDataType`, `ApplicationArrayDataType` |
| implementation_types.py | 实现层数据类型 | `ImplementationValueDataType`, `ImplementationStructureDataType`, `ImplementationArrayDataType` |
| sw_addr_method.py | 软件地址方法 | `SwAddrMethod` |
| data_mapping.py | 应用-实现类型映射 | `DataTypeMapping`, `DataTypeMappingSet` |
| sw_component_type.py | 软件组件类型和端口 | `ApplicationSwComponentType`, `RPortPrototype`, `PPortPrototype`, `PRPortPrototype` |
| interface.py | 接口定义 | `SenderReceiverInterface`, `ClientServerInterface`, `ModeSwitchInterface` |
| package.py | AUTOSAR 包 | `Package` |
| swc_internal_behavior.py | SWC 内部行为 | `RunnableEntity`, `TimingEvent`, `InitEvent`, `SwcInternalBehavior` |

### utils 模块 - 工具层

提供 ARXML 文档创建和写入功能。

| 文件 | 职责 | 关键函数 |
|------|------|----------|
| arxml_writer.py | ARXML 文档创建和写入 | `create_arxml_document()`, `write_arxml()`, `write_arxml_pretty()` |

## 类型继承体系

```
Base (core.base)
├── BaseType (types.base_type)
├── Unit (types.unit)
├── DataConstraint (types.data_constraint)
├── CompuMethod (types.compu_method)
│   ├── Linear
│   └── TextTable
├── ApplicationDataType (types.application_types)
│   ├── ApplicationBooleanDataType
│   ├── ApplicationValueDataType
│   ├── ApplicationStructureDataType
│   │   └── StructureElement (内部类)
│   └── ApplicationArrayDataType
│       └── ArrayElement (内部类)
├── ImplementationDataType (types.implementation_types)
│   ├── ImplementationValueDataType
│   ├── ImplementationStructureDataType
│   │   └── StructureElement (内部类)
│   └── ImplementationArrayDataType
│       └── ArrayElement (内部类)
├── SwAddrMethod (types.sw_addr_method)
├── DataTypeMapping (types.data_mapping)
│   └── DataTypeMappingSet
├── SwComponentType (types.sw_component_type)
│   ├── AtomicComponentType
│   │   └── ApplicationSwComponentType
│   └── CompositionSwComponentType
├── PortPrototype (types.sw_component_type)
│   ├── RPortPrototype
│   ├── PPortPrototype
│   └── PRPortPrototype
├── Interface (types.interface)
│   ├── SenderReceiverInterface
│   │   └── DataElement (内部类)
│   ├── ClientServerInterface
│   │   ├── Operation (内部类)
│   │   └── Argument (内部类)
│   ├── ModeSwitchInterface
│   ├── ParameterInterface
│   ├── TriggerInterface
│   └── NvDataInterface
├── Package (types.package)
└── SwcInternalBehavior (types.swc_internal_behavior)
    ├── RunnableEntity
    └── EventType (Union)
        ├── InitEvent
        ├── TimingEvent
        ├── OperationInvokedEvent
        └── DataReceivedEvent
```

## 依赖关系图

```
                    ┌─────────────────────────────────────┐
                    │      arxml_sdk (src/__init__.py)     │
                    │   导出全部 193 个公共 API 符号        │
                    └─────────────────────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │                           │                           │
         ▼                           ▼                           ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   core 模块     │      │   types 模块    │      │   utils 模块    │
│   (基础设施层)  │      │   (业务逻辑层)  │      │   (工具层)      │
├─────────────────┤      ├─────────────────┤      ├─────────────────┤
│ Base 基类       │      │ 数据类型类      │      │ ARXML文档创建   │
│ 常量定义       │◄─────►│ 组件类型类      │      │ ARXML文件写入   │
│ 枚举定义       │      │ 接口定义类      │      │                 │
│ UUID/文本工具  │      │ 包管理类        │      │                 │
└─────────────────┘      │ 内部行为类      │      └─────────────────┘
                         └─────────────────┘
                                    │
                                    ▼
                         ┌─────────────────┐
                         │   tests 模块    │
                         │   (测试层)      │
                         ├─────────────────┤
                         │ 单元测试        │
                         │ 集成测试        │
                         └─────────────────┘
```

**依赖约束：**
- `core` → 无依赖（最底层）
- `types` → 依赖 `core`
- `utils` → 依赖 `core`
- `tests` → 依赖 `src` 所有模块

## 设计模式

### 1. 工厂函数模式

所有类型都配有 `create_xxx()` 工厂函数，简化对象创建：

```python
# 使用工厂函数
uint8 = create_base_type("UInt8", size=8)

# 替代直接实例化（如果存在构造函数）
uint8 = BaseType(name="UInt8", size=8)
```

### 2. 组合模式

通过 `add_xxx()` 方法支持动态添加子元素：

```python
component = ApplicationSwComponentType(name="Sensor")
component.add_port(PPortPrototype(name="DataPort"))
```

### 3. 序列化模式

所有类型都实现 `to_arxml(doc)` 方法，将自身序列化为 ARXML DOM 元素：

```python
element = component.to_arxml(doc)
```

### 4. 数据类模式

使用 `@dataclass` 简化数据类定义：

```python
@dataclass
class BaseType:
    name: str
    size: int
    category: Optional[Category] = None
    encoding: Optional[Encoding] = None
```

## 数据流

```
用户代码
    │
    ▼
创建对象 (工厂函数)
    │
    ├──► BaseType, ApplicationDataType, SwComponentType 等
    │
    ▼
序列化 (to_arxml)
    │
    ├──► XML DOM Element
    │
    ▼
写入文件 (arxml_writer)
    │
    ▼
.arxml 文件
```

## 技术栈

| 方面 | 详情 |
|------|------|
| 编程语言 | Python 3 |
| 标准库 | `uuid`, `xml.dom.minidom`, `dataclasses`, `typing`, `enum` |
| 测试框架 | pytest |
| 目标格式 | AUTOSAR ARXML (R4.4 schema) |
| 版本 | 2.0.1 |