# Redfish Schema 更新工具

用于更新 Redfish schema 文件的 Python 脚本，支持从 DMTF 官方仓库或本地 zip 文件获取最新的 schema 文件。

## 功能特性

- **远程下载**：从 DMTF 官方网站自动下载指定版本的 Redfish schema
- **本地导入**：从本地 zip 文件导入 schema 文件
- **智能过滤**：只更新项目中已使用的资源类型
- **版本管理**：
  - CSDL (XML) 文件：直接覆盖更新
  - JSON schema 文件：保留历史版本，同时获取最新版本
- **可选更新**：
  - 可选择是否更新 `mapping_config` 目录中所有 JSON 文件的 `@odata.type` 版本引用（默认启用）
  - 可选择是否更新 `metadata/index.xml` 文件中的 Namespace 引用（默认启用）

## 依赖

### Python 版本要求
- Python 3.10 或更高版本（使用了类型注解 `str | None` 等语法）

### Python 包依赖
```bash
pip install requests
```

**说明**：urllib3 会作为 requests 的依赖自动安装，无需单独安装。

## 使用方法

### 基本用法

```bash
# 从远程下载最新版本
python schema_updater.py --version DSP8010_2025.4

# 从本地 zip 文件导入
python schema_updater.py --source local --zip-path /path/to/DSP8010_2025.4.zip
```

### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--version` | string | 条件必填 | None | 指定 Redfish schema 版本（如：DSP8010_2025.4）。`--source=remote` 时必填 |
| `--source` | string | 否 | remote | 指定 zip 文件来源：`remote`（远程下载）或 `local`（本地文件） |
| `--zip-path` | string | 条件必填 | None | 本地 zip 文件路径。`--source=local` 时必填 |
| `--output-dir` | string | 否 | None | 指定 schema 文件输出目录路径（相对于项目根目录）。如未指定，使用默认路径 |
| `--update-odata-type` | flag | 否 | True | 启用 `mapping_config` 目录中的 `@odata.type` 版本更新 |
| `--no-update-odata-type` | flag | 否 | False | 禁用 `mapping_config` 目录中的 `@odata.type` 版本更新 |
| `--update-metadata` | flag | 否 | True | 启用 `metadata/index.xml` 文件的 Namespace 引用更新 |
| `--no-update-metadata` | flag | 否 | False | 禁用 `metadata/index.xml` 文件的 Namespace 引用更新 |

### 使用示例

#### 示例 1：从远程下载指定版本

```bash
python schema_updater.py --version DSP8010_2025.4
```

这将：
1. 从 `https://www.dmtf.org/sites/default/files/standards/documents/DSP8010_2025.4.zip` 下载文件
2. 提取项目中已使用的资源类型的 schema 文件
3. 更新到默认目录 `interface_config/redfish/static_resource/redfish/v1/schemastore/en/dmtf/`

#### 示例 2：从本地文件导入

```bash
python schema_updater.py --source local --zip-path ~/Downloads/DSP8010_2025.4.zip
```

#### 示例 3：指定输出目录

```bash
# 使用绝对路径
python schema_updater.py --version DSP8010_2025.4 --output-dir /tmp/schema_test

# 使用相对路径（相对于项目根目录）
python schema_updater.py --version DSP8010_2025.4 --output-dir test/output
```

#### 示例 4：禁用 @odata.type 更新

```bash
# 只更新 schema 文件，不修改 mapping_config 目录
python schema_updater.py --version DSP8010_2025.4 --no-update-odata-type

# 或从本地文件导入且不更新 odata.type
python schema_updater.py --source local --zip-path ~/Downloads/DSP8010_2025.4.zip --no-update-odata-type
```

#### 示例 5：禁用 metadata 更新

```bash
# 只更新 schema 文件，不修改 metadata/index.xml
python schema_updater.py --version DSP8010_2025.4 --no-update-metadata

# 禁用所有后处理更新
python schema_updater.py --version DSP8010_2025.4 --no-update-odata-type --no-update-metadata
```

## 工作流程

1. **获取源文件**：根据 `--source` 参数从远程下载或读取本地 zip 文件
2. **版本识别**：从文件名或参数中提取版本号（如 `DSP8010_2025.4`）
3. **类型过滤**：扫描本地已存在的 schema 文件，获取已使用的资源类型列表
4. **文件提取**：
   - CSDL 文件：提取匹配的资源类型，直接覆盖
   - JSON schema 文件：提取匹配的资源类型，保留历史版本，添加最新版本
5. **版本更新**（可选）：扫描新下载的 JSON schema 文件，提取最新版本号
6. **配置更新**（可选）：
   - 如果启用 `--update-odata-type`，更新 `mapping_config` 目录下所有 JSON 文件中的 `@odata.type` 引用
   - 如果启用 `--update-metadata`，更新 `metadata/index.xml` 文件中的 Namespace 引用

## 输出目录结构

```
interface_config/redfish/static_resource/redfish/v1/schemastore/en/dmtf/
├── csdl/              # CSDL (XML) schema 文件
│   ├── accountservice.xml
│   ├── chassis.xml
│   └── ...
└── json_schema/       # JSON schema 文件
    ├── accountservice.json
    ├── accountservice.v1_0_0.json
    ├── accountservice.v1_15_1.json
    └── ...
```

## 环境变量

- `https_proxy`：可选，用于设置 HTTP 代理。脚本会自动读取此环境变量用于远程下载。

## 注意事项

1. **网络要求**：使用 `--source=remote` 时需要能够访问 DMTF 官方网站
2. **目录权限**：确保对目标目录有写权限
3. **版本兼容性**：请确保下载的 schema 版本与项目兼容
4. **文件覆盖**：CSDL 文件会被完全覆盖，JSON schema 文件会保留历史版本
5. **@odata.type 更新**：默认会更新 `mapping_config` 目录中的版本引用，如需禁用请使用 `--no-update-odata-type` 参数
6. **metadata 更新**：默认会更新 `metadata/index.xml` 文件中的 Namespace 引用，如需禁用请使用 `--no-update-metadata` 参数

## 故障排除

### 问题：无法连接到 DMTF 网站

**解决方案**：
- 检查网络连接
- 设置代理：`export https_proxy=http://your-proxy:port`
- 使用 `--source=local` 从本地文件导入

### 问题：找不到本地资源类型

**原因**：脚本只会更新本地已存在的资源类型

**解决方案**：确认默认目录或指定的输出目录中已存在对应的 schema 文件

### 问题：版本号提取失败

**解决方案**：
- 确保本地 zip 文件名和 DMTF 官网下载文件名一致
- 或使用 `--version` 参数显式指定版本号

## 维护建议

- 定期检查 [DMTF 官网](https://www.dmtf.org/standards/redfish) 发布的新版本
- 建议在测试环境中先验证新版本 schema 的兼容性
- 更新前建议备份现有的 schema 文件
