cetustek 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6a6aca36dc760878fe11e9107416c7296ef5fa7835d1e223f3cab8248970fb7
-  data.tar.gz: 96fb067d26a7cb40e0b429a8a9f502fa486bc5bc2efcded04bb136bcba4b99c1
+  metadata.gz: f87e7bbfa74ad309c50b741139f8cfd66f7a197813c2e2b8d515d4e810bd0ef2
+  data.tar.gz: 89e531c88d9aff213eae2e6c75a089a7121abd5a8604d0abeadbed3bc255a0c5
 SHA512:
-  metadata.gz: 4cdf8f6a063bb979aecd5d974dd1482329582359831bf0cbb20f46c50987dbbb677e675dd3507c3bbd69883277103760900dc12b55c3650f3215b1e3ab3dc408
-  data.tar.gz: 6240dd9f19af70f835d4323a5fad194a77ef8be409f503013887095c1bd25ece1331507030443ae8a7ea571aa97c6a47eb6982e0142a2605f467afbd47977564
+  metadata.gz: 0af507e99327c3b63d4aee2f04398722cb7cf167604027fdacbaccdf374aa2e0300c21bf904dbd366f2390c129df0a34d36a9d46f9fb7e1471a941f11b1b3f0b
+  data.tar.gz: 2be9f5c9c30991581dc725b53235abdd608ea5b1e3c6ac356ec7f2f52dc7dde0d0874bdfcc630f508548a8c578f9806372e3ae80703cc2141203f1f6a6443148

data/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0] - 2026-09-09
+
+### Fixed
+
+- 亂填的代碼欄位不再被當成 0 靜靜送出去。`'x'.to_i` 是 `0`，而 `0` 是
+  `donate_mark` 的「載具」與 `round_num` 的「四捨五入」有效代碼，所以
+  `donate_mark: 'x'` 原本不會被擋，會被當成載具發票開出去。`tax_type: '1abc'`
+  會變成應稅，`CreateAllowance` 的 `check_allowance: 'x'` 也能通過「必須為 0」
+  的檢查。發票與折讓兩條路徑改用共用的字串比對。
+
+### Changed
+
+- **Breaking**: 最低 Ruby 版本提高到 3.3.0。3.0 已於 2024-04 EOL，不再收安全更新。
+- **Breaking**: 上述代碼欄位原本會被默默接受的值現在會 raise `ArgumentError`。
+  影響的是本來就送錯值的呼叫端 —— 那些請求送到平台也是失敗，只是現在提早失敗。
+- `Cetustek::Xml` 從 `module_function` 改為 `extend self`。`Xml.foo` 與
+  include 後的呼叫方式都不變。
+
+### Internal
+
+- 導入 mutant 做 mutation testing（`bundle exec mutant run`）。mutation coverage
+  從 57.42% 提升到 97.13%，行覆蓋率 100%。上面那個 bug 就是這樣挖出來的。
+- 每週排程跑 mutation testing，掉出門檻才失敗（`.github/workflows/mutant.yml`）。
+- 移除 `configuration.rb` 裡與 `lib/cetustek.rb` 重複的 `Cetustek.config` 定義
+  （被後者蓋掉的死碼）。
+
+## [0.11.1] - 2026-09-04
+
+### Fixed
+
+- `QueryAllowance.find` 查無折讓單時會 raise `ResultError: nodata`，而不是回 nil。
+  `nodata` 的判斷原本是 `Xml.parse_response` 的 `nil_values:` 參數，只有
+  `QueryInvoice` 有傳。改成 `Xml::NIL_VALUES` 常數，所有查詢共用同一個判斷。
+
 ## [0.11.0] - 2026-08-24
 
 ### Added

data/README.md

@@ -368,7 +368,7 @@ Cetustek::PhoneBarcode.valid?('/ABC123')  # => true / false
 
 ## Requirements
 
-- Ruby >= 3.0.0
+- Ruby >= 3.3.0
 - `ox` gem for XML processing
 - `savon` gem for SOAP services
 

data/config/mutant.yml

@@ -0,0 +1,13 @@
+# 對 lib/ 全部 subject 跑 mutation testing：bundle exec mutant run
+# 開源專案用 --usage opensource，不需要 license key。
+usage: opensource
+integration:
+  name: rspec
+requires:
+  - cetustek
+matcher:
+  subjects:
+    - Cetustek*
+coverage_criteria:
+  timeout: false
+  process_abort: true

data/lib/cetustek/configuration.rb

@@ -40,14 +40,4 @@ module Cetustek
       @environment == :sandbox
     end
   end
-
-  class << self
-    def configure
-      yield(config)
-    end
-
-    def config
-      @config ||= Configuration.new
-    end
-  end
 end

data/lib/cetustek/create_allowance.rb

@@ -21,7 +21,8 @@ module Cetustek
     # check_allowance 只剩 0（已確認的折讓單）：規格 §2.9 已刪除 1，
     # 114/01/01 起上傳的折讓單皆為已確認。
     def initialize(allowance_data, check_allowance: 0)
-      raise ArgumentError, 'check_allowance must be 0 (114/01/01 起折讓單皆為已確認)' unless check_allowance.to_i.zero?
+      # to_i 會把 'x' 也變成 0，字串比對才擋得住亂填的值。
+      raise ArgumentError, 'check_allowance must be 0 (114/01/01 起折讓單皆為已確認)' unless check_allowance.to_s == '0'
 
       @data = allowance_data
       @check_allowance = 0

data/lib/cetustek/models/allowance_data.rb

@@ -53,7 +53,7 @@ module Cetustek
       end
 
       def validate_tax_type!
-        return if TAX_TYPES.include?(@tax_type.to_i)
+        return if code_in?(TAX_TYPES, @tax_type)
 
         raise ArgumentError, "tax_type must be 1 (應稅), 2 (零稅率) or 3 (免稅), got #{@tax_type.inspect}"
       end
@@ -65,14 +65,19 @@ module Cetustek
       end
 
       def validate_round_num!
-        return if @round_num.nil? || ROUND_NUMS.include?(@round_num.to_i)
+        return if @round_num.nil? || code_in?(ROUND_NUMS, @round_num)
 
         raise ArgumentError, "round_num must be between #{ROUND_NUMS.first} and #{ROUND_NUMS.last}, " \
                              "got #{@round_num.inspect}"
       end
 
+      # 見 InvoiceData#code_in?：to_i 會把亂填的代碼變成 0，而 0 是有效代碼。
+      def code_in?(codes, value)
+        codes.map(&:to_s).include?(value.to_s)
+      end
+
       def blank?(value)
-        value.nil? || value.to_s.strip.empty?
+        value.to_s.strip.empty?
       end
     end
   end

data/lib/cetustek/models/invoice_data.rb

@@ -160,7 +160,7 @@ module Cetustek
       def validate_donate_mark!
         raise ArgumentError, 'donate_mark is required (0 載具, 1 捐贈, 2 紙本)' if blank?(@donate_mark)
 
-        unless DONATE_MARKS.include?(@donate_mark.to_i)
+        unless code_in?(DONATE_MARKS, @donate_mark)
           raise ArgumentError, "donate_mark must be 0 (載具), 1 (捐贈) or 2 (紙本), got #{@donate_mark.inspect}"
         end
 
@@ -197,7 +197,7 @@ module Cetustek
       end
 
       def validate_tax!
-        unless TAX_TYPES.include?(@tax_type.to_i)
+        unless code_in?(TAX_TYPES, @tax_type)
           raise ArgumentError, "tax_type must be one of #{TAX_TYPES.join(', ')}, got #{@tax_type.inspect}"
         end
 
@@ -217,20 +217,26 @@ module Cetustek
       end
 
       def validate_remark!
-        return if @remark.nil? || @remark.to_s.length <= MAX_REMARK_LENGTH
+        return if @remark.to_s.length <= MAX_REMARK_LENGTH
 
         raise ArgumentError, "remark must not exceed #{MAX_REMARK_LENGTH} characters"
       end
 
       def validate_round_num!
-        return if @round_num.nil? || ROUND_NUMS.include?(@round_num.to_i)
+        return if @round_num.nil? || code_in?(ROUND_NUMS, @round_num)
 
         raise ArgumentError, "round_num must be between #{ROUND_NUMS.first} and #{ROUND_NUMS.last}, " \
                              "got #{@round_num.inspect}"
       end
 
+      # 'x'.to_i 是 0，而 0 是「載具」「四捨五入」的有效代碼 —— 用 to_i 比對，
+      # 亂填的值會被當成 0 靜靜送出去。代碼一律轉字串比對。
+      def code_in?(codes, value)
+        codes.map(&:to_s).include?(value.to_s)
+      end
+
       def blank?(value)
-        value.nil? || value.to_s.strip.empty?
+        value.to_s.strip.empty?
       end
     end
 
@@ -273,7 +279,7 @@ module Cetustek
       end
 
       def blank?(value)
-        value.nil? || value.to_s.strip.empty?
+        value.to_s.strip.empty?
       end
     end
   end

data/lib/cetustek/queries.rb

@@ -30,7 +30,7 @@ module Cetustek
     # §2.5 QueryInvoicebyOrderid shares this exact XML shape (Table 13), so
     # QueryInvoiceByOrderId#find reuses this instead of duplicating it.
     def self.parse(xml)
-      root = Xml.parse_response(xml, nil_values: %w[nodata])
+      root = Xml.parse_response(xml)
       return nil unless root
 
       data = Xml.parse_fields(root, FIELDS)
@@ -66,7 +66,7 @@ module Cetustek
     # Query* classes — it used to be returned as if it were the number.
     def self.find(order_id)
       body = soap_return(query(order_id), :query_invoice_number_by_orderid).to_s.strip
-      return nil if body.empty? || body == 'nodata'
+      return nil if body.empty? || Xml::NIL_VALUES.include?(body)
       return body if body.match?(FORMAT)
 
       ResultCode.raise!(body, ResultCode::COMMON)
@@ -90,8 +90,8 @@ module Cetustek
     end
 
     # Same query, with the returned XML parsed into a Hash of snake_case keys
-    # plus a :details array. Values are the raw strings from the XML; returns
-    # nil when the platform answers with nothing at all.
+    # plus a :details array. Values are the raw strings from the XML; nil when
+    # the platform answers with nothing at all, or the documented "nodata".
     def self.find(allowance_number)
       parse(soap_return(query(allowance_number), :query_allowance))
     end

data/lib/cetustek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cetustek
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/cetustek/xml.rb

@@ -8,8 +8,13 @@ module Cetustek
   # and a single <Invoice>/<Allowance> root carrying XSDVersion.
   module Xml
     XSD_VERSION = '2.8'
+    # 查無資料時平台回的字串，不是結果代碼。
+    NIL_VALUES = %w[nodata].freeze
 
-    module_function
+    # extend self（而不是 module_function）：module_function 會把方法複製一份到
+    # singleton，mutation testing 改到的是 instance method 那份，正式碼呼叫的
+    # 卻是複本，整個模組的變異都殺不掉。
+    extend self
 
     def document(root_name)
       doc = Ox::Document.new
@@ -41,12 +46,13 @@ module Cetustek
     end
 
     # Shared guard every Query* class needs before it can parse a response
-    # body: nil for an empty answer or one of the documented sentinel strings
-    # (e.g. "nodata"); ResultError for a bare result code; otherwise the
-    # parsed root element, ready for parse_fields.
-    def parse_response(body, nil_values: [])
+    # body: nil for an empty answer or the documented "nodata" sentinel;
+    # ResultError for a bare result code; otherwise the parsed root element,
+    # ready for parse_fields. "nodata" is not per-query — every 查詢 answers
+    # with it when the number simply isn't there, so it lives here.
+    def parse_response(body)
       text = body.to_s.strip
-      return nil if text.empty? || nil_values.include?(text)
+      return nil if text.empty? || NIL_VALUES.include?(text)
 
       ResultCode.raise!(text, ResultCode::COMMON) unless text.start_with?('<')
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Zac
@@ -78,6 +78,7 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
+- config/mutant.yml
 - lib/cetustek.rb
 - lib/cetustek/cancel_allowance.rb
 - lib/cetustek/cancel_invoice.rb
@@ -110,7 +111,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="