k3cloud-sdk 0.4.7 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4e97bc6484eec7584bfcc9de98131e7151ed09a76dfc2b3ea8eb4baa9a4e096
-  data.tar.gz: 57e7395a941904011c00aba90008850ff5fbb369e9a108e7cee9d2cfb673f48b
+  metadata.gz: ac60c158c0d8bb63fa78e7412f1a7207ce7317f6bbaa1cbe751556740987770d
+  data.tar.gz: 8ab6ad5bff05101523fc21ac786d4c7611713bc5283f0cce6e6dd2ea61b5c030
 SHA512:
-  metadata.gz: b3d2691366e94a654ba597e65c87dcfa441392ca01bd68130384b682d3a265d2d6ed3608e5585d0c46633b13ddfb7d774bcc50f93d538b0b55dd96b75d87e7bf
-  data.tar.gz: adb88e87428a8dab018f2aa98bd3da3f1cd294f0d78b448c26f9cc4b4b7ad0441ab2e8e0fa6d4a44c2ac72eaad78df119de076b1fc0930db6c48ae2bce11fb6c
+  metadata.gz: '01281a40210d978bdda71290370b0e05a1504ee23f923ab54935e2858e6e66c5ae56ade375f9d674fb077d755fa043091208a4e681045aa9d9acc02befc2170f'
+  data.tar.gz: da96968ea62312e524f5abe5bad731506a23b07221060e6aef64751c653bbbd4ae45e8ae6e44f5240567858fa6a20e4bbca92ef831d50e2b4a37a493ba744260

data/.rubocop.yml

@@ -1,5 +1,13 @@
 AllCops:
-  TargetRubyVersion: 2.0
+  TargetRubyVersion: 2.5
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "**/*.md"
+    - "ChangeLog*"
+    - "CHANGELOG*"
+    - "vendor/**/*"
+    - "pkg/**/*"
 
 Style/StringLiterals:
   Enabled: true
@@ -11,3 +19,40 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+# 本仓库既有签名/加密逻辑偏过程式，文档与度量类 cops 放宽以避免大改业务逻辑。
+Style/Documentation:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: true
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/FormatString:
+  EnforcedStyle: format
+
+Naming/FileName:
+  Exclude:
+    - "lib/k3cloud-sdk.rb"
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "k3cloud.gemspec"
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/ParameterLists:
+  Max: 10
+
+Metrics/ClassLength:
+  Max: 150

data/CHANGELOG.md

@@ -1,5 +1,121 @@
-## [Unreleased]
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0]
+
+### Added
+
+- 请求重试：`Configuration#retry_max` / `retry_interval` / `retry_backoff`，仅对超时与 5xx 生效，默认重试 3 次指数退避。
+- trace 日志：DEBUG 级记录每次请求的耗时（`elapsed_ms`）、状态码、重试次数、响应字节数。
+- 单据查询分页封装 `execute_bill_query_all(data, limit:)`，自动按 `StartRow`/`Limit` 拉取全部单据。
+- 配置校验：必填字段缺失时抛出 `K3cloud::ConfigurationError`，给出友好提示。
+- 新增 `SECURITY.md` 漏洞上报流程与安全说明。
+
+### Changed
+
+- 默认启用请求重试（`retry_max` 默认 3，原 0.5.0 不重试）；如需保持不重试请设 `retry_max = 0`。
+- `verify_ssl` 文档明确仅 https 生效（http URL 自动跳过）。
+- 日志调用统一为字符串：text 模式输出干净字符串，json 模式包装为 `{msg, level, time}`。
+- `handle_query_result` 错误识别更鲁棒：兼容顶层 Hash 与行内任意列含 `Message`/`InnerExWrapper`/`InnerException` 的错误对象。
+- `WebApiClient#url_path` 对非 http(s) URL 抛 `ArgumentError`，避免签名错误。
+- gemspec 启用 `metadata["rubygems_mfa_required"] = "true"`，提升发布安全。
+- 异常与日志消息英文化。
+- README 重写为英文，按目录组织并标注全部可调用方法。
+
+## [0.5.0] - 2026-07-17
+
+### ⚠ Breaking Changes
+
+- 最低 Ruby 版本提升至 `>= 2.5.0`。
+- 默认启用 HTTPS 证书校验；私有云 https 自签证书需显式设置 `Configuration#verify_ssl = false`。
+- `Configuration` 为 `lcid`、`connect_timeout`(30s)、`request_timeout`(60s)、`verify_ssl` 提供默认值。
+- 工具类与常量迁移至 `K3cloud` 命名空间（`K3cloud::Base64Utils`、`K3cloud::MD5Utils`、`K3cloud::ConstDefine`），不再保留无命名空间别名。
+- `Http` 构造参数改为关键字参数。
+
+### Security
+
+- 构造签名头失败时不再静默返回空 header，改为抛出异常。
+- 签名密钥为空时 `MD5Utils.hash_mac` 改为抛出 `ArgumentError`。
+- `K3cloudError.parse` 对空索引做判空保护，避免 `NoMethodError`。
+
+### Fixed
+
+- 修复 `MD5Utils.encrypt` 在 Ruby 下始终返回空字符串的 bug。
+- 修复公有云请求 URL 出现双斜杠的问题。
+
+### Added
+
+- 日志输出支持可配置格式：`Configuration#log_format` 取 `:text`（默认，常规 Logger 格式）或 `:json`（每行一个 JSON，便于采集与检索）。
+- 支持注入自定义 logger（`K3cloud.logger = Rails.logger`）与重建默认 logger（`K3cloud.reset_logger!`）。
+
+## [0.4.7] - 2025-02-18
+
+### Fixed
+
+- 修复 `execute_bill_query` 查询成功时误返回空数组、丢失业务数据的问题。
+
+## [0.4.6] - 2025-02-18
+
+### Fixed
+
+- 修复 `execute_bill_query` 在空结果时误判为错误的问题。
+
+## [0.4.5] - 2025-02-18
+
+### Changed
+
+- 自定义错误类型统一改为抛出 `K3cloud::ResponseError`。
+- `execute_bill_query` 增加对错误返回结构的识别：当首行首列为 Hash 时记录日志并返回空数组。
+- User-Agent 携带 SDK 版本与运行环境信息。
+
+## [0.4.4] - 2024-07-19
+
+### Added
+
+- HTTP 请求超时自动重试（最多 5 次，间隔 5 秒）。
+
+## [0.4.3] - 2023-11-29
+
+### Added
+
+- 新增统一异常类 `K3cloud::ResponseError`、`K3cloud::K3cloudError`。
+
+## [0.4.2] - 2023-11-29
+
+### Fixed
+
+- 修复非 200/206 响应被误判为失败的问题（`response.code` 为字符串比较恒为假）。
+
+## [0.4.1] - 2023-11-28
+
+### Changed
+
+- HTTP 请求失败时改为抛出异常，不再静默返回 `nil`。
+
+## [0.4.0] - 2023-11-17
+
+### Changed
+
+- 兼容更低版本 Ruby 语法。
+
+## [0.3.0] - 2023-11-14
+
+### Added
+
+- 多账号配置支持：通过 `K3cloud.new_api(config)` 创建多账号客户端实例。
+
+## [0.2.0] - 2023-10-09
+
+### Fixed
+
+- 修复入口文件大小写问题导致部分平台上 `require "k3cloud-sdk"` 失败。
 
 ## [0.1.0] - 2023-09-26
 
-- Initial release
+### Added
+
+- 初始版本：封装金蝶云星空 OpenApi，涵盖暂存/保存/提交/审核/查看/查询/删除/下推/分配等单据操作及附件、工作流、报表等共 26 个业务方法。

data/Gemfile

@@ -6,5 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
-
 gem "rspec", "~> 3.0"
+gem "rubocop", require: false
+gem "webmock", "~> 3.0", group: :test
+# Ruby 3.x: base64 became a bundled gem, declare explicitly so vendored bundle resolves it.
+gem "base64", require: false
+gem "json", require: false

data/Gemfile.lock

@@ -1,13 +1,35 @@
 PATH
   remote: .
   specs:
-    k3cloud-sdk (0.4.7)
+    k3cloud-sdk (0.6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
     diff-lcs (1.5.0)
+    hashdiff (1.2.1)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
     rake (13.0.6)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -21,15 +43,42 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.1)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-25
 
 DEPENDENCIES
+  base64
+  json
   k3cloud-sdk!
   rake (~> 13.0)
   rspec (~> 3.0)
+  rubocop
+  webmock (~> 3.0)
 
 BUNDLED WITH
    2.4.14

data/README.md

@@ -1,9 +1,33 @@
-# K3cloud-sdk
-Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology to avoid plaintext transmission of keys and enables automatic login.
+# K3cloud SDK
+
+Ruby Gem for Kingdee K3Cloud OpenApi. Uses cryptographic signature technology
+to avoid plaintext transmission of keys and supports automatic login.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Single Account](#single-account)
+  - [Multi Account](#multi-account)
+  - [Optional Settings](#optional-settings)
+- [Error Handling](#error-handling)
+  - [In Scheduled Jobs](#in-scheduled-jobs-sidekiq--cron--rake)
+- [Available API Methods](#available-api-methods)
+  - [Bill Operations](#bill-operations)
+  - [Query Operations](#query-operations)
+  - [Group Operations](#group-operations)
+  - [Attachment Operations](#attachment-operations)
+  - [Metadata & Report Operations](#metadata--report-operations)
+  - [Workflow & Organization Operations](#workflow--organization-operations)
+- [Logger](#logger)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
 
 ## Installation
 
-Install the gem and add to the Rails application's Gemfile by executing:
+Install the gem and add it to a Rails application's Gemfile:
 
     $ bundle add k3cloud-sdk
 
@@ -11,81 +35,251 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install k3cloud-sdk
 
-## Usage
+## Configuration
 
-#### 1. Single Account Configuration:
-You'll need to configure it in `config/initializers/k3cloud.rb`:
+### Single Account
+
+Configure it in `config/initializers/k3cloud.rb`:
 
 ```ruby
-  K3cloud.configure do |config|
-    config.acct_id = ENV['K3CLOUD_ACCT_ID']
-    config.user_name = ENV['K3CLOUD_USERNAME']
-    config.app_id = ENV['K3CLOUD_APP_ID']
-    config.app_secret = ENV['K3CLOUD_APP_SECRET']
-    config.server_url = ENV['K3CLOUD_SERVER_URL']
-  end
+K3cloud.configure do |config|
+  config.acct_id    = ENV["K3CLOUD_ACCT_ID"]
+  config.user_name  = ENV["K3CLOUD_USERNAME"]
+  config.app_id     = ENV["K3CLOUD_APP_ID"]
+  config.app_secret = ENV["K3CLOUD_APP_SECRET"]
+  config.server_url = ENV["K3CLOUD_SERVER_URL"] # blank for public cloud
+end
 ```
 
-Then you can call the k3cloud API using the following code:
+Then call the K3Cloud API directly:
+
 ```ruby
-  data = {
-    FormId: "",
-    FieldKeys: "",
-    FilterString: ""
-  }
-  K3cloud.execute_bill_query(data)
+data = {
+  FormId: "PRD_MO",
+  FieldKeys: "FMaterialId.FNumber, FNoStockInQty",
+  FilterString: "FStatus not in (6, 7)"
+}
+K3cloud.execute_bill_query(data)
 ```
 
-#### 2. Multi Account Configuration:
-You'll need to configure it in `config/initializers/k3cloud.rb`:
+### Multi Account
+
+Create multiple `K3cloud::Configuration` instances and build clients for each:
 
 ```ruby
-  config1 = K3cloud::Configuration.new do |c|
-    c.acct_id = ENV['K3CLOUD1_ACCT_ID']
-    c.user_name = ENV['K3CLOUD1_USERNAME']
-    c.app_id = ENV['K3CLOUD1_APP_ID']
-    c.app_secret= ENV['K3CLOUD1_APP_SECRET']
-    c.server_url = ENV['K3CLOUD1_SERVER_URL']
-  end
+config1 = K3cloud::Configuration.new do |c|
+  c.acct_id    = ENV["K3CLOUD1_ACCT_ID"]
+  c.user_name  = ENV["K3CLOUD1_USERNAME"]
+  c.app_id     = ENV["K3CLOUD1_APP_ID"]
+  c.app_secret = ENV["K3CLOUD1_APP_SECRET"]
+  c.server_url = ENV["K3CLOUD1_SERVER_URL"]
+end
+
+config2 = K3cloud::Configuration.new do |c|
+  c.acct_id    = ENV["K3CLOUD2_ACCT_ID"]
+  c.user_name  = ENV["K3CLOUD2_USERNAME"]
+  c.app_id     = ENV["K3CLOUD2_APP_ID"]
+  c.app_secret = ENV["K3CLOUD2_APP_SECRET"]
+  c.server_url = ENV["K3CLOUD2_SERVER_URL"]
+end
+
+client1 = K3cloud.new_api(config1)
+client2 = K3cloud.new_api(config2)
+
+client1.execute_bill_query(data)
+client2.execute_bill_query(data)
+```
+
+### Optional Settings
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `verify_ssl` | `true` | HTTPS certificate verification. Only affects `https` URLs (http URLs skip SSL automatically). Set `false` for private cloud self-signed certificates. |
+| `connect_timeout` | `30` | Connection timeout in seconds. |
+| `request_timeout` | `60` | Request read timeout in seconds. |
+| `retry_max` | `3` | Max retries on timeout / 5xx. `0` disables retry. |
+| `retry_interval` | `1` | First retry interval in seconds, then exponential backoff. |
+| `retry_backoff` | `2` | Backoff multiplier between retries. |
+| `log_format` | `:text` | Logger output format: `:text` or `:json`. |
+
+```ruby
+K3cloud.configure do |config|
+  # ... required fields above ...
+  config.verify_ssl       = true
+  config.connect_timeout  = 30
+  config.request_timeout  = 60
+  config.retry_max        = 3
+  config.retry_interval   = 1
+  config.log_format       = :json
+end
+```
+
+## Error Handling
+
+All request failures raise `K3cloud::ResponseError`. A missing or invalid
+configuration raises `K3cloud::ConfigurationError` on the first request. Wrap
+calls accordingly:
+
+```ruby
+begin
+  K3cloud.save("PRD_MO", data)
+rescue K3cloud::ConfigurationError => e
+  # missing config: app_id / app_secret / acct_id / user_name
+  logger.error("Config error: #{e.message}")
+rescue K3cloud::ResponseError => e
+  # network or Kingdee business error
+  logger.error("Request failed: #{e.message}")
+end
+```
+
+### In Scheduled Jobs (Sidekiq / cron / rake)
+
+The SDK raises `K3cloud::ResponseError` after retries are exhausted. Always
+`rescue` explicitly in scheduled jobs to prevent the exception from bubbling up
+and failing the container/process:
 
-  config2 = K3cloud::Configuration.new do |c|
-    c.acct_id = ENV['K3CLOUD2_ACCT_ID']
-    c.user_name = ENV['K3CLOUD2_USERNAME']
-    c.app_id = ENV['K3CLOUD2_APP_ID']
-    c.app_secret= ENV['K3CLOUD2_APP_SECRET']
-    c.server_url = ENV['K3CLOUD2_SERVER_URL']
+```ruby
+class SyncK3cloudJob
+  def perform
+    rows = K3cloud.execute_bill_query_all({ FormId: "PRD_MO" }, limit: 1000)
+    # ... process rows ...
+  rescue K3cloud::ConfigurationError => e
+    logger.error("[k3cloud] config error: #{e.message}")
+  rescue K3cloud::ResponseError => e
+    logger.error("[k3cloud] request failed: #{e.message}")
+    # Re-raise so the scheduler (e.g. Sidekiq) can retry the job
+    raise e
   end
+end
+```
+
+> Tip: In scheduled jobs, set a small `retry_max` (e.g. 0 or 1) and let the
+> job scheduler decide the next attempt, instead of sleeping inside the SDK
+> and occupying the worker thread. For example:
+> `K3cloud.configure { |c| c.retry_max = 1 }`.
+
+## Available API Methods
+
+All methods are available on both:
+- `K3cloud.<method>` — uses the default account (delegates to `K3cloud.default_api`).
+- `K3cloud.new_api(config).<method>` — uses a specific account configuration.
+
+### Bill Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `draft` | `draft(form_id, data)` | Temporarily save a bill (暂存). |
+| `save` | `save(form_id, data)` | Save a bill (保存). |
+| `batch_save` | `batch_save(form_id, data)` | Batch save bills (批量保存). |
+| `submit` | `submit(form_id, data)` | Submit a bill (提交). |
+| `audit` | `audit(form_id, data)` | Audit a bill (审核). |
+| `un_audit` | `un_audit(form_id, data)` | Un-audit a bill (反审核). |
+| `view` | `view(form_id, data)` | View a bill detail (查看). |
+| `delete` | `delete(form_id, data)` | Delete a bill (删除). |
+| `cancel_assign` | `cancel_assign(form_id, data)` | Cancel assignment (撤销). |
+| `push` | `push(form_id, data)` | Push down a bill (下推). |
+| `execute_operation` | `execute_operation(form_id, op_number, data)` | Status transition: close/reopen/void/unvoid etc. (状态转换). |
+| `allocate` | `allocate(form_id, data)` | Allocate a bill (分配). |
+| `cancel_allocate` | `cancel_allocate(form_id, data)` | Cancel allocation (取消分配). |
+| `disassembly` | `disassembly(form_id, data)` | Disassembly operation (拆单). |
+| `flex_save` | `flex_save(form_id, data)` | Flex save (弹性域保存). |
+| `send_msg` | `send_msg(form_id, data)` | Send message (发送消息). |
+
+### Query Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `execute_bill_query` | `execute_bill_query(data)` | Query bills with parameters `{ FormId:, FieldKeys:, FilterString: }` (单据查询). Returns a 2D array; returns `[]` on error. |
+| `execute_bill_query_all` | `execute_bill_query_all(data, limit: 1000)` | Paginated query that fetches **all** bill rows by auto-injecting `StartRow` and `Limit` until a page returns fewer than `limit` rows (分页批量查询). Returns the merged 2D array. |
+
+Example:
+
+```ruby
+# Single-page query (you handle pagination manually)
+rows = K3cloud.execute_bill_query(
+  FormId: "PRD_MO",
+  FieldKeys: "FMaterialId.FNumber, FNoStockInQty",
+  FilterString: "FStatus not in (6, 7)",
+  StartRow: 0,
+  Limit: 100
+)
 
-    K3cloud1 = K3cloud.new_api(config1)
-    K3cloud2 = K3cloud.new_api(config2)
+# Paginated query (SDK handles pagination for you)
+all_rows = K3cloud.execute_bill_query_all(
+  { FormId: "PRD_MO", FieldKeys: "FMaterialId.FNumber", FilterString: "" },
+  limit: 1000
+)
 ```
 
-Then you can call the k3cloud API using the following code:
+### Group Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `group_save` | `group_save(form_id, data)` | Save a group (分组保存). |
+| `query_group_info` | `query_group_info(data)` | Query group info (分组信息查询). |
+| `group_delete` | `group_delete(data)` | Delete a group (分组删除). |
+
+### Attachment Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `attachment_upload` | `attachment_upload(data)` | Upload an attachment (附件上传). |
+| `attachment_download` | `attachment_download(data)` | Download an attachment (附件下载). |
+
+### Metadata & Report Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `query_business_info` | `query_business_info(data)` | Query business metadata (元数据查询). |
+| `get_sys_report_data` | `get_sys_report_data(form_id, data)` | Query system report data (查询报表数据). |
+
+### Workflow & Organization Operations
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `workflow_audit` | `workflow_audit(data)` | Workflow audit (工作流审核). |
+| `switch_org` | `switch_org(data)` | Switch organization (切换组织). |
+
+## Logger
+
+By default, logs are written to `$stderr` in plain text. You can switch to
+JSON-per-line format (useful for log aggregation) or inject your own logger.
+
 ```ruby
-  data = {
-    FormId: "",
-    FieldKeys: "",
-    FilterString: ""
-  }
-  K3cloud1.execute_bill_query(data)
-  K3cloud2.execute_bill_query(data)
+# JSON format
+K3cloud.configure { |c| c.log_format = :json }
+K3cloud.reset_logger! # rebuild the default logger after changing log_format
+
+# Inject a custom logger (e.g. Rails.logger)
+K3cloud.logger = Rails.logger
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zevinto/k3cloud-sdk. 
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zevinto/k3cloud-sdk/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/zevinto/k3cloud-sdk. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](https://github.com/zevinto/k3cloud-sdk/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the K3cloud-sdk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zevinto/k3cloud-sdk/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the K3cloud-sdk project's codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/zevinto/k3cloud-sdk/blob/main/CODE_OF_CONDUCT.md).

data/k3cloud.gemspec

@@ -9,11 +9,17 @@ Gem::Specification.new do |spec|
   spec.email = ["zevinto@163.com"]
 
   spec.summary = "Ruby Gem for K3cloud API."
-  spec.description = "Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology to avoid plaintext transmission of keys and enables automatic login."
+  spec.description = "Ruby Gem for K3cloud OpenApi. Uses cryptographic signature technology to avoid " \
+                     "plaintext transmission of keys and enables automatic login."
   spec.homepage = "https://github.com/zevinto/k3cloud-sdk"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.0.0"
+  spec.required_ruby_version = ">= 2.5.0"
   spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  # spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.