!15256 新增快速修复指导文档

Merge pull request !15256 from wangtiantian/quickfix

zh-cn/application-dev/quick-start/Readme-CN.md

@@ -19,6 +19,10 @@
       - [多HAP使用规则](multi-hap-rules.md)
       - [多HAP运行机制及数据通信方式](multi-hap-principles.md)
     - [应用程序包安装和卸载流程](application-package-install-uninstall.md)
+    - [应用程序包更新流程](application-package-update.md)
+    - 应用程序包快速修复
+      - [快速修复概述](quickfix-principles.md)
+      - [快速修复调试指导](quickfix-debug.md)
   - 应用配置文件（Stage模型）
     - [应用配置文件概述（Stage模型）](application-configuration-file-overview-stage.md)
     - [app.json5配置文件](app-configuration-file.md)

zh-cn/application-dev/quick-start/application-package-update.md

+# 应用程序包更新流程
+OpenHarmony包管理服务提供了应用程序包更新能力，更新方式如下。
+
+1. 应用市场内更新：新版本应用通过应用市场上架后，应用市场通知终端用户该应用有新版本，终端用户可以根据通知到应用市场（客户端）进行应用升级。
+2. 应用内检测升级：终端用户启动应用时，应用市场检测到该应用有新版本会通知终端用户，可以到应用市场进行应用的下载更新。
\ No newline at end of file

zh-cn/application-dev/quick-start/quickfix-debug.md

+# 快速修复命令行调试开发指导
+
+当前阶段，OpenHarmony为开发者提供了命令行的调试开发工具可供使用。比如，包名为com.ohos.quickfix的示例应用，版本号为1000000。该应用的当前版本运行中有某问题需要修复，此时，开发者可参考如下指导使用快速修复能力解决应用问题。
+
+## 编写配置文件patch.json
+
+目前DevEco Studio中还不支持patch.json的配置，因此开发者可根据项目需要编写好该文件后，放到的项目任意目录，方便后续打包工具能够找到该文件即可。在本地新建一个patch.json文件，配置编写示例如下：
+```json
+{
+    "app" : {
+        "bundleName" : "com.ohos.quickfix",
+        "versionCode" : 1000000, // 应用版本号
+        "versionName" : "1.0.0.1",
+        "patchVersionCode" : 1000000, // 补丁版本号
+        "patchVersionName" : "1.0.0.1"
+    },
+    "module" : {
+        "name" : "entry",
+        "type" : "patch",
+        "deviceTypes" : [
+            "default",
+            "tablet"
+        ],
+        "originalModuleHash" : "11223344556677889900" // 待修复hap包的sha256值
+    }
+}
+```
+
+## 生成快速修复文件
+### 快速修复TS文件的代码
+* 在DevEco Studio中修改TS文件后，编译HAP，可以在工程目录下找到对应的abc文件，如`build\default\cache\default\LegacyCompileETS\jsbundle\temporary\pages\index.abc`。
+
+### 快速修复C++中的代码
+
+* 在DevEco Studio中编译原C++的代码生成.so文件；修复原C++的代码，编译生成新的.so文件。可以在工程目录中找到该so，如`build\default\intermediates\libs\default\arm64-v8a\libentry.so`。
+* 在本地OpenHarmony SDK路径的`toolchains`文件夹下查看`diff.exe`。通过该工具，基于新.so文件和旧的.so文件，生成.so的快速修复文件，命令如下：
+```shell
+$ diff.exe -s Example.z.so -d Example.z.so -p Example.z.so.diff
+```
+命令行参数含义：
+- -s：旧so的路径
+- -d：新so的路径
+- -p：生成的差分文件的路径
+
+## 生成.hqf的快速修复包
+
+基于上述的patch.json、.abc快速修复文件和.so快速修复文件，可以通过本地OpenHarmony SDK路径的`toolchains`文件夹下的`app_packing_tool.jar`生成.hqf包，执行打包命令如下：
+```shell
+$ java -jar app_packing_tool.jar --mode hqf --json-path patch.json --lib-path libs --ets-patch patchs --out-path entry-default-unsigned.hqf --force true
+```
+
+命令行参数介绍：
+| 命令 |说明  | 备注|
+| --- | --- |---|
+| mode  |模式  | 必选|
+| json-path|patch.json路径|必选|
+| lib-path|.so快速修复文件路径，该路径可参考[快速修复包结构](quickfix-principles.md#快速修复包结构)|可选|
+| ets-path|.abc快速修复文件路径|可选|
+
+## 快速修复包的签名
+
+签名与hap签名相同，将上述生成的entry-default-unsigned.hqf包，通过[签名工具](../security/hapsigntool-guidelines.md)进行签名。可以使用本地OpenHarmony SDK路径的`toolchains`文件夹下的`hap-sign-tool.jar`，命令如下：
+
+```shell
+$ java -jar hap-sign-tool.jar sign-app -keyAlias "OpenHarmony Application Release" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "OpenHarmonyApplication.pem" -profileFile "ohos_provision_release.p7b" -inFile "entry-default-unsigned.hqf" -keystoreFile "OpenHarmony.p12" -outFile "entry-signed-release.hqf" -keyPwd "123456" -keystorePwd "123456"
+```
+
+## 安装快速修复包
+
+将上述entry-signed-release.hqf包推送到设备上
+```shell
+hdc.exe file send .\entry-signed-release.hqf /data/
+```
+
+在设备上通过下述命令行安装补丁包
+```shell
+$ bm quickfix -a -f /data/entry-signed-release.hqf
+```
+
+快速修复相关完整命令行参考如下：
+```
+$ bm quickfix -h
+usage: bm quickfix <options>
+options list:
+-h, --help                                   list available commands
+-q, --query                                  indicates query quickfix, used with -b or --bundle-name
+-b, --bundle-name <bundle-name>              query quickfix status and information by a specified bundle name
+-a, --apply                                  indicates apply quickfix, used with -f or --file-path
+-f, --file-path <file-path>                  apply a quickfix file by a specified path
+-f, --file-path <file-path> <file-path> ...  apply some quickfix files of one bundle
+-f, --file-path <bundle-direction>           apply quickfix files by direction, under which are quickfix files
+```

zh-cn/application-dev/quick-start/quickfix-principles.md

+# 快速修复概述
+
+快速修复是OpenHarmony系统提供给开发者的一种技术手段，支持开发者以远快于应用升级的方式对应用程序包进行缺陷修复。和全量应用升级软件版本相比，快速修复的主要优势在小、快和用户体验好。在较短的时间内不中断正在运行的应用的情况下（即不需要重启应用），修复应用的缺陷。
+
+## 快速修复的使用规则
+
+* 仅支持修复应用的TS和C++代码，对应的文件为.abc文件（TS编译后的文件）和.so文件（C++编译后的文件），不支持对资源的修复。
+* 不支持新增.abc文件和.so文件。
+* 快速修复包部署时要确保对应应用包已安装，如果未安装，则部署失败。
+* 快速修复包中配置的包名和应用版本号必须和已安装的包名和版本号应用相同，如果不同则部署失败。
+* 如果已经部署过快速修复包，新部署的快速修复包的版本号必须大于之前快速修复包的版本号，否则部署失败。
+* 快速修复包的签名信息和待修复的应用的签名信息必须一致，否则会部署失败。
+* 新的应用版本发布安装时，会清理掉快速修复包。
+
+## 快速修复包结构
+
+![快速修复包结构](figures/quick_fix_bundle_struct.png)
+<br>上图是OpenHarmony应用程序发布的快速修复的包格式
+* 从图中可以看出包含两种包格式：
+    * appqf（Application Quick Fix）
+    <br> appqf与应用的app pack包是一一对应关系，具体可参考[应用程序包结构](application-package-structure-stage)的介绍。
+        * appqf包是OpenHarmony应用用于发布到应用市场的单元，不能够直接安装到设备上。
+        * 它是由一个或多个hqf（Harmony Ability Package Quick Fix）组成，这些hqf包在应用市场会从appqf包中拆分出来，再被分发到具体的设备上。
+        * appqf包上架到应用市场前要有开发者的签名信息。签名方式可可参考[Hap包签名工具](../security/hapsigntool-overview.md)的介绍。
+    * hqf（Harmony Ability Package Quick Fix）
+    <br> hqf包是修复HAP中问题的快速修复包，用于安装到设备上的快速修复单元。一个hqf可以包含.abc的快速修复文件，.so的快速修复文件和描述该包的配置文件。
+        * `.abc`文件：应用中修改后的ts代码，编译后生成的字节码文件。
+        * `libs`目录：存放.so库文件的差分文件，以`.so.diff`为后缀。区分的不同的系统cpu架构，例如arm平台、x86平台。
+        * `patch.json`：
+        <br> 该文件用于描述hqf包版本信息的配置文件，由开发者填写，具体内容如下：
+            ```json
+            {
+                "app" : {
+                    "bundleName" : "com.ohos.quickfix",
+                    "versionCode" : 1000000,
+                    "versionName" : "1.0.0",
+                    "patchVersionCode" : 1000000,
+                    "patchVersionName" : "1.0.0"
+                },
+                "module" : {
+                    "name" : "entry",
+                    "type" : "patch",
+                    "deviceTypes" : [
+                    "default",
+                    "tablet"
+                    ],
+                    "originalModuleHash" : "11223344556677889900"
+                }
+            }
+            ```
+            具体字段说明：
+            | 字段 |类型  |说明  |备注 |
+            | --- | --- | --- | --- |
+            |bundleName | string | 对应应用的包名    | 不可缺省 |
+            |versionCode | int |对应应用版本号          | 不可缺省  |
+            |versionName |string |对应应用的版本名称 | patch类型不可缺省 |
+            |patchVersionCode |int |补丁包的版本号   | 不可缺省 |
+            |patchVersionName |string |补丁包的版本名称 | patch类型不可缺省 |
+            |name |string |对应应用的moduleName，用来修复该module的 | 不可缺省 |
+            |type | string|对应补丁包的类型，当前可选择为patch | 不可缺省 |
+            |deviceTypes |array<string> |补丁包支持的设备类型 | 不可缺省 |
+            |originalModuleHash| string |原始module Name对应包的哈希值 | 不可缺省 |
+
+## 快速修复TS编译后的文件
+
+![快速修复生成abc](figures/quick_fix_gen_abc.png)
+
+上图是通过TS代码编译工具生成快速修复.abc文件的流程：
+* 原始应用编译时，生成.abc文件和.map文件。.abc是TS代码编译后的字节码文件，应用运行时使用该文件。.map文件是通过TS代码编译工具编译TS代码时生成的中间文件，记录有代码中的函数、类等信息。
+* 修复问题后的应用编译时，根据上述的.map文件，结合当前的TS代码，得到差异部分，根据差异部分生成快速修复的.abc文件。该.abc文件也既是最终要放到hqf包中的快速修复文件。
+
+## 快速修复C++编译后的文件
+
+![快速修复差分so生成](figures/quick_fix_gen_so.png)
+
+上图是通过差分工具生成快速修复.so文件的流程：
+* 原始应用C++源码通过编译工具生成.so文件，该.so文件供应用在运行时使用。
+* 修复问题后的C++源码通过编译工具生成.so文件，该.so文件和原应用的.so文件通过差分工具生成.so快速修复文件，该.so快速修复文件也既是最终要放到hqf包中的快速修复文件。
+
+## 快速修复包的发布部署流程
+
+![快速修复包的发布](figures/quick-fix-devel_release.png)
+
+上图涉及到的模块如下：
+* DevEco Studio：用于开发代码的项目工程的集成开发环境。在快速修复的工程中能够给予原应用的代码和修复问题后的代码生成快速修复包，并完成快速修复包的签名。
+* 应用市场服务器端：开发者将开发完成的快速修复包上架到该平台，平台会对上架的包进行签名验证、风险扫描和拆包重签名等，然后分发到客户端。
+* 应用市场客户端：用于接收应用市场服务器端分发的快速修复包，并触发安装快速修复包。
+* 包管理服务：设备上用于管理应用包及快速修复包安装和卸载的系统服务程序。
+* 快速修复引擎：设备上用于管理应用切换使用快速修复包的系统服务程序。如果应用正在运行，快速修复引擎接收到有快速修复包部署完成会通知应用切换快速修复包，进而使得应用使能快速修复包。
+* 文件系统：应用及快速修复包部署在设备上的位置。
+
+上图是快速修复包的端到端发布部署流程：
+1. 开发者通过DevEco Studio，基于原应用的源码和修复后的源码编译打包生成快速修复包，并通过DevEco Studio完成快速修复包的签名。
+2. 将生成的带有签名的快速修复包上架到应用市场，应用市场通过验证签名、风险扫描和拆包重签名后进行分发。
+3. 设备侧的应用市场客户端检测到应用市场服务器端有新上架的快速修复包会下载最新版本的快速修复包，接着通过系统中的包管理服务来安装部署快速修复包。
+4. 快速修复包部署完成后，再由快速修复引擎触发应用使用快速修复包，进而保证用户使用到问题修复后的功能。
+
+## 快速修复包的调试流程
+
+![快速修复包的调试](figures/quick-fix-debug.png)
+
+* DevEco Studio中暂时还没有集成快速修复的能力。当前阶段，OpenHarmony为开发者提供了命令行的调试开发工具可供使用，具体的调试开发流程如下：
+1. 基于原应用的源码和修复后的源码，通过命令行工具可以编译生成快速修复包，并通过命令行签名工具完成对快速修复的包的签名。通过命令行调试开发，要对.hqf包签名，并通过命令行工具将.hqf包安装到设备上，.appqf包不能直接安装到设备上。
+2. 通过快速修复的命令行工具，将.hqf包安装部署到设备上。
+3. .hqf包安装部署完成后，回调通知快速修复引擎触发应用使用快速修复包，进而保证用户使用到问题修复后的功能。
\ No newline at end of file