五倍券 Banner - 首頁 - desktop

五倍券 Banner - 首頁 - mobile

五倍的五倍券優惠活動

Blogs - Sidebar


這是綠界的電子發票介接技術文件：[綠界科技股份有限公司 電子發票介接技術文件](https://www.ecpay.com.tw/Content/files/ecpay_004.pdf)

根據這份文件，我們可以做的事情有蠻多的，本文只介紹最最基本的功能：

- 開立發票
- 查詢發票明細

本文將會從建立一個新的 Rails App 開始，最後實作開發票和查詢發票明細的功能。

# 建立一個 Rails App

在 console 輸入以下指令：

```bash
rails new ecpay_invoice_demo
cd ecpay_invoice_demo
```

# 新增一個開發票的 service

在專案資料夾中的 `app/services/ecpay/invoice` 資料夾下，新增 `create_service.rb`，此時你應該會發現 app 資料夾下不存在 services 資料夾，你要自己新增資料夾。

在 `create_service.rb` 中加入以下程式碼：

```ruby
module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
      end

      def run
        'yo'
      end
    end
  end
end
```

接著在 Rails console 下測試看看

```ruby
> Ecpay::Invoice::CreateService.new.run
# => "yo"
```

看到 yo 代表你做對了。

# 串接綠界API

在這裡我會直接使用綠界提供的測試環境做展示，所以不會實作切換環境的程式碼，以下是綠界的測試環境：

相關連結

- 開立發票的API網址：[https://einvoice-stage.ecpay.com.tw/Invoice/Issue](https://einvoice-stage.ecpay.com.tw/Invoice/Issue)
- 綠界測試環境後台登入頁：[https://vendor-stage.ecpay.com.tw/Home/Index](https://vendor-stage.ecpay.com.tw/Home/Index)
- 綠界測試環境電子發票後台：[https://vendor-stage.ecpay.com.tw/Einvoice/Index](https://vendor-stage.ecpay.com.tw/Einvoice/Index)

綠界測試環境後台帳密

- 帳號：StageTest
- 密碼：test1234

API 串接參數

- MerchantID：2000132
- HashKey：ejCk326UnaZWKisg
- HashIV：q9jcZX8Ib9LM8wYk

我們只需要把正確的參數傳進正確的網址，就可以成功開立發票了，現在來修改一下我們的 service code：

```ruby
module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
        @params = params
      end

      def run
        create(sample_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Invoice/Issue'
      end

      def sample_params
        {}
      end

      def create(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        response.body.force_encoding('UTF-8')
      end
    end
  end
end
```

目前的程式碼可以幫我們把 sample_params 傳到綠界，並且獲得回應內容。只要我們再將 sample_params 填入，整個開發票的功能就完成了。現在讓我們回到 Rails console 測試一下目前的程式跑起來是怎樣的結果：

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "無效的MerchantID「商品編號為空白」"
```

我們成功獲得了來自綠界測試環境的錯誤訊息。

# 填入開發票的參數

修改開發票的參數 sample_params 如下：

```ruby
def sample_params
  # 基本參數
  {
    'TimeStamp' => Time.current.to_i.to_s,
    'MerchantID' => '2000132',
    'RelateNumber' => SecureRandom.hex(10), # 訂單編號
    'CustomerEmail' => 'service@5xruby.tw', # 客戶信箱
    'TaxType' => '1', # 課稅類別
    'InvType' => '07', # 字軌類別

  # 商品參數
    'SalesAmount' => 1900, #總金額
    'ItemCount' => '3|2', #商品數量
    'ItemPrice' => '300|500', #商品單價
    'ItemAmount' => '900|1000', #商品小計
    'ItemName' => '衣服|褲子', #商品名稱
    'ItemWord' => '件|件', #商品單位

  # 發票參數
    'Print' => '0', # 要列印嗎？ 0代表不要 1代表要
    'Donation' => '1', # 要捐嗎？ 0代表不要 1代表要
    'LoveCode' => '168001', # 要捐給誰，一個7字元的愛心碼
  }
end
```

試用一下

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "InvoiceDate=&InvoiceNumber=&RandomNumber=&RtnCode=10200090&RtnMsg=CheckMacValue is null.&CheckMacValue=2F3E82F5A5C582BB0E1E5E34EE749F1A"
```
他傳回了一個 query string 來告訴我們發生了什麼事情，我們要關注的地方是 `RtnMsg`。這裡我特寫一下：

```ruby
RtnMsg=CheckMacValue is null.
```

# 計算 CheckMacValue

綠界的回應是說我們沒有傳遞 CheckMacValue 給綠界， CheckMacValue 的功能是用來確認雙方身分用的。我們會把我們要傳遞的參數加入綠界給我們的 HashKey 跟 HashIV，然後進行一個 hash 運算，就可以獲得 CheckMacValue 了。

CheckMacValue 的詳細計算流程如下：
- 將傳遞參數依照第一個英文字母，由 A 到 Z 的順序來排序(遇到第一個英名字母相同時，以第二個英名字母來比較，以此類推)，並且以&方式將所有參數串連。
- 參數最前面加上 HashKey、最後面加上 HashIV
- 將整串字串進行 URL encode
- 轉為小寫
- 使用 MD5 產生雜凑值
- 再轉大寫

由於綠界的 API Server 是用 ASP.NET 實作的，所以我們的 URL encode 的結果必須跟 ASP.NET 上的 URL encode 相同。不同的語言實作的 URL encode 的結果可能會有些微差異，所以我們需要針對這一點特別處理。

全部實作完之後的程式碼如下：

```ruby
require 'net/http'

module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
        @params = params
      end

      def run
        create(sample_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Invoice/Issue'
      end

      def sample_params
        # 基本參數
        {
          'TimeStamp' => Time.current.to_i.to_s,
          'MerchantID' => '2000132',
          'RelateNumber' => SecureRandom.hex(10), # 訂單編號
          'CustomerEmail' => 'service@5xruby.tw', # 客戶信箱
          'TaxType' => '1', # 課稅類別
          'InvType' => '07', # 字軌類別

        # 商品參數
          'SalesAmount' => 1900, #總金額
          'ItemCount' => '3|2', #商品數量
          'ItemPrice' => '300|500', #商品單價
          'ItemAmount' => '900|1000', #商品小計
          'ItemName' => '衣服|褲子', #商品名稱
          'ItemWord' => '件|件', #商品單位

        # 發票參數
          'Print' => '0', # 要列印嗎？ 0代表不要 1代表要
          'Donation' => '1', # 要捐嗎？ 0代表不要 1代表要
          'LoveCode' => '168001', # 要捐給誰，一個7字元的愛心碼
        }
      end

      def create(params)
        params['CheckMacValue'] = compute_check_mac_value(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        response.body.force_encoding('UTF-8')
      end

      def compute_check_mac_value(params)
        # 先將參數備份
        params = params.dup

        # 某些參數需要先進行 url encode
        %w[CustomerName CustomerAddr CustomerEmail].each do |key|
          next if params[key].nil?
          params[key] = urlencode_dot_net(params[key])
        end

        # 某些參數不需要參與 CheckMacValue 的計算
        exclude_keys = %w[InvoiceRemark ItemName ItemWord ItemRemark]
        params = params.reject do |k, _v|
          exclude_keys.include? k
        end

        # 轉成 query_string
        query_string = to_query_string(params)
        # 加上 HashKey 和 HashIV
        query_string = "HashKey=ejCk326UnaZWKisg&#{query_string}&HashIV=q9jcZX8Ib9LM8wYk"
        # 進行 url encode
        raw = urlencode_dot_net(query_string)
        # 套用 MD5 後轉大寫
        Digest::MD5.hexdigest(raw).upcase
      end

      def urlencode_dot_net(raw_data)
        # url encode 後轉小寫
        encoded_data = CGI.escape(raw_data).downcase
        # 調整成跟 ASP.NET 一樣的結果
        encoded_data.gsub!('%21', '!')
        encoded_data.gsub!('%2a', '*')
        encoded_data.gsub!('%28', '(')
        encoded_data.gsub!('%29', ')')
        encoded_data
      end

      def to_query_string(params)
        # 對小寫的 key 排序
        params = params.sort_by do |key, _val|
          key.downcase
        end

        # 組成 query_string
        params = params.map do |key, val|
          "#{key}=#{val}"
        end
        params.join('&')
      end

    end
  end
end
```

試試看結果如何：

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "InvoiceDate=2018-07-19 14:35:02&InvoiceNumber=FX30000137&RandomNumber=8833&RtnCode=1&RtnMsg=開立發票成功&CheckMacValue=D2AEB7BDE6F9ADA94831233A4D0FB2BC"
```

節錄重點：

```ruby
RtnMsg=開立發票成功
InvoiceNumber=FX30000137
```

發票開立成功了！而且我們獲得了發票號碼。

# 發票參數簡介

我把發票參數分為三類：

- 基本參數
- 商品參數
- 發票參數

### 基本參數
- TimeStamp：你的系統的目前時間，綠界會用來做 timeout 檢查
- MerchantID：商店代號，這是綠界發給你的參數
- RelateNumber：在你的電商系統上的訂單編號
- CustomerEmail：買家的mail，如果發票開立成功或中獎，這個信箱有可能會收到信
- TaxType：課稅類別，填 1 代表應稅，填 2 代表零稅率，填 3 代表免稅
- InvType：發票字軌類型，填 07 代表一般稅額， 填 08 代表特種稅額

### 商品參數
- SalesAmount：發票總金額
- ItemCount：商品數量，以 | 做為分隔符號
- ItemPrice：商品單價，以 | 做為分隔符號
- ItemAmount：商品小計，以 | 做為分隔符號
- ItemName：商品名稱，以 | 做為分隔符號
- ItemWord：商品單位，以 | 做為分隔符號

綠界會檢查商品小計的加總必須等於發票總金額

### 發票參數

#### 我要捐發票
如果你這張發票是要捐的，需要傳遞以下參數：

- Print：要列印這張發票嗎？填 0 代表不要，填 1 代表要
- Donation => 要捐嗎？填 0 代表不要，填 1 代表要
- LoveCode => 要捐給誰？填入愛心碼

其中 Print 傳 0，Donation 傳 1。

#### 我要印發票
如果你這張發票是要印的，需要傳遞以下參數：

- Print：1
- Donation：0
- CustomerName：客戶名稱
- CustomerAddr：客戶地址
- CustomerIdentifier：統一編號，此欄位為選填欄位

也就是說，如果你要印，就不能捐。如果你要打統編，就一定要印。即使你必須將客戶名稱跟地址傳給綠界，綠界還是不會幫你印發票寄給客戶。

所以當客戶選擇要印發票時，管理人員則必須要回到綠界電子發票後台去操作列印。

綠界電子發票列印頁網址：[https://vendor-stage.ecpay.com.tw/Einvoice/InvoicePrint](https://vendor-stage.ecpay.com.tw/Einvoice/InvoicePrint)

#### 我要存發票
如果你不捐，也不印，那麼你要找一個載具來儲存這張電子發票，載具相關參數如下：

- Print：0
- Donation：0
- CarruerType：載具類別，值可能為 1、2、3 其中之一
- CarruerNum：載具編碼

其中 CarruerType 的值的意義如下：

- 1：綠界科技電子發票載具
- 2：自然人憑證號碼
- 3：手機條碼

CarruerNum 的值會在 CarruerType 的值不同而改變其意義，特別的是當 CarruerType 為 1 時，CarruerNum 必須傳遞空字串。

# 微調程式碼

剛剛我們是使用測試資料來開發票，但真正要使用的時候，params 應該是要由外部傳入。

需要修改程式碼如下：

```ruby
def run
  create(@params)
end
```

再 parse 一下輸出：

```ruby
def create(params)
  params['CheckMacValue'] = compute_check_mac_value(params)
  uri = URI(url)
  # 送出 Post request 到綠界，並取得回應內容
  response = Net::HTTP.post_form(uri, params)
  body = response.body.force_encoding('UTF-8')
  CGI.parse(body).transform_values(&:first)
end
```

測試一下效果

```ruby
params = Ecpay::Invoice::CreateService.new.send(:sample_params)
Ecpay::Invoice::CreateService.new(params).run
 => {"InvoiceDate"=>"2018-07-19 17:11:18", "InvoiceNumber"=>"FX30000163", "RandomNumber"=>"5453", "RtnCode"=>"1", "RtnMsg"=>"開立發票成功", "CheckMacValue"=>"848B5BAF997E316617967BFC09079BA6"}
```

順利～
補充說明：在這邊我使用 `Ecpay::Invoice::CreateService.new.send(:sample_params)`，而不是寫 `Ecpay::Invoice::CreateService.new.sample_params` 是因為 `sample_params` 是 private 方法，不能直接從外部呼叫。

# 查詢發票明細

一樣，我們建立一個 Ecpay::Invoice::FindService，以下就直接來：

```ruby
require 'net/http'

module Ecpay
  module Invoice
    class FindService
      def initialize(relate_number)
        @relate_number = relate_number
      end

      def run
        find(build_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Query/Issue'
      end

      def build_params
        {
          'TimeStamp' => Time.current.to_i.to_s,
          'MerchantID' => '2000132',
          'RelateNumber' => @relate_number, # 訂單編號
        }
      end

      def find(params)
        params['CheckMacValue'] = compute_check_mac_value(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        body = response.body.force_encoding('UTF-8')
        CGI.parse(body).transform_values(&:first)
      end

      ...下略 compute_check_mac_value
      
    end
  end
end
```

其實只是修改網址跟換一下參數，查詢發票明細就完成了。現在讓我們來測試一下，測試流程如下：
- 產生測試參數
- 從參數中擷取出訂單編號 relate_number
- 使用參數開立一張發票
- 使用訂單編號做查詢

```ruby
params = Ecpay::Invoice::CreateService.new.send(:sample_params)
relate_number = params["RelateNumber"]
Ecpay::Invoice::CreateService.new(params).run
Ecpay::Invoice::FindService.new(relate_number).run
 => {"IIS_Award_Flag"=>"", "IIS_Award_Type"=>"", "IIS_Carruer_Num"=>"", "IIS_Carruer_Type"=>"", "IIS_Category"=>"B2C", "IIS_Check_Number"=>"", "IIS_Clearance_Mark"=>"", "IIS_Create_Date"=>"2018-07-19 17:14:46", "IIS_Customer_Addr"=>"", "IIS_Customer_Email"=>"service@5xruby.tw", "IIS_Customer_ID"=>"", "IIS_Customer_Name"=>"", "IIS_Customer_Phone"=>"", "IIS_Identifier"=>"0000000000", "IIS_Invalid_Status"=>"0", "IIS_IP"=>"118.163.124.163", "IIS_Issue_Status"=>"1", "IIS_Love_Code"=>"168001", "IIS_Mer_ID"=>"2000132", "IIS_Number"=>"FX30000167", "IIS_Print_Flag"=>"0", "IIS_Random_Number"=>"9234", "IIS_Relate_Number"=>"f633510627a2eddeea0c", "IIS_Remain_Allowance_Amt"=>"", "IIS_Sales_Amount"=>"1900", "IIS_Tax_Amount"=>"0", "IIS_Tax_Rate"=>"0.050", "IIS_Tax_Type"=>"1", "IIS_Turnkey_Status"=>"", "IIS_Type"=>"07", "IIS_Upload_Date"=>"", "IIS_Upload_Status"=>"0", "InvoiceRemark"=>"", "ItemAmount"=>"900|1000", "ItemCount"=>"3|2", "ItemName"=>"衣服|褲子", "ItemPrice"=>"300|500", "ItemRemark"=>"", "ItemTaxType"=>"", "ItemWord"=>"件|件", "PosBarCode"=>"10708FX300001679234", "QRCode_Left"=>"FX3000016710707199234000000000000076c0000000053538851KIjD/jYtIwQXOONltIuFzA==:**********:2:2:1:", "QRCode_Right"=>"**衣服:3:300:褲子:2:500","RtnCode"=>"1", "RtnMsg"=>"查詢發票成功", "CheckMacValue"=>"20F155F2A8CDB994B4EB7B949D98FD9E"}
```

查詢發票成功！值得一提的是發票號碼的 key 變成 `IIS_Number` 了呢～由於篇幅的關係，今天就講到這裡。

因為本次的教學其實根本沒講到 Rails，所以你們要自己實作自己的 Controller 和 Model，並且傳遞正確的參數進入 Service。記得如果想要使用正式環境，就要修改Url、HashKey、HashIV 那些東西哦～重構什麼的自己來齁～

對了，在綠界的測試環境裏只能使用綠界的測試帳號，所以你無法使用你自己註冊的綠界帳號去打綠界的測試環境。你問我「其實綠界有提供 SDK，為什麼你不用？」嗯... 這個不好說阿，但這是一個很棒的問題。

還有，我把程式碼都放在[github](https://github.com/etrex/ecpay_invoice_demo)上了，想要的話就拿去吧。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post-Rails 串接 Ecpay 電子發票，就是這麼簡單/cover

Rails 串接 Ecpay 電子發票，就是這麼簡單


# The ABC of Rails Engines

 > 本文內容主要參考自 http://guides.rubyonrails.org/engines.html

本文會以下列三個段落來介紹 Rails Engine 的基礎知識及用法

* Rails Engine 是什麼?
* 打造一個 Rails Engine
* 在主程式中使用 Rails Engine

## Rails Engine 是什麼？

Rails Engine 主要的目的是透過簡單易用的程式介面 (interface) 來提供主程式 (Host) 額外功能，筆者認為可以把主程式 (Host) 想像成原型機器人，Rails Engine 則可視為具有不同能力的裝甲，只要將具有特殊能力的裝甲，適當地裝備 (hook) 在原型機器人身上，就可以組裝出具有各式能力的裝甲機器人，而程式介面 (interface) 就是相同的裝甲可裝載在不同機器人上的關鍵，當然組裝不好時也會造成效能不佳或容易故障的問題，亦或是選用設計不佳的裝甲 (Rails Engine) 也可能影響原機體 (Host) 的正常運作。

由此可看得出來裝甲之裝載並非是絕對必要的，如果你的團隊有足夠的能力、時間及資源，當然可以將所需要的功能直接「內建」在原型機器人裡，所以裝甲的選用與團隊的現況有直接的關係。

雖然每個裝甲都有既定的能力，但這並非完全不能改動的，技術人員仍然可以依照實際的需求，調整強化 (override) 裝甲原本的行為，使得改良過後的裝甲更為適用，這是因為原型機器人 (Host) 的優先權高於機甲 (Rails Engine) 的關係。

這邊的原型機器人(Host/ a rails application) 是指透過 Rails 框架所建造出來的，而原型機器人基本上就是一個強化版本 (a supercharged engine)，因此 Rails applications 與 Rails Engines 且有很高的共通性，Rails engines 亦可看成是小型的應用程式 (miniature applications)。

## 打造一個 Rails Engine

要打造一個 Rails Engine 很簡單，只要透過 `rails plugin new` 指令就可以產生一個 engine 的雛形。 這邊要特別說明的是 Engines 與 Plugins 是很相似的，相同的是他們都有一個 `lib` 資料夾，也都是透過 `rails plugin new` 指所產生的，不同是當我們提及 engine 時，通常指的是一個完整的 plugin (full plugin)，需要在產生時傳入 `--full` 或 `--mountable` 參數。

指令如下:

* `rails plugin new YOUR_ENGINE_NAME --full` 或
* `rails plugin new YOUR_ENGINE_NAME --mountable`

下列比較表將以 **blorgh** 做為 engine name，主要以 `--full` 與 `--mountable` 參數所產生的 engines 為比較基準

|   |NO OPTION|`--full` | `--mountable` |
|---|--------|---------|---------------|
|app/ 資料夾|╳|〇|〇|
|bin/ 資料夾|〇|〇|〇|
|config/ 資料夾|╳|〇|〇|
|lib/ 資料夾|〇|〇|〇|
|test/ 資料夾|〇|〇|〇|
|config/<br>routes.rb|╳|Rails.application.routes.draw do<br>end|**Blorgh::Engine**.routes.draw do<br>end|
|lib/<br>blorgh/<br>engine.rb|╳|module Blorgh<br>&nbsp;&nbsp;class Engine < ::Rails::Engine<br>&nbsp;&nbsp;end<br>end|module Blorgh<br>&nbsp;&nbsp;class Engine < ::Rails::Engine<br>&nbsp;&nbsp;&nbsp;&nbsp;**isolate_namespace Blorgh**<br>&nbsp;&nbsp;end<br>end|
|app/<br>helpers/<br>**blorgh**/<br>application_helper.rb|╳|╳|module Blorgh<br>&nbsp;&nbsp;module ApplicationHelper<br>&nbsp;&nbsp;end<br>end|
|app/<br>views/<br>layouts/<br>**blorgh**/<br>application.html.erb|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application.js|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application.css|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application_controller.rb|╳|╳|module Blorgh<br>&nbsp;&nbsp;class ApplicationController < ActionController::Base<br>&nbsp;&nbsp;&nbsp;&nbsp;protect_from_forgery with: :exception<br>&nbsp;&nbsp;end<br>end|
|test/<br>dummy/<br>config/<br>routes.rb|Rails.application.routes.draw do<br>end|Rails.application.routes.draw do<br>end|Rails.application.routes.draw do<br>&nbsp;&nbsp;**mount Blorgh::Engine => "/blorgh"**<br>end|

### 實作即將開始
### 這個 Rails Engine (blorgh) 將提供主程式 (host) 一個基本的部落格功能:

* 文章列表
* 新增文章
* 編輯文章
* 刪除文章
* 留言評論

> 此範例取自 [Getting Started with Engines](http://guides.rubyonrails.org/engines.html)

> 請使用 Rails 5.1+ 版本

#### Step1. 產生一個 mountable 的 rails engine 雛形

```ruby
$ rails plugin new blorgh --mountable
```

Engine 產生成功後，請切換到 blorgh 根目錄，找到 blorgh/blorgh.gemspec 檔案，將含有 `TODO` 的資訊進行修改，不然在後續的步驟中會出現 `blorgh/blorgh.gemspec is not valid. Please fix this gemspec. (Gem::InvalidSpecificationException)
The validation error was '"FIXME" or "TODO" is not a description'` 的錯誤訊息。

```ruby
# blorgh/blorgh.gemspec
# 這邊只是用來說明用的範例，請依照實際情況填寫

Gem::Specification.new do |s|
  s.name        = "blorgh"
  s.version     = Blorgh::VERSION
  s.authors     = [""]
  s.email       = [""]
  # 修改前
  # s.homepage    = "TODO"
  s.homepage    = "http://example.com"

  # 修改前
  # s.summary     = "TODO: Summary of Blorgh."
  s.summary     = "Summary of Blorgh."

  # 修改前
  # s.description = "TODO: Description of Blorgh."
  s.description = "Description of Blorgh."
  s.license     = "MIT"

  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md"]

  s.add_dependency "rails", "~> 5.2.0"

  s.add_development_dependency "sqlite3"
end
```

#### Step2. 快速產出文章的 Scaffolding (CRUD)

```ruby
# engine 根目錄
$ bin/rails generate scaffold article title:string text:text
```

在 Engine 根目錄，輸入下列指令，執行 migration 以產生 blorgh_articles 資料表

```ruby
# engine 根目錄
$ bin/rails db:migrate
#=> 執行完畢會產生 blorgh_articles 資料表
```

請切換目錄到 `test/dummy` 底下，鍵入 `rails s` 啟動 rails server，在瀏覽器中輸入 http://localhost:3000/blorgh/articles 可看到具有CRUD功能的文章管理畫面，此時你應該已經可以新增、編輯、刪除文章，並在新增文章後可以看到文章列表。這邊的 test/dummy 其實是一個簡化版的 rails application，可讓我們在開發 engine 的時候用來測試之用，模擬日後 Engine 被掛入主程式的行為。

#### Step3. 指定 engine 首頁路徑

```ruby
# 在 config/routes.rb
Blorgh::Engine.routes.draw do
  resources :articles
  root to: "articles#index"
end
```

重啟 rails server 後，瀏覽 http://localhost:3000/blorgh 將會顯示文章列表頁面

#### Step4. 產生評論 (comments) 資源

```ruby
# engine 根目錄
$ bin/rails generate model Comment article_id:integer text:text

# engine 根目錄
$ bin/rails db:migrate

# => 達行完畢後會產生 blorgh_comments 資料表
# 這邊異動的是 test/dummy app
```

為了在文章下面顯示評論內容，需要在 app/views/blorgh/articles/show.html.erb 中的 `<%= link_to 'Edit'` 之前加上下列程式碼

```erb
<h3>Comments</h3>
<%= render @article.comments %>
```

由於一篇文章 (article) 可以有多則評論 (comments)，因此需要在 article model 中定義 `has_many :comments` 關聯

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ApplicationRecord
    has_many :comments
  end
end
```

#### Step5. 加入可新增評論的表單

為了要可以新增評論，我們需要一個表單，在 app/views/blorgh 目錄中建立一個 comments 資料夾，並建立一個 _form.html.erb 的檔案，表單的程式碼如下

```erb
<h3>New comment</h3>
<%= form_with(model: [@article, @article.comments.build], local: true) do |form| %>
  <p>
    <%= form.label :text %><br>
    <%= form.text_area :text %>
  </p>
  <%= form.submit %>
<% end %>
```

將表單放在文章評論 `<%= render @article.comments %>` 的下方，要修改的檔案是 app/views/blorgh/articles/show.html.erb

```erb
<%= render "blorgh/comments/form" %>
```

我們已經在 model 中定義了關聯，還需要定義對應文章-評論的巢狀路由 (Nested Resources)，在 config/routes.rb 中修改路由如下

```ruby
# config/routes.rb
Blorgh::Engine.routes.draw do
  resources :articles do
    resources :comments
  end

  root to: "articles#index"
end
```

有了 model，也有了路由，我們還需要對應新增 comment 所需的控制器 (controller)，可透過下列指令建立一個空的控制器

```ruby
# engine 根目錄
$ bin/rails g controller comments
```

找到剛產生的控制器檔案 app/controllers/blorgh/comments_controller.rb，定義 create 方法，這個方法用以對應新增評論表單中的 POST 請求，程式碼如下

```ruby
# app/controllers/blorgh/comments_controller.rb
def create
  @article = Article.find(params[:article_id])
  @comment = @article.comments.create(comment_params)
  flash[:notice] = "Comment has been created!"
  redirect_to articles_path
end

private
  def comment_params
    params.require(:comment).permit(:text)
  end
```

最後一步我們需要在 app/views/blorgh/comments/ 新增一個 _comment.html.erb 用做評論呈現的畫面，這個畫面對應的是先前加入  app/views/blorgh/articles/show.html.erb 中的 `<%= render @article.comments %>` 部份，畫面所需的程式碼如下，代表的是「一則評論」的樣子

```erb
<%= comment_counter + 1 %>. <%= comment.text %>
```

目前 app/views/blorgh/articles/show.html.erb 中的程式碼應如下所示

```erb
<p id="notice"><%= notice %></p>

<p>
  <strong>Title:</strong>
  <%= @article.title %>
</p>

<p>
  <strong>Text:</strong>
  <%= @article.text %>
</p>

<h3>Comments</h3>
<%= render @article.comments %>
<%= render "blorgh/comments/form" %>

<%= link_to 'Edit', edit_article_path(@article) %> |
<%= link_to 'Back', articles_path %>
```

現在再次瀏覽任一篇文章時，應該可以在下面看見一個表單，輸入評論後按下 Create Comment，就可以看到評論已經被新增並顯示在該文章的下方了。

完成上述的步驟便可以完成一個可提供發文與評論留言的簡單部落格 Rails Engine

## 在主程式中使用 Rails Engine

首先我們先用 Rails 建立一各新的 Rails application (unicorn)

```ruby
$ rails new unicorn
```

#### Step1. 安裝 Engine

在主程式中使用 Rails Engine 的方式很簡單，你應該也不會太陌生，只要找到主程式的 Gemfile 檔案並加入下列描述即可

```ruby
# 由於我們開發的 Rails Engine 是在本機中，因此要使用 path 指定所在路徑
gem 'blorgh', path: '../the-abc-of-rails-engines/blorgh'
```

接著記得下在主程式的根目錄下 `bundle install` 安裝我們的 engine

#### Step2. 掛載 Engine
然後我們還需要在主程式的 config/routes.rb 中將 engine 掛進來，如此主程式才可以存取 engine 中的路由

```ruby
# config/routes.rb
# at: "/可依個人需求喜好命名"
mount Blorgh::Engine, at: "/blog"
```

#### Step3. 複製 Engine 的 migration 檔案
此指令可重覆執行，不會有重複複製的副作用(用以匯入 Engine 的 migration 檔案)

```ruby
# 在主程式的根目錄
$ bin/rails blorgh:install:migrations

# 會出現下列訊息，檔案時戳會略有不同
# => Copied migration 20180719154413_create_blorgh_articles.blorgh.rb from blorgh
# => Copied migration 20180719154414_create_blorgh_comments.blorgh.rb from blorgh
```

#### Step4. DB migrate

```ruby
# 在主程式的根目錄執行 migrate
$ bin/rails db:migrate

# => 產生 blorgh_articles 與 blorgh_comments 資料表
```

現在在主程式的根目錄中使用 `rails s` 指令啟動伺服器，並瀏覽 http://localhost:3000/blog 應該可以看見文章頁面，你此時應該已經可以新增、刪除、修改文章，還可以在文章下方新增評論了。

*如果沒有要針對 Engine 的既有行為做調整，基本上到這邊就可以告一個段落了。*

接下來要討論是如何讓 Engine 使用主程式所定義的類別，而為了滿足這個需求，我們還需要調整 Engine 最初的設計，這邊希望達成的主要目的是希望可以為文章增加作者的資訊，而這個「作者」類別是具有彈性，將由主程式來進行定義，也就是說在這個調整之後，要使用這個 Engine 的主程式，一律需要告訴 Engine「作者」代表的是主程式中的哪一個類別。

*文章與評論由 Engine 負責定義，作者則交給「主程式」來定義*

#### Step5. 在 Engine 中提供可由主程式定義「作者」類別的方法

修改 lib/blorgh.rb 的 Blorgh module 中加入下列程式碼

```ruby
# blorgh/lib/blorgh.rb
module Blorgh
  # 此類別存取子將開放給主程式定義「作者」類別之用
  mattr_accessor :author_class

  # 覆寫原本的 author_class getter 方法，使回傳值為常數物件
  def self.author_class
    @@author_class.constantize
  end
end
```

#### Step6. Article 的作者

在 article (app/models/blorgh/article.rb) 定義與作者的關聯及參照來源

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ActiveRecord::Base
    # ... 略
    # 由於 Blorgh.author_class 會回傳常數物件，應轉型為字串
    belongs_to :author, class_name: Blorgh.author_class.to_s
    # ... 略
  end
end

```

#### Step7. 新增 author_id 到 article 中的 migration 檔案

```ruby
# engine 根目錄
$ bin/rails g migration add_author_id_to_blorgh_articles author_id:integer

# engine 根目錄
$ bin/rails db:migrate

# => 新增欄位 author_id 到 blorgh_articles 資料表
# 這邊異動的是 test/dummy app
```

#### Step8. 修改 article model 如下

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ActiveRecord::Base

    # 新增 author_name 欄位供暫時存取之用
    attr_accessor :author_name

    has_many :comments
    belongs_to :author, class_name: Blorgh.author_class.to_s

    # 透過這個 callback 建立/修改文章所對應的作者 (Blorgh.author_class)
    before_validation :set_author

    private

    def set_author
      self.author = Blorgh.author_class.find_or_create_by(name: author_name)
    end
  end
end

```

#### Step9. 新增作者名稱欄位
在 Engine 中的文章表單中 (app/views/blorgh/articles/_form.html.erb) 的 :title 欄位前新增作者名稱欄位

```erb
  <div class="field">
    <%= form.label :author_name %><br>
    <%= form.text_field :author_name %>
  </div>
```

#### Step10. 允許 :author_name 參數的傳遞
在 Engine 的 app/controllers/blorgh/articles_controller.rb 中的私有方法 article_params 允許 :author_name 參數欄位的傳入

```ruby
# app/controllers/blorgh/articles_controller.rb
  def article_params
    params.require(:article).permit(:title, :text, :author_name)
  end
```

#### Step11. 顯示作者資訊
於 Engine 的 views/blorgh/articles/show.html.erb 中，在 "Title" 的上方加入作者的資訊

```erb
<p>
  <b>Author:</b>
  <%= @article.author&.name %>
</p>
```

#### Step12. 用 test/dummy 來測試

```ruby
# blorgh/test/dummy
# 新增 User 類別
$ rails g model user name:string

# blorgh/test/dummy
# 執行 db:migrate
$ bin/rails db:migrate

# => 新增 users 資料表

```

#### Step13. 定義「作者」

在 test/dummy/config/initializers 中新增一個 blorgh.rb 的檔案，並加入下列程式碼指定「作者」的類別

```ruby
# 這邊一定要使用「字串型態」的類別名穩，不可直接類別物件來定義，不然 Rails 會試圖去載入該類別並參考與其對應的資料表，如果此資料表還不存在時，將會造成不必要的問題
Blorgh.author_class = "User"
```

一樣透過 `rails s` 啟動 rails server，打開瀏覽器瀏覽 [http://localhost:3000/blorgh](http://localhost:3000/blorgh)
現在新增文章時應該可同時加上作者資訊，成功新增後亦可顯示作者資訊，但若要正常地編輯作者資訊，則還需要調整一下 Engine 裡 articles_controller 中 edit 方法，完整程式碼請參閱[這邊](https://github.com/spartchou/the-abc-of-rails-engines-engine/tree/master/practice/blorgh)。

如果可以讓 test/dummy 運作正常，那麼在[主程式中只要實作 Step12 及 Step13](https://github.com/spartchou/the-abc-of-rails-engines-main-app)，就可以達到一樣的效果了。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>


post-The ABC of Rails Engines / cover

The ABC of Rails Engines


在與 Sketch 相遇後，已經回不去用其他軟體設計網頁的我 ( hen 誇張 )，前陣子從公司的大大那邊聽聞 Google 發表了一個叫做「 Material Theme Editor 」的工具，而它竟然是今年五月份才發表的東西！就讓我來為大家稍微介紹一下這個還熱騰騰的新玩意吧～

**▸ 簡單來說，「 Material Theme Editor 」是什麼？**

一言以蔽之，這是「讓你快速製作自家品牌的 Material Design 風格 Sketch 套件」。( 也太拗口 )
有接觸網頁、APP設計的設計師應該多少都有聽聞過 Material Design，它是 Google 在 2014 年 6 月的Google I/O 大會發表的 Google 獨創的設計準則，在那之後也影響了非常多介面設計在對於扁平化、紙張特性、轉場動畫等方面的思考方向，在四年後的今天，我們仍然可以隨處看到 Material Design 的深遠影響。
而在基於 Material Design 準則下出生的 Material Theme Editor ，他除了有豐富的 Material Design 元件庫，還能夠使用非常簡單且所見即所得的介面調整整體風格與色系！是不是讓人很心動呢？馬上來看看要怎麼使用吧！

**▸ 下載～安裝～打開～**

下載網址：https://material.io/tools/theme-editor
安裝套件後在工具列選取 Plugins > Material > Open Theme Editor 打開 Material Theme Editor

![Material Theme Editor-安裝](//images.ctfassets.net/8er52l3j5u76/Y0YxX6fqipPecMkoBXeL5/966bd85b7ce5c18a2012ca4b637e8896/UNEvTxW.png)

**▸ 主題選擇**

打開 Material Theme Editor 後可以看到 Sketch 內出現了一個黑黑的小視窗，裡面有「 Baseline 」( 基本設計 ) 、「 Crane 」( 旅遊 ) 、「 Fortnightly 」( 新聞 ) 、「 Shrine 」( 購物 ) 四種主題可選擇，除了最基礎的 Material Design 元件以外，也有針對各個不同類別產品所設計的元件庫。

![Material Theme Editor-主題選擇](//images.ctfassets.net/8er52l3j5u76/6QVX7C3E6db9N5HQKWX965/70084222f7d72c1e8ddbb80e863c1d22/vKN7lHa.png)

選擇了任一主題後，可以看到有五個內建的頁面，分別是 Cover 、 Getting Started 、 Material Theme 、 Material Components 、 Symbols ， 其中 Material Theme 是主要範例介面的展示， Material Components 是所有元件的列表， Symbols 就是所有元件庫。

![Material Theme Editor-頁面](//images.ctfassets.net/8er52l3j5u76/57PrrEGHXnBeg4eWwZ1BAf/726a8aa77741e16318b55d547c48e02e/LFPa3WW.png)

**▸ 四大功能**

功能一：調色盤
在這個操控介面上，我們可以任意改變「主要」、「強調」、「背景」這三個顏色，點入任一色塊後，我們可以從 Custom 裡面任意選擇我們要的顏色，也可以從 Material 裡面 Material Design 提供的色盤去選取，選取顏色後會自動產生 Primary ( 主要 ) 、 Light ( 較亮 ) 、 Dark ( 較暗 ) 三種顏色。

![Material Theme Editor-調色盤](//images.ctfassets.net/8er52l3j5u76/23WZGxFbuK35Gwj9Dpnwel/85d23c3a7206fed6e9c007787a278dd3/AKgj2mX.png)

選好顏色以後，這些顏色就會套用在元件上各個對應的色彩設定，完全不需要再像以前一樣要一個個手動調整，是否很方便呢！

功能二：字型設定
在這個功能可以設定預設的字型，並可以對不同的標題字階層設定不同的粗細，但無法修改字體的大小。

![Material Theme Editor-字型設定](//images.ctfassets.net/8er52l3j5u76/ZbllVBWeJkacyLgFpRWHq/e314afc3458837354548c1b302bd9a47/2GlqOaF.png)

功能三：形狀設定
形狀設定中有「Curved」和「Angied」兩種模式， Curved 會是平滑的圓角，而 Angied 則會是切角的效果。

Curved
![Material Theme Editor-Curved](//images.ctfassets.net/8er52l3j5u76/75chekq5aOTUE6DTw5UPBE/78cff92c42347849ed53f2f406343515/XxHCO5z.png)

Angied
![Material Theme Editor-Angied](//images.ctfassets.net/8er52l3j5u76/4Vj7QqrmaRegbT7mYIWq54/7f24ae89bf54e7763137ff0d7b33d2b5/aRJqdTB.png)

功能四：Icon 設定
在這裡提供了五種不同風格的 Icon ，點選以後可以前往下載，下載以後是一套包含 16 種分類、超過上千種的 Icon，各種想得到想不到的 Icon 都有，非常方便！

![Material Theme Editor-Icon 設定](//images.ctfassets.net/8er52l3j5u76/4uyeZNP8VHnYprzKRpGGoC/a3f9dfbe5ed6d978373cf9a7500a2e67/GiPD3qK.png)

**▸ 最後**

附上官方的介紹影片，希望這篇介紹文能對大家有所幫助！

[https://www.youtube.com/watch?v=BLrgDgd_1c0](https://www.youtube.com/watch?v=BLrgDgd_1c0)


post-Material Design 新利器：Material Theme Editor / cover

Material Design 新利器：Material Theme Editor


之前曾經寫過一篇我們公司專案使用敏捷開發的案例，當時我們在預期的時間讓 MVP 的產品能夠上線，讓敏捷開發的價值得底被證明。不過這一次我想從另一個同樣是跑敏捷開發卻跑的不盡理想的專案中，重新探究敏捷開發的價值。

專案的背景是與國外企業的 RD 部門將部分的產品委外給我們開發，產品的規劃、設計由他們主導，我們只要負責好開發的部分，聽起來是非常單純的委外開發。但短短的半年期間，雙方經歷過多次的調整，才終於催生出產品進到使用者測試的階段。

### 溝通的高牆

敏捷開發宣言裡提到：個人與互動重於流程與工具

在最剛開始接下這專案時，負責管理我們的是客戶公司（以下簡稱Ａ社）的 Tech Lead 以及負責這個產品的 Product Manager、Product Owner，我們與其他 RD 的溝通幾乎是零。

我們走我們的 Scrum，他們走他們的 Scrum，只有 Tech Lead 和 PM 知道雙方在做什麼。
這樣延伸出來的主要問題是功能開發的速度會變的緩慢。

在一個有打算做跨部門的組織裡，要讓這件事情得以實現，我想還是需要讓對於同一功能再進行開發的相關人員有能夠溝通的管道，不然的話兩個團隊各做各的狀況其實還是一種 waterfall 的流程，只是裝上了敏捷開發流程的殼。

當時為了解決這個問題，Ａ社的新 CTO 在剛上任時找了我們幾位同事到他們公司一起共事幾天，和他們一起每日站立會議，確實與他們的工程師面對面的溝通時，許多之前需要等待很長時間回應的狀況就馬上等到解決，但由於我們終究不是駐點的團隊，這一次的面對面溝通只是暫時化解當時正在開發功能上的一些問題，並沒有真正解決之前溝通的高牆。

### 小小的調整，讓問題提早被發現

舉例來說我們當時遇到的狀況是開發功能的流程是固定的，功能設計與圖完稿後才會進到功能開發，我們沒有機會可以對設計圖上問題提出改善建議，必須要照圖開發，直到一個不正確的功能被開發完成後再重新由 Product Manager 開新需求進行調整，理想上這雖然是一個完整程序，但開發者及設計師就會面臨一種時常在打掉重練的挫敗感，對產品而言則是不停地在累積技術債。

![post-從失敗案例重新思考敏捷開發價值](//images.ctfassets.net/8er52l3j5u76/YZvwV2YPJmVMCYRNUDTjy/8d065402c363e2c7ede151388dcf0271/WSH7bjP.png)

後來，針對上面提到的情境我們做了一點溝通上的調整，使得一些邏輯面上的問題在交付給客戶之前就能得到解決，雖然說交付給客戶之後，有一定的機率客戶會要求修改或調整功能，但至少工程師們在開發過程中就發現的邏輯問題能夠在交付給客戶前就得到討論，減少一些未來開發上所累積的技術債。

![post-從失敗案例重新思考敏捷開發價值](//images.ctfassets.net/8er52l3j5u76/TNL6tqgGxTEmwTxMyxbkS/706a5061943dc3457d92b492cd8b6cef/nkTtpPC.png)

### 不再只有單一對話窗口，多團隊看板開發

除了剛才提到一點流程上的改變，在我們回國後，CTO 下了一個決策，我們從一開始的 Scrum 換成了 Kanban 的管理方式。
過去不同團隊做的事情如果會相互影響到，很難在各自的站立會議中發現，因此非常倚賴 Tech Lead 來同步溝通個團隊的狀況，導致開發速度一直都很緩慢，大家都互相的等來等去，而且還不知道到底等的是誰。

改成看板開發後，以這家公司規模（工程師在20位以內）還可以在同一時間一起開會，主要由 CTO 擔任會議主持人瀏覽看板，因為不同部門的正在負責的票都在同一個看板上，Ａ團隊的票被 B 團隊影響著的狀態就能夠在看板上一目瞭然。

解決了之前不同團隊對於進度瞭解上的高牆。

### 持續堅持站立會議

站立會議是大家耳熟能詳在 Scrum（敏捷軟體開發過程）中的一部份。

在專案的這段時間內，不論有沒有和客戶那邊一起站立會議，我們自己這邊則是一直都有進行著，我想除了同步彼此的進度狀況，發現專案的問題、進度的問題、技術的問題之外，我另外有個心得是覺得站立會議同時還是一個建立團隊默契及感情滿重要的會議。

這個專案中有過幾次工程師上的人力調整，除了全職的工程師外也有一些 Remote 工程師在我們的團隊當中，透過每日的站立會議，讓新進的工程師或是無法常常面對面對話的  Remote 工程師們都有一段時間和其他團隊成員對話、溝通，能夠幫助他們更快地融入團隊中，這點是我覺得站立會議在敏捷開發中的另一個價值。

在這專案中，客戶有客戶團隊自己的開發腳步，站在外包團隊的角度正好可以觀察到這些事情，更加讓我體會到敏捷開發絕對不是單單只有那些原則、圖表和方法，還會牽扯到組織的文化及管理。我想要做到資深的管理者（或說 Scrum Master）需要有效且精準地找出組織問題的癥結點並加以改善，才能夠讓敏捷開發一直保有他敏捷的優勢，而不是只是流於形式。

post-從失敗案例重新思考敏捷開發價值/cover

從失敗案例重新思考敏捷開發價值


## Multi-tenant 應用程式：讓人又愛又恨的 Apartment

隨著現在個人化網站的興起，許多網路服務都提供使用者自訂網站的功能。這些功能涵蓋許多面向，包含論壇、部落格與網路個人商店等。典型的自訂網站例子如 Wix 與 Weebly，個人商店則如 Shopmatic 與 Shopify 等等。在這些服務中，使用者可以在某些限度下自定網站的內容，建立屬於自己的資料，而不會與其他使用這個服務的使用者衝突。換句話說，不同的使用者使用同一個服務，但他們的資料卻是各自分離的，這便是最基本的 multi-tenant 的精神。由於以 multi-tenant 風格的網站建立越來越熱門，因此在各大網站開發框架上都有提供相關的開發工具可用。今天要跟各位讀者分享的，便是最常被用在 Rails 應用程式中的 multi-tenant 工具：`apartment`。

此篇文章中會大致介紹 `apartment` 這個套件如何使用，以及帶讀者建立一個簡單的 multi-tenant 部落格示範網站，並且提出一些使用 `apartment` 可能會遇到的問題。

## `apartment` 是什麼

`apartment`（[Github repo](https://github.com/influitive/apartment)）是 Ruby/Rails 圈最常用來製作 multi-tenant 的 gem。如同其英文「公寓」，`apartment` 可以讓我們蓋出公寓般的資料庫結構，每一戶的格局相同但卻都是獨立運行，互不影響。我們通常會把一戶單獨的使用者稱為一個「tenant」，也就是（公寓）的承租人。`apartment` 最大的特色是與 Rails 的 ActiveRecord 做了相當緊密的結合，使用者可以在指定了特定的 tenant 後，直接使用自己所熟悉的 ActiveRecord ORM（如部落格網站中取得所有文章的 ORM: `Article.all`，來取得只屬於自己 tenant 的資料），而不需要明確的加上 `where` 篩選條件（也就是不必用 `Article.where(tenant_id: 1)` 明確篩選自己的 `tenant_id`）。因為有著如此便利的特性，使得 `apartment` 經常被用來快速開發 multi-tenant 網站的原型。

底層資料庫的支援部分，`apartment` 最早先是以 PostgreSQL 為主要支援的資料庫，主要原因是因為 PostgreSQL 有「schema」的特性可以使用。`apartment` 會替每一個不同 tenant 各自開一個 schema，已達到資料隔離的功能。

後來版本的 `apartmemt` 也逐漸支援如 MySQL 等資料庫系統。不過基於穩定性與功能性因素，仍然建議大家使用 PostgreSQL 作為 `apartment` 底層的資料庫系統。因此，以下的情境都會假設使用者使用的資料庫是 PostgreSQL。

## `apartment` 的基本應用與例子

為了讓大家了解更近一步了解 multi-tenant 的應用程式運作，在這個章節中會帶讀者一步一步建立一個 multi-tenant 的部落格網站。以下環境是基於 `ruby 2.4.1` 與 `rails 5.1.4`

> **附註**：這個範例因為夠簡單，即使不需要使用 `apartment`，也可以輕易透過傳統的 `where` 條件來實作。`apartment` 帶來的好處在當網站中的 model 數量夠多時才會比較明顯（也比較讓人願意使用 `apartment`），但這裡基於示範的目的而刻意在這個迷你專案中使用 `apartment`。

首先我們先來定義一下這個迷你專案的功能。我們會製作一個具有登入功能的部落格網站，每一個使用者登入之後都可以對屬於自己的文章進行 CRUD （Create, Read, Update, Delete）操作，且無法干涉其他使用者的資料。

資料庫結構的部分如下圖，我們只會有兩個 model，分別是 `User` 與 `Article`。`User` 是存放登入用的使用者，同時也是文章的擁有者。使用者登入系統的部分我們會直接使用 `devise`（[Github repo](https://github.com/plataformatec/devise)）這一個套件來建立。至於 `Article` 則是每個使用者自己的文章，這個 model 會直接透過 Rails 的 Scaffold 功能直接建立。

在這個架構中，我們希望 `Article` 是每個使用者各自分開的，讓他們不能互相干擾。而 `User` 則是不根據 tenant 分開，因為這個 model 是給 `devise` 登入系統使用，因此是所有 tenant 之間共用的（稱為 `public` schema）。

大部分的欄位相信讀者都不陌生，幾個值得注意的是：`User` 有個特殊的欄位稱為 `tenant_name`，這是用來區別這一個使用者的 tenant，讓 `apartment` 知道該去哪一個 PostgreSQL schema 存取資料。至於存放在各 schema 中的表得（如 `Article`）則不需要傳統的 `user_id` 之類的欄位來記錄該文章屬於哪一個使用者。

![資料庫結構圖](https://i.imgur.com/1P7WJYc.png)

### 第一階段：建立沒有 multi-tenant 功能的一般專案

我們先由建立一個沒有 multi-tenant 功能的專案開始，先確保我們需要的每個零件都有正常運作。之後再來加入 `apartment` 來實現 multi-tenant 功能。

- 建立新專案

```text
rails new apartment-demo
```

- 修改 `Gemfile`，加入要用到的 gem，並且將資料庫 gem 改為 `pg`，並執行 `bundle`

```ruby
gem 'devise'
gem 'apartment'
gem 'pg'
# gem 'sqlite3' # 註解掉原本的 sqlite3
```

- 修改 `database.yml`，改為使用 PostgreSQL

```yml
default: &default
  adapter: postgresql
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  timeout: 5000

development:
  <<: *default
  database: apartment-demo-dev

test:
  <<: *default
  database: apartment-demo-test

production:
  <<: *default
  database: apartment-demo-production
```

- 建立資料庫

```text
rake db:create
```

- 初始化 `devise`，並產生 devise views

```text
rails g devise:install
rails g devise:views
```

- 修改 `application.html.erb`，新增登入登出的連結

<script src="https://gist.github.com/lctseng/a26520daa61946ca5d15fed9fdbca8de.js"></script>

- 使用 `devise` 建立 `User` model，並加入 tenant_name 的欄位，同時也產生 controllers 供未來修改使用

```text
rails g devise user tenant_name:string
rails g devise:controllers users -c=registrations
```

- 修改產生的 migration file，記得將 `tenant_name` 設定為 `null: false` 並加入 unique index

```ruby
class DeviseCreateUsers < ActiveRecord::Migration[5.1]
  def change
    create_table :users do |t|
      ## Database authenticatable
      t.string :email,              null: false, default: ""
      t.string :encrypted_password, null: false, default: ""

      ## Recoverable
      t.string   :reset_password_token
      t.datetime :reset_password_sent_at

      ## Rememberable
      t.datetime :remember_created_at

      ## Trackable
      t.integer  :sign_in_count, default: 0, null: false
      t.datetime :current_sign_in_at
      t.datetime :last_sign_in_at
      t.inet     :current_sign_in_ip
      t.inet     :last_sign_in_ip

      t.string :tenant_name, null: false

      t.timestamps null: false
    end

    add_index :users, :email,                unique: true
    add_index :users, :reset_password_token, unique: true

    add_index :users, :tenant_name, unique: true
  end
end
```

- 修改 `app/views/devise/registrations/new.html.erb`，新增欄位讓我們可以填寫 `tenant_name`

<script src="https://gist.github.com/lctseng/eb1664442c6ff06a12a525e50899d491.js"></script>

- 修改 `routes.rb`，讓 `devise` 使用我們自訂的 controllers

```ruby
devise_for :users, controllers: {
  registrations: 'users/registrations'
}
```

- 修改 `app/controllers/users/registrations_controller.rb`，使得我們可以更新 `tenant_name` 這個欄位

```ruby
class Users::RegistrationsController < Devise::RegistrationsController
  before_action :configure_sign_up_params, only: [:create]
  def configure_sign_up_params
    devise_parameter_sanitizer.permit(:sign_up, keys: [:tenant_name])
  end
end
```

- 建立 `Article` 的 Scaffold。注意我們並不需要 `user_id` 欄位。

```text
rails g scaffold article title:string content:text
```

- 在產生的 `app/controllers/articles_controller.rb` 上方加入權限控制

```ruby
before_action :authenticate_user!
```

- 執行 DB migrate，此時可能會看到 `apartment` 噴出的一些警告，目前可以暫時忽略

```text
rake db:migrate
```

- 設定 `routes.rb`，將網頁的首頁指向文章列表

```ruby
root to: 'articles#index'
```

到目前為止，讀者可以啟動 `rails server`，檢視 `devise` 與 Scaffold 是否可以正常運作。這邊我們先註冊兩個使用者 Alice 與 Bob，其 `tenant_name` 分別設置為 `alice` 與 `bob`。此時雖然有使用者驗證，但你會發現此時的 `Article` 並沒有根據使用者做區別，所有人的文章都混在一起。

### 第二階段：使用 `apartment` 將不同 tenant 的資料區隔開

有了基礎專案之後，接下來就是進行 `apartment` 相關的修改，使得不同使用者之間的資料完全區隔。

- 建立 `apartment` 設定檔：`config/initializers/apartment.rb`，並修改內容：

```ruby
Apartment.configure do |config|
  # 因為 Devise 登入只能放在同一個 schema，因此將之從 apartment 排除
  config.excluded_models = ["User"]
  # 告知 apartment 如何找出所有的 tenant_name 供 migration 使用，這裡我們使用 User model 同名的欄位 tenant_name
  config.tenant_names = lambda{ User.pluck(:tenant_name) }
end
```

- 手動替 `alice` 與 `bob` 建立各自的資料庫 schema。由於前一階段並沒有替這兩個 tenant 建立 schema，因此這邊透過   `rails console` 手動建立

```ruby
Apartment::Tenant.create('alice')
Apartment::Tenant.create('bob')
```

- 讓未來新註冊的使用者可以自動建立 schema，修改 `app/controllers/users/registrations_controller.rb`

```ruby
class Users::RegistrationsController < Devise::RegistrationsController
  def create
    super do |user|
      # 這個 block 將在使用者被建立後執行，因此我們可以從這裡取出 tenant_name 來建立 schema
      Apartment::Tenant.create(user.tenant_name)
    end
  end
end
```

- 修改`app/controllers/articles_controller.rb`，限制所有的資料都只能在當前登入的 tenant schema 底下操作（也就是資料隔離）

```ruby
class ArticlesController < ApplicationController
  # 注意這幾個 before_action 的順序
  before_action :authenticate_user! # 設定 devise 時加入的
  before_action :switch_tenant # 新加入
  before_action :set_article, only: [:show, :edit, :update, :destroy] # scaffold 產生的

  # 這個 before_action 將會根據當前的使用者切換至該使用者的 schema
  def switch_tenant
    Apartment::Tenant.switch! current_user.tenant_name
  end
end
```

完成了！沒錯，就這麼簡單。重新啟動 rails server 後，你會發現現在 alice 與 bob 所建立的 `Article` 已經完全隔離了。不但不會在列表中看到別人的文章，就算透過 `/articles/1` 這樣的路徑，也只能看到自己名下編號為1的文章而已，沒辦法看到其他使用者的。此時你如果建立第三個使用者 Carol，其 `tenant_name` 為 `carol`，你也會發現這個新建立的使用者完全與其他人資料隔離。

本範例專案的原始碼也可以在 [Github](https://github.com/lctseng/rails-apartment-demo) 上找到。

## 使用 `apartment` 可能會遭遇到的問題

從上面的專案中我們可以看到使用 `apartment` 建立 multi-tenant 應用程式是多麼容易的事情。那為什麼這篇文章的標題卻又說「又愛又恨」呢？原因是 `apartment` 天生設計上就有一個缺陷，那就是當 tenant 數量成長到一定程度時，會出現許多預想不到的副作用。

最簡單的例子就是 Database Migration。因為 `apartment` 把資料完全隔離，所以在進行 migration 時各個 schema 會別處理。因此，當你使用的 schema 數量越來越大時，最首先感覺到的變化就是進行 migration 的時間會拉長。

另一個問題是記憶體消耗與程式啟動時間。由於在 `rails 4.2.2` 之前版本的架構中，會在啟動時根據資料庫 schema 中的表格逐個建立一份對應的資料存在記憶體中。這是個相當消耗時間與記憶體的動作。這個問題在 `apartment` 的 Github repo 中有給予一個 [patch 後的 rails 版本](https://github.com/influitive/apartment#excessive-memory-issues-on-activerecord-4x)，可以稍微舒緩記憶體壓力。

最後一個問題是硬碟空間。在某些檔案系統中，單一磁區所能儲存的檔案數是有上限的。因此如果 schema 總數太高，會造成 PostgreSQL 建立過多的檔案導致碰撞到這個上限。雖然這個問題解法比較多元，且不同檔案系統對檔案數上限也不同，因此也不一定會被讀者的專案所遇到。但如果今天萬一遇到了，不像前面幾個問題可以透過升級記憶體或者等待更長時間來解決，而是必須進行立即的資料搬移。我們都知道資料搬移是一個相當繁重的過程，且過程中可能需要讓服務停機，其損失不可估計。

## 實際案例

筆者近期經手的專案就一次碰到了以上三個問題。曾經有一個 `apartment` 專案使用了超過十萬個 schema，除了 migration 幾乎快要一整天以外，每次啟動 server 或 console 都要花費十幾分鐘的時間，且 server 記憶體動輒就消耗到 10GB。最嚴重的是這個專案還曾經在 production 營運時撞到了檔案系統的檔案數上限，導致服務差點就要凍結。

最後，在筆者與該專案開發團隊的努力下，成功找出一勞永逸的方案，並僅花四小時的停機時間進行資料轉換與搬移。詳細過程與解決方案，筆者將會在今年四月底舉辦的 [Ruby X Elixir Conf Taiwan 2018](https://2018.rubyconf.tw/program#liang-chi-tseng) 中分享這些細節，歡迎各位讀者共襄盛舉！

---

原文刊載於 [Henry Tseng's Digital Space](https://lctseng.github.io/post/multi-tenant-apartment/)

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post-Multi-tenant 應用程式：讓人又愛又恨的 Apartment/cover

Multi-tenant 應用程式：讓人又愛又恨的 Apartment

圖片上傳是一個在網路上隨處可見的功能，但是要做起來還真多細節在裡頭。

比方說：

客戶：「那可以預覽圖片嗎？」
客戶：「可以在上傳之前弄個裁切嗎？」
客戶：「可以一次上傳多張圖嗎？」
客戶：「可以拖曳上傳嗎？」

老闆：「加點要等哦～」

## 圖片上傳
圖片上傳可以使用套件來完成，我會推薦使用 [carrierwave](https://github.com/carrierwaveuploader/carrierwave)。

細節就跳過不講，總之我會先用產生器來生成一個 uploader。

```ruby
rails g uploader normal
```

會生成這樣的檔案：

```ruby
class NormalUploader < CarrierWave::Uploader::Base

  storage :file

  def store_dir
    "uploads/#{model.class.to_s.underscore}/#{mounted_as}/#{model.id}"
  end
end
```

store_dir 說明了圖檔會被存在哪個資料夾。在一個正常的開發環境下，上傳圖片成功後，你可以在 `/public` 資料夾下找到 uploads 資料夾。

以上傳使用者大頭照來說，我會在 User 上指定透過 image 這個欄位來儲存圖片路徑：

```ruby
class User < ApplicationRecord
  mount_uploader :image, NormalUploader
end
```

對應的 form 欄位大概是長這樣：

```ruby
<%= form_for(user) do |f| %>

...略

  <div class="field">
    <%= f.label : %>
    <%= f.file_field :image, id: 'add_image' %>
  </div>

...略

<% end %>
```

只要 image 的值是一個檔案或是一個網址，carrierwave 就會幫我們把圖存進指定的資料夾中。

## 圖片預覽

在古代，圖片預覽是不可能辦到的事，而現代大概有兩種做法：

### 透過 server

當用戶選擇一個圖檔後，先透過 ajax 上傳圖片到 server，而 server 將圖片儲存後，回傳圖片網址以及圖片 id，瀏覽器端使用 `<img src="圖片網址"/>` 來達成圖片預覽。

### 透過 base64

當用戶選擇一個圖檔後，透過 FileReader.readAsDataURL 獲得 base64 格式的檔案內容，使用 img ，在 src 填入 base64 字串，達成圖片預覽。 

透過 server 的好處是，實際上圖片早已存在 server 上，這表示在最終表單送出時，用戶就不需要等待圖片上傳了。

但是相對的，透過 server 的缺點是也許用戶上傳圖片後基於某些原因（也許是停電），他無法填完表單，這將導致 server 上將會存在一些被人們遺忘的圖片，而這些圖片需要定期清理。

透過 base64 達成圖片預覽的話，就比較簡單了。

透過 server 的做法應該很容易就能查到，我就不介紹了。

透過 base64 達成圖片預覽的寫法是這樣的：

```javascript
function file_to_base64(file, callback){
  var reader = new FileReader();
  reader.onload = function (e){
    callback(e.target.result);
  }
  reader.readAsDataURL(file);
}
```

這是一個丟入檔案進去會回傳 base64 格式回來的函數。

```javascript
$("#add_image").change(function(e){
  file_to_base64(e.target.files[0],function(base64){
    $("#preview").attr("src", base64);
  });
});
```

我們在當用戶上傳一張圖片後，將圖檔 `e.target.files[0]` 傳入 `file_to_base64`，獲得對應的 base64 字串後放進 img 就完成了，是不是很簡單呢？

## 圖片裁切

圖片裁切也有兩種做法，透過 server 以及透過 base64。

### 透過 server
當用戶選擇一個圖檔後，先做預覽圖片，然後在畫面上顯示一個裁切區域提供給用戶標記裁切位置，當用戶裁切完成時，將裁切座標儲存至 hidden field 並且透過 css 將預覽圖調整成裁切後的樣子。
在送出表單後圖片將會傳回 server，由 server 進行圖片裁切，通常這會是點陣圖檔的操作。

### 透過 base64
當用戶選擇一個圖檔後，先做預覽圖片，然後在畫面上顯示一個裁切區域提供給用戶標記裁切位置，當用戶裁切完成時，透過 canvas 進行裁切並取得對應的 base64 內容，將 base64 儲存至 hidden field 並將預覽圖的 src 值替換掉。
在送出表單後代表圖片的 base64 將會傳回 server，由 server 將 base64 轉存成圖片。

不管採用哪個做法，我們都需要使用裁切套件來協助我們取得裁切座標，我們這裡示範使用的套件是 [cropper](https://fengyuanchen.github.io/cropper/)。

### cropper 介紹

cropper 官方示範的裁切介面如圖中的左側區塊：

![裁切介面](//images.ctfassets.net/8er52l3j5u76/5II94lEUzICQHnqSEwD7bJ/4ac255300f3f42c9a26092b10933461d/2018-03-05_19.05.12.png)

他的用法也很簡單：

```javascript
$("img").cropper();
```

這樣寫就可以將一個 image 區塊變成一個裁切介面。

如果我們是這樣寫的話：

```javascript
$("#add_image").change(function(e){
  file_to_base64(e.target.files[0],function(base64){
    $("#preview").attr("src", base64).cropper();
  });
});
```

就會在上傳圖片後立即看到裁切介面。

然而我們不只需要一個裁切介面，我們可以做成點擊預覽圖後跳出一個裁切介面，並且包含一個`好哦～`按鈕，當按下`好哦～`時，將裁切介面關閉，並且把裁切數據保留。

我們可以把這樣的工作做成一個函數，讓我們傳入預覽圖片的 base64 值，並且在指定位置下生成裁切區域，在裁切之後將裁切資訊以 callback 傳回。

```javascript
var crop_zone_html = `<div class="crop_zone">
  <img />
  <button class="ok" data-turbolinks="false">好哦～</button>
</div>`;

function crop_for_base64(base64, container, callback){
  var crop_zone = $(crop_zone_html);
  var cropping_img = crop_zone.find("img");
  cropping_img.attr("src", base64).cropper();
  container.append(crop_zone);
  crop_zone.find(".ok").click(function(){
    var base64 = $(cropping_img).cropper('getCroppedCanvas').toDataURL('image/png');
    var cropbox = $(cropping_img).cropper('getCropBoxData');
    callback({base64:base64, cropbox:cropbox});
    $(this).parent().remove();
  });
}
```

我們使用一個樣板字串 `crop_zone_html` 去做出裁切區域，裡面包含一個 img 和一個按鈕。

把 base64 值傳入後，設定到空的 image tag 上再呼叫 `cropper()`，裁切區域就完成了。

當 OK 按鈕被按下後，我們就從 cropper 中擷取對應的 base64 值傳回給 callback，並結束裁切介面。

以下是使用情境：

```javascript
$("#add_image").change(function(e){
  file_to_base64(e.target.files[0],function(base64){
    $("#preview").attr("src", base64).click(function(){
      var preview_img = $(this);
      crop_for_base64(base64, $("#for_cropper"), function(crop_data){
        preview_img.attr("src", crop_data.base64);
      });
    });
  });
});
```

我們在點擊預覽圖片後會去呼叫前面寫好的 crop_for_base64 函數。在每次裁切後會將 base64 設定回預覽圖，結果當然是完美的。剩下來的問題就是如何將結果傳回 server。

那麼以下將示範如何將 base64 傳回並且串接到 carrierwave。

### 透過 base64 裁切
#### 上傳 base64

當我們選擇將 base64 的圖檔傳回 server 時，我們就已經不再需要原本的 file field 了。所以我們可以改成用一個 hidden field 去保存 base64。

model：

```ruby
attr_accessor :base64_image
```

form：

```ruby
<%= f.hidden_field :base64_picture, id:"base64_image_field" %>
```

js：

```javascript
$("#add_image").change(function(e){
  file_to_base64(e.target.files[0],function(base64){
    $("#base64_image_field").val(base64);
    $("#preview").attr("src", base64).click(function(){
      var preview_img = $(this);
      crop_for_base64(base64, $("#for_cropper"), function(crop_data){
        $("#base64_image_field").val(crop_data.base64);
        preview_img.attr("src", crop_data.base64);
      });
    });
  });
});
```

這樣 base64 就會存在 hidden field 裡，前端的部分這樣就完成了，接下來是在後端收到 base64 後該如何串接 carrierwave 的問題。

#### base64 與 carrierwave 串接

簡單的想法是 carrierwave 可以接受檔案的格式，所以我們應該先將圖片存成檔案，再傳給 carrierwave。不過，我們可能不想因為存個檔就產生一個暫存檔。如果他可以只存在記憶體，不產生實體檔案，那就更理想了。

直接使用 StringIO 是個不錯的想法，不過我決定要繼承 StringIO。

目標程式：

```
image = Base64ImageStringIO.new(base64_image)
```

希望經過一個轉換後將 base64 轉換為 StringIO 的樣子讓 carrierwave 能夠進行存檔工作。

完整的 Base64ImageStringIO 的寫法如下：

```
class Base64ImageStringIO < StringIO
  REGEXP = /\Adata:([-\w]+\/[-\w\+\.]+)?;base64,(.*)/m

  def initialize(base64_image)
    @extension = '.png'
    super(base64_to_binary(base64_image))
  end
  def original_filename
    @original_filename ||= "#{SecureRandom.uuid}.#{@extension}"
  end

  def base64_to_binary(base64_image)
    data_uri_parts = base64_image.match(REGEXP)
    return nil if data_uri_parts.nil?
    @extension = MIME::Types[data_uri_parts[1]].first.preferred_extension
    Base64.decode64(data_uri_parts[2])
  end
end
```

在建構時，先假設所有圖片都是 png，並且將 base64 轉換為 binary 再丟給 StringIO 的建構式。

關於檔名的部分，程式會隨機生成一個檔案名稱，並且確保副檔名binary 中的內容相同。carrierwave 會自動抓取 original_filename 的值做為檔案名稱。

這就是完整的圖片裁切流程。

如果是上傳多張圖片再加上裁切，同時還要考慮更新資料時舊圖片跟新圖片的處理，那情況就更複雜了，不過跟透過 server 裁切的方法比起來，我覺得還是各有利弊啦。

### 透過 server 裁切

如果是透過 server 裁切的話，前端就要將 cropbox 資訊透過 hidden field 傳到後端。

可以讓 carrierwave 幫我們做點事：

```
class CropUploader < CarrierWave::Uploader::Base

  # Include RMagick or MiniMagick support:
  # include CarrierWave::RMagick
  include CarrierWave::MiniMagick

  # Choose what kind of storage to use for this uploader:
  storage :file
  # storage :fog

  # Override the directory where uploaded files will be stored.
  # This is a sensible default for uploaders that are meant to be mounted:
  def store_dir
    "uploads/#{model.class.to_s.underscore}/#{mounted_as}/#{model.id}"
  end

  process :crop

  def crop
    if model.crop_attributes.present?
      cropbox = JSON.parse(model.crop_attributes)
      manipulate! do |img|
        x = cropbox["x"].to_i
        y = cropbox["y"].to_i
        w = cropbox["w"].to_i
        h = cropbox["h"].to_i
        # example: mogrify +repage -crop 1x2+3+4 file_patch
        img.combine_options do |c|
          c.repage.+
          c.crop("#{w}x#{h}+#{x}+#{y}")
        end
      end
    end
  end
end
```

其他的部分就不多說了，最難的部分就是這個 crop，其中：

```
include CarrierWave::MiniMagick
```

需要 gem "mini_magick" 以及 brew install imagemagick。

```
process :crop
```

這是一個 callback，會在圖片儲存前給你一個機會對圖片做事。所以只要前端傳遞一個矩形座標到後端就能切圖。這裡就先隨便用 1、2、3、4 做為代表。

```
img.crop("#{w}x#{h}+#{x}+#{y}")
```

這個 crop 方法會被轉為系統指令

```
mogrify -crop 3x4+1+2 file_path
```

mogrify 是 imagemagick 提供的指令，可以拿它來切圖。

說明書在這裡：[https://www.imagemagick.org/script/mogrify.php](https://www.imagemagick.org/script/mogrify.php)

一切運作良好，直到我遇到這張圖：

![Color](//images.ctfassets.net/8er52l3j5u76/5y0sRh2MpA7Y3jhO5SvpN2/1fcfd88241682837c7b9f67193441114/color_18_3_lg.png)

怎麼切位置都是錯的。

強者我同事爬了一下文，發現是 ImageMagick 支援叫做 Virtual Canvas （虛擬圖層？）的資訊，這種東西其實是圖片的 Metadata 的一部分。

把出問題那張圖片拿去解析 Metadata會發現

```
Image Offset: 54, 64
```

也就是 ImageMagick 發現他有設定位移，所以就照這個設定去裁切了。然後用 +repage 可以讓他把 Offset 設回 0,0

所以這是我們的目標指令：

```
mogrify +repage -crop 3x4+1+2 file_path
```

但 ruby 是要這樣寫：

```
img.combine_options do |c|
  c.repage.+
  c.crop("#{w}x#{h}+#{x}+#{y}")
end
```
因為有兩個以上的參數，所以需要用 combine_options 去串接參數。
```
c.repage.+
```
會生成出
```
+repage
```

事實上他會把函數名稱拿去當作參數名稱，如果我這樣寫：

```
img.combine_options do |c|
  c.jsdiofaodj.+
  c.crop("#{w}x#{h}+#{x}+#{y}")
end
```

他就會嘗試執行

```
mogrify +jsdiofaodj -crop 199x154+234+343 file_path
```

如果把 .+ 拔掉：

```
img.combine_options do |c|
  c.jsdiofaodj
  c.crop("#{w}x#{h}+#{x}+#{y}")
end
```

就會變成

```
mogrify -jsdiofaodj -crop 199x154+234+343 file_path
```

如果調換順序：

```
img.combine_options do |c|
  c.crop("#{w}x#{h}+#{x}+#{y}")
  c.repage.+
end
```

會變成

```
mogrify -crop 3x4+1+2 +repage file_path
```

你可能會想說，參數順序有差嗎？還真的有差。

因為他不是參數順序，而是執行順序。

總而言之，強者我同事守護了世界的和平。

還是切雞排容易多了。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>


post-老闆來一份上傳圖片要切/cover

老闆來一份上傳圖片要切


# 專案管理起步走：五件重要的小事

最近因為參加聚會聽到了在不同領域擔任專案管理的分享，談到專案管理過程中幾個共通的問題，剛好趁這個機會，想回顧一下，這兩年內學會了什麼，心態上又改變了什麼？於是整理出五件我覺得改變我工作方式的重要小事

1. 事情分輕重緩急，追蹤問題
2. 學習談判，細心與耐心
3. 專案的建議，但把選擇權交回客戶
4. 建立團隊從小原則開始
5. 抓好時間管理，讓客戶感受到被重視

### 1. 事情分輕重緩急，追蹤問題

> 剛開始做 PM 工作的第一個月，每一封信每一個對話我都回的戰戰兢兢，深怕遺漏掉任何事情，只要客戶一問「這東西進度怎麼樣啦？」我就會緊張的跑到工程師旁邊問他所以進度怎麼樣，弄的大家都很緊張...

雖然說工作上是以客為尊，快速的回應會讓顧客有好印象，但若只為了這樣而中斷自己甚至工程師的工作時，就可以停下來想一下客戶提出來的問題是不是真的這麼的迫切？

適時的讓客戶知道，我們已經收到你提出來的疑問了，並且會盡快為他處理這些問題
也因此 PM 身上也會一串長長的追蹤事項，每天固定找一個時間，重新檢視一次今天需要追蹤的問題，把處理掉的問題劃掉，

### 2. 學習談判，細心與耐心

PM 其中一個重要的工作在於如何溝通協調，對外我們要判斷需求，並適時的給予客戶專業建議、對內需要學著跟工程師協調任務的先後順序，這也是為什麼大家常說 PM 學著說不同的話，在面對不同領域的人有著不一樣的腦袋，如何聽懂對方的話、使彼此交流順常，找出最適的解決方案，溝通是專案管理最重要的軟實力。

關於協調與談判，我自己的心得是可以從耐心的傾聽以及換位思考開始練習，在 <卡內基溝通與人際關係：如何贏取友誼與影響他人> 書中，戴爾‧卡內基（Dale Carnegie）曾提到，假如你在職場上只學會一樣東西，就是能從自己與別人的角度思考、去看事情，那很有可能是你人生、事業成功的踏腳石。

### 3. 專案的建議，但把選擇權交回客戶

>「這樣不行，那樣不好，不然你告訴我你覺得怎麼樣才行？」

從第二點延伸，許多時候客戶會提出不太明確的需求或是天馬行空的想法，在我們傾聽完客戶的需求後，對於一些複雜的需求我們可能將需求帶回去在和工程師討論可行的方案，而最後我們可以怎麼呈現給客戶？

在想解決方案的過程中透過換位思考的方式，重新站在客戶考量他的需求，這裡的需求有時不單只是產品需求，還有成本、時間的考量也要加在這當中，透過提案的方式，列出可行的解決方案的優缺點後、需要開發的時間、成本後，將最後的選擇權交回給客戶。

透過良好的表達方式呈現我們解決問題的專業，同時也尊重客戶的選擇，除了能把問題解決之外最重要的是贏得客戶的信任。做 PM 給我一個很大的訓練是，我們得先聽懂並且了解對方的需求，在以專業的建議表達自己的需求，從中找尋交集的解決方式，就可以創造雙贏。

### 4.  建立團隊從小原則開始

理想上我們都希望能待在一個好的團隊，團隊裡的成員會自發性的去學習、並且積極地完成工作。但有時就算很幸運的遇上一群擁有很高熱忱的成員，若能有一些小的原則在這團隊當中發酵，更能將大家的力量凝結起來，發揮團隊最大的作用。

我覺得可以從每日的站立會議開始

站立會議其實是 Scrum（敏捷軟體開發過程）中的一部份，但我自己的心得是不一定只能用在 Scrum 的專案中 (畢竟不是每個專案都適合 scrum) ，每日的站立會議，能夠讓團隊成員有更多時間專注在工作上，同時也讓 PM 更輕鬆、即時地掌握實際情報

有效的站立會議我覺得有幾個要點：

  *  每天固定的時間
  *  會議時間不超過 15 分鐘
  *  一次只有一個人發言，並只針對三個重點說明，包括「昨天完成了哪些任務」、「今天的預計要執行的任務」、「碰到的問題」
  *  遠端的工程師可使用一些視訊軟體輔助，一樣可以參加站立會議

PM 在這當中有點像是引導者，透過發問的方式，讓團隊成員們慢慢的熟悉站立會議的模式，同時也讓自己更能掌握實際的狀況。

### 5. 要讓客戶感受到被重視

由於 PM 身上可能會不只處理一個專案，如何在不同專案之間做好顧客關係管理，我想很大一部分跟時間管理有關係。

在第一點時我提到了事情要分輕重緩急，分完後依序地處理每件事情之外，另外也可以透過一些工作摘要整理成進度跟客戶做回報，表現出主動追蹤處理問題的態度，重點式的回報進度給客戶，客戶在知道專案狀況後通常會比較放心。

許多時候 PM 除了專注於管理專案的進度之外，也需要服務客戶的心理狀態，讓客戶放心也感受到備受重視

### 最後，我對 PM 工作的想法

專案管理有趣卻也困難的是在於許多事情沒有完美或唯一正確的解答，只有能被大家接受的解決方法，當 PM 需要學會在這灰色地帶中透過有效的溝通作出決定，並學習接受現實世界中不可能滿足所有人的狀況下，如何使專案能夠向前推進。


五倍紅寶石・專業程式教育機構

ASTRO Camp

線上課程

短期課程

技術文章

五倍消息

技術文章

Rails 串接 Ecpay 電子發票，就是這麼簡單

The ABC of Rails Engines

Material Design 新利器：Material Theme Editor

從失敗案例重新思考敏捷開發價值

Multi-tenant 應用程式：讓人又愛又恨的 Apartment

老闆來一份上傳圖片要切

專案管理起步走：五件重要的小事

訂閱文章

電話 | (02) 2331-5247

信箱 | [email protected]

地址 | 10046 台北市中正區衡陽路 7 號 5 樓

專業課程

ASTRO Camp

線上課程

短期課程

關於我們

關於五倍紅寶石

聯絡我們

媒體報導

加入我們

部落格

技術文章

五倍消息

幫助與政策

常見問題

隱私權政策

服務條款