format: key

src/main/asciidoc/specs/base/communication.adoc

@@ -3,18 +3,13 @@ RPS_TOC
 
 canonical={canonical}
 
-// tag::main[]
-
 == RPS_KEY_DEF
 
-* 前端
-** 贴近真实用户侧的软件，主要与后端服务交互并将其可视化为用户提供界面的软件，通常在用户侧的设备上运行，
-* 通信
-** 两个不在一个内存空间甚至不在一个设备上运行的程序，需要通过网络来进行通信以表达请求、传递数据的过程。
-* 通信协议
-** 对软件通信进行了一定的规范和约束定义，使得软件交互过程更加清晰、明了，这里指软件在应用层交互的协议如HTTP协议、FTP协议、gRPC。
-* 序列化/反序列化
-** 这里的序列化指软件运行时内存态数据转化为通信协议所需数据的过程。
+[horizontal]
+前端:: 贴近真实用户侧的软件，主要与后端服务交互并将其可视化为用户提供界面的软件，通常在用户侧的设备上运行，
+通信:: 两个不在一个内存空间甚至不在一个设备上运行的程序，需要通过网络来进行通信以表达请求、传递数据的过程。
+通信协议:: 对软件通信进行了一定的规范和约束定义，使得软件交互过程更加清晰、明了，这里指软件在应用层交互的协议如HTTP协议、FTP协议、gRPC。
+序列化/反序列化:: 这里的序列化指软件运行时内存态数据转化为通信协议所需数据的过程。
 
 == 🆚 现代常见通信协议比较
 
@@ -22,13 +17,13 @@ canonical={canonical}
 
 === Restful API
 
-**REST**：表述性状态传递 Roy Fielding博士在2000年他的博士论文中提出REST（Representational State Transfer）风格的软件架构模式，REST出现后，迅速取代了复杂而笨重的SOAP，成为Web API的标准，
-**Restful**：REST 风格的设计。
-**Restful API** REST风格的应用程序接口。link:api.html[Shoulder API 规范]中有一定说明。
+**REST**:: 表述性状态传递 Roy Fielding博士在2000年他的博士论文中提出REST（Representational State Transfer）风格的软件架构模式，REST出现后，迅速取代了复杂而笨重的SOAP，成为Web API的标准，
+**Restful**:: REST 风格的设计。
+**Restful API**:: REST风格的应用程序接口。link:api.html[Shoulder API 规范]中有一定说明。
 
-基于HTTP/1协议设计，由于其足够简单，几乎被互联网完全认可，是互联网的通用协议，绝大多数设备均支持，协议穿透性好。由于其基于HTTP的文本协议，与其他二进制通信协议相比较重，性能自然差一些。
+NOTE: 基于HTTP/1协议设计，由于其足够简单，几乎被互联网完全认可，是互联网的通用协议，绝大多数设备均支持，协议穿透性好。由于其基于HTTP的文本协议，与其他二进制通信协议相比较重，性能自然差一些。
 
-适用于系统的开放边界，与第三方交互的地方。
+TIP: 适用于系统的开放边界，与第三方交互的地方。
 
 === Dubbo
 
@@ -59,6 +54,3 @@ canonical={canonical}
 ** 有性能需求场景、且在考虑调用方与服务提供方开发成本的前提下，优先选择 dubbo/gRPC 系列
 ** 通用场景可以选择 Restful 进行快速迭代。
 
-
-
-// end::main[]

src/main/asciidoc/specs/base/errorCode.adoc

@@ -7,15 +7,11 @@ canonical={canonical}
 
 == RPS_KEY_DEF
 
-* 错误码
-** 特定的错误的标识，可用于自动化处理或或便于排查等。
-* 程序处理状态
-** 成功
-*** 服务器理解请求的意图，并正确执行了该请求。
-** 正常失败
-*** 请求或处理过程种与服务器所期待的状态不一致，且服务器知晓这类错误的原因（在编码时便考虑到了），拒绝执行了该请求。如：请求参数不合法、无权限等。这类错误通常需要提醒使用者修改输入。
-** 异常失败
-*** 请求已被服务器接收理解，认为其合法，但在执行时未能正确处理请求，如：`NullPointException`、assert 失败等（在编码时未考虑到或认为不应该发生的错误）。这类错误运行时本不应该发生，需要维护者来排查。
+错误码:: 特定的错误的标识，可用于自动化处理或或便于排查等。
+程序处理状态::
+. 成功（Success）: 服务器理解请求的意图，并正确执行了该请求。
+. 正常失败（Failure）: 请求或处理过程种与服务器所期待的状态不一致，且服务器知晓这类错误的原因（在编码时便考虑到了），拒绝执行了该请求。如：请求参数不合法、无权限等。这类错误通常需要提醒使用者修改输入。
+. 异常失败（Unknown）: 请求已被服务器接收理解，认为其合法，但在执行时未能正确处理请求，如：`NullPointException`、assert 失败等（在编码时未考虑到或认为不应该发生的错误）。这类错误运行时本不应该发生，需要维护者来排查。
 
 == RPS_CONSTRAINT
 

src/main/asciidoc/specs/base/log.adoc

@@ -7,17 +7,11 @@ canonical={canonical}
 
 == RPS_KEY_DEF
 
-* 日志
-** 运行日志/系统日志
-*** 开发人员为了方便定位错误而打的日志，该部分较为自由
-** 追踪日志/调用链日志
-*** 分布式系统中为了追踪某个调用链流程相关的日志，该部分一般遵循一定的规范如 https://opentracing.io/docs/overview/[OpenTracing]。
-** 特殊日志
-*** 面向某特定领域，具有统一格式约束的日志，以在特定场景实现某一功能的日志。如操作日志/业务日志、审计日志。如：操作日志统一使用 `JSON` 格式，并且要求包含指定的字段。
-* 级别
-** 用于日志分类：描述日志重要程度、统一处理某一级别的日志（如控制输出路径、文件名、保存时间、是否输出等）。
-* 日志服务
-** 拥有处理日志的能力的软件系统，通常具有采集、存储、检索、分析日志的能力，典型如 `ELK`。
+运行日志/系统日志:: 开发人员为了方便定位错误而打的日志，该部分较为自由
+追踪日志/调用链日志:: 分布式系统中为了追踪某个调用链流程相关的日志，该部分一般遵循一定的规范如 https://opentracing.io/docs/overview/[OpenTracing]。
+特殊日志:: 面向某特定领域，具有统一格式约束的日志，以在特定场景实现某一功能的日志。如操作日志/业务日志、审计日志。如：操作日志统一使用 `JSON` 格式，并且要求包含指定的字段。
+日志级别:: 用于日志分类：描述日志重要程度、统一处理某一级别的日志（如控制输出路径、文件名、保存时间、是否输出等）。
+日志服务:: 拥有处理日志的能力的软件系统，通常具有采集、存储、检索、分析日志的能力，典型如 `ELK`。
 
 == RPS_CONSTRAINT
 

src/main/asciidoc/specs/devOps/cicd.adoc

@@ -7,7 +7,7 @@ canonical={canonical}
 
 == RPS_KEY_DEF
 
-* 持续集成/构建：当触发自动构建的条件（如提交代码至主分支，定时构建），`CI服务器` 从版本控制系统中取出最新代码开始编译，对代码进行 `静态检查` 、 `构建` 、 `部署` 、 `测试` 的自动化过程。
+持续集成/构建（CI）:: 当触发自动构建的条件（如提交代码至主分支，定时构建），`CI服务器` 从版本控制系统中取出最新代码开始编译，对代码进行 `静态检查` 、 `构建` 、 `部署` 、 `测试` 的自动化过程。
 
 == 🔑 关键阶段
 

src/main/asciidoc/specs/security/negotiate.adoc

@@ -9,27 +9,18 @@ canonical={canonical}
 
 == RPS_KEY_DEF
 
-* 公钥、私钥
-** 公钥会进入网络传输的，该部分是公开的。
-** 私钥由部分不允许公开。
-* `DH` 密钥交换（协商）算法
-** 全称为Diffie-Hellman ，该算法仅传输双方各自的公钥即可使得双方计算出相同的key，可以使用这个key作为密钥加密信息；即使攻击者只获取到双方公钥也无法计算出Key值。
-** 关键点：需要保证在互换双方公钥时不被中间人进行替换，否则可能遭受中间人攻击。
-* 共享密钥/会话密钥
-** DH算法中，双方进行密钥（公钥）交换后，通过对方公钥和己方私钥生成的Key值（双方结果相同）。
-** 只要私钥不被破解，该值就是安全的。
-* 数据密钥
-** 真正用于加密数据的key，每次会话随机生成，使用该密钥加密敏感数据，然后用共享密钥和共享iv（ `shareIv` ）进行加密，随后该值将被销毁。
+公钥:: 公钥会进入网络传输的，该部分是公开的，需要确保使用者感知的公钥是正确的。
+私钥:: 密钥中私钥部分不允许公开。
+`DH` 密钥交换（协商）算法:: 全称为 `Diffie-Hellman` ，该算法仅传输双方各自的公钥，即可使得双方各自计算出相同的 `key`，可以使用这个 `key` 作为 `密钥` 来加密敏感信息。可确保攻击者通过监听网络与抓包请求获取到双方公钥也无法计算出 `key` 值。
+* 关键点：需要保证在互换双方公钥时不被中间人进行替换，否则可能遭受中间人攻击。
+共享密钥/会话密钥:: `DH` 算法中，双方进行密钥（公钥）交换后，通过对方公钥和己方私钥生成的Key值（双方结果相同），只要私钥不被窃取/破解，该值就是安全的。
+数据密钥:: 真正用于加密数据的key，每次会话随机生成，使用该密钥加密敏感数据，然后用共享密钥和共享iv（ `shareIv` ）进行加密，随后该值将被销毁。
 ** 发送数据时，会将 `使用该值加密过的敏感数据密文` 、 `共享iv` 、 `使共享密钥加密过的数据密钥（该值）` 传递给对方，对方会先解密出 `数据密钥明文` ，然后解密出本次传输的敏感信息。
 ** 该值仅在内存中使用时临时生成和恢复，用后即销毁，因为该值是临时的，且不在网络中传输，所以可以保证敏感数据的安全。
-* 安全会话标识
-** 类似SessionId，用于记录对方是谁，通过该值来判断是否已经进行秘钥交换、获取共享秘钥，双方都会保存该标识。
-* AES支持算法
-** 加密用的规则，请求方所支持的AES加密种类，如果支持多个，用分号分割。这些值取决于代码实现的种类。
-* AES算法选型
-** 响应方从请求方的AES-supports挑选一个随机的加密方法，作为本次会话中使用的AES加密算法。
-* B2S(bytes[])
-** 代表将bytes[] 转化为字符串，一般采用base64编码。
+安全会话标识:: 类似SessionId，用于记录对方是谁，通过该值来判断是否已经进行秘钥交换、获取共享秘钥，双方都会保存该标识。
+AES支持算法:: 加密用的规则，请求方所支持的AES加密种类，如果支持多个，用分号分割。这些值取决于代码实现的种类。
+AES算法选型:: 响应方从请求方的AES-supports挑选一个随机的加密方法，作为本次会话中使用的AES加密算法。
+B2S(bytes[]):: 伪代码简写，代表将 `bytes[]` 转化为 `字符串`，一般采用 `base64编码`。
 
 == 🔄 交互流程
 

src/main/asciidoc/specs/security/security.adoc

@@ -7,21 +7,17 @@ canonical={canonical}
 
 == RPS_KEY_DEF
 
-* 用户数据 User Data
-** 指用户拥有的数据，包括但不限于原始数据（用户输入的数据）、处理原始数据产生的数据（用户上线习惯、用户画像等）、系统运行产生的数据（音视频、图片、日志、事件等）。
+[horizontal]
+用户数据(User Data):: 指用户拥有的数据，包括但不限于原始数据（用户输入的数据）、处理原始数据产生的数据（用户上线习惯、用户画像等）、系统运行产生的数据（音视频、图片、日志、事件等）。
 
-* 隐私数据 Privacy Data
-** 用户的机密/隐私信息以及个人的敏感数据。
-** 如：个人敏感信息包括身份证件号码、个体生物识别信息（指纹、人脸等）、银行账户、通信记录和内容、行踪轨迹、住宿信息、14周岁及以下儿童的个人信息等。
+隐私数据(Privacy Data):: 用户的机密/隐私信息以及个人的敏感数据。
+* 如：个人敏感信息包括身份证件号码、个体生物识别信息（指纹、人脸等）、银行账户、通信记录和内容、行踪轨迹、住宿信息、14周岁及以下儿童的个人信息等。
 
-* 数据主体 Data Subject
-** 用户数据所标识的自然人或者拥有数据的组织或个人，包括但不限于个人、用户、第三方。
+数据主体(Data Subject):: 用户数据所标识的自然人或者拥有数据的组织或个人，包括但不限于个人、用户、第三方。
 
-* 数据处理 Processing of Data
-** 针对用户数据进行的操作行为：如采取收集、记录、组织、构造、存储、调整、更改、检索、咨询、使用、通过传输而公开、散布或其他方式对他人公开、排列或组合、限制、删除或销毁而公开等自动化方式。
+数据处理(Processing of Data):: 针对用户数据进行的操作行为：如采取收集、记录、组织、构造、存储、调整、更改、检索、咨询、使用、通过传输而公开、散布或其他方式对他人公开、排列或组合、限制、删除或销毁而公开等自动化方式。
 
-* 生物性识别数据 Biometric Recognition Data
-** 基于特别技术处理自然人的相关身体、生理或行为特征而得出的个人数据，这种个人数据能够识别或确定自然人的独特标识，例如脸部形象或指纹数据。
+生物性识别数据(Biometric Recognition Data):: 基于特别技术处理自然人的相关身体、生理或行为特征而得出的个人数据，这种个人数据能够识别或确定自然人的独特标识，例如脸部形象或指纹数据。
 
 == RPS_CONSTRAINT