cetustek 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887153f21f24293aa3ef9f6e4ee7ad48ec803c65f7104605a4d615894a5be19a
-  data.tar.gz: 14667650b0e2bf27c060df01cef3bb220d73bdb4ab6deb8bf5c1bf29bd9ba050
+  metadata.gz: 90bc8844eac9b3eb305d59f5550be7bf6e552b0fffafe74b0e71e6afc31c55ef
+  data.tar.gz: a9337fd9f37f80a3ec6532a319c4eac87ce1db79a475d7e237e3f2b59567a850
 SHA512:
-  metadata.gz: 508a2c1acb9f548116e963c7ce6b536a8e5aec3bc3d18189a56b52403a0d32f485191d5af2d6c5a3eef4a30a1f041a0eb94fe5ba8f73e38c7b30f06022f85a55
-  data.tar.gz: e2235999236cd67ee01462050391d1de6bfb4968eea812b7c9b4c7fc96b0559334e0800d5701d485d410d30f10d8486cd68bc217e04e1a9fb80169cc3e227977
+  metadata.gz: 57e5c7e15f119c182c8d0f38ef0c98ce40c682bc0262ed7043a09ed8c379a2603ae88d581bef8bcdc9e0f0a95cc5be85e6a6dc502f7c883bb7f6e74c9ebd8fa3
+  data.tar.gz: c267be5d85ea54c917d932453a910bfcca464b4e5441ad4f2c98aec3e4b2f567712e65617e6250186ebd6164ec39f4157ad12014cfce6445847afe7c8db1b926

data/CHANGELOG.md

@@ -5,6 +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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-08-07
+
+延續 0.9.0 的 code review：統一驗證力度與查詢介面，讓四個查詢類別與
+`CancelInvoice`/`CancelAllowance` 的行為一致。
+
+### Added
+- `QueryInvoice.find`、`QueryInvoiceByOrderId.find`、`QueryInvoiceNumberByOrderId.find`：
+  比照既有的 `QueryAllowance.find`，把 Savon 回應解析成 snake_case 的 Hash（`QueryInvoice`
+  與 `QueryInvoiceByOrderId` 共用 Table 13 格式，含 `:seller`/`:buyer`/`:details`），
+  `nil` 表示空回覆或規格說的 `"nodata"`，非 XML 的代碼字串一律拋 `Cetustek::ResultError`
+- `CancelInvoice` 補上 `invoice_number`/`invoice_year` 必填檢查（Table 9 皆為 Y），
+  原本只驗證 `remark`，另兩個欄位空白時要等伺服器回 `M:?` 才會發現
+
+### Changed
+- 四個查詢類別的 XML 解析共用邏輯(`text_of`/`snake_case`)搬到 `Cetustek::Xml.parse_fields`，
+  不再各自留一份幾乎相同的 private method
+- `QueryInvoice`/`QueryInvoiceNumberByOrderId`/`QueryAllowance` 改用 `Soap#soap_call`，
+  不再手動組 `source`/`rentid`，與 `QueryInvoiceByOrderId`/`CancelInvoice` 等類別一致
+- `QueryInvoice.parse`/`QueryAllowance.parse` 共用的「空值/nodata 判斷、非 XML 代碼丟
+  `ResultError`、解析成 Ox root」邏輯收成 `Cetustek::Xml.parse_response`
+- `QueryInvoice.party` 改名 `parse_party`，跟同一個類別的 `parse` 放在一起看更清楚
+
+### Fixed
+- **Breaking:** `QueryInvoiceNumberByOrderId.find` 原本會把非發票號碼、非 `"nodata"`
+  的回覆(如 `Invalid`)直接當發票號碼回傳；現在會比對 Table 9 的字軌+8碼數字格式，
+  格式不符者一律丟 `Cetustek::ResultError`，跟其他 `Query*.find` 一致
+
 ## [0.9.0] - 2026-08-05
 
 比對規格 AVM-26-03 做的 code review 修正:0.8.0 有幾條規則寫得比規格寬或比規格嚴,

data/README.md

@@ -212,6 +212,10 @@ Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '明細錯誤',
                             return_tax_document_number: '65327645').execute
 ```
 
+`invoice_number` and `invoice_year` are Table 9's other two `必填` fields, and
+raise `ArgumentError` if left blank — the same guaranteed-rejection guarantee
+`InvoiceData`/`AllowanceData` give for their own required fields.
+
 Uploading is not the end of it: the cancellation still has to be confirmed
 manually on the 鯨躍 platform before the invoice counts as void. Any code other
 than `"C0"` raises `Cetustek::ResultError` (`C5 - 該發票已經作廢過`, …), and
@@ -219,10 +223,35 @@ marking your own record as canceled is the caller's job.
 
 ### Query invoices
 
+Each query class has both a raw `.query` (the Savon response, for callers who
+want the untouched SOAP object) and a `.find` that parses the same response
+into a plain Ruby value, mirroring `QueryAllowance` below:
+
+```ruby
+Cetustek::QueryInvoiceByOrderId.query(order_id)             # raw Savon response
+Cetustek::QueryInvoiceByOrderId.find(order_id)               # parsed Hash, or nil
+Cetustek::QueryInvoice.query(invoice_number, invoice_year)   # raw Savon response
+Cetustek::QueryInvoice.find(invoice_number, invoice_year)    # parsed Hash, or nil
+Cetustek::QueryInvoiceNumberByOrderId.query(order_id)        # raw Savon response
+Cetustek::QueryInvoiceNumberByOrderId.find(order_id)          # bare invoice number String, or nil
+```
+
+`.find` returns `nil` when the platform answers with nothing at all or with
+the documented `"nodata"`; a non-XML answer (a result code) is raised as
+`Cetustek::ResultError`, same as `QueryAllowance.find`.
+
+`QueryInvoice.find`/`QueryInvoiceByOrderId.find` (both share Table 13's XML
+shape) return the fields as snake_case symbols, with `:seller`/`:buyer`
+sub-hashes and the line items under `:details`:
+
 ```ruby
-Cetustek::QueryInvoiceByOrderId.query(order_id)             # by order id
-Cetustek::QueryInvoice.query(invoice_number, invoice_year)  # by invoice number + year
-Cetustek::QueryInvoiceNumberByOrderId.query(order_id)       # just the invoice number
+{ order_id: '44556655', invoice_number: 'AA00000027', invoice_date: '2011/05/19',
+  invoice_time: '19:10:49', invoice_status: '開立', donate_mark: '0',
+  sales_amount: '120', tax_amount: '6', total_amount: '126', ctk_url: nil,
+  seller: { identifier: '53118823', name: '鯨躍科技有限公司', ... },
+  buyer: { identifier: '55669988', name: '漢客料理店', ... },
+  details: [{ product_code: 'AA783457', description: '筆記本(綠色)', quantity: '1',
+              unit: nil, unit_price: '60', amount: '60', sequence_number: '1' }] }
 ```
 
 ### Tax-inclusive vs tax-exclusive prices (`hastax`)

data/lib/cetustek/cancel_invoice.rb

@@ -22,6 +22,8 @@ module Cetustek
 
     # remark 是 Table 9 的必填作廢原因，沒有預設值可用：理由是業務決定的。
     def initialize(invoice_number, invoice_year, remark:, return_tax_document_number: nil)
+      raise ArgumentError, 'invoice_number is required' if invoice_number.to_s.strip.empty?
+      raise ArgumentError, 'invoice_year is required' if invoice_year.to_s.strip.empty?
       raise ArgumentError, 'remark (作廢原因) is required' if remark.to_s.strip.empty?
       raise ArgumentError, "remark must not exceed #{MAX_REMARK_LENGTH} characters" if remark.length > MAX_REMARK_LENGTH
 

data/lib/cetustek/queries.rb

@@ -1,41 +1,81 @@
 # frozen_string_literal: true
 
-require 'ox'
-
 module Cetustek
   # @deprecated use Cetustek::Soap. Kept so `extend Queries` keeps working.
   Queries = Soap
 
   # 2.4 QueryInvoice 查詢發票資訊 (by invoice number + year)
   class QueryInvoice
-    extend Queries
+    extend Soap
+
+    # Spec AVM-26-03 Table 13.
+    FIELDS = %w[OrderID InvoiceNumber InvoiceDate InvoiceTime MainRemark CheckNumber
+                RandomNumber InvoiceStatus DonateMark SalesAmount FreeTaxSalesAmount
+                ZeroTaxSalesAmount TaxAmount TotalAmount CtkUrl].freeze
+    PARTY_FIELDS = %w[Identifier Name Address PersonInCharge TelephoneNumber
+                      FacsimileNumber EmailAddress].freeze
+    DETAIL_FIELDS = %w[ProductCode Description Quantity Unit UnitPrice Amount SequenceNumber].freeze
 
     def self.query(invoice_number, invoice_year)
-      soap_client.call(:query_invoice, message: {
-                         invoicenumber: invoice_number,
-                         invoiceyear: invoice_year,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_invoice, invoicenumber: invoice_number, invoiceyear: invoice_year)
+    end
+
+    # Same query, with the returned XML parsed into a Hash of snake_case keys
+    # plus :seller/:buyer sub-hashes and a :details array. nil when the
+    # platform answers with nothing at all, or the documented "nodata".
+    def self.find(invoice_number, invoice_year)
+      parse(soap_return(query(invoice_number, invoice_year), :query_invoice))
+    end
+
+    # §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])
+      return nil unless root
+
+      data = Xml.parse_fields(root, FIELDS)
+      data[:seller] = parse_party(root, 'Seller')
+      data[:buyer] = parse_party(root, 'Buyer')
+      data[:details] = root.locate('Details/ProductItem').map { |item| Xml.parse_fields(item, DETAIL_FIELDS) }
+      data
+    end
+
+    def self.parse_party(root, name)
+      element = root.locate(name).first
+      element && Xml.parse_fields(element, PARTY_FIELDS)
     end
+
+    private_class_method :parse_party
   end
 
   # 2.6 QueryInvoiceNumberbyOrderid 以訂單編號查詢發票號碼
   class QueryInvoiceNumberByOrderId
-    extend Queries
+    extend Soap
+
+    # 發票號碼格式，字軌 2 碼大寫字母+8 碼數字 (Table 9). Anything else that
+    # isn't the "nodata" sentinel is a bare result code, not a number.
+    FORMAT = /\A[A-Z]{2}\d{8}\z/
 
     def self.query(order_id)
-      soap_client.call(:query_invoice_number_by_orderid, message: {
-                         orderid: order_id,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_invoice_number_by_orderid, orderid: order_id)
+    end
+
+    # Same query, returning just the bare invoice number string, or nil for
+    # an empty response or the documented "nodata". A response that isn't
+    # either shape is a result code, raised as ResultError like the other
+    # 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 body if body.match?(FORMAT)
+
+      ResultCode.raise!(body, ResultCode::COMMON)
     end
   end
 
   # 2.11 QueryAllowance 查詢折讓資料
   class QueryAllowance
-    extend Queries
+    extend Soap
 
     # Spec AVM-26-03 Table 20. Note the query response uses ProductCode and
     # InvoiceDate, unlike CreateAllowance's ProductionCode and InvoiceYear.
@@ -46,11 +86,7 @@ module Cetustek
                        UnitPrice Amount Tax TaxType].freeze
 
     def self.query(allowance_number)
-      soap_client.call(:query_allowance, message: {
-                         allowancenumber: allowance_number,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_allowance, allowancenumber: allowance_number)
     end
 
     # Same query, with the returned XML parsed into a Hash of snake_case keys
@@ -61,29 +97,12 @@ module Cetustek
     end
 
     def self.parse(xml)
-      body = xml.to_s.strip
-      return nil if body.empty?
-      # §2.11 只描述成功時的 XML；非 XML 的回覆是代碼字串，原樣拋給呼叫端。
-      ResultCode.raise!(body, ResultCode::COMMON) unless body.start_with?('<')
-
-      root = Ox.parse(body)
-      root = root.root if root.is_a?(Ox::Document)
-
-      data = FIELDS.to_h { |field| [snake_case(field), text_of(root, field)] }
-      data[:details] = root.locate('Details/ProductItem').map do |item|
-        DETAIL_FIELDS.to_h { |field| [snake_case(field), text_of(item, field)] }
-      end
-      data
-    end
-
-    def self.text_of(element, name)
-      element.locate(name).first&.text
-    end
+      root = Xml.parse_response(xml)
+      return nil unless root
 
-    def self.snake_case(name)
-      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      data = Xml.parse_fields(root, FIELDS)
+      data[:details] = root.locate('Details/ProductItem').map { |item| Xml.parse_fields(item, DETAIL_FIELDS) }
+      data
     end
-
-    private_class_method :text_of, :snake_case
   end
 end

data/lib/cetustek/query_invoice_by_order_id.rb

@@ -8,5 +8,11 @@ module Cetustek
     def self.query(order_id)
       soap_call(:query_invoice_by_orderid, orderid: order_id)
     end
+
+    # Same query, parsed into a Hash. §2.5 shares Table 13's XML shape with
+    # §2.4, so this reuses QueryInvoice.parse instead of duplicating it.
+    def self.find(order_id)
+      QueryInvoice.parse(soap_return(query(order_id), :query_invoice_by_orderid))
+    end
   end
 end

data/lib/cetustek/version.rb

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

data/lib/cetustek/xml.rb

@@ -39,5 +39,34 @@ module Cetustek
 
       element << tag(name, value)
     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: [])
+      text = body.to_s.strip
+      return nil if text.empty? || nil_values.include?(text)
+
+      ResultCode.raise!(text, ResultCode::COMMON) unless text.start_with?('<')
+
+      root = Ox.parse(text)
+      root.is_a?(Ox::Document) ? root.root : root
+    end
+
+    # Shared response-parsing side: every Query* class turns a response
+    # element into a Hash of snake_case keys, so this lives here once instead
+    # of once per query class.
+    def parse_fields(element, fields)
+      fields.to_h { |field| [snake_case(field), text_of(element, field)] }
+    end
+
+    def text_of(element, name)
+      element&.locate(name)&.first&.text
+    end
+
+    def snake_case(name)
+      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+    end
   end
 end

data/lib/cetustek.rb

@@ -8,8 +8,8 @@ require_relative "cetustek/soap"
 require_relative "cetustek/models/allowance_data"
 require_relative "cetustek/create_invoice"
 require_relative "cetustek/cancel_invoice"
-require_relative "cetustek/query_invoice_by_order_id"
 require_relative "cetustek/queries"
+require_relative "cetustek/query_invoice_by_order_id"
 require_relative "cetustek/create_allowance"
 require_relative "cetustek/cancel_allowance"
 require_relative "cetustek/phone_barcode"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Zac