この記事は,センターリスニング4点の英語(LRWS)が出来ない投稿者による英語勉強録です。
誤った記述の可能性があるため,万が一でも参考とされる際は,翻訳元を必ず確認のうえ御参照下さい。
○ 翻訳規則等
- 見出しの「<>」は,一つの目次を示す。
- 「■」は,目次中のページを示す。
- 「○」は,「■」中のページを示す。
- 「・」は,翻訳元の段落始まりを示す。
- 「・」以下に続く文頭のスペースは,前項と同じ段落であることを示す。
- コード中の「$」は,ターミナルの入力を示す。
- コード中の「>」は,ターミナルの入力結果を示す。
- コード中の「)」は,ファイルへのコード入力を示す。
- 「DB」は,データベースを示す。
- 「PR」は,プルリクエストを示す。
- 「Product」は,Solidusで販売している製品を示す。
- 「Variant」は,製品の[L,M,S]サイズ等のバリエーションの概念を示す。
- 「LineItem」は,1つのOrderに係る注文した商品群を示す。
- 「Frontend」は,Solidusにおいて,ユーザに利用される画面を示す。
- 「Backend」は,Solidusにおいて,管理者画面を示す。
○ 覚書
・翻訳元サイト:https://guides.solidus.io/developers/
・公式サイト:https://solidus.io/
・Github:https://github.com/solidusio/solidus
・拡張機能(公式リスト):https://github.com/solidusio/solidus/wiki/List-of-Extensions
・拡張機能(Solidusコミュニティ):https://github.com/solidusio-contrib
・クラス情報:http://docs.solidus.io/top-level-namespace.html
・作業期間:2019年5月11日~
<Adjusments>
■ Overview
・Spree::Adjustmentモデルは,価格調整の追跡に使用され,価格の増減どちらでも対応しており,例としては,税金やPromotionで価格調整が発生する。
・Adjustment値は,adjustment-sources(税率やPromotion等)に由来し,調整可能な合計金額に影響を与える。
- adjustable_type,adjustable_id
- 調整対象のオブジェクトであり,特定の注文,商品群,配送にあたる。
- source_type,source_id
- 金額調整のソースであり,税率やPromotion等にあたる。
- amount
- 調整金額である。
- label
- 金額調整のラベルであり,何を目的とした調整かを示す。
- eligible
- 調整金額が関連付けられたオブジェクトを調整資格の有無を示す。
- included
- 調整金額は,Trueの場合,関連付けられたオブジェクトの最終金額に含まれていること,Falseの場合,合計金額に追加される。この属性は,税額にのみ適用される。詳細情報はTaxationドキュメントを確認すること。
- finalized
- 調整が終了したかを示す。Trueの場合,調整金額は自動更新されない。
○ Adjustment sources
・Adjustment値は,他のオブジェクトを参照しており,Spree::TaxRate又はSpree::PromotionActionは,調整金額の量を提供してくる。
・調整ソースは,次のとおりである。
- Spree::PromotionAction
- Promotionルールに基づく金額を生成する。
- Spree::TaxRate
- 税率に基づく金額を生成する。
- Spree::UnitCancel
- 注文されたが出荷されなかった在庫単位の量である。
- Spree::ReturnAuthorization
- 返品されたLineItemの量である。
○ Tax adjustments
・注意事項として,税額調整は,環境によってPromotionの調整と扱いが異なる。
- デフォルトでは,Promotionの調整は,毎回,税額調整より前に適用されており,課税規則による。詳細情報は,Taxationドキュメントを見ること。
- 一般的に調整額は,関連付けられたオブジェクトの価格に追加されるが,付加価値税調整は,税込となり,合計は変わらない。
○ Adjustables
・Adjustableは,価格を調整できるオブジェクトであり,次のオブジェクトを含む。
- Spree::Order
- 全注文に対する調整である。
- Spree:LineItem
- 1注文の単一商品群に対する調整である。
- Spree:Shipment
- 配送料に対する調整である。
○ Charges vs. credits
・調整は,金額の増減に対応している。
増加のみか減少のみかを判断してcharge又はcreditのadjustment-scopesを使用される。
○ Adjustment scopes
・Spree:Adjustment自身又は,adjustments関連のクラス(Orders, LineItems, shipments)をscopesで呼び出すことができる。
・例として,eligibleのTrue値と併せてadjustmentsの全てを呼び出すことができる。
- Spree::Order.find(1).adjustments.eligible
- ID1のOrderに対する調整資格を返す。
- Spree:LineItem.find(1).adjustments.eligible
- ID1のLineItemに対する調整資格を返す。
- Spree::Shipment.find(1).adjustments.eligible
- ID1のShipmentに対する調整資格を返す。
○ List of adjustment scopes
- tax
- Spree::TaxRateからの調整である。
- price
- Spree::LineItemを調整する。
- shipping
- Spree::Shipmentを調整する。
- promotion
- Spree::PromotionActionからの調整である。
- return_authorization
- Spree::ReturnAuthorizationからの調整である。
- eligible
- 関連付けられた調整可能オブジェクトの調整資格である。例として,税額の調整資格の場合では,LineItmeに適用される。
- charge
- 増額調整です。
- credit
- 減額調整です。
- is_included
- オブジェクトの金額に含まれていることを示す。一般的には,付加価値税のみがこの値を持つ。
- additional
- オブジェクトの金額が変わる変数である。全ての調整のためのデフォルトである。
○ Adjustment associations
・Spree::Orders,Spree:LineItem,Spree::Shipmentは,全て調整可能です。
・Orderのこれらの調整には,(1)のとおり,adjustments関連で呼び出せる。
・LineItemの調整を呼び出したい場合,(2)のとおりline_item_adjustmentsメソッドを使用する。
・Shipmentの調整を呼び出したい場合,(3)のとおりshipment_adjustmentsメソッドを使用する。
・最後に,Orderに対する全ての調整を呼び出したい場合,(4)のとおりall_adjustmentsメソッドを使用する。
(1) $ Spree::Order.find(1).adjustments
(2) $ Spree::Order.find(1).line_item_adjustments
(3) $ Spree::Order.find(1).shipment_adjustments
(4) $ Spree::Order.find(1).all_adjustments
<Assets>
■ Asset management
・Solidusは,frontendとbackendの拡張とカスタムによるRailsアセットパイプラインを活用している。
我々は,Solidusの既存Assetを修正や上書きする前に,Railsのアセットパイプラインと活用していくことを推奨する。
・この記事は,SolidusがどのようにAssetを管理するかの概要を説明する。
注意事項として,Solidusの代表的な機能を備えているSlidus_frontendとsolidus_backendのGemの使用を身につけること。
○ Quick start
・アセットパイプラインに係る詳細情報については,以下のとおりである。
Assetの使用方法の概要はここにある。
- 外部JavaScript,Stylesheets,画像は,vendor/assetsディレクトリに格納される。それ以外の追加カスタムAssetは,app/assetsツリーに格納される。
- マニフェストファイル(/assetsツリーにあるall.css, all.js, application.js)は,外部ライブラリ又はカスタムAsset(何らかのファイル又は深いディレクトリにあるファイル)を必要とする。
- 利用者は,solidus_frontendとsolidus_backend-Gem又は他のGemによるAssetを上書きできる。詳細情報は,Override Solidus assetsを参照すること。
○ Solidus's asset pipeline
・全てのSolidusアプリは,基本的なRails assets-pipelineを含む。
- app/assets
- lib/assets
- vendor/assets
・Assetツリーは,images,javascripts, stylesheetsのAsset形式により,サブディレクトリが決まる。
・Solidusは,どこで使用されるAssetかによって,spree/frontendかspree/backendのAsset形式によりさらにサブディレクトリが決まる。
・appとvendorによるフォルダ構造は,次のとおりになる。
app|vendor
└─ assets
└─ images
| └─ spree
| └─ frontend
| └─ backend
├─ javascripts
| └─ spree
| └─ frontend
| └─ backend
└─ stylesheets
└─ spree
└─ frontend
└─ backend
・このフォルダ構造は,solidus_frontendとsolidus_backendが互いに衝突しないAsset構造を維持するように設計されている。
・Solidusは,利用者の固有ファイルと同様に,Solidus自身のStylesheetやJavaScriptの全てを必要とする最上位のマニフェストファイルも生成する。
・SolidusのAssetsを確認するには,利用者のシステムにインストールされたsolidus_frontendとsolidus_backend-Gemを確認するか,Githubのリポジトリで,app/assetsを確認すること。
○ Solidus manifests
・solidus_frontendとsolidus_backend-Gemは,必要とする全てのJavaScriptファイルとStylesheetファイルを纏めるためのAssetマニフェストファイルを生成する。
例として,all.cssとall.jsファイルが,vendorツリーに確認できる。
vendor
└─ assets
└─ javascripts
| └─ spree
| ├─ frontend
| | └─ all.js
| └─ backend
| └─ all.js
└─ stylesheets
└─ spree
├─ frontend
| └─ all.css
└─ backend
└─ all.css
・利用者のプロジェクトの「vendor/assets/javascripts/spree/backend/all.js」ファイルでは,spree/backendディレクトリの中で,JQueryや他のファイルを含むSolidus backendを確認できます。
//= require jquery
//= require rails-ujs
//= require spree/backend
//= require_tree .
○ Managing application assets
・我々は,Rails' suggested approach to asset organizationの使用を推奨しており,コンフリクトや偶発的なファイルの上書きを回避するために,spree/frontend又はspree/backendにカスタムファイルを配置する。
・例として,ストアのFrontendにFoundation CSS frameworkを使用したい場合,(1)のとおり次のディレクトリにfoundation.cssを配置する。
・このとおりすることは,FoundationがFrontendであることがわかりやすくなり,Backendのユーザインターフェースに影響することはない。
・次に,ホームページで特定のstyleを上書きしたい場合,(2)のとおりapp/assetsツリーに他のファイルを生成します。
(1) vendor/assets/stylesheets/spree/frontend/foundation.css
(2) app/assets/stylesheets/spree/frontend/home.css
○ Managging your Solidus extension's assets
・我々は,全てのサードパーティ製の拡張は,Slidusが提供するマニフェストファイルにおいて,solidus_frontendとsolidus_backend-Gemにより使用されている同じ名前と同じディレクトリに適合するよう推奨する。
・サードパーティ製の拡張に係るマニフェストファイルは,利用者のマニフェストファイルの中に自動的に含まれないようになっている。
利用者は,どのように開発者が拡張機能に必要なAssetを手動で追加する方法を参照するか,追加方法を自動化するRails generatorを使用する方法かを参照することになる。
・StylesheetとMigrationをインストールするGeneratorを使用する拡張例として,solidus_static_contentについて,install_generatorで確認できる。
■ Override Solidus assets
・もし,AssetとViewを提供するGem(solidus_frontendとsolidus_backend-Gem)を使用したい場合,自分でカスタムしたAssetやViewで上書きや置換ができる。
・Solidusの拡張機能又はストアのFrontendとBackendのために生成されるカスタムAssetは,自動的にIncludeや保存をしない。
Solidusに自分のカスタムAsset追加に係る詳細情報は,Asset managementを見ること。
・この記事では,SolidusのAsset管理方法の概要を説明する。
注意事項として,利用者は,Solidusの代表的な機能を含んでいるsolidus_frontendとsolidus_backend-Gemの使用方法を身に付けていること。
○ Overrides and upgrading Solidus
・我々は,最小限のAssetの上書きを推奨している。
Assetの上書きは,長期的に見て,自分のアプリをより複雑化して維持することになります。
・solidus_frontendとsolidus_backend-Gemsは,各バージョンで異なるため,一つのバージョンの上書きが次のバージョンに引き継がない可能性があります。
○ Override individual CSS or JavaScript definitions
・もし,CSS定義の微調整や,JavaScriptメソッドの個別動作を変更したい場合,app/assetsツリーのファイルの中で,再定義することで上書きできる。
□ Stylesheets
・もし,Stylesheetから単一Styleを上書きしたい場合,新規Stylesheet(例:foo.css)を生成でき,同じStyleで再定義できる。
新規Stylesheetは,どの既存の定義を上書きしたGemの中で設定後において,上書きすることになる。
・例として,(1)のとおりsolidus_frontendのscreen.css.scssファイルの中にあるfooter Styleを上書きしてみる。
・新規Stylesheeを「your_app/app/assets/stylesheets/spree/frontend」に生成するだけで,foo.cssが呼ばれ,(2)のとおり変更したい箇所が再定義されます。
(1)
footer#footer {
padding: 10px 0;
border-top: $default_border;
}
(2)
footer#footer {
border: none;
}
□ JavaScript
・単一CSS定義を上書きするのと同様で,JavaScriptの既存機能を上書きできる。
・例として,solidus_frontendのproduct.jsに由来するSpree.showVariantImagesメソッドを上書きしたい場合,プロジェクトAssetの中でJavaScriptを変更できる。
・例として,新規JSファイルであるyour_app/app/assets/javascripts/spree/frontend/showVariantImages.jsを生成すると,以下の通とおりメソッドが新定義される。
・利用者がJavaScriptsをfrontend/app.jsへコンパイルされ,クライアントに役立つとき,Spree.showVariantImagesメソッドが両方とも含まれることになるが,利用者の化ステム定義は,最後に定義されたメソッドと,リクエストに応じて実行されるメソッドになる。
Spree.showVariantImages = function(variant_id) {
alert('hello world');
}
○ Override an image, stylesheet, or JavaScript file
・Gem(solidus_frontend又はsolidus_backend)により生成される全体のファイルを置換したい場合,ファイルの名前と場所が一致するプロジェクトのapp/assetsディレクトリで新規ファイルを生成する。
利用者は,Gemにより生成されるImage, Stylesheet, JavaScriptを生成できます。
・例として,「/app/assets/stylesheets/spree/frontend/_variables.scss」にあるsolidus_frontendの_variables/scssを置換するためには,利用者自身の定義と合わせて,「your_app/app/assets/stylesheets/spree/frontend/_variables.scss」で置換して保存する必要がある。
・上記のとおりでは,単一定義を上書きするよりも脆弱になり,Solidusで機能が動作するかを保証されなくなる。
・注意事項として,このメソッドは,stylesheetやJavaScriptによる機能を完全に置換する。
・同様の手段で,サードパーティ製の拡張機能によるファイルも上書きする。
<Calculators>
■ Overview(URL)
・Solidusにおける全てのCalculatorは,Spree::Calculatorベースクラスを継承しており,Promotion,Tax,Shippingに係る値を計算して返す。
Solidusは,配送料金レート,割引率,税金,付加価値税(VAT)等の一般的なCalculationの型を内蔵している。
・利用者が新たな配送方法,税率,PromotionActionの設定時において,新たなSpree::Calculatorのインスタンスも生成することになる。
・例として,$10の定額料金である"USPS Ground"を呼び出すShipping-Methodを新規に生成する場合,Spree::Calculator::Shipping::FlatRateと呼ばれるインスタンスを生成することになる。
- 新規のCalculatorインスタンスは,Spree::ShippingMethodのcalculable_typeとして所有することになり,なぜなら,税率やPromotionActionよりもShippingMethodとポリモーフィックな関連性を持つためである。この関連付けに係る詳細情報は,Calculableの記事を確認すること。
- 新規のCalculatorインスタンスであるpreferences属性は,{:preference=>10, :currency=>"USD"}の値を持つ。
○ Attributes
・Spree::Calculatorオブジェクトは,次の属性を持つ。
- type
- 使用されるCalculatorの型を示す。例として,Shippingの場合,Spree::Calculator::Shipping::FlatRateのようにShipping-Calculatorとなる。
- calculable_type, calculable_id
- Calculableの型とそれに適合するIDを示す。例として,オブジェクトがShippingを計算する場合,Calculableは,Spree::ShippingMethodモデルからのものとなる。詳細情報は,Calculabelsを確認すること。
- preferences
- CalculatorのPreferenceとその値を格納するハッシュであり,各Calculatorの型では,型自身のPreferenceを持つ。詳細情報は,Preferencesを確認すること。
○ Calculables
・Calculableは,Spree::Calculatorによる計算に必要なオブジェクトであり,Railsにおいては,Polymorphic associationが例となる。
全てのCalculatorは,一般的なベースクラスを共有しているが,異なるオブジェクトTypeを計算することができる。
・Spree::Calculatorの場合において,3つの異なるcalculable_typesを持つ。
- Spree::ShippingMehod
- Spree::TaxRate
- Spree::PromotionAction
・Calculableは,Spree::CalculatedAdjustmentsモジュールを含んでおり,このモジュールは,一つのCalculatorオブジェクトを持つ各Calculableを必要とすることから,Spree::Calculatorインスタンスも各Calculableオブジェクトのために生成される。
・例として,$10の定額料金を付加する"USPS Ground"が呼ばれるShipping-Methodがあり,このメソッドは,Calculableであり,Calclatorの関連を必要とすることから,各配送レートは,Spree::Calculator::Shipping::FlatRateオブジェクトの関連により計算されている。
・同様にして,ストアの各税率Calculableであることから,Spree::Calculator::DefaultTaxのCalculatorインスタンスも生成され,LineItem,配送料,注文に適用される税額が計算される。
○ Preferences
・各Spree::Calcuretorは,static model preferenesを持ち,各Calculatorのインスタンスは,preferencesのハッシュを保存するpreferences属性を持つ。
・例として,ストアで2つの定額配送料が設定されており,各Spree::Calcultor::Shipping::FlatRateのCalculatorを探す場合,static-preferencesが異なる設定をどのように持つかを確認可能である。
Spree::Calculator::Shipping::FlatRate.find(1).preferences
# => {:amount=>8, :currency=>"USD"}
Spree::Calculator::Shipping::FlatRate.find(2).preferences
# => {:amount=>4, :currency=>"EUR"}
上記のとおりなるのは,各Calculatorが異なる機能を持ち,機能自身にPreferencesが設定されているからである。
次の例として,パーセントの計算目的で使用されるCalculatorは,:currencyを持たないが,特定の通貨の量を使用するCalculatorは,:currencyーPreferenceを持つ。
Spree::Calculator::Shipping::FlatRate.find(2).preferences
# => {:amount=>4, :currency=>"EUR"}
Spree::Calculators::Shipping::FlatPercentItemTotal.find(3).preferences
# => {:flat_percent=>0.2e1}
○ Preferred methods
Calculatorにおける各Preferenceにおいて,Preference値を参照又は設定するためのpreferred_メソッドが使用可能である(は,preferenceの名前を示す。)。
Spree::Calculator.find(1).update(preferred_amount: 20)
○ Custom calculators
・Solidus内臓のCalculatorsに不足を感じる場合,自分自身のカスタムCalculatorを生成可能である。
なぜなら,Promotion, Shipping, Tax calculatorsは異なる要求を持つことから,我々は,利用者が構築したいと考えるカスタムCalculatorをいくつか記事を用意している。
- Custom promotions calculator [Note: work in progress]
- [Custom shipping calculators(https://guides.solidus.io/developers/shipments/custom-shipping-calculators.html)
- Custom tax calculators
■ Promotion calculators
~翻訳中~
<Extensions>
■ Decorators
・Solidusは,他のRailsモデルやコントローラと同様にして,末尾に_decorator.rbが付く/appディレクトリにあるファイルを自動読み込みする。
これは,利用者のストアに対して,Solidusの機能性に係るモンキーパッチを許可していることになる。
・例として,Spree::Orderモデルにメソッドを追加したい場合,次のとおり/app/models/mystore/order_decorator.rbを生成することになる。
module MyStore::OrderDecorator
def total
super + BigDecimal(10.0)
end
Spree::Order.prepend self
end
・これは,ルックアップチェーンのメソッドの中において,メソッドの前置子としてMyStore::OrderDecoratorを呼び出す新たなモジュールを生成していることから,Spree::Orderオブジェクトの呼び出し時は,Decoratorのtotalメソッドが元々のtotalメソッドを上書きした形となる。
・今後は,全てのOrderにおいて,total呼び出し時に合計が$10値上げした戻り値となる。
○ Using class-level methods in decorator
・class-lecelメソッドにアクセスするためには,次のとおり特別なメソッドを定義する必要がある。
module MyStore::ProductDecorator
# This is the place to define custom associations, delegations, scopes and
# other ActiveRecord stuff
def self.prepended(base)
base.has_many :comments, dependent: :destroy
base.scope :sellable, -> { base.where(...).order(...) }
base.delegate :something, to: :something
end
...
Spree::Product.prepend self
end
・この例において,Decoratorは,Spree::Productの機能を拡張するために使用されており,Activerecordの関連や,スコープ,委譲を所有する。
○ Decorators and Solidus upgrated
・Decoratorは,Solidusのアップグレードで複雑化してしまうことがある。
もし,利用者がDecoratorに依存している場合,本番環境でアップグレードする前にテストできるようにしておくべきである。
注意事項として,Solidus-coreクラスは,各リリースで変更される可能性がある。
■ Installing extensions
・Solidusの拡張は,機能の変更又は拡張するGemを使用しており,多数の拡張機能は,次の簡単なステップでインストールできる。
- Gemfileに拡張Gemを追加する。
- bundle installを実行する。
- Gemによる供給されたジェネレータを実行する。ここは,各機能のドキュメントを確認すること。
・例として,solidus_related_products中の拡張機能は,RelationTypesを使用することでProduct間の関連受けを定義するための包括的な方法を供給する。
この拡張機能のドキュメントは,次のとおりである。
- Gemfileにsolidus_related_products-Gemを追加して,
- bundle installして,
- bundle exec rails generate solidus_related_products:installする。
・拡張機能によっては,初期化前に他でカスタム設定が必要になる。
・我々は,本番環境に適用する前において,拡張機能のドキュメントを読むことを強く推奨している。
○ Supported extensions
・利用者は,Solidusuの拡張機能を使用して,ストアに追加機能を設定可能であり,サポートされている拡張機能は,Extensions solidus.ioで確認可能である。
・もし,新規のSolidus拡張機能を作成したい場合,solidus_cmd-Gemを使用すると良い。
○ Soliton
・利用者は,Nebulabの厚意の検索エンジンであるSolitonを使用して,他の拡張機能を探すことができる。
■ Writing a New Solidus Extension
・Solidusによるサイト構築には,カスタマイズ性が求められることもあり,Solidusの拡張機能もプラットフォームの機能を拡張又は変更するためのRails-Enginesなのである。
○ Find existing extensions
・新規の拡張機能を作成する前に,利用者の必要性に合致する既に存在する拡張機能を探してみること。
Solidusは,Supported extensionsの公式リストの機能をメンテナンスしているが,また,solitonでも拡張機能を探すことができる。
・他にもSolidus-contribで利用可能な拡張機能がまとめられている。
○ Developing a Solidus extension lacally
□ Install the solidus_cmd gem
・Solidusの拡張機能は,Rails-Engineであり,利用者も他のRails-Engineを構築する全く同じ方法で拡張機能を構築できる。
・しかし,solidus_cmd-Gemを使用することを推奨している。
$ gem install solidus_cmd
・solidus_cmd-Gemは,Rails-Engineの雛形を生成することで,利用者にデフォルトの依存性等の失敗を防ぐ。
□ Generate a new Solidus extension
・solidus_cmdのインストール後,solidusコマンドでアクセスし,solidus extensionを使用してカレントディレクトリに新しい拡張機能のテンプレートを生成する。
$ solidus extension extension_name
□ Configure your extension
・solidus_cmd-Gemが拡張機能のテンプレート生成後,gemspecファイルに設定を加える必要があり,Building any Ruby gemに類する流れである。
・これは,利用者の拡張機能に対するSolidusのバージョンを設定するところであり,利用者は,Dependencyと利用者のgemspecファイル中の他のDependencyを設定する。
□ Dveloping your extension lacally
・利用者の拡張機能を動作させるためには,Solidusに拡張機能をホストさせる必要があり,特に推奨されるテスト用にSolidusを設定する。
・拡張機能の読み込みは,Gemfileに追加するだけで簡単である。
・利用者の テストに拡張機能を読み込み準備ができると,pathオプションを使用してアプリのGemfileにGemwo追加できる。
) gem "solidus_extension_name", path: "path/to/extension"
・bundleコマンドを使用して,拡張機能をインストールできる。
○ Registering your extension
・Solidusの拡張機能は,コミュニティで共有されることで利益があり,利用者の拡張機能の共有化は,他のSolidus開発者達に対して,コードの機能性を拡張していくことを許可することである。
・利用者は,自分の拡張機能を公式サポートリストにPRとして送信できる(solidusio/extensions.solidus.io)。
■ Testing extensions
・Solidusの拡張機能は,Solidusバージョンにおいて,動作してテストされるものである。
この記事は,どのようにして,Solidusとsolidusis-contrib extensionsがテストされているのかを概説しており,利用者自身が各調委機能を開発する際の指針とすること。
○ TravisCI
・通常,我々は,TravisCIで拡張機能をテストしており,複数のSolidusバージョンを横断してテストするためにbuild matrix featureを活用している。
また,我々は,MySQLやPostgreSQL等の複数DBに対してもテストしている。
・Solidusの拡張機能は,masterブランチを含め,製造中止ではない全てのSolidusバージョンに対してテストされるべきである。
・ここに2.2から2.7までにテストされる.travis.ymlの例と,masterブランチを記載する。
language: ruby
rvm:
- 2.3.1
env:
matrix:
- SOLIDUS_BRANCH=v2.2 DB=postgres
- SOLIDUS_BRANCH=v2.3 DB=postgres
- SOLIDUS_BRANCH=v2.4 DB=postgres
- SOLIDUS_BRANCH=v2.5 DB=postgres
- SOLIDUS_BRANCH=v2.6 DB=postgres
- SOLIDUS_BRANCH=v2.7 DB=postgres
- SOLIDUS_BRANCH=master DB=postgres
- SOLIDUS_BRANCH=v2.2 DB=mysql
- SOLIDUS_BRANCH=v2.3 DB=mysql
- SOLIDUS_BRANCH=v2.4 DB=mysql
- SOLIDUS_BRANCH=v2.5 DB=mysql
- SOLIDUS_BRANCH=v2.6 DB=mysql
- SOLIDUS_BRANCH=v2.7 DB=mysql
- SOLIDUS_BRANCH=master DB=mysql
○ Gemfile
・TravisCI build matrixから特定バージョンを使用するためには,以下のとおりGemfileで環境変数の使用が必要である。
source "https://rubygems.org"
branch = ENV.fetch('SOLIDUS_BRANCH', 'master')
gem "solidus", github: "solidusio/solidus", branch: branch
if branch == 'master' || branch >= "v2.0"
gem "rails-controller-testing", group: :test
else
gem "rails", '~> 4.2.7' # workaround for bundler resolution issue
gem "rails_test_params_backport", group: :test
end
gem 'pg'
gem 'mysql2'
gemspec
○ Migrations
・ActiveRecord::Migrationを直接継承していることについて,Rails5.0で廃止される可能性があり,5.1ではエラーになる。
・同じ拡張機能をRails5.1と4.2の両方でサポートするためには,solidus_support-Gemからのヘルパーを使用する。
・以下のとおり,ヘルパーの使用過程を示す。
1..gemspecにsolidus_サポートを追加する。
s.add_dependency 'solidus_core', ['>= 1.1', '< 3']
s.add_dependency 'solidus_support'
2.Gemの/lib/your_gem.rbファイルからsolidus_サポートをrequireする。
require 'solidus_core'
require 'solidus_support'
3.Gem中にあるActiveRecord::Migrationの生成物全てを置換する。ここでは,全てのdb/migrate/*マイグレーションファイルを示している。
class MyAwesomeMigration < SolidusSupport::Migration[4.2]
...
end
4.sedを使用することで,自動的にActiveRecord::Migrationの全てを置換可能である。
$ sed -i 's/ActiveRecord::Migration/SolidusSupport::Migration[4.2]/' db/migrate/*.rb
○ extensions.solidus.io
・extensions.solidus.ioにおいて,Solidusの拡張機能リストとテストスイートのステータスを全て確認可能である。
・もし,自身の拡張機能を追加したい場合,the Solidus Slack teamに参加して,#solidus channelで友達になろう。
○ Rails 5 request specs
・Rails5において,テストのリクエストに係る構文が変化した。
# Pre-Rails 5
get :users, {id: '123'}, { user_id: 1 }
# Rails 5
get :users, params: { id: '123'}, session: { user_id: 1 }
・これら両方のテストスイートを可能にするため,我々はrails_test_params_backport-Gemを活用している。
・これは,Rails5-spec-converter-Gemを使用して自動的に修正されている。
<Events>
・Spree::Eventモジュールは,Solidusのコードベース及び拡張機能の中において,イベントの開始や申し込みを担当している。
・このモジュールは,低レベルで実際にイベント管理する異なるアダプタを使用しており,デフォルトのアダプタは,RailsのActiveSupport::Notificationである。将来のリリースでは他のアダプタが含まれる予定である。
・他の用途として,Solidusのコードベースでは,注文の完了や返金完了時において,確認メールを送信するイベントで使用される。
・イベントは,カスタム性を持つSolidusに対して簡単に拡張可能であり,例として,基本的なメール機能に加えて,注文完了時に顧客に対して,SMSテキストメッセージを送信したい場合,次のコードのとおり機能してくれる。
Spree::Event.subscribe 'order_finalized' do |event|
order = event.payload[:order]
SmsLibrary.deliver(order, :finalized)
end
○ Changing the adapter
・アダプタは,次のコードを使用して変更可能である。
Spree::Config.events.adapter = "Spree::EventBus.new"
○ Subscribing to events
・Spree::Event.subscribeは,特定のイベントに対して応答することができ,イベント名は命令的で,オプションのブロックはイベント実行時に毎回,実行されるようになる。
Spree::Event.subscribe 'order_finalized' do |event|
order = event.payload[:order]
Spree::Mailer.order_finalized(order).deliver_later
end
○ Firing events
・Spree::Event.fireは,イベント実行を担当しており,イベント名を命令的にして,オプションのハッシュとコードブロックの両方が通ることができる。
Spree::Event.fire 'order_finalized', order: @order do
@order.finalize!
end
・次に代替方法として,ブロックを使用しないで同じ機能を実装するには,次のコードのとおりである。
@order.finalize!
Spree::Event.fire 'order_finalized', order: @order
・詳細情報は,Spree::Eventモジュールの中に含まれるRDOCドキュメントを参照すること。
<Inventory>
~翻訳中~
<Locations>
~翻訳中~
<Orders>
■ Overview
・Spree::Orderモデルは,Solidusにおける重要モデルの一つであり,顧客の注文に係る情報の中心地となっている。
情報としては,LineItme, Adjustment, Payment, Address, ReturnAuthorization, Shipmentを収集する。
・顧客の注文情報がアップデートされる度に,Spree::OrderUpdaterは,注文をアップデートする。
もし,注文周辺の機能が生成か変更される場合,Manually call the order updaterが必要となる。
・Orderが持つ属性は次のとおり。
- number
- Spree::Order::NumberGeneratorにより生成される注文に係る一意の識別子を示す。「R」文字から始まる値であり,9つの数字からなる(例:R123456789)。この数値は,ユーザから確認可能であり,Spree::Order.find_by(number: "R123456789")として,注文の検索に使用される。
- item_total
- 注文に係る全てのLineItemの個数を示す。
- total
- item_totalとadjustment_total属性の合計を示す。
- state
- 現在の注文状態を示す。詳細情報は,Order state machine記事を見ること。
- adjustment_total
- 注文に係る全ての調整金額の合計を示す。
- user_id
- 注文したユーザのIDを示す。ログイン済ユーザにより発注された場合のみ発生する。
- completed_at
- 注文完了時のタイムスタンプを示す。
- bill_address_id, ship_address_id
- 請求先と配送先の住所情報であるSpree::Addressに関連するIDである。
- payment_total
- 注文に係る全てにおける最終支払金額の合計を示す。
- shipment_state
- 注文に係る現在の配送状況である。
- payment_state
- 注文に係る現在の支払状況である。
- email
- 注文に係る顧客が提供したEmailを示す。この属性は,ゲストユーザであっても保存される。
- special_instructions
- 顧客からレジ中に指定された特別な内装指示を示す(special shipping instruction。
- currency
- 注文に使用する通貨を示し,注文時に設定されるSpree::Config[:currency]の値で決定する。
- last_ip_address
- Frontendで注文をアップデートした最後のIPアドレスを示す。
- created_by_id
- 注文生成時のIDを示す。
- shipment_total
- 注文に係る全ての配送料の合計を示す。
- additional_tax_total
- 注文のLineItemとShipmentに対するadditional_tax_total(消費税等)の合計を示す。
- promo_total
- 注文のShipment, LineItem, Promotionに係るpromo_totalの合計を示す。
- channel
- 他のストアから注文受領時におけるChannelを明確にする。例として,利用者がAmazonを使用していて,Amazonを通じて注文を受けた時,この注文におけるChannel値は,amazonを持つことになる。それ以外では,Spreeになる。
- included_tax_total
- 注文のLineItemとShipmentにおけるincluded_tax_total(付加価値税等)の合計である。
- item_count
- 注文に係るLineItemの個数を示す。
- approver_id
- 注文を受け付けたユーザIDを示す。
- approver_name
- 注文を受け付けたユーザ名を示す。
- approved_at
- Approverが注文を承認したタイムスタンプを示す。
- confirmation_delivered
- 注文確認メールを送信したことを示すBooleanを示す(True or Fail)。
- guest_token
- ブラウザCookieを通して,注文未完了のゲストユーザに関連付けられるトークンを示す。
- canceler_id
- 注文をキャンセルしたユーザのIDを示す。
- canceled_at
- 注文がキャンセルされた場合,キャンセル時にタイムスタンプが記録される。
- store_id
- どこで注文が生成されたかを示すSpree::StoreのIDを示す。
・Orderは,Solidusに不可欠なモデルであるため,注文の合計と小計が簡単に確認できるように,利用可能なメソッドがたくさんある。Display totals medhods記事を確認しておくこと。
○ Related models
・Spree::Orderモデルは,多くのモデルと関連している。この記事では,Orderが特に必要である要点のモデルを見てみる。ドキュメントの場所もリンクしておく。
□ Line items
・Spree::LineItemモデルは,注文に追加される各商品の費用を供給しており,LineItemは,注文と,Spree::Productと,Spree::Variant間を取り持つ。
LineItem, Product, Variantの詳細情報は,Products and variants記事を確認すること。
□ Adjustments
・Spree::Adjustmentsモデルは,注文に係るLineItemやShipmentの調整金額を供給しており,Promotionを通しての減額や,ShipmentやTaxを通しての増額も可能である。
□ Shipments
・Spree::Shipmentsモデルは,注文における商品に追加する複数の配送情報を生成しており,利用者のストアにおける配送カテゴリや配送方法や注文商品に影響される。
・Shipmentは,Spree::InventoryUnitを使用している。
InventryUnitは,商品がどのOrderかShipmentかに属しているかを追跡する目的で,注文に追加される商品毎に生成され,OrderとSpree::Shipmentの間を取り持つ。
・詳細情報は,Shipmentドキュメントを確認すること。
□ Addresses
・Spree::Addressモデルは,顧客の住所を保存し,ship_address_idとbill_address_idを通じて,Orderと共有する。
Orderは,一つか二つの異なる住所情報を持っており,顧客が優先する配送先か請求先かに左右される。
・詳細譲歩は,Addressesドキュメントを確認すること。
□ Payments
・Spree::Paymentモデルは,注文に係る支払情報を保存しており,支払金額がアップデートされると,Orderのpayment_total値も同時にアップデートされる。
・詳細情報は,Paymentsドキュメントを確認すること。
□ Return Authorizations
。Spree::ReturnAuthorizationモデルは,管理者が承認した顧客の返品情報を保存している。
■ Display total methods
・Spree::Orderモデルは,合計と残高を表示する多数の便利メソッドを持っている。
- display_outstanding_balance
- 注文に係る未払額について,total(支払合計)からpayment_total(支払い済額)を減じて計算する。
- display_item_total
- 注文に係るLineItemの合計を示す。
- display_adjustment_total
- 注文に係る調整金額の合計を示す。
- display_total
- Order全てを示す。
- display_total_available_store_credit
- 利用可能なストアポイント(例:dポイント)の残高を示す。
- display_order_total_after_store_credit
- 使用後のストアポイントの残高を示す。
・デフォルトでは,(1)のメソッドでSpree::Moneyに設定されたOrderに係る通貨シンボルを返す。
・Spree::Moneyは,Ruby Money libraryを元にするため,formatメソッドを使用することで,表示される情報をさらに変更可能である。
(1)
$ @order.display_total.to_html
> "$10.99"
(2)
$ @order.display_total.format(with_currency: true)
> "$10.99 USD"
■ Order state machine
・Orderは,Spree::Order::Checkoutモデルの中で定義されたState-Machineを通して動作しており,Cart状態から開始し,Complete状態で終了する。
・デフォルトの状態は,次のとおり6つある。
- cart
- address
- delivery
- payment
- confirm
- complete
・solidus_frontend-Gemにあるレジを通過する場合,レジの間でこれらの各状態のための明らかに定義されているということが確認可能である。
・Payment状態は,payment_required?でTrueが還ってくる場合のみ発生する。
・Complete状態は,二つの方法のうちから一つの方法で発生する。
- 注文に係る支払義務が無い場合(Totalが0)
- Paymentが注文を必要としており,少なくとも注文に係る支払金額を受け取っている場合
○ State criteria
・各注文状態は,状態変更前に条件を満たす必要がある。
例として,CartからAddressに状態が変わる前には,LineItemがOrderに存在している必要がある。また,AddressからDeliveryに変わる時,ユーザは,デフォルトのAddressを入力している必要がある。
・Orderの状態は,次の状態に移行する基準を満たすと,次の状態へ移行するためにOrderに対して,次のとおり"next"が呼ばれる。
例として,solidus_frontend-Gemの中で,Spree::CheckoutControllerは,注文が完了しない限り,いつでも"next"を呼ぶtransition_forwardメソッドを定義している。
・"next"がFalseを返す場合は,Orderが基準を満たさない時や,次の状態に移行しない時である。
def transition_forward
if @order.can_complete?
@order.complete
else
@order.next
end
end
○ Payments and shipments have their own state machines
・注意事項として,Spree::OrderがComplete状態であることは,支払済であることや,配送済であることを意味していない。
payment_stateとshipment_stateの属性値も確認すること。
■ Payment states
・通常,Spree::Orderは,一つ以上の関連したPaymentを持っているため,Orderは,注文に係る全ての支払を追跡するpayment_state属性を持つ。
・例として,顧客がストアポイントで$20持っているが,注文が$40の場合,支払方法として2種類必要とすることになる(Spree::StoreCreditと他の利用可能な支払方法)。
・Spree::Orderは,以下のpayment_stateのうち一つの状態を持つことになり,利用可能な状態は次のリストのとおりである。
- balance_due
- 注文に係る残高不足を示しており,payment_total(支払済額j)値が,total値(請求額)を下回っている状態を示す。
- failed
- 最近の注文に対する支払失敗を示す。
- credit_owed
- 注文に対する支払を請求額以上に振り込んでいる状態であり,Orderのpayment_total値がtotal値以上となる。
- paid
- 注文への支払を終了していることを示す。
- void
- 注文がキャンセルされており,支払も,支払残高も無くて,注文への支払が無い状態を示す。
○ Completed payments
・Spree::Orderのpayment_stateは,支払済みで支払残高が無い場合,支払のミスることが出来る。
これが意味することは,payment_totalとtotalの値が等しいことを示す。
・以下のテーブルでは,$40のtotal値を持つSpree::Orderであり,複数の支払方法と,payment_stateのbalance_due状態を持つ。
PAYMENT SOURCE TYPE | AMOUNT | STATE |
---|---|---|
Spree::StoreCredit | $20 | completed |
Spree::CreditCard | $20 | balance_due |
・次のテーブルにおいては,payment_stateのpaid状態を持つSpree::Orderである。
PAYMENT SOURCE TYPE | AMOUNT | STATE |
---|---|---|
Spree::StoreCredit | $20 | completed |
Spree::CreditCard | $20 | completed |
・最後のテーブルにおいては,支払失敗しているが,payment_stateのpaid状態を持つSpree::Orderである。
PAYMENT SOURCE TYPE | AMOUNT | STATE |
---|---|---|
Spree::StoreCredit | $20 | completed |
Spree::CreditCard | $20 | invalid |
Spree::CreditCard | $20 | failed |
Spree::CreditCard | $20 | paid |
○ Credit owed
・Orderが複数の支払方法を持ち,顧客が注文額以上に支払いすぎた場合,payment_stateは,credit_owed状態に変化する。
・Orderがpaid状態に変化するためには,Orderを初期化し,顧客に超過額を返還しなければならない。
・Orderにおける支払について,Spree::Refundを生成可能であり,全額返還するか,差額だけを返還するかどちらかの対応となる。
・詳細情報は,Refundsドキュメントを確認すること。
○ Checking payment states
・payment_stateメソッドを使用することで,注文に関連する全ての支払状態を確認することができる。
・payment_stateメソッドは,決済業者と自身の統合システムを構築した場合,とても便利に使用することができる。
例として,payment_stateのfailed状態の急増を自身の統合システムの問題と確認することになる。また,ストアの顧客満足度にも影響を与えるだろう。
$ Spree::Order.find(1).payment_state
> "balance_due"
■ Update orders
・Spree::Orderでアップデートしてtotalを維持するためには,recalculateメソッドの使用が必要になる。
注意事項として,LineItemとAdjustmentの追加や変更の度に合計値が変動する。
recalculateメソッドは,Spree::OrderUpdaterクラスを呼び出す。
・例として,solidus_backend-GemのSpree::Admin::AdjustmentsControllerは,注文の全てを通して,合計値全てをアップデートするためにrecalculateメソッドを使用する。
・update_totalsメソッドは,Adjustmentの生成時,削除時,編集時に呼ばれている。
def update_totals
@order.reload.recalculate
end
・Spree::Orderの値を動かすコードを変更する度に,注文の合計値を正確化するためにrecalculateメソッドが使用される。
例として,次の場合にrecalculateメソッドを呼びたくなる。
- 注文のpayment_state値を変更するSpree::Paymentの生成又は変更する時
- 注文におけるSpree::LineItemが持つ価格を変更する時
<Payments>
■ Overview
・Solidusは,会計時に使用可能な複数の支払方法を有する柔軟性の高い支払システムを持っている。
・支払工程のロジックは,SolidusのOrderシステムと分離しており,独自の支払方法を定義しやすくなっている。
・支払システムは,多段階の工程となり,要点を次のとおりまとめる。
- (1) Payment service providers
- (2) Payment methods
- 決済業者に支払情報を送信するため,支払方法を設定している複数のSpree::PaymentMethodを持つ。
- (3) Payments
- 顧客が注文に係る支払情報を送信後,新しいSpree::Paymentオブジェクトが生成される。
- (4) Payment sources
- Spree::Paymentは,支払情報ソースであり,使用される支払方法に依存する。例として,支払情報ソースとしては,Spree::CreditCard,Spree::StoreCredit,決済業者によるSpreeモデルによらないモデルである。
- (5) Payment processing
- 注文が完了すると,支払が実行される。ここの要点として,Spree::Payment::ProcessingクラスがSpree::PaymentMethodを呼び出し,支払情報を保存しようとする。
・支払システムの複雑性については,利用者が使用する支払方法と,サポートを必要とする支払方法の数に左右される。
・この記事の残りは,これらのシステムの一部を要約していく。
○ Payment service providers(PSPs)
・支払が上手くいくためには,Spree::PaymentMethodが,Payment service provider(PSP)に情報を送信する必要がある。
・Solidusコミュニティは,利用者に人気なPSPs(Braintree, Adyen, Affirm Paybright)に接続するための多数の拡張機能を作成している。
・通常,PSPは,PSPの仕様やAPIを構築するためのBaseクラスであるSpree::PaymentMethodを使用している。
・Solidus自身は,支払工程を構築せず,人気なPSPsのシステムを持たないため,利用者は,拡張機能をインストールするか,自分自身でシステムを作成する必要がある。
○ Payment methods
・Solidusにおいて,各Spree::PaymentMethodは,支払を受けるためにストアが選択した方法を示す。
例として,PayPalとクレジットカードという支払方法といして,分割して設定可能である。
デフォルトでSolidusは,動作する支払方法を持たず,通常は,Payment service providerによる支払方法を追加する必要がある。
・Solidusは,テストのため,自分のクレジットカード支払に係るモデリングのために使用可能であるSpree::PaymentMethod::CreditCardのため,他の基本支払方法のため,偽造クレジットカード支払を持っている。
・詳細情報は,Payment methodsの記事を確認すること。
○ Payments
・Spree::Paymentモデルは,支払情報を追跡しており,顧客が会計時に支払情報を送信すると,新しいPaymentが生成される。
・Paymentは,利用可能なSpree::PaymentMethod,Spree::CreditCard, Spree::StoreCredit, 他のnon-Spreeモデルのうち一つと関連するように,特定のSpree::Orderと関連している。
・注意事項として,Paymentが生成されることは,支払が上手くいったわけではない。
Spree::Paymentモデルは,支払状態を追跡する役割を持つ。
決済業者によって支払が実行されると,状態は,「complete, failed, void, etc.」に変化する。
○ Payment sources
・各Spree::Paymentは,支払ソースを追跡しており,利用者が規定する支払方法のTypeに依存する。
・例として,Solidus内蔵のSpree::PaymentMethod::CreditCardによる支払方法を使用する場合,支払ソースは,毎回,Spree::CreditCardが設定される。
・支払方補は,より複雑な支払ソースになりやすくなる。
例として,solidus_paypal_braintree-Gemを使用する場合,Paymentは,支払ソースであるSolidusPaypalBreaintree::Sourceを使用して作られるが,このクラスは,ApplePay, Creditcard, 又はPayPalAccountの値であるpayment_typeメソッドを持つことになる。
○ Payment processing
・Spree::Payment::Processingクラスのprocess!メソッドは,対応完了した注文を操作しており,顧客が選択したSpree::PaymentMethodを呼び出したり,決済業者に支払情報を送信した注文を保存する。
■ Payment methods
・Solidusにおいて,各Spree::PaymentMethodは,ストアが支払を受けるために選択した方法を示している。
例として,Paypalやクレジットカードによる支払のため,支払方法を分割して設定したくなると考えられる。
・利用者は,決済業者とのシステムを構築する時,Spree::PaymentMethodBase Classを継承している。詳細情報は,Payment service providersの記事を確認すること。
・Spree::PaymentMethodオブジェクトは,次の属性を持っている。
- type
- 支払方法を示すSpree::PaymentMethodのサブクラスを示す。
- name
- 支払方法の名称を示す。
- description
- 支払方法に係る説明を示す。
- auto_capture
- 支払方法を終了したか(True),支払工程が認証されただけか(False)を示す。
- preferences
- 現在の支払方法に係るPreferenceのハッシュとそれらの設定を示す。
- preference_source
- Preferenceのハッシュ内容に係るソースを設定している。利用者の支払方法によっては,決済業者とのインターフェースに係る追加のPreferenceが必要となる可能性がある。詳細情報は,Preferencesを確認すること。
- active
- 支払方法がactive状態かが設定される。Falseの場合,顧客からは支払方法は隠されている。
- available_to_users
- 支払方法が顧客に見えるかを設定する。
- available_to_admin
- 支払方法が管理者に見えるかを設定する。
○ Preferences
・各支払方法は,ハッシュとして設定されるPreference属性を持っており,この属性値は,決済業者に渡されるため,利用者の支払方法で塚Preferenceを設定の必要の可能性がある(例:PublicとPrivate API-Key)。
・Spree::PaymentMethodは,2つだけのPreferenceを持つ。
- :server
- 利用者のサーバ名であり,デフォルトでは"Test"になっている。
- :test_mode
- 支払方法が,testモードかどうかを設定している。
○ Auto-capture
・全てのSpree::Paymentオブジェクトは,決済業者への送信前に保存される必要がある。
PaymentMethodでauto_capture属性がfalseに設定されている場合,管理者は,手動でPaymentを保存する必要があるが,自動保存モードにPaymentMethodを設定可能である。
○ Application-wide auto-capture default
・PaymentMethodでauto_capture属性が設定されていない場合,デフォルトでは,ストアのSpree::Config[:auto_capture]の値が設定される。
○ Set a payment source class
・Spree::PaymentMethodベースクラスは,PaymentMethodに関連する支払ソースを設定するpayment_source_classを呼び出している。
自分自身のPaymentMethodを生成時,nilであっても,payment_source_classを定義する必要がある。
・Solidusは,Spree::CreditCartやSpree::StoreCreditのような支払ソースを内蔵しているが,Solidusの拡張機能(例:solidus_paypal_braintree)として内蔵するPaymentMethodは,完璧な支払ソースとして使用される。
例として,solidus_paypal_breaintree-Gemは,全ての支払に係る支払ソースとして,SolidusPaypalBraintree::Sourceが使用している。
○ Built-in payment methods
・Solidusは,デフォルトで動作可能なPaymentMethodを内蔵していないが,決済業者と独自のシステムを構築するために役立つ基本的なPaymentMethodは内蔵している。
・これらのPaymentMethodは,以下のとおりである。
- Spree::PaymentMethod::Check
- 小切手で支払うためのクラスである。
- Spree::PaymentMethod::StoreCredit
- 顧客のストアポイントから支払うためのクラスである。
- Spree::PaymentMethod::CreditCard
- 典型的なクレジットカードで支払うためのベースクラスであり,支払ソースとしてはSpree::CreditCartが使用される。
・Solidusは,テスト目的として仮想クレジットカードによるPaymentMethodを所有する。
- Spree::PaymentMethod::BogusCreditCard
- Spree::PaymentMethod::SimpleBogusCreditCard
・Paymentメソッドに係るソースコードは,/core/app/models/spree/payment_method/のとおりである。
・SimpleBogusCreditcardは,Payment Profilesをサポートしていない。
※Payment Profileとは,特定顧客とクレジットカードをペアとするレコードであり,Payment Gateway又は請求システムが使用するが,他のシステムでは使用されないものである。
■ Payment processing
・Solidusは,元々支払機能が無い代わりに,StripeやBraintree等の電子決済業者に頼る形となっていることから,支払機能を実装したい場合は,初めに電子決済業者とPaymentMethodを連携させて,支払データを送信する必要がある。
・一方で,Spree::Paymentモデルが支払に係る多くのロジックとPaymentの状態管理を担当しており,Spree::Payment::Processingクラスを含むことを覚えておくこと。
○ Interfacing with a payment service provider
・自身のPaymentMethodを設定する時,PaymentMethodと電子決済業者を連携させる必要があり,利用者自身が臨む方法で連携させることはできるが,SolidusのSpree::PaymentMethodとSpree::Payment::Processingクラスを使用した次の事項のとおり設定して欲しいと申し伝えたい。
- Spree::PaymentMethodは,Active\merchat-Gemを使用したAPI-Keyと同様の方法を持つ。
- Spree::PaymentMethodクラスは,電子決済業者により規定されるハッシュオプションを読み込むためのGatewayメソッドを使用する。
- 自身のPayment method内において,Gatewayメソッドが呼ぶことと,電子決済業者にこの情報を送信することが可能であり,
○ Gate options
・Spree::Payment::Processingクラスは,gateway_optionsメソッドを使用可能にしており,当該メソッドは,現在のSpree::PaymentオブジェクトとOrderを使用して,電子決済業者に送信可能な関連注文情報をハッシュ化することに関連する。
・全てのGatewayアクションのための,Gatewayオプションは次のとおりである。
- email, customer
- Emailは,Spree::Oerderに関連する。
- ip
- 注文に係る最後のIPアドレスを示す。
- order_id
- Spree::Orderのnumber属性であり,Orderに関連する各Paymentのためのidentifierと類似する。これらは,Pyamentの生成時に生成される。
- originator
- Spree::Payment自身を示す。
- shipping
- 注文に係る合計配送料を示す。
- tax
- 注文に係る合計税額を示す。
- subtotal
- 注文に係る商品の合計を示す。
- discount
- 注文に係るPromotionの値引き額を示す。
- currency
- 注文に係る3文字の通貨コードを示す。
- billing_address
- 注文に係るShipping Addressとして使用されたSpree::Addressを含むハッシュを示す。
- shipping_address
- 注文に係るBilling Addressとして使用されたSpree::Addressを含むハッシュを示す。
○ The process! method
・支払工程では,Spree::Payment::Processingクラス中に含むprocess!に依存する。
・注意事項として,process!メソッドは,現在のSpree::Paymentの状態と,支払ソース,Spree::PaymentMethodに設定された方法によって,多数の条件と結果を持つ。
・要約として,process!メソッドは,次の方法の内一つによって支払を処理する。
- Spree::PaymentMethodのauto_captureがTrueに設定されている場合,purchase!が呼び出され,支払が認証されて保存されたことを意味しており,Payment状態が既にCompletedでも発生する。
- Spree::PaymentMethodのauto_captureがFalseに設定されている場合,支払は認証されるが,保存されないことを意味しており,Payment状態が既にCompletedでも発生する。
・注意事項として,支払状態がCompletedでもprocessingに移行することもでき,completed状態でprocess!が呼ばれることは,Paymentに再authorize!と再purchase!をしようとすることである。
○ If process! cannot complete
・Paymentは,いくつかの条件において,process!メソッドを使用しても処理されない。
- 現在のPaymentのためのSpree;;PaymentMethodがない。
- Spree::PaymentMethodが支払ソースを要求しない。
- Spree::MaymentMethodのauto_capture属性がFalseに設定されており,Paymentが既に認証されている。
- 現在のPaymentがprocessing状態である。
・process!メソッドは,次の場合において,処理が継続されず,例外処理も機能しない。
- 支払ソースが見当たらないか,Invalidのとき。
- 現在のPaymentの状態が,processingに移行できないとき(例として,状態が既にFailed,Void, Invalid)。
○ Processing walkthrough
・ここでは,支払実行に係る段階の詳細を記載する。
- Spree::Orderのpayment_required?メソッドがTrueで完了した場合,process!メソッドが呼ばれて支払が実行されようとする。
- Paymentに関連付けられたSpree::PaymentMethodが支払ソースを要求し,Paymentのsource_typeとsource_id属性が検証されたPaymentを参照して,支払を処理しようとする。
- Paymentに関連付けられたSpree::PaymentMethodのauto_capture属性がTrueに設定された場合,purchase!メソッドが呼ばれ,呼ばれない場合は,authorize!メソッドが呼ばれる。両方のメソッドは,電子決済業者に支払情報を送信している。詳細情報は,The authorize! and purchase!記事のとおり。
- Paymentは,認証を必要とし,Solidusが支払処理を終了する前に電子決済業者による処理が実行される。どのようにauthorize!とpurchase!メソッドが操作されるのかは,Spree::PaymentMethodがどのように実行されるかと,どの電子決済業者が使用されるのかに左右される。電子決済業者は,顧客の支払を許可することも拒否することもできる。
- 電子決済業者からのレスポンス後,支払が完璧に認証されて入金されたかどうかの連絡を受ける。もし,purchase!メソッドが完了した場合,Spree::Paymentの状態は,completedに移行し,移行しない場合は,failedに移行する。
- auto_captureが利用不可の場合,支払はcapture!メソッドを使用して,手動で支払を確定させる。
- Paymentの保存時において,関連するSpree::Orderもアップデートされ,この時点でSpree::Orderの現在のpayment_stateが変更される。詳細情報は,注文のpayment_stateに係るPayment statesの記事を確認すること。
○ The authorize! and purchase! methods
・Spree::Payment::Processingモデルは,authorize!とpurchase!メソッドを持ち,現在のSpree::PaymentMethodに係る電子決済業者との連携に使用される。
各Spree::Paymentは,電子決済業者に情報送信することができるgateway optionsのハッシュを持つ。
・Spree::PaymentMethodオブジェクトは,auto-capture支払が設定されると,(1)のようにSpree::Payment::Processing#purchase!メソッドが呼ばれる。
・もし,auto-capture支払が設定されない場合,(2)のとおりSpree::Payment::Processing#authorize!メソッドが呼ばれる
(1)
payment_method.purchase(<amount>, <source>, <gateway options>)
(2)
payment_method.authorize(<amount>, <source>, <gateway options>)
■ Payment service providers
・Solidusは,自前で決済機能を構築せず,人気のPayment Service Providers(PSPs)との連携機能も内蔵していないため,自分でSolidusの拡張機能をインストールする必要がある。
○ Solidus extensions for payment processing
・人気のPSPsにアクセスするための拡張機能リストは次のとおり。
- solidus_braintree
- solidus_paypal_braintree
- solidus_adyen
- solidus_affirm
- solidus_klarna_payments
- solidus_paybright
- solidus_culqi
- solidus_payu_latam
○ Sending payments to PSPs
・うまく支払処理を進めるためには,Payment-MethodがPSPsに支払情報を送信する必要があり,PSPsとの連携する必要がある場合は,Spree::PaymentMethodとSpree::PaymentMethod::CreditCardクラスを使用することになる。
○ The Spree::PaymentMethod base class
・通常,PSPとの連携は,PSPの仕様とAPIを構築するためのSpree::PaymentMethodベースクラスが使用される。
・注意事項として,Spree::PaymentMethodベースクラスは,active_marchant-Gemにより同様の機能を持っている。
・例として,どのようにして,solidus_paypal_braintree-GemがSolidusPaypalBraintree::Gatewayクラスをを構築しているかを確認すると,自身のPreferenceが設定され,多くのメソッドがSpree::PaymentMethodの中で独自に定義されている。
○ Spree::PaymentMethod::CreditCard
・Solidusは,Spree::PaymentMethod::CreditCardクラスを提供しており,機能的では無いクレジットカードをベースにした支払方法である一方で,自前でクレジットカードを支払方法として構築するには,良い選択肢となる。
・推奨するPSPとの連携によりこのクラスを拡張又は上書きすることになるでしょう。
■ Payment sources
・各Spree::Paymentオブジェクトは,支払ソースのモデルを示すために,任意のsource_typeとsource_id属性を持っており,使用されるSpree::PaymentMethodによりsource_typeが決まる。
・Solidusは,Spree::CreditCardとSpree::StoreCreditのような支払ソースを持つが,自身のPayment-Methodがpayment_source_classメソッド内のカスタム支払ソースを定義する。
○ Credit cards
・もし,支払ソースとしてSpree::CreditCardを支払処理機能に使用している場合,このモデルは全ての支払情報を保存しないことを覚えておく必要があり,Solidusは,顧客に対してどのクレジットカードを使用されているかを確認できるようにするため,必要十分なデータを収集している。
・全ての収集したクレジットカードのデータは,即座に電子決済業者に送信され,自分のデータベースには,少しの時間も顧客の完全なクレジットカードデータを保存してはならない。
・脆弱な顧客のデータを保存する時は,PCIコンプライアンス違反のリスクを負っているため,我々は,Spree::CreditCardクラスを使用して,顧客データを責任持って保存すること等を推奨する。詳細情報は,PCI Security Standardsを確認すること。
■ Payments
・Spree::Paymentモデルは,Paymentsを追跡しており,顧客が会計時にPayment情報を送信すると,新たにPaymentが生成される。
Paymentの状態がcompletedを示すと,Spree::Orderの合計に対してカウントされる。
・Paymentは,利用可能なSpree::PaymentMethod及び支払ソース(Spree::CreditCard, Spree::StoreCreditなど)の一つと同様に特定のSpree::Orderと関連付けられている。
・Spree::Paymentオブジェクトの属性は次のとおり。
- amount
- 支払額を示す。
- order_id
- Spree::Orderに関連しているIDを示す。
- source_type, source_id
- 支払ソースとそのIDに使用されるモデルを示し,例として,Spree::CreditCardがある。詳細情報は,Payment sources記事のとおり。
- payment_method_id
- Spree::PaymentMethodに関連しているIDを示す。
- state
- Paymentの現在の状態を示しており,詳細情報は,Payment-Stateを確認すること。
- response_code
- 一般化されたコードか,又は電子決済業者から受け取ったTokenを示す。利用者は,電子決済業者に基づくこの属性を設定する必要がある。例として,後で参照する必要が場合において,Stripe-Transaction-Tokenを見るために使用される。
- avs_response
- AVSレスポンスコードは,電子決済業者から送信されたコードであり,詳細情報は,Response-Codesを確認すること。
- number
- 現在の支払を特定する一意の数値であり,詳細情報は,Payment-Identifiersを確認すること。
- cvv_response_code, cvv_response_message
- CVV2レスポンスは,電子決済業者から送信されており,詳細情報は,Response-Codesを確認すること。
○ Payment identifiers
・Spree::Paymentの生成時,一意である8つの文字からなる識別子として,number属性が生成され(2EYGNY8D),電子決済業者に支払情報を送信する時に使用される。
・電子決済業者は,一意でない識別子を要求することはないだろうが,他のサービスでは,要求するかもしれないし,むしろ推奨するかもしれない。
昔は,支払の識別子が記録されない時,誤った二重払いが報告されていた。
○ Response codes
・Spree::Paymentは,電子決済業者が返信するAVSとCVV2のコードを保存しており,これらのレスポンスコードは,その支払が,危険か安全か無効なのかを分類することを助けてくれる。これらのコードが何を意味するか,もっと学習したい場合,PayPal's list of AVS and CVV response codesを確認すること。
○ Payment states
・Spree::Paymentのstate属性は,電子決済業者に対する送信前後で変化しており,ここでは,各状態を説明する。
- checkout
- Spree::Orderが未完了を示す。
- processing
- 電子決済業者により進行中のPaymentを示し,支払の二重送信を防止しようとする一時的な状態である。
- pending
- 電子決済業者が支払を実行したが,まだ入金されていない状態を示す。
- failed
- 電子決済業者が支払を失敗した状態を示す。
- invalid
- 支払が無効であり,再実行する必要がある。
- void
- 支払が注文に対するものとカウントされるべきで無かった。
- completed
- 支払完了を示す。
・注意事項として,completed状態のPaymentは,Orderの合計に対してカウントされている。
○ Payment event methods
・Spree::Paymentモデルは,状態移行に使用できるイベントメソッドを所有している。
- started_processing
- failure
- pend
- complete
- void
- invalidate
■ Refunds
・Spree::Refundは,Spree::Paymentオブジェクトが存在する時に生成され,支払全額又はその一部金額のみと同額である。
・顧客への返金が生じた場合,Spree::Reimbursementと関連付けられる。
・Spree::Refundオブジェクトは,次の属性を持つ。
- payment_id
- Refundに関連するSpree::PaymentのIDを示す。
- amount
- Paymentに対する返金額を示す。
- transaction_id
- 一意となるトランザクションIDであるが,Spreeモデルと無関連である。
- refund_reason_id
- Refundモデルに関連するSpree::RefundReasonのIDである。
- reimbursement_id
- Refundモデルに関連するSpree::ReimbursementのIDである。詳細情報は,Reimbursementsの記事を確認すること。
○ Refund reasons
・Spree::RefundReasonの属性は,次のとおり。
- name
- 返金理由の記述名を示す。
- active
- Refund-reasonが入力済みであり,使用可能かどうかを示す。
- mutable
- Refund-reasonの名称が変更されたかを示し,新しいSpree::RefundReasonの場合は,Trueが設定される。
- code
- 選択可能なコードである。
○ Admin interface
・Solidus_backendが提供するインターフェースにおいて,ストア管理者は,注文のPaymentページから支払に対するRefundsを生成することができ,返品手続きを開始するRefund-buttonを使用することができるようになる。
<Preferences>
■ Add model preferences
・Solidusは,多数の特定有線モデルからなり,ストアとして相応しいデフォルト値が設定されている。
Preferenceは,Spree::Baseを継承するモデルにより設定することができる。
・注意事項として,Preferenceモデルは,現行モデルにのみ適合しており,詳細情報については,App configuration記事を確認すること。
・我々は,必要最小限のPreferenceモデルを維持することを推奨しているが,もし,ストアで追加Preferenceを必要とする場合,引数の数だけカスタムPreferenceを生成できる。
○ Define new preferences
・Preferenceをモデルの中に次のとおり設定できる。
module Mystore
class SubscriptionRules < Spree::Base
preference :hot_salsa, :boolean
preference :dark_chocolate, :boolean, default: true
preference :color, :string
end
end
・定義できるPreferenceは,次のとおりである。
・上記の:dark_chocolateのとおり,デフォルト値を設定可能であり,他の値で設定され無い限り,使用できる。
- boolean
- string
- password
- integer
- text
- array
- hash
○ Add columns for your preferences
・新しいPreferenceを維持するためには,(1)のとおり,マイグレーションを使用して関連モデルにカラムを追加する必要があり,追加後は(2)のとおり,マイグレーションを実行する。
(1)
class AddPreferencesToSubscriptionRules < ActiveRecord::Migration[5.0]
def change
add_column :my_store_subscription_rules, :preferences, :text
end
end
(2)
$ bundle exec rails db:migrate
○ Access your preferences
・設定されたモデルからPreferenceの値にアクセスするには,(1)のとおり実行する。
・特定のPreferenceの値のみアクセスする場合は,(2)のとおり実行する。
(1)
$ MyStore::SubscriptionRules.find(1).preferences
> {:hot_salsa => nil, :dark_chocolate => true, :color => "grey"}
(2)
$ MyStore::SubscriptionRules.find(1).preferences.fetch(:dark_chocolate)
> true
■ App configuration
・Solidusは,一般的なストアに相応しいデフォルト設定を持つ多数のPreferenceを所有している。
SolidusのPreferenceとそのデフォルト値のリストは,定義されたPreferenceがどこにあるかを示すSpree::AppConfigurationドキュメントで確認できる。
・内蔵Preferenceは,ECサイトの複雑な動作を実行するための充分にテストされているオプションである。
・これらのPreferenceの設定を制御するには,solidus_backendにおける管理者画面から,ストア管理者により設定することができる。
・Solidusは,Rails-engineであり,動作の多くは,Initializerを通してカスタムでき,Initializerを使用して,Preferenceの変更や初期化を実行できる。
デフォルトのPreferenceは,config/initializers/spree.rb中で,明確に設定されている。
・(1)のSpree.configブロックにおいて,CurrencyとMails_formのPreferenceは,変更したいデフォルト値であると思う。
・このブロックは,solidus_coreのための主要設定Objectを示しており,ここで,よく使用される振る舞いに変更することができる。
・アプリ上で初期化時は,Spree::AppConfigurationのインスタンスであるSpree::Configを使用して,Preferenceを設定可能であり,例として,ストアの使用通貨を変更する場合等である。
(1)
Spree.config do |config|
config.currency = "USD"
config.mails_from = "store@example.com"
end
(2)
Spree::Config.currency = "AUD"
○ Don't extend application-wide-preference
・我々は,Spree::AppConfigurationを変更したり拡張に対してサポートしていないが,利用者は,モデルに特定のPreferenceを追加を必要とすることで,使用を機能的にできる可能性がある。詳細情報は,Add model preferencesの記事を確認すること。
・他の方法としては,Rails.configurationをカスタマイズすることであり,詳細と実装例は,Rails guidesを確認すること。
○ Read the current preference settings
・利用者は,(1)のとおり,RailsコンソールでSolidusにおける現在設定されている全Preferenceを手早く確認できる。
・また,(2)のとおり,特定のPreference値のみも確認できる。
(1) $ Spree::Config
(2) $ Spree::Config.currency
■ Class extension points
・Spree::AppConfigurationは,拡張ポイントとしてSolidusのクラスに対するゲッターとセッターを所有している。
・クラスへの拡張前に,注意深く基本的な導入方法を勉強して欲しい。
この導入方法を理解すると,自身のストアに対して,派生やその再実行への拡張ポイントを使用できるようになる。
○ Example usage
・クラス拡張時,単一機能かストア全体の動作を変更できる。
・例として,Spree::Core::Search::Baseの拡張により,顧客の検索結果に表示される内容を変更でき,この方法では,Solidusの検索機能に対する完全な上書きは必要なくて,Solidus自身が(1)のとおり,クラスの拡張ポイントを提供している。
class_name_attribute :searcher_class, default: 'Spree::Core::Search::Base'
・特記事項として,この拡張ポイントを使用しない場合,Spree::Core::Search::Baseを使用して,sercher_classの使用をsercher_classをデフォルトにする。
・searcherの拡張は,次のとおり,複数段階を踏む。
- /lib/mystore/product_sech.rbで,カスタムsearcherを生成する。
- Spree::Core::Search::Baseから継承したクラスを上書きするため,get_base_scopoeプライベートメソッドを定義する。
- Searcherをconfig/initializers/spree.rbのSolidus initializerの中にある:searcher_class拡張ポイントに接続する。
・これでMystore::ProductSearchクラスの中では,要求された機能であるSpree::Core::Search::Baseのget_base_scopeメソッドが上書きされた。
module MyStore
class ProductSearch < Spree::Core::Search::Base
private
def get_base_scope
super.where("name LIKE '%rails%'")
end
end
end
・このSearcherは,base_scope変数をパスして,"rails"文字を持つ検索結果のみを表示することになる。
・その結果,config/initializers/spree.rbにおいて,先程の拡張ポイントを適合可能となる。
require 'my_store/product_search'
Spree.config do |config|
config.searcher_class = MyStore::ProductSearch
end
・これで,MyStore::ProductSearch機能が,デフォルトの機能に代わり使用可能となる。
○ Generating extension points
・もし,定義可能なインターフェースに対してクラスを上書きしていると気付き,拡張ポイントが無い場合は,その変更可能なクラスに対して,PRの送信を検討願う。
<Products and variants>
■ Overview
・Productsとvariantsは,Solidusに必要不可欠な概念である。
さらにSpree::ProductとSpree::Variantモデルは,互いに依存関係にあるため,どのような差異があるかを理解することが大事である。
- Spree::Product
- 製品に係る一般的な情報を示しており,製品情報や顧客がストアの項目から製品を見つけるための固定リンクを含む。もし,マグカップとTシャツを売る場合,各商品を分けて設定することになる。
- Spree::Variant
- 製品のVariantに係る特定の情報を示しており,例として,寸法や重量を含む。Variantは,OrderやShipmentに必要な情報を供給する。もし,赤と緑のTシャツを売る場合,各色をTシャツProductのVariantを作ることになる。同様に,Tシャツの全てがS/M/Lに分類される場合,それぞれ「S緑Tシャツ,S赤Tシャツなどなど・・・」の追加Variantを作ることになる。 ・以下の記事では,Solidusにおいて,ProductとVariantを使用するための要点となる情報を紹介していく。
○ Products
・Spree::Productは,ストアで一意となる製品を示す。もし,マグカップとTシャツを売る場合,各製品でProductを設定することになる。
・もし,S/M/Lサイズのように類別可能な項目を持つ場合,3つのProductを分割して用意する代わりに,Variantとして用意できる。
・Taxonomies and propertiesを使用して,製品を分類することができる。
そして,単一Productに係るより多くの情報を持たせたい場合,Productのためにカスタムproduct propertiesを追加できる。
○ Variants
・Spree::Variantは,販売する複数の類似Productとして,一意の属性を示す。
例として,類似点が多数の赤と緑のマグカップを売る場合,2つのVariantを持つProduct「Mug」を生成できる。
・ここでは,Variantに係るいくつかの要点を次のとおり示す。
- Productが1つ以上のVariantを持つ場合,全てのVariantは,オプションTypeとValueを必要とする(例として,オプションのTypeがサイズで,ValueがS/M/Lとなる。)。
- 全てのProductは,Master Variantを持つ。追加のVariantの生成時,Master Variantから属性を継承する。その属性は,Variant自身の一意のValueで上書きすることができる。
- 全てのProductの画像は,ProductのVariantに関連付けられている。Product画像は,特定のVariantに関連付けられているか,全てのVariantに使用されているかどちらかである。
・Variantに係る詳細情報は,Variant記事を見ること。
○ Taxonomies and taxons
・Spree::TaxonomyとSpree::Taxonを使用することで,製品分類を作成できる。
- Categories
- Brands
・分類はサブカテゴリとして,分類方法で分けられる。
Categories
|-- Luggage
|-- Clothing
|-- T-shirts
|-- Socks
|-- Shoes
Brands
|-- Adidas
|-- Bentley
|-- Calvin Klein
・分類は,Spree::Classificationモデルを通したProductに関連付けられるようになる。
・TaxonomiesとTaxonsに係る詳細情報については,Taxonomies and taxons記事を見ること。
■ Multi-currency-support
・Spree::Priceは,特定の通貨とVariantの組み合わせのための価格を示す。
例として,Variantの価格が15-USD又は7-EURの場合,各通貨に関連付けられるSpree::Priceを二つ持つことになる。
・もし,ProductのSpree::Variantが,サイトで設定される通貨の価格を持たない場合,そのProductは,Frontendで表示されません。
・利用者は,(1)のとおりPriceインスタンスメソッドにより,サイトで設定された通過のVariant価格を見ることができる。
・また,Spree::ProductにおいてもPriceメソッドを呼び出すことができる。
・(2)のとおり,Product又はVariantに関連付けられたSpree::Price全てのリストのため,インスタンスに対してPricesメソッドを呼び出すことができる。
(1)
$ Spree::Variant.find(1).price
> 15.99
(2)
$ Spree::Product.find(1).prices
> [#<Spree::Price id: 2 ...]
> [#<Spree::Price id: 3 ...]
$ Spree::Variant.find(1).prices
> [#<Spree::Price id: 4 ...]
> [#<Spree::Price id: 5 ...]
■ Product images
・Product画像は,Spree::Imageモデルに属し,ProductのVariantにも属する。
Solidusは,Paperclipを使用して,画像の生成と保存を処理している。
・これらのProduct Image属性は次のとおりである。
- viewable_id
- 画像と関連するVariantのためのIDである。
- attachment_width, attachment_height
- アップロードされた元画像の幅と高さである。SolidusがどのようにProduct画像をリサイズしているかについては,Paperclip secionを確認すること。
- position
- 画像リスト中のImageの配置場所を設定する。例として,「2」の値では,「1」の値の後で表示される。
- alt
- Imageに対するテキストである。管理者は,Backendから追加できる。※投稿者:Universal Design参照
○ Fallback images
・全てのProuct画像は,特定のSpree::VariantのIDに関連付けられるが,VariantがマスターVariantである場合(Variantで「is_master==True」),他のVariantの画像は代替画像として除外されて,表示されることになる。
・もし,Productに画像が無い時に,表示される画像を変更したい場合,「app/assets/images/noiamges」ディレクトリ中にあるSolidusのデフォルト画像である「noimage」を上書きすることができる。
・もし,Paperclip configurationを変更したい場合,利用者が定義した各画像添付キーが「noimage」画像を含むことを確認して下さい。
デフォルトキーでは,「mini, small, product, large」です。
○ Images for all variants
・管理者は,solidus_backendでProductを追加,編集時に画像をアップロードすることができる。
画像は,全てのVariantの中から一部のVariantのみ表示されるよう設定可能である。
・全てのVariantに設定する場合,viewable_idを現行のProductにおけるマスターVariantで設定すること。
○ Paperclip settings
・Paperclipは,Product画像の生成と保存を処理する。
デフォルトでは,指定サイズで各バージョンの画像を生成している。
・(1)のとおり,Railsコンソールで,attachment_definitionsメソッドを呼び出すことにより,デフォルトの指定サイズを確認できる。
・デフォルトサイズは,初期化して設定することもできる。
例として,(2)のとおり,新規デフォルトを「config/initializers/paperclip.rb」で設定できる。
(1)
$ Spree::Image.attachment_definitions[:attachment][:styles]
>=> {
> mini=>"48x48>",
> small=>"100x100>",
> product=>"240x240>",
> large=>"600x600>"
>}
(2)
$ Spree::Image.attachment_definitions[:attachment][:styles] = {
mini: '128x128>',
small: '256x256>',
product: '512x512>',
large: '1024x1024>'
}
○ Regenerate thumbnails
・デフォルト画像サイズを変更する場合,Rake taskを次のとおり実行してPaperclip thumbnailsを再生成しなければならない。
$ bundle exec rake paperclip:refresh:thumbnails CLASS=Spree::image
■ Product properties
・Productの属性は,Spree::ProductPropertyモデルに属する。
特に属性が特定のProductにのみ適合する場合,個々のProductの属性を示す。
通常,Productの属性は,技術的な仕様又は追加Product情報に使用されている。
・例として,Tシャツの限定版のためのProduct属性リストは,次のテーブルのとおりである。
PROPERTY NAME | PROPERTY VALUE |
---|---|
Fit | Tapered |
Manifacturer | American Apparel |
Material | 100% cotton |
・利用者は,(1)のとおり,属性名を通じてPropertyメソッドを呼び出すことにより,Spree::Product上から,属性値を受け取ることができる。
・利用者は,(2)のとおり,set_propertyメソッドを呼び出してProductの属性を再設定できる。
・(2)において,fit属性が存在していない場合,新規のPropertyインスタンスとして生成することになる。
(1)
$ Spree::Product.find(1).property("fit")
> "Tapered"
(2)
$ Spree::Product.find(1).set_property("fit", "Tapared")
○ Product properties are not option types
・Product Propertyは,既に定義したProductのVariantのOption Typeと混同しないようにすべきである。
・Product Propertyに"綿100%のTシャツ"と記述する時では,Option Typeでは,Variantが互いに明確にするため,"Tシャツは赤と緑色のうち一つを購入することができます。"のように使用すること。
○ Variant properties
・一つのVariantのみ適合するProduct Propertyがある場合,Product Propertyと同様にVariant Propertyを設定できる。
・Spree::VariantからVariant Propertyの適用ができる。
$ Spree::Variant.find(1).variant_properties
■ Products
・Spree::Productは,ストアにおいて,別個のProductを示す。
利用者が,マグカップとTシャツを売る場合,各製品でProductを設定することになる。
・Productの属性は,次のとおりである。
- name
- Productの省略名である。
- description
- Productの全説明である。
- slug
- Product名に基づくSEOスラッグである。ProductのURLに使用されている。
- available_on
- ストアでの取扱開始日である。この属性を設定しない場合,ストアの販売製品の中に表示されなくなる。
- deleted_at
- ストアでの販売中止日である。
- meta_description
- SEOを目的とした説明文である。この説明文は,検索結果で表示され,160文字以上は切り捨てられる。
- meta_keywords
- カンマで分割されたキーワードで製品に関連する文言であり,SEOを目的としている。
- meta_title
- HTMLのタグである。空である場合,代わりにProduct名がが使用される。
- promotionable
- そのProductがPromotion対象かを確認できる(管理者画面で"Promotable"とラベルされる。)。
○ Variants
・ビジネスロジックに関するSolidusの製品の多くは,ProductよりもSpree::Variantに属している。
Variantは「製品価格・寸法・画像」を所有している。
・たとえ,利用者が1種類のサイズと色のみを持つ単一Productのみを売る場合でも,そのProductは,追加属性を管理するための一つのVariantを持つことになる。
○ Product properties
・利用者は,Product Propertyを持つProductも設定できる。Product Propertyは,単一Productに対するカスタム製品情報を追加することを許可している。
・サイズ属性は,多くのProductで使用されており,VariantのためのOption Typeとして,より使いやすくできるが,限定版のTシャツを販売決定した場合,マーケティング目的で,「Fit,Material,Manufacturer」のような一意となるProduct Propertyを追加したくなるだろう。
■ Taxonomies and taxons
・TaxonomyとTaxonは,Productにおける頑強なクラス分類とカテゴリ分類方法であり,Spree::TaxonomyとSpree::Taxonsモデルからなる。
・管理者は,Backendから必要なだけ多くの分類を定義できるし,Spree::Classificationモデルを使用して,いくつかのTaxonomy又はTaxonと個々のProductに関連付けることができる。
・Taxonomy使用時には,理解すべき二つの要点がある。
- Taxonomy
- 個々のTaxonで構成される階層リストである。各Taxonomyは,一つのTaxonに関連しており,それは親ノードとなっている。
- Taxon
- Taxonomy内に存在する単一の子ノードである。各Taxonは,追加で子ノードを持つことができる。管理者は,必要な分だけTaxonomyを定義できるし,各Taxonomyから複数のTaxonをProductに関連付けられる。
○ Taxonomies
・自分のストアで高い次元において,Productを分類する方法を定義するため,Taxonomyは使用され,Taxonの親ノードとなる。
・ECストアで一般的なTaxonomyは,次のとおりである。
- Categories(カテゴリ)
- Brands(ブランド)
○ Taxons
・Taxonomyを生成すると,Taxonと呼ばれる子ノードが追加されることにより,低レベル構造の分類を始めることができる。
・例として,TaxonとしてCategoriesとBrandsを生成する場合,Taxonomyは,次のとおりとなる。
Categories
|-- Luggage
|-- Clothing
|-- T-shirts
|-- Socks
|-- Shoes
Brands
|-- Adidas
|-- Bentley
|-- Calvin Klein
・Taxonは,さらに子ノードであるTaxonを持つことができ,例としては,Clothing Taxonは,Tシャツや靴下のように,さらにサブカテゴリを持つことができる。
○ Classifications and taxon management
・Spree::Productは,Spree::Classificationモデルを通して,Taxonと関連付けられる。
・Spree::Classificationモデルは,Productが削除された場合に,当該ProductからTaxonへの全リンクも削除するために存在する。
同様にTaxonが削除された場合も同じであり,Productへの全リンクを自動的に削除される。
○ Using taxons in controllers and templates
・コントローラ又はテンプレートの中でTaxonにリンクする時は,spree_nested_taxons_pathヘルパーを使用しており,「/t/categories/clothing」のようなURLを生成するため,Taxonの固定リンクを使用する。
○ Database tables
・Taxonは,階層構造にNested set modelを使用している。
・Spree::Taxonsモデルにおける「lft」と「rgt」属性は,商品の階層構造の中にある位置を示している。
この理論は,awesome_nested_set-Gemにより実行されており,当該理論に係る詳細情報は,Gemのドキュメントを確認すること。
■ Variants
・Spree::Variantは,販売している複数の同種Productにおける異なっている属性を示す。
・例として,多数の共通点を持つ赤と緑のマグカップを販売する場合,2つのVariantと合わせて,単一の"Mag"Productを生成することになる。
・"Mag"Productは,"Color"のOption Typeを必要とし,"Color"Option Typeは,2つの値(赤と緑)のOption Typeが必要になる。
赤と緑の両Variantは,各々で価格,寸法,その他の属性を持つことができる。
・LineItemは,Orderと一緒にVariantと関連しているvariant_idを使用しているため,全ての製品は,少なくとも一つのSpree::Variantを持つことになり,マスターVariantも同じである。
・Variantは,Variant特有の属性を定義している。
- Weight, height, width, depth
- 一意となる寸法又は重さが設定される。
- cost_currency
- 代替となる通貨を示す。
- cost_price
- 製造原価が設定される。
- position
- Variantリスト中におけるPositionが設定される。例として,2つのVariantがある場合,1又は2になる(管理者は,Product's Variantsタブ中のリストにおいて,ドラッグ&ドロップによりPositionを設定できる。)。
- track_inventory
- 当該Variantにおける在庫を追跡できるかが設定される。
- tax_category_id
- 当該Variantに係るProductの税区分を上書きする。詳細情報はTaxationを確認すること。
○ Option types
・Variantを生成するためには,Option TypeとOption Valueを生成する必要がある。
- Productは,Variantに割り当てられているSpree::OptionTypeが少なくとも一つ持つ必要がある。例として,複数の色でProductを販売しようとする場合,"Color"のOption Typeを生成することになる。
- Option Typeは,使用するためにSpree::OptionValueを少なくとも一つ必要とする。例として,”Color"Option Typeは,10又は100のOption Valueを持つことになる。 ・管理者は,OptionTypeとOptionValueをBackendで生成することができる(Product->OptionTypes page)。Productを追加か編集したときは,Productに利用可能なOptionType,各VariantにOptionValueを追加することができる。
○ Master variants
・全てのProductは,MaterVariantを持つ。デフォルトで,MasterVariantは,Product生成時の最初のVariantになる。例として,管理者がsolidus_backendを使用して新Productを生成する時に,ProductのMasterVariantもまた生成されている。
・追加のVariantの生成時,異なる属性が設定されるまでは,MasterVariantの属性を継承する。
○ Usage
・MasterVariantは,Spree::LineItemにより2つの方法で使用される。
- MasterVariantがProductの唯一のVariantである場合,MasterVariantは,LineItemに関連付けられたVariantとなる。これが意味することは,LineItemは,MasterVariantの属性とSpree::Priceが使用されることになる。
- Productが一つ以上のVariantを持つ場合,MasterVariantは,価格と他の属性をLineItemに渡さない。この場合,MasterVariantは,売ることができない代わり,他のVariantのためのテンプレートとして使用されることになる。
・MasterVariantは,全ての追加Variantのために包括的なテンプレートとなるべきである。
もし,Productが"Color"と"Size" Optonがある場合,MasterVariantは,Productに関連付けられた"Color"又は"Size"を持つことはない。
ただし,Variantの全てが同じ価格で販売する場合は,MasterVariantに価格を割り当てることができる。
"MUG" VARIANT | Color | SIZE | PRICE |
---|---|---|---|
1(master variant) | -- | -- | $12 |
2 | Green | Large | $12 |
3 | Red | Medium | $12 |
4 | Red | Large | $12 |
5 | White | Medium | $12 |
○ Master variant methods
・MasterVariantは,master又はvariants_including_masterメソッドを使用して,明確に呼ばれなければならない。例として次のとおりである。
・MasterVariantは,variantsメソッドによりアクセスされるVariantのリスト中には存在していない。
$ Spree::Product.find(1).master
> <Spree::Variant id: 2, is_master: true, ...>
○ Product images
・ProductImageは,Spree::Imageモデルを通じてVariantに関連付けられている。詳細情報は,Product imagesの記事を見ること。
<Promotions>
~翻訳中~
<Returns>
~翻訳中~
<Shipments>
~翻訳中~
<Taxation>
~翻訳中~
<Upgrades>
~翻訳中~
<Users>
~翻訳中~
<Views>
■ Custom frontend
・SolidusはRails-engineとして,ゼロからFrontendのカスタムアプリケーションを構築することができる。
他のRailsアプリと同様の方法でFrontendを増築していける。
・この記事では,アプリにおけるViewを増築する方法に焦点をあてるが,元々のSolidusモデルの活用も必要であることや,機能的なFrontendにするためのコントローラを生成することを覚えておくこと。
○ solidus_frontend
and solidus_backend
・Solidusは,ユーザが操作するFrontendと管理者画面であるBackendを有している。
Frontendは,CSSグリッドのためのSkeleton,Backendは,Bootstrapを使用しており,これらのGemは,一般的なストア機能を提供し,solidus_coreの機能にも広く利用される。
・自分のストアで他のGemを使用したい人もいるだろうが,FrontendとBackendの構築時,以下のGemを使用しないといけない。
・以下のGemが,Viewの生成に要する。
○ Getting started with Rails frontend development
・もし,Solidusストアにおいて,自分自身のFrontend又はBackend画面を生成する場合,我々は,初めに利用者自身がRailsの使用になれることを推奨している。
Solidusは,Rails-engineであるため,他のRailsアプリと同じ方法で開発することができるしょう。
・もし,Railsに触れるのが初めての場合,以下のリンクで,アプリ開発に慣れることができる。
・我々は,Rails Guideの全てを推奨しているが,Frontend開発では,特に以下に関連するRails Guideの情報を見て欲しい。
- Ruby on Rails Tutorial
- Getting Started with Rails(Rails Guide)
- The Asset Pipeline(Rails Guide)
- Rails Internationalization(I18n)API(Rails Guide
○ Create your own Solidus frontend
・もし,solidus_frontend-Gemを使用しない場合,ゼロから自分でFrontendを構築することになるため,solidus-specific setup情報の下の方にあるリストを確認すること。
○ Solidus application settings
・Solidus::Configの設定は,ストアのFrontend全体で大きな影響を与えており,利用者は,「config/initializers/spree.rb」ファイル又は他の初期値の設定を変更できる。
・Railsコンソールで以下のコマンドを送ることで,Spree::Configのデフォルト設定を全て確認できる。
・利用者は,特にFrontendを開発していくほど,Spree::Configの設定を初期化したくなるだろう。
- :layout
- 「/app/view」ディレクトリにあり,Frontendのための基本レイアウトであるViewである。デフォルト値は,solidus_end-Gemの中にあるファイルであり,「spree/layouts/spree_application[.html.erb]」となる。
- :logo
- 「/app/assets/images」ディレクトリにあり,Frontend上のロゴとして使用されるファイルである。利用者は,<%= logo %>を使用することで,複数のViewでロゴ値を取り出せる。デフォルト値は「logo/solidus.svg」である。
- :products_per_page
- 一つのページに表示されるProductの数を設定できる。デフォルト値は,12である。
$ Spree::Config.inspect
○ Contributing back to Solidus
・もし,SolidusにPRを送りたい場合,solidus_frontendとsolidus_backendのコードの全てをpure JavaScriptを使用することを覚えておくこと。
CoffeeScriptで記述されたファイルは,適合していない。
詳細情報は,Contributingガイドを確認すること。
■ Override views
・solidus_frontendとsolidus_backend-Gemは,FrontendとBackend画面において全ての機能を提供しており,それらのGemは,Solidus目的にも使用できるが,デフォルトでSolidusとして包括的に提供している。
・利用者は,Frontend又はBackendで,自身のプロジェクトPathに複製したViewテンプレートを上書きできる。
例として,solidus_frontendの「/app/views/spree/address/_form_html.erb」パーシャルを複製したい場合,プロジェクトの「app/views/apree/address/_form_html.erb」として同じファイルを生成できる。
・利用者は,ゼロからViewを記述することも選択可能であり,又は,オリジナルのViewを使用や編集も可能である。
Railsアプリとして,利用者のアプリは,同じPathと名前である限り,いつでもGemのViewを上書き可能である。
・特記事項として,同様の方法で,CSSとJavaScriptのAssetも上書き可能である。詳細情報は,Override Solidus assets記事を見ること。
○ Rails generator for frontend overrides
・solidus_frontend-GemのViewを上書きする場合,(1)のとおり,ホストアプリ付属のRails generatorで生成可能である。
・(1)のコマンドは,編集可能な全てのFrontendのViewのコピーを生成する。
・いくつかのViewのみをコピーする場合,(2)のとおり,--only引数により実現可能である。
・(3)のとおり,--only引数は,「app/vies/spree」フォルダから,サブストリング名でも使用可能である。
・(3)では,ディレクトリ又はファイル名に’product'の文字を含むViewをコピーする。
(1)
$ cd your-rails-project
$ bundle exec rails generate solidus:views:override
(2)
$ bundle exec rails generate solidus:views:override --only products/show
(3)
$ bundle exec rails generate solidus:views:override --only product
○ Overrides and Solidus upgrades
・SolidusのViewは,各バージョンにより変更されている。Viewの上書き次第では,アプリのViewをいつもテストしておき,本番環境においても,アップグレード前にSolidusのChangeLogを読んでおくと良い。
○ Deface
・難しいアップグレードを避けたい場合や,必要機能のために少しの変更だけを必要とする場合,Deface-Gemを使用すると良い。
Defaceは,適当に利用者のテンプレートをダイナミックに変更する。
・しかし,大規模にDefaceを使用する場合,実際にHTMLの一部がどこから参照されているのかが分かりにくくなってしまう。