unidom-common 1.10 → 1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82885ef3b635b592845732747e2969ff094fb704
-  data.tar.gz: 5dfb807730c4303586b7c434bc2adea8198a9614
+  metadata.gz: 8d9cd0cf5814089ba939160bb2ad58af74acfab2
+  data.tar.gz: e926c6a1f817e200cab79619d80e6fe7be0eef07
 SHA512:
-  metadata.gz: a666ed1ac16160fcff279ea5d289b63f4b5b366eb6eef45cae6baf230feff72e0a15768149fd940c2cf9ad80631a64254519c8312e18682a95f7a73da471212e
-  data.tar.gz: 51499f8975ee71f6c40cb7e01a1c0029f58635b8bc230592290ee319e8745685e40d0bfaa1e0ca08e4c6201fbae18666db354439db65e21b9269176abfab2dde
+  metadata.gz: d7e967c73037be4d337f418e70dfd9715bc7e067ba9bd3ba754a452ae7788458ed91ffe66324eb1b8d1d8d50cdfde34970ed9733849bb7f656e25dc05c706123
+  data.tar.gz: 9dd384ddeecbcb0cce714086a9d28246d8c969b07a930a933815079e5f3cbdaa4a4231612f2e335d6d395596a36a1198ff4b88e725b4d63553358ed8b0a9a070

data/README.md

@@ -32,7 +32,7 @@ gem 'unidom-common'
 rake db:migrate
 ```
 The migration versions starts with 200001.
-The migration enabled the PostgreSQL uuid-ossp extension.
+The migrations enabled the PostgreSQL uuid-ossp extension and the pgcrypto extension.
 
 
 

data/app/models/unidom/common/concerns/aes256_cryptor.rb

@@ -18,8 +18,6 @@ module Unidom::Common::Concerns::Aes256Cryptor
 
     ##
     # 将密文 encoded 用秘钥 key 进行解密。如：
-    # decrypt encoded
-    # 或
     # decrypt encoded, key: aes256_key
     def decrypt(encoded, key: nil)
       self.class.decrypt encoded, key: key
@@ -29,10 +27,18 @@ module Unidom::Common::Concerns::Aes256Cryptor
       self.class.aes_256_padding
     end
 
+    ##
+    # 将明文 message 用秘钥 key 进行加密，并转换成16进制表达。如：
+    # hex_encrypt 'clear text', key: aes256_key
     def hex_encrypt(message, key: nil)
       self.class.hex_encrypt message, key: key
     end
 
+    ##
+    # 将明文 message 用秘钥 key 进行解密，并转换成16进制表达。如：
+    # hex_decrypt 'clear text'
+    # 或
+    # hex_decrypt 'clear text', key: aes256_key
     def hex_decrypt(encoded, key: nil)
       self.class.hex_decrypt encoded, key: key
     end
@@ -45,6 +51,11 @@ module Unidom::Common::Concerns::Aes256Cryptor
       'AES-256-CBC'
     end
 
+    ##
+    # 将明文 message 用秘钥 key 进行加密。如：
+    # encrypt 'clear text'
+    # 或
+    # encrypt 'clear text', key: aes256_key
     def encrypt(message, key: nil)
 
       raise ArgumentError.new('The message argument is required.') if message.blank?
@@ -59,6 +70,9 @@ module Unidom::Common::Concerns::Aes256Cryptor
 
     end
 
+    ##
+    # 将密文 encoded 用秘钥 key 进行解密。如：
+    # decrypt encoded, key: aes256_key
     def decrypt(encoded, key: nil)
 
       raise ArgumentError.new('The encoded argument is required.') if encoded.blank?
@@ -77,10 +91,16 @@ module Unidom::Common::Concerns::Aes256Cryptor
       respond_to?(:cryption_padding) ? cryption_padding : 9
     end
 
+    ##
+    # 将明文 message 用秘钥 key 进行加密，并转换成16进制表达。如：
+    # self.hex_encrypt 'clear text', key: aes256_key
     def hex_encrypt(message, key: nil)
       Unidom::Common::Numeration.hex encrypt(message, key: key)
     end
 
+    ##
+    # 将明文 message 用秘钥 key 进行解密，并转换成16进制表达。如：
+    # self.hex_decrypt 'clear text', key: aes256_key
     def hex_decrypt(encoded, key: nil)
       Unidom::Common::Numeration.hex decrypt(Unidom::Common::Numeration.rev_hex(encoded), key: key)
     end

data/app/models/unidom/common/concerns/argument_validation.rb

@@ -18,6 +18,9 @@ module Unidom::Common::Concerns::ArgumentValidation
 
   module ClassMethods
 
+    ##
+    # 断言给定的参数 value 非空。如果为空，则抛出 ArgumentError 异常。如：
+    # assert_present! :person, person
     def assert_present!(name, value)
       raise ArgumentError.new("The #{name} argument is required.") if value.blank?
     end

data/app/models/unidom/common/concerns/exact_column.rb

@@ -1,3 +1,6 @@
+##
+# Exact Column 为加密数据提供摘要索引。
+
 module Unidom::Common::Concerns::ExactColumn
 
   extend ActiveSupport::Concern
@@ -31,6 +34,8 @@ module Unidom::Common::Concerns::ExactColumn
 
     end
 
+    ##
+    # 计算精确索引列的值。此方法被 exact_column 方法调用。
     def exact_signature(klass, name, value, secret_key_base: Rails.application.secrets[:secret_key_base])
       text = "#{secret_key_base}/#{klass.table_name}##{name}=#{value}"
       #text = "#{Rails.application.secrets[:secret_key_base]}@#{Rails.root}/#{klass.table_name}##{name}=#{value}"

data/app/models/unidom/common/concerns/md5_digester.rb

@@ -21,6 +21,16 @@ module Unidom::Common::Concerns::Md5Digester
       self.class.digest message, pepper: pepper
     end
 
+    ##
+    # 对明文 message 进行 MD-5 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Md5Digester
+    #   def some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       self.class.hex_digest message, pepper: pepper
     end
@@ -29,10 +39,30 @@ module Unidom::Common::Concerns::Md5Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 MD-5 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Md5Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::MD5.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 MD-5 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Md5Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/app/models/unidom/common/concerns/model_extension.rb

@@ -1,3 +1,6 @@
+##
+# Model Extension 是通用的模型扩展关注点，提供参数验证、JSON 注解字段、加密字段等。
+
 module Unidom::Common::Concerns::ModelExtension
 
   extend ActiveSupport::Concern
@@ -115,6 +118,10 @@ module Unidom::Common::Concerns::ModelExtension
       #relation
     end
 
+    ##
+    # 对当前对象进行软删除。软删除之后， #closed_at 会被置为当前时间， #defunct 会被置为 false 。并且对象会被自动保存。如：
+    # model = YourModel.find your_id
+    # model.soft_destroy
     def soft_destroy
       self.closed_at = Time.now
       self.defunct = true
@@ -143,6 +150,10 @@ module Unidom::Common::Concerns::ModelExtension
       model.respond_to?(:id) ? model.id : model
     end
 
+    ##
+    # 将模型对象或者 code 转换成 code 。如：
+    # to_id(category)      # category.id
+    # to_id(category.code) # category.id
     def to_code(code)
       code.respond_to?(:code) ? code.code : code
     end

data/app/models/unidom/common/concerns/notation_column.rb

@@ -1,3 +1,6 @@
+##
+# Notation Column 提供定义 JSON 注解列的方法。
+
 module Unidom::Common::Concerns::NotationColumn
 
   extend ActiveSupport::Concern
@@ -35,6 +38,17 @@ module Unidom::Common::Concerns::NotationColumn
       end
     end
 
+    ##
+    # 定义标注字段的 boolean 型的列。如：
+    # class YourModel < ApplicationRecord
+    #   include Unidom::Common::Concerns::NotationColumn
+    #   notation_boolean_column :still_alive
+    # end
+    # 则为 YourModel 的实例生成2个方法：still_alive? 和 still_alive=。
+    # model = YourModel.new still_alive: true
+    # model.still_alive? # true
+    # model.still_alive = false
+    # model.still_alive? # false
     def notation_boolean_column(*names)
       names.each do |name|
         name = name.to_s

data/app/models/unidom/common/concerns/secure_column.rb

@@ -1,3 +1,5 @@
+##
+# Secure Column 提供定义加密列的方法。
 module Unidom::Common::Concerns::SecureColumn
 
   extend  ActiveSupport::Concern
@@ -41,6 +43,22 @@ module Unidom::Common::Concerns::SecureColumn
 
   module ClassMethods
 
+    ##
+    # 配置加密列。如：
+    # class YourModel < ApplicationRecord
+    #   attr_accessor :identity_card_name, :identity_card_address, :passport_name, :passport_address
+    #   include Unidom::Common::Concerns::SecureColumn
+    #   secure_column :secure_identity_card, fields: [ :identity_card_name, :identity_card_address ]
+    #   secure_column :secure_passport,      fields: [ :passport_name, :passport_address ]
+    # end
+    #
+    # model = YourModel.create! identity_card_name: '张三', identity_card_address: '地址1',
+    #   passport_name: '李四', passport_address: '地址2'
+    # #identity_card_name 和 #identity_card_address 会被加密后保存到 #secure_identity_card 字段中。
+    # #passport_name 和 #passport_address 会被加密后保存到 #secure_passport 字段中。
+    # model_2 = YourModel.find model.id
+    # model_2.identity_card_name # 张三
+    # #secure_identity_card 中存储的加密信息会被自动解密，并存储到 #identity_card_name 和 #identity_card_address 中。
     def secure_column(name, fields: [])
 
       name                = name.to_s

data/app/models/unidom/common/concerns/sha1_digester.rb

@@ -39,10 +39,30 @@ module Unidom::Common::Concerns::Sha1Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 SHA-1 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha1Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::SHA1.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 SHA-1 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha1Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/app/models/unidom/common/concerns/sha256_digester.rb

@@ -39,10 +39,30 @@ module Unidom::Common::Concerns::Sha256Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 SHA-256 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha256Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::SHA256.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 SHA-256 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha256Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/app/models/unidom/common/concerns/sha2_digester.rb

@@ -39,10 +39,30 @@ module Unidom::Common::Concerns::Sha2Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 SHA-2 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha2Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::SHA2.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 SHA-2 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha2Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/app/models/unidom/common/concerns/sha384_digester.rb

@@ -39,10 +39,30 @@ module Unidom::Common::Concerns::Sha384Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 SHA-384 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha384Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::SHA384.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 SHA-384 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha384Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/app/models/unidom/common/concerns/sha512_digester.rb

@@ -39,10 +39,30 @@ module Unidom::Common::Concerns::Sha512Digester
 
   module ClassMethods
 
+    ##
+    # 对明文 message 进行 SHA-512 摘要， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha512Digester
+    #   def self.some_method(param_1)
+    #     digest param_1
+    #     # 或者
+    #     digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def digest(message, pepper: nil)
       message.present? ? Digest::SHA512.digest("#{message}_#{Rails.application.secrets[:secret_key_base]}_#{pepper}") : nil
     end
 
+    ##
+    # 对明文 message 进行 SHA-512 摘要，并以16进制的形式返回， pepper 是用于增加混乱的内容。如：
+    # class SomeModel
+    #   include Unidom::Common::Concerns::Sha512Digester
+    #   def self.some_method(param_1)
+    #     hex_digest param_1
+    #     # 或者
+    #     hex_digest param_1, pepper: 'my_pepper'
+    #   end
+    # end
     def hex_digest(message, pepper: nil)
       message.present? ? Unidom::Common::Numeration.hex(digest(message, pepper: pepper)) : nil
     end

data/db/migrate/20000101000010_enable_pgcrypto_extension.rb

@@ -0,0 +1,7 @@
+class EnablePgcryptoExtension < ActiveRecord::Migration
+
+  def change
+    enable_extension 'pgcrypto' unless extension_enabled? 'pgcrypto'
+  end
+
+end

data/lib/unidom/common.rb

@@ -17,6 +17,8 @@ module Unidom
     FROM_DATE = '1970-01-01'.freeze
     THRU_DATE = '3000-01-01'.freeze
 
+    STATE = 'C'.freeze
+
     mattr_accessor :options
 
     ##

data/lib/unidom/common/version.rb

@@ -1,5 +1,5 @@
 module Unidom
   module Common
-    VERSION = '1.10'.freeze
+    VERSION = '1.11'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unidom-common
 version: !ruby/object:Gem::Version
-  version: '1.10'
+  version: '1.11'
 platform: ruby
 authors:
 - Topbit Du
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-26 00:00:00.000000000 Z
+date: 2017-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -114,6 +114,7 @@ files:
 - app/views/layouts/unidom/common/application.html.erb
 - config/routes.rb
 - db/migrate/20000101000000_enable_uuid_extension.rb
+- db/migrate/20000101000010_enable_pgcrypto_extension.rb
 - lib/tasks/common_tasks.rake
 - lib/unidom/common.rb
 - lib/unidom/common/data_helper.rb