k3cloud-sdk 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dfedb0c66eddf2de607406e2cf083b98f54350412d9cbb2699d177eb66c347a
-  data.tar.gz: b73a7c6847c615b4d2ec9fcb0dbacce4e69078ba24e204fa2cf850974a28404c
+  metadata.gz: ac60c158c0d8bb63fa78e7412f1a7207ce7317f6bbaa1cbe751556740987770d
+  data.tar.gz: 8ab6ad5bff05101523fc21ac786d4c7611713bc5283f0cce6e6dd2ea61b5c030
 SHA512:
-  metadata.gz: 14bba40c28f9a4909551df05847b713ffce4029928fc5b9a82b020c95d7f1f155fff0a2eccce316b54c261c3bdcc3e085e823702eb3a8bf11787e181c0f52a6e
-  data.tar.gz: 1339bf2093aad7ee854a1d342d50341f0f0bcaf376daf68e620914271d3576fbcbdfc7ee41f08d8925192a150038809298c06614646042a205a68306ed9971b1
+  metadata.gz: '01281a40210d978bdda71290370b0e05a1504ee23f923ab54935e2858e6e66c5ae56ade375f9d674fb077d755fa043091208a4e681045aa9d9acc02befc2170f'
+  data.tar.gz: da96968ea62312e524f5abe5bad731506a23b07221060e6aef64751c653bbbd4ae45e8ae6e44f5240567858fa6a20e4bbca92ef831d50e2b4a37a493ba744260

data/.rubocop.yml

@@ -25,7 +25,7 @@ Style/Documentation:
   Enabled: false
 
 Gemspec/RequireMFA:
-  Enabled: false
+  Enabled: true
 
 Style/FormatStringToken:
   Enabled: false
@@ -52,4 +52,7 @@ Metrics/CyclomaticComplexity:
   Max: 12
 
 Metrics/ParameterLists:
-  Max: 8
+  Max: 10
+
+Metrics/ClassLength:
+  Max: 150

data/CHANGELOG.md

@@ -5,14 +5,33 @@ 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).
 
-## [Unreleased]
+## [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 证书校验；私有云自签证书需显式设置 `Configuration#verify_ssl = false`。
+- 默认启用 HTTPS 证书校验；私有云 https 自签证书需显式设置 `Configuration#verify_ssl = false`。
 - `Configuration` 为 `lcid`、`connect_timeout`(30s)、`request_timeout`(60s)、`verify_ssl` 提供默认值。
 - 工具类与常量迁移至 `K3cloud` 命名空间（`K3cloud::Base64Utils`、`K3cloud::MD5Utils`、`K3cloud::ConstDefine`），不再保留无命名空间别名。
 - `Http` 构造参数改为关键字参数。
@@ -21,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - 构造签名头失败时不再静默返回空 header，改为抛出异常。
 - 签名密钥为空时 `MD5Utils.hash_mac` 改为抛出 `ArgumentError`。
+- `K3cloudError.parse` 对空索引做判空保护，避免 `NoMethodError`。
 
 ### Fixed
 
@@ -98,4 +118,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- 初始版本：封装金蝶云星空 OpenApi，涵盖暂存/保存/提交/审核/查看/查询/删除/下推/分配等单据操作及附件、工作流、报表等共 26 个业务方法。
+- 初始版本：封装金蝶云星空 OpenApi，涵盖暂存/保存/提交/审核/查看/查询/删除/下推/分配等单据操作及附件、工作流、报表等共 26 个业务方法。

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    k3cloud-sdk (0.5.0)
+    k3cloud-sdk (0.6.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,10 +1,33 @@
-# K3cloud-sdk
+# K3cloud SDK
 
-Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology to avoid plaintext transmission of keys and enables automatic login.
+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
 
@@ -12,85 +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:
+### Single Account
 
-You'll need to configure it in `config/initializers/k3cloud.rb`:
+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:
+### Multi Account
 
-You'll need to configure it in `config/initializers/k3cloud.rb`:
+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)
 
-  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']
+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:
+
+```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
+)
 
-  client1 = K3cloud.new_api(config1)
-  client2 = 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: ""
-  }
-  client1.execute_bill_query(data)
-  client2.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

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   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.

data/lib/k3cloud/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "k3cloud/errors/configuration_error"
+
 module K3cloud
   class Configuration
     # 服务Url地址(私有云必须配置金蝶云星空产品地址，K3Cloud/结尾。若为公有云则必须置空)
@@ -29,16 +31,26 @@ module K3cloud
     # 组织编码，启用多组织时配置对应的组织编码才有效
     attr_accessor :org_num
 
-    # 连接/请求超时（秒）。私有云自签证书时可设 verify_ssl=false 跳过校验
+    # 连接/请求超时（秒）。
+    # verify_ssl 仅对 https 生效（http URL 自动跳过 SSL 校验）；
+    # 私有云 https 自签证书时可设为 false 关闭校验，默认 true。
     attr_accessor :connect_timeout, :request_timeout, :verify_ssl
 
     # 日志输出格式：:text（默认，常规 Logger 格式）或 :json（每行一个 JSON）
     attr_accessor :log_format
 
+    # 请求重试：对超时与 5xx 进行重试。retry_max=0 表示不重试
+    attr_accessor :retry_max, :retry_interval, :retry_backoff
+
     DEFAULT_LCID = 2052
     DEFAULT_CONNECT_TIMEOUT = 30
     DEFAULT_REQUEST_TIMEOUT = 60
     DEFAULT_LOG_FORMAT = :text
+    DEFAULT_RETRY_MAX = 3
+    DEFAULT_RETRY_INTERVAL = 1
+    DEFAULT_RETRY_BACKOFF = 2
+
+    REQUIRED_FIELDS = %i[acct_id user_name app_id app_secret].freeze
 
     def initialize(options = {})
       @acct_id          = options[:acct_id]
@@ -53,10 +65,22 @@ module K3cloud
       @request_timeout  = options.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT)
       @verify_ssl       = options.fetch(:verify_ssl, true)
       @log_format       = options.fetch(:log_format, DEFAULT_LOG_FORMAT)
+      @retry_max        = options.fetch(:retry_max, DEFAULT_RETRY_MAX)
+      @retry_interval   = options.fetch(:retry_interval, DEFAULT_RETRY_INTERVAL)
+      @retry_backoff    = options.fetch(:retry_backoff, DEFAULT_RETRY_BACKOFF)
 
       yield(self) if block_given?
     end
 
+    # 校验必填字段。nil 视为未配置，空串视为兼容历史不阻断。
+    def validate!
+      missing = REQUIRED_FIELDS.select { |f| public_send(f).nil? }
+      return if missing.empty?
+
+      raise K3cloud::ConfigurationError,
+            "K3cloud configuration missing: #{missing.join(", ")}. Please set them in K3cloud.configure."
+    end
+
     class << self
       def default
         @default ||= Configuration.new

data/lib/k3cloud/errors/configuration_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module K3cloud
+  # 配置缺失或非法时抛出
+  class ConfigurationError < StandardError; end
+end

data/lib/k3cloud/errors/k3cloud_error.rb

@@ -29,7 +29,7 @@ module K3cloud
       kd_error.inner_exception = inner_exception ? K3cloudError.parse(inner_exception.to_json) : nil
       kd_error
     rescue StandardError => e
-      K3cloud.logger.error({ msg: "Failed to parse exception message. #{e.message}", type: "error", level: "ERROR" })
+      K3cloud.logger.error("Failed to parse exception message: #{e.message}")
       nil
     end
   end

data/lib/k3cloud/http.rb

@@ -10,47 +10,87 @@ module K3cloud
   # HTTP Client
   class Http
     attr_accessor :url, :header, :body, :connect_timeout, :request_timeout, :verify_ssl, :status_code
+    attr_reader :retry_count
 
-    def initialize(url:, header:, body:, connect_timeout: Configuration::DEFAULT_CONNECT_TIMEOUT,
-                   request_timeout: Configuration::DEFAULT_REQUEST_TIMEOUT, verify_ssl: true)
+    # retry_max/interval/backoff: 失败重试参数，仅对超时与 5xx 生效。
+    def initialize(
+      url:, header:, body:,
+      connect_timeout: Configuration::DEFAULT_CONNECT_TIMEOUT,
+      request_timeout: Configuration::DEFAULT_REQUEST_TIMEOUT, verify_ssl: true,
+      retry_max: 0, retry_interval: 1, retry_backoff: 2
+    )
       @url = url
       @header = header || {}
       @body = body
       @connect_timeout = connect_timeout
       @request_timeout = request_timeout
       @verify_ssl = verify_ssl
+      @retry_max = retry_max.to_i
+      @retry_interval = retry_interval.to_f
+      @retry_backoff = retry_backoff.to_f
+      @retry_count = 0
     end
 
     def post
       uri = URI.parse(@url)
       http = build_http(uri)
+      request = build_request(uri)
+      body_str = perform_with_retry(http, request)
+      log_trace(body_str)
+      body_str
+    end
 
-      request = Net::HTTP::Post.new(uri.request_uri)
-      request.initialize_http_header(@header)
-      request["Content-Type"] = "application/json"
-      request["User-Agent"] = generate_user_agent
-      request.body = @body.is_a?(String) ? @body : @body.to_json
+    private
+
+    def perform_with_retry(http, request)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        send_request(http, request)
+      rescue RetryableError => e
+        if @retry_count < @retry_max
+          @retry_count += 1
+          wait = @retry_interval * (@retry_backoff**(@retry_count - 1))
+          K3cloud.logger.debug("Request failed, retrying #{@retry_count}/#{@retry_max} " \
+                               "after #{wait}s: #{e.message} url=#{@url}")
+          sleep(wait)
+          retry
+        end
+        raise K3cloud::ResponseError, "Request failed after #{@retry_count} retries: #{e.message}"
+      ensure
+        @last_elapsed_ms = elapsed_ms_since(started_at)
+      end
+    end
 
+    def send_request(http, request)
       response = http.request(request)
       @status_code = response.code.to_i
+      raise RetryableError, "server error status=#{@status_code}" if @status_code >= 500
+
       raise K3cloud::ResponseError, "status: #{response.code}, desc: #{response.body}" if @status_code >= 400
 
       response.body
-    rescue Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
-      raise K3cloud::ResponseError, "Request timed out: #{e.message}"
-    rescue K3cloud::ResponseError
+    rescue RetryableError, K3cloud::ResponseError
       raise
+    rescue Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
+      raise RetryableError, "timeout: #{e.message}"
     rescue Net::HTTPServerError => e
-      raise K3cloud::ResponseError, "Server error: #{e.message}"
+      raise RetryableError, "server error: #{e.message}"
     rescue StandardError => e
       raise K3cloud::ResponseError, "Unexpected error: #{e.message}"
     end
 
-    private
+    def build_request(uri)
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request.initialize_http_header(@header)
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = generate_user_agent
+      request.body = @body.is_a?(String) ? @body : @body.to_json
+      request
+    end
 
     def build_http(uri)
-      http = connection(uri) || Net::HTTP.new(uri.host, uri.port)
-      configure_ssl!(http, uri) if uri.scheme == "https"
+      http = Net::HTTP.new(uri.host, uri.port)
+      configure_ssl!(http) if uri.scheme == "https"
       http.open_timeout = @connect_timeout
       http.read_timeout = @request_timeout
       http.write_timeout = @request_timeout if http.respond_to?(:write_timeout=)
@@ -58,19 +98,27 @@ module K3cloud
       http
     end
 
-    def configure_ssl!(http, _uri)
+    # 仅 https 生效。http URL 不调用此方法，verify_ssl 配置对其无意义。
+    def configure_ssl!(http)
       http.use_ssl = true
       http.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
     end
 
-    # 子类可覆盖以注入复用的连接（如 Net::HTTP::Persistent）。
-    def connection(_uri)
-      nil
+    def log_trace(body_str)
+      size = body_str ? body_str.bytesize : 0
+      K3cloud.logger.debug("HTTP completed POST #{@url} status=#{@status_code} \
+elapsed_ms=#{(@last_elapsed_ms || 0).round(2)} retries=#{@retry_count} resp_bytes=#{size}")
+    end
+
+    def elapsed_ms_since(started_at)
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0
     end
 
-    # Generate User-Agent string with client info
     def generate_user_agent
       "Kingdee/Ruby WebApi SDK(v#{K3cloud::VERSION}) (Ruby #{RUBY_VERSION}; #{RUBY_PLATFORM})"
     end
+
+    # 内部异常：可重试的瞬时错误（超时/5xx），区别于最终抛出的 ResponseError。
+    class RetryableError < StandardError; end
   end
 end

data/lib/k3cloud/k3cloud_api.rb

@@ -46,6 +46,24 @@ module K3cloud
       handle_query_result(rows)
     end
 
+    # 分页拉取全部单据。data 为基础查询参数（FormId/FieldKeys/FilterString 等），
+    # 自动注入 StartRow与 Limit，按分页连续请求直到返回行数少于 limit。
+    # 返回合并后的二维数组。limit 建议不超过 1000。
+    def execute_bill_query_all(data, limit: 1000)
+      base = data.dup
+      all = []
+      start_row = 0
+      loop do
+        page = base.merge("StartRow" => start_row, "Limit" => limit)
+        rows = execute_bill_query(page)
+        all.concat(rows)
+        break if rows.nil? || rows.size < limit
+
+        start_row += limit
+      end
+      all
+    end
+
     # 删除
     def delete(form_id, data)
       execute("Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Delete", [form_id, data])
@@ -135,19 +153,34 @@ module K3cloud
 
     private
 
-    # 金蝶 ExecuteBillQuery 在出错时会把错误信息放在首行首列（一个 Hash），
-    # 正常查询则返回二维数组。这里识别并记录错误，避免把错误对象当业务数据返回。
-    def handle_query_result(rows)
-      return rows if rows.nil? || rows.empty?
-
-      first_row = rows[0]
-      result = first_row.nil? || first_row.empty? ? nil : first_row[0]
-      if result.is_a?(Hash)
-        K3cloud.logger.error({ msg: result, type: "error", level: "ERROR" })
-        []
-      else
-        rows
+    # 金蝶 ExecuteBillQuery 正常返回二维数组；出错时返回值结构不一：
+    # 可能是首行首列放置一个含 Message/InnerEx 的 Hash，也可能是顶层 Hash。
+    # 这里在多种形态下识别错误，避免把错误对象当作业务数据返回。
+    def handle_query_result(result)
+      return result if result.nil? || (result.respond_to?(:empty?) && result.empty?)
+
+      if error_result?(result)
+        K3cloud.logger.error("ExecuteBillQuery error: #{result.inspect}")
+        return []
       end
+      result
+    end
+
+    def error_result?(result)
+      return true if error_hash?(result)
+
+      first_row = result.is_a?(Array) ? result[0] : nil
+      return false unless first_row.is_a?(Array)
+
+      candidate = first_row.find { |cell| cell.is_a?(Hash) }
+      candidate && error_hash?(candidate)
+    end
+
+    def error_hash?(obj)
+      return false unless obj.is_a?(Hash)
+
+      # 错误对象通常含 Message / InnerExWrapper / InnerException 等字段
+      ERROR_MARKERS.any? { |k| obj.key?(k) }
     end
   end
 end

data/lib/k3cloud/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K3cloud
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/k3cloud/web_api_client.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require "cgi"
 require "k3cloud/errors/k3cloud_error"
+require "k3cloud/errors/configuration_error"
 require "k3cloud/errors/response_error"
 require "k3cloud/utils/md5_utils"
 require "k3cloud/utils/base64_utils"
@@ -10,13 +12,22 @@ require "k3cloud/http"
 
 module K3cloud
   class WebApiClient
+    # 金蝶 ExecuteBillQuery/ResponseError 中标识错误的关键字
+    ERROR_MARKERS = %w[Message InnerExWrapper InnerException].freeze
+
+    # 金蝶 app_id 内嵌 secret 的 XOR 密钥，协议固定值，来源见 README。
+    # https://vip.kingdee.com/article/163905337846351872?productLineId=1
+    XOR_SEC_KEY = "0054f397c6234378b09ca7d3e5debce7"
+
     attr_accessor :config
 
     def initialize(config = Configuration.default)
       @config = config
+      @validated = false
     end
 
     def execute(service_name, parameters)
+      ensure_configured!
       result = execute_json(service_name, parameters)
       if result.start_with?("response_error:")
         error = K3cloudError.parse(result)
@@ -37,6 +48,13 @@ module K3cloud
 
     private
 
+    def ensure_configured!
+      return if @validated
+
+      @config.validate!
+      @validated = true
+    end
+
     def execute_json(service_name, parameters)
       url = build_url(service_name)
       K3cloud.logger.info("Request URL: #{url}")
@@ -49,7 +67,10 @@ module K3cloud
         body: body,
         connect_timeout: @config.connect_timeout,
         request_timeout: @config.request_timeout,
-        verify_ssl: @config.verify_ssl
+        verify_ssl: @config.verify_ssl,
+        retry_max: @config.retry_max,
+        retry_interval: @config.retry_interval,
+        retry_backoff: @config.retry_backoff
       )
       request.post
     end
@@ -67,11 +88,12 @@ module K3cloud
       end
     end
 
+    # 仅 https/http 的 URL 才能切片出签名用 path，否则说明 URL 构造异常。
     def url_path(url)
-      return url unless url.start_with?("http")
+      raise ArgumentError, "Unsupported URL scheme: #{url.inspect}" unless url.start_with?("http")
 
       index = url.index("/", 10)
-      index ? url[index..-1] : url
+      index ? url[index..-1] : "/"
     end
 
     # @note: https://vip.kingdee.com/knowledge/specialDetail/229961573895771136?category=229964512944566016&id=423060878259269120&productLineId=1
@@ -113,8 +135,7 @@ module K3cloud
     end
 
     def x_or_sec(buffer)
-      sec_key = "0054f397c6234378b09ca7d3e5debce7"
-      pwd = sec_key.encode("UTF-8").bytes
+      pwd = XOR_SEC_KEY.encode("UTF-8").bytes
 
       buffer.each_with_index do |byte, i|
         buffer[i] = byte ^ pwd[i % pwd.length]

data/lib/k3cloud.rb

@@ -46,9 +46,16 @@ module K3cloud
     end
 
     API_METHODS = %i[
-      draft save batch_save submit audit un_audit view execute_bill_query delete cancel_assign push execute_operation
-      allocate cancel_allocate group_save query_group_info group_delete attachment_upload attachment_download
-      query_business_info get_sys_report_data flex_save send_msg disassembly workflow_audit switch_org
+      execute_bill_query execute_bill_query_all view
+      draft save batch_save submit delete
+      audit un_audit
+      cancel_assign push execute_operation
+      allocate cancel_allocate
+      group_save query_group_info group_delete
+      attachment_upload attachment_download
+      query_business_info get_sys_report_data
+      flex_save send_msg disassembly workflow_audit
+      switch_org
     ].freeze
 
     def_delegators :default_api, *API_METHODS
@@ -71,16 +78,18 @@ module K3cloud
     end
 
     def format_log_json(severity, datetime, msg)
-      payload = msg.is_a?(Hash) ? msg.dup : { msg: msg.to_s }
-      payload[:level] = severity
-      payload[:time] = datetime.strftime("%Y-%m-%dT%H:%M:%S.%L")
-      "#{payload.to_json}\n"
+      "#{{ msg: msg.to_s, level: severity, time: datetime.strftime("%Y-%m-%dT%H:%M:%S.%L") }.to_json}\n"
     end
 
     def format_log_text(severity, datetime, msg)
-      body = msg.is_a?(Hash) ? msg.inspect : msg.to_s
-      format("%s, [%s#%d] %5s -- %s\n", severity[0..0],
-             datetime.strftime("%Y-%m-%dT%H:%M:%S.%L"), Process.pid, severity, body)
+      format(
+        "%s, [%s#%d] %5s -- %s\n",
+        severity[0..0],
+        datetime.strftime("%Y-%m-%dT%H:%M:%S.%L"),
+        Process.pid,
+        severity,
+        msg.to_s
+      )
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: k3cloud-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - zevinto
@@ -34,6 +34,7 @@ files:
 - lib/k3cloud-sdk.rb
 - lib/k3cloud.rb
 - lib/k3cloud/configuration.rb
+- lib/k3cloud/errors/configuration_error.rb
 - lib/k3cloud/errors/k3cloud_error.rb
 - lib/k3cloud/errors/response_error.rb
 - lib/k3cloud/http.rb
@@ -51,6 +52,7 @@ metadata:
   source_code_uri: https://github.com/zevinto/k3cloud-sdk
   changelog_uri: https://github.com/zevinto/k3cloud-sdk/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/zevinto/k3cloud-sdk/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib