k3cloud-sdk 0.4.7 → 0.6.0

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,7 +31,26 @@ module K3cloud
     # 组织编码，启用多组织时配置对应的组织编码才有效
     attr_accessor :org_num
 
-    attr_accessor :connect_timeout, :request_timeout
+    # 连接/请求超时（秒）。
+    # 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]
@@ -39,14 +60,36 @@ module K3cloud
       @app_secret       = options[:app_secret]
       @server_url       = options[:server_url]
       @org_num          = options[:org_num]
-      @connect_timeout  = options[:connect_timeout]
-      @request_timeout  = options[:request_timeout]
+      @lcid             = options.fetch(:lcid, DEFAULT_LCID)
+      @connect_timeout  = options.fetch(:connect_timeout, DEFAULT_CONNECT_TIMEOUT)
+      @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
 
-    def self.default
-      @@default ||= Configuration.new
+    # 校验必填字段。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
+      end
+
+      # 测试或重新配置时重置默认配置
+      def reset_default!
+        @default = nil
+      end
     end
   end
 end

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

@@ -14,17 +14,22 @@ module K3cloud
     end
 
     def self.parse(json)
+      return nil if json.nil? || json.to_s.empty?
+
+      json = json.to_s
       index = json.index("{")
-      json = json[index..-1] if index >= 0
+      json = json[index..-1] if index
 
       parsed_json = JSON.parse(json)
       kd_error = K3cloudError.new
       kd_error.message = parsed_json["Message"]
-      kd_error.inner_ex_wrapper = K3cloudError.parse(parsed_json["InnerExWrapper"].to_json)
-      kd_error.inner_exception = K3cloudError.parse(parsed_json["InnerException"].to_json)
+      inner_wrapper = parsed_json["InnerExWrapper"]
+      inner_exception = parsed_json["InnerException"]
+      kd_error.inner_ex_wrapper = inner_wrapper ? K3cloudError.parse(inner_wrapper.to_json) : nil
+      kd_error.inner_exception = inner_exception ? K3cloudError.parse(inner_exception.to_json) : nil
       kd_error
     rescue StandardError => e
-      K3cloud.logger.error({ errmsg: "Failed to parse exception message. #{e.message}", backtrace: "#{e.backtrace}", type: 'error', lever: 'ERROR' })
+      K3cloud.logger.error("Failed to parse exception message: #{e.message}")
       nil
     end
   end

data/lib/k3cloud/http.rb

@@ -9,51 +9,116 @@ require "json"
 module K3cloud
   # HTTP Client
   class Http
-    attr_accessor :url, :header, :body, :connect_timeout, :request_timeout, :status_code
+    attr_accessor :url, :header, :body, :connect_timeout, :request_timeout, :verify_ssl, :status_code
+    attr_reader :retry_count
 
-    def initialize(url, header, body, connect_timeout = 120, request_timeout = 120)
+    # 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 = Net::HTTP.new(uri.host, uri.port)
-      # SSL/TLS configuration
-      if uri.scheme == "https"
-        http.use_ssl = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      end
+      http = build_http(uri)
+      request = build_request(uri)
+      body_str = perform_with_retry(http, request)
+      log_trace(body_str)
+      body_str
+    end
 
-      http.open_timeout = @connect_timeout
-      http.read_timeout = @request_timeout
-      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 RetryableError, K3cloud::ResponseError
+      raise
     rescue Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
-      raise K3cloud::ResponseError, "Request timed out: #{e.message}"
+      raise RetryableError, "timeout: #{e.message}"
     rescue Net::HTTPServerError => e
-      raise K3cloud::ResponseError, "Server error: #{e.message}"
-    rescue => e
+      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 = 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=)
+      http.ssl_timeout = @request_timeout if http.respond_to?(:ssl_timeout=) && uri.scheme == "https"
+      http
+    end
+
+    # 仅 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
+
+    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,13 +153,34 @@ module K3cloud
 
     private
 
-    def handle_query_result(rows)
-      if !rows[0].nil? && !rows[0].empty? && (result = rows[0][0]).is_a?(Hash)
-        K3cloud.logger.error({ errmsg: result, type: 'error', lever: '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/utils/base64_utils.rb

@@ -2,18 +2,16 @@
 
 require "base64"
 
-module Base64Utils
-  def self.encoding_to_base64(buffer)
-    b64buffer = Base64.strict_encode64(buffer.pack("C*"))
-    b64buffer.force_encoding("UTF-8")
-  rescue StandardError => e
-    raise e
-  end
+module K3cloud
+  module Base64Utils
+    def self.encoding_to_base64(buffer)
+      b64buffer = Base64.strict_encode64(buffer.pack("C*"))
+      b64buffer.force_encoding("UTF-8")
+    end
 
-  def self.decoding_from_base64(base64)
-    buffer = base64.encode("UTF-8")
-    Base64.strict_decode64(buffer).bytes
-  rescue StandardError => e
-    raise e
+    def self.decoding_from_base64(base64)
+      buffer = base64.encode("UTF-8")
+      Base64.strict_decode64(buffer).bytes
+    end
   end
 end

data/lib/k3cloud/utils/const_define.rb

@@ -1,43 +1,45 @@
 # frozen_string_literal: true
 
-module ConstDefine
-  X_API_CLIENT_ID = "X-Api-ClientID"
+module K3cloud
+  module ConstDefine
+    X_API_CLIENT_ID = "X-Api-ClientID"
 
-  X_API_AUTH_VERSION = "X-Api-Auth-Version"
+    X_API_AUTH_VERSION = "X-Api-Auth-Version"
 
-  X_API_TIMESTAMP = "x-api-timestamp"
+    X_API_TIMESTAMP = "x-api-timestamp"
 
-  X_API_NONCE = "x-api-nonce"
+    X_API_NONCE = "x-api-nonce"
 
-  X_API_SIGN_HEADERS = "x-api-signheaders"
+    X_API_SIGN_HEADERS = "x-api-signheaders"
 
-  X_API_SIGNATURE = "X-Api-Signature"
+    X_API_SIGNATURE = "X-Api-Signature"
 
-  X_KD_APP_KEY = "X-Kd-Appkey"
+    X_KD_APP_KEY = "X-Kd-Appkey"
 
-  X_KD_APP_DATA = "X-Kd-Appdata"
+    X_KD_APP_DATA = "X-Kd-Appdata"
 
-  X_KD_SIGNATURE = "X-Kd-Signature"
+    X_KD_SIGNATURE = "X-Kd-Signature"
 
-  KD_SERVICE_SESSIONID = "kdservice-sessionid"
+    KD_SERVICE_SESSIONID = "kdservice-sessionid"
 
-  SESSION_ID = "ASP.NET_SessionId"
+    SESSION_ID = "ASP.NET_SessionId"
 
-  X_KD_SID = "SID"
+    X_KD_SID = "SID"
 
-  COOKIE_SET = "Set-Cookie"
+    COOKIE_SET = "Set-Cookie"
 
-  BEGIN_METHOD_HEADER = "beginmethod"
+    BEGIN_METHOD_HEADER = "beginmethod"
 
-  QUERY_METHOD_HEADER = "querymethod"
+    QUERY_METHOD_HEADER = "querymethod"
 
-  BEGIN_METHOD_METHOD = "BeginQueryImpl"
+    BEGIN_METHOD_METHOD = "BeginQueryImpl"
 
-  QUERY_METHOD_METHOD = "QueryAsyncResult"
+    QUERY_METHOD_METHOD = "QueryAsyncResult"
 
-  QUERY_INVODE_STATE_PENDING = 0
+    QUERY_INVODE_STATE_PENDING = 0
 
-  QUERY_INVODE_STATE_RUNNING = 1
+    QUERY_INVODE_STATE_RUNNING = 1
 
-  QUERY_INVODE_STATE_COMPLETE = 2
+    QUERY_INVODE_STATE_COMPLETE = 2
+  end
 end

data/lib/k3cloud/utils/md5_utils.rb

@@ -3,33 +3,26 @@
 require "digest"
 require "base64"
 
-module MD5Utils
-  def self.encrypt(data_str)
-    m = Digest::MD5.new
-    m.update(data_str.encode("UTF-8"))
-    s = m.digest
-    result = ""
+module K3cloud
+  module MD5Utils
+    UNSECURE_KEY = "0054f397c6234378b09ca7d3e5debce7"
 
-    s.each_byte do |byte|
-      result += (byte & 0xFF | -256).to_s(16)[6..-1]
+    # 返回 32 位小写十六进制 MD5。原来的逐字节位运算 hack 在 Ruby 下会得到 `nil`，
+    # 且被 rescue 吞掉返回空串，故直接使用 Digest::MD5.hexdigest。
+    def self.encrypt(data_str)
+      Digest::MD5.hexdigest(data_str.encode("UTF-8"))
     end
 
-    result
-  rescue StandardError => e
-    e.backtrace
-    ""
-  end
+    def self.hash_mac(data, secret)
+      raise ArgumentError, "secret is required for HMAC" if secret.nil? || secret.to_s.empty?
 
-  def self.hash_mac(data, secret)
-    kd_mac = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), secret, data)
-    hex_string = bytes_to_hex(kd_mac.bytes)
-    Base64.strict_encode64(hex_string)
-  rescue StandardError => e
-    e.backtrace
-    nil
-  end
+      kd_mac = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), secret, data)
+      hex_string = bytes_to_hex(kd_mac.bytes)
+      Base64.strict_encode64(hex_string)
+    end
 
-  def self.bytes_to_hex(bytes)
-    bytes.map { |byte| byte.to_s(16).rjust(2, "0") }.join
+    def self.bytes_to_hex(bytes)
+      bytes.map { |byte| byte.to_s(16).rjust(2, "0") }.join
+    end
   end
 end

data/lib/k3cloud/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K3cloud
-  VERSION = "0.4.7"
+  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,19 +12,29 @@ 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)
         raise K3cloud::ResponseError, result if error.nil?
 
-        message = error.inner_ex_wrapper.nil? ? error.message : "#{error.message} --> #{error.inner_ex_wrapper&.message}"
+        inner_msg = error.inner_ex_wrapper&.message
+        message = inner_msg ? "#{error.message} --> #{inner_msg}" : error.message
         raise K3cloud::ResponseError, message
 
       else
@@ -36,34 +48,54 @@ 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}")
 
       header = build_header(url_path(url))
       body = { parameters: parameters }
-      request = Http.new(url, header, body, @config.connect_timeout, @config.request_timeout)
+      request = Http.new(
+        url: url,
+        header: header,
+        body: body,
+        connect_timeout: @config.connect_timeout,
+        request_timeout: @config.request_timeout,
+        verify_ssl: @config.verify_ssl,
+        retry_max: @config.retry_max,
+        retry_interval: @config.retry_interval,
+        retry_backoff: @config.retry_backoff
+      )
       request.post
     end
 
     def build_url(service_name)
-      base_url = if @config.server_url.nil? || @config.server_url.empty?
-              "https://api.kingdee.com/galaxyapi/"
-            else
-              @config.server_url.to_s.strip.chomp("/")
-            end
       "#{base_url}/#{service_name}.common.kdsvc"
     end
 
-    def url_path(url)
-      if url.start_with?("http")
-        index = url.index("/", 10)
-        index > -1 ? url[index..-1] : url
+    def base_url
+      server = @config.server_url
+      if server.nil? || server.empty?
+        "https://api.kingdee.com/galaxyapi"
       else
-        url
+        server.to_s.strip.chomp("/")
       end
     end
 
+    # 仅 https/http 的 URL 才能切片出签名用 path，否则说明 URL 构造异常。
+    def url_path(url)
+      raise ArgumentError, "Unsupported URL scheme: #{url.inspect}" unless url.start_with?("http")
+
+      index = url.index("/", 10)
+      index ? url[index..-1] : "/"
+    end
+
     # @note: https://vip.kingdee.com/knowledge/specialDetail/229961573895771136?category=229964512944566016&id=423060878259269120&productLineId=1
     def build_header(url)
       header = {}
@@ -94,9 +126,6 @@ module K3cloud
         header[ConstDefine::X_KD_SIGNATURE] = kd_signature
       end
       header
-    rescue StandardError => e
-      K3cloud.logger.error({ errmsg: "Build header exception.", backtrace: "#{e.backtrace}", type: 'error', lever: 'ERROR' })
-      {}
     end
 
     def decode_sec(sec)
@@ -106,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]