*openUBMC bingo自升级支持同步更新Studio和Qemu工具-功能详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>CICD</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>25.2.0</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>王敏</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2025.08.20</td>
    </tr>
</table>

**Copyright © 2025 openUBMC Community**

您对&quot;本文档&quot;的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称&quot;MulanPSL2&quot;)的约束。
为了方便用户理解，您可以通过访问<https://license.coscl.org.cn/MulanPSL2>了解MulanPSL2的概要 (但不是替代)。
MulanPSL2的完整协议内容您可以访问如下网址获取：<https://license.coscl.org.cn/MulanPSL2>。

**改版记录**

<table>
    <tr>
        <th>日期</th>
        <th>修订版本</th>
        <th>修订描述</th>
        <th>作者</th>
        <th>审核</th>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

**List of abbreviations**  **缩略语清单** ：

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->
工程工具需要明确安装依赖关系，并实现依赖管理。

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->
bingo的deb安装包将QEMU工具添加为可选依赖，用户安装bingo时默认安装QEMU。

执行bingo up升级时，能够根据用户提供的命令参数选择是否升级studio和qemu。

## 1.3 功能场景
<!-- 描述该需求的业务使用场景，内容包括：
1) 场景出发条件及对象：什么角色/工具/接口等在什么具体情况下使用该特性，使用对象技能如何？
2) 使用时间及频度
3) 描述该特性主要有哪些场景、子场景及关键任务操作 -->
- 社区用户安装bingo
- bingo升级

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | bingo自升级支持同步更新Studio和Qemu工具 | bingo自升级支持同步更新Studio和Qemu工具 |


# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->
- bingo安装：以deb可选依赖的形式安装qemu
- bingo升级：参照InstallStudio类实现qemu的自动升级

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->
- bingo安装

    在bingo/tools/deb/DEBIAN/control文件中，qemu-system-aarch64是qemu在apt源上的包名，本次将其从Depends改为Recommends，使其作为可选依赖（用户默认安装）

    流水线：不影响。

    对于不需要安装Recommends依赖的场景，可以在安装时指定--no-install-recommends参数。

- bingo 升级

    deb包的依赖升级必须通过指定依赖项的版本号范围实现，无法实现自动更新。因此，本需求在bingo upgrade命令中实现Studio和qemu的同步更新。

    bingo upgrade当前仅升级bingo工具，如下图：
    ![](./images/bingo-upgrade.png)

    为bingo upgrade 命令加入studio和qemu的工具支持，在现有机制的基础上，`bingo upgrade`为升级全部已安装工具到最新版本；
    `bingo upgrade -v XX=XX` 升级指定工具到指定版本，如`bingo upgrade -v qemu=6.1.0-3build9`


#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->
![](./images/bingo-upgrade-process.png)

#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->


### 2.1.2 内部依赖分析
<!-- 是否涉及与其他组件接口依赖，如果涉及需要确认当前是否已完成，是否匹配当前需求开发诉求 -->
不涉及

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
不涉及

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 -->
不涉及

### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
不涉及

### 2.1.6 定制化接口分析
<!-- 如果支持定制化设置，则需要给出定制化时的默认值（空定制化项条件下的设置值），如果涉及到定制化接口变更或新增，注意定制化接口文档需配套修改。注意定制化默认值变更对白牌包的影响 -->
不涉及

### 2.1.7 导入导出分析
<!-- 如果支持导入导出的配置，则需要分析导入导出的schema。 -->
不涉及

### 2.1.8 传感器分析
<!-- 如果需要新增传感器，则需要提前登记和评审新增的传感器要素。新增传感器评审需要上SIG-Interface进行评审 -->
不涉及

### 2.1.9 精准告警事件分析
<!-- 如果需要新增事件，则需要提前登记和评审新增的时间要素 -->
不涉及

### 2.1.10 系统锁定分析
<!-- 对外的接口或者命令是否支持系统锁定 -->
不涉及

### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->

| 场景 | Studio现状 | qemu现状 | 期望结果 |
| ---- | ---- | ---- | --- |
| 安装bingo deb | 不安装 | 安装 | 保持一致 |
| init.py初始化 | 安装25.03版本 | 不安装（通过bingo安装） | Studio改为安装最新版本 |
| bingo upgrade | 不升级 | 不升级 | 如果当前环境中存在Studio或qemu，升级到最新版本 |


# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1【功能编号】bingo自升级支持同步更新Studio和Qemu工具
### 3.1.1 功能实现设计

- bingo安装

    在bingo/tools/deb/DEBIAN/control文件中，qemu-system-aarch64是qemu在apt源上的包名，本次将其从Depends改为Recommends，使其作为可选依赖（用户默认安装）

    流水线：不影响。

    对于不需要安装Recommends依赖的场景，可以在安装时指定--no-install-recommends参数。

- bingo 升级

    deb包的依赖升级必须通过指定依赖项的版本号范围实现，无法实现自动更新。因此，本需求在bingo upgrade命令中实现Studio和qemu的同步更新。基于InstallManager类实现Studio和qemu的自动升级。

    bingo upgrade 升级bingo工具；带-a/--all 升级全部工具

    qemu升级：复用AptInstaller升级到最新版本。

    Studio升级：将Studio deb包上传至apt源中（与QEMU类似），复用AptInstaller升级到最新版本。


### 3.1.2 功能详细设计

代码实现逻辑

![](./images/bingo-upgrade-logic.png)

### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
功能覆盖验证，不涉及DT。

#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->

#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->
