easy_tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68fe26d2e704b26fafef4dbf80b51d02f9fb23d7b6f2294d957192e725d82add
+  data.tar.gz: af7447ee4aae049bb9f9aa6e9ca8b73af9c9ed3a6d345e7b89d324f0d9121245
+SHA512:
+  metadata.gz: ba25b53e0d8be84825f03afae7deb5b2755027a57e08b2d036a538d1feefb1b2f1dc581b2982f2b5d6d63dc97f38941b9b6b534ade7efe66e3e0741f63a150f6
+  data.tar.gz: 38433117b123422f6a0e05c0a390f9035502954487e525308392a1052b10038586176a2f6838a808bf84a13ae8539033f8b7d886763e2e5238ac0ba7e2e5a500

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 1.17.2

data/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "pavlitsky.yard"
+  ]
+}

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at andy.you@rccchina.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 andy.you
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+<!--
+ * @Author: andy.you andy.you@rccchina.com
+ * @Date: 2025-08-20 13:42:05
+ * @LastEditors: andy.you andy.you@rccchina.com
+ * @LastEditTime: 2025-08-20 13:44:27
+ * @FilePath: /easy_tools/README.md
+ * @Description: 这是默认设置,请设置`customMade`, 打开koroFileHeader查看配置 进行设置: https://github.com/OBKoro1/koro1FileHeader/wiki/%E9%85%8D%E7%BD%AE
+-->
+# EasyTools
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/easy_tools`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+一些简单的辅助工具，帮助你减少一些重复的代码
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'easy_tools'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install easy_tools
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/easy_tools. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the EasyTools project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/easy_tools/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/easy_tools.gemspec

@@ -0,0 +1,46 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_tools/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'easy_tools'
+  spec.version       = EasyTools::VERSION
+  spec.authors       = ['andy.you']
+  spec.email         = ['andy.you@rccchina.com']
+
+  spec.summary       = 'EasyTools is a collection of utility methods and classes for Ruby on Rails applications.'
+  spec.description   = 'EasyTools provides a set of helper methods and classes to simplify common tasks in Ruby on Rails applications, enhancing productivity and code maintainability.'
+  spec.homepage      = 'https://git.rccchina.com/leads-in/omnicrm'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['source_code_uri'] = 'https://git.rccchina.com/leads-in/omnicrm'
+    spec.metadata['changelog_uri'] = 'https://git.rccchina.com/leads-in/omnicrm'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+      'public gem pushes.'
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        # 过滤一些不希望打包进gem的文件
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile .rubocop.yml])
+    end
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.17'
+  # spec.add_development_dependency 'rake', '~> 10.0'
+  # spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/lib/auto_load.rb

@@ -0,0 +1,45 @@
+# 自动加载
+class AutoLoad
+  def self.define_autoloads(base_dir, namespace)
+    base_dir = File.expand_path(base_dir)
+
+    Dir.glob("#{base_dir}/**/*.rb").each do |file|
+      # 获取相对路径并移除扩展名
+      relative_path = file.sub("#{base_dir}/", '').sub('.rb', '')
+      path_parts = relative_path.split('/')
+
+      # 最后一个部分是类名
+      class_name = camelize(path_parts.pop)
+      # 前面的部分是模块路径
+      module_parts = path_parts.map { |part| camelize(part) }
+
+      # 找到或创建父模块
+      parent_module = find_or_create_module(module_parts, namespace)
+
+      # 设置 autoload（必须是符号）
+      parent_module.autoload class_name.to_sym, file
+    end
+  end
+
+  def self.find_or_create_module(module_parts, base_module)
+    current_module = base_module
+
+    module_parts.each do |mod_name|
+      mod_symbol = mod_name.to_sym
+
+      if current_module.const_defined?(mod_symbol)
+        current_module = current_module.const_get(mod_symbol)
+      else
+        new_module = Module.new
+        current_module.const_set(mod_symbol, new_module)
+        current_module = new_module
+      end
+    end
+
+    current_module
+  end
+
+  def self.camelize(string)
+    string.split('_').map(&:capitalize).join
+  end
+end

data/lib/easy_tools/batch_manager.rb

@@ -0,0 +1,42 @@
+module EasyTools
+  # 批量处理数据
+  class BatchManager
+    attr_accessor :is_wait, :interval, :max_thread
+
+    def initialize(data)
+      @data = data
+      @size = data.size
+      # 最大线程数不能超过数据库连接数
+      # 可能会取不到线程数，默认为1
+      @max_thread = ActiveRecord::Base.connection_pool.db_config.pool rescue 1
+      # 每根线程处理的业务数量
+      @interval = 100
+      # 是否等待结束
+      @is_wait = false
+      # 线程数组
+      @threads = []
+    end
+
+    #
+    #  启用多线程处理
+    #
+    def do_action
+      step = @size < @interval ? @size : @interval
+      start = 0
+      (start...@size).step(step).each_with_index.map do |index, _i|
+        end_step = step + index
+        @threads << Thread.new(@data[start...end_step]) do |data|
+          append_thread_function
+          yield data
+        end
+        start = end_step
+        # 线程大于等于线程数，阻塞等待
+        @threads.map(&:join) if @threads.size >= @max_thread
+      end
+      @threads.map(&:join) if @is_wait
+    end
+
+    # 增加线程处理中统一的方法
+    def append_thread_function; end
+  end
+end

data/lib/easy_tools/constant.rb

@@ -0,0 +1,53 @@
+module EasyTools
+  module Constant
+    # 一分钟的秒数
+    SECONDS_IN_MINUTE = 60
+    # 一小时的秒数
+    SECONDS_IN_HOUR = 60 * 60
+    # 一天的秒数
+    SECONDS_IN_DAY = 60 * 60 * 24
+    # 一周的秒数
+    SECONDS_IN_WEEK = 60 * 60 * 24 * 7
+    # 30天的秒数
+    SECONDS_IN_MONTH = 60 * 60 * 24 * 30 # 按30天计算
+    # 365天的秒数
+    SECONDS_IN_YEAR = 60 * 60 * 24 * 365 # 按365天计算
+    # 邮箱 正则表达式
+    EMAIL_REGULAR_EXPRESSION = /\w[-\w.+]*@([A-Za-z0-9][-A-Za-z0-9]+\.)+[A-Za-z]{2,14}/.freeze
+    # 手机号 正则表达式
+    MOBILE_REGULAR_EXPRESSION = /^1(3\d|4[5-9]|5[0-35-9]|6[2567]|7[0-8]|8\d|9[0-35-9])\d{8}$/.freeze
+    # 电话 正则表达式
+    PHONE_REGULAR_EXPRESSION = /\d{3}-\d{8}|\d{4}-\d{7}/.freeze
+    # 网址/链接正则
+    LINK_REGULAR_EXPRESSION = %r{^((ht|f)tps?)://[\w-]+(\.[\w-]+)+([\w\-.,@?^=%&:/~+#]*[\w\-@?^=%&/~+#])?$}.freeze
+
+    # 支持的所有日期时间格式正则表达式
+    DATETIME_FORMATS = {
+      # 基本日期格式（支持个位数）
+      yyyymmdd: /\A\d{8}\z/,                      # 20231225
+      yyyy_mm_dd: /\A\d{4}-\d{1,2}-\d{1,2}\z/,    # 2023-12-25 或 2023-1-5
+      yyyy_slash_mm_dd: %r{\A\d{4}/\d{1,2}/\d{1,2}\z}, # 2023/12/25 或 2023/1/5
+      yy_mm_dd: /\A\d{2}-\d{1,2}-\d{1,2}\z/,      # 23-12-25 或 23-1-5
+      yy_slash_mm_dd: %r{\A\d{2}/\d{1,2}/\d{1,2}\z}, # 23/12/25 或 23/1/5
+      yyyy_dot_mm_dd: /\A\d{4}\.\d{1,2}\.\d{1,2}\z/,  # 2023.12.25 或 2023.1.5
+      yy_dot_mm_dd: /\A\d{2}\.\d{1,2}\.\d{1,2}\z/,    # 23.12.25 或 23.1.5
+
+      # 中文日期格式（支持个位数）
+      chinese_date: /\A\d{4}年\d{1,2}月\d{1,2}日\z/,        # 2023年12月25日 或 2023年1月5日
+      chinese_short_date: /\A\d{2}年\d{1,2}月\d{1,2}日\z/,  # 23年12月25日 或 23年1月5日
+
+      # 日期时间格式（支持个位数）
+      yyyymmdd_hhmmss: /\A\d{8} \d{1,2}:\d{1,2}:\d{1,2}\z/,                # 20231225 14:30:45 或 20231225 4:3:5
+      yyyy_mm_dd_hhmmss: /\A\d{4}-\d{1,2}-\d{1,2} \d{1,2}:\d{1,2}:\d{1,2}\z/,  # 2023-12-25 14:30:45 或 2023-1-5 4:3:5
+      yyyy_slash_mm_dd_hhmmss: %r{\A\d{4}/\d{1,2}/\d{1,2} \d{1,2}:\d{1,2}:\d{1,2}\z}, # 2023/12/25 14:30:45 或 2023/1/5 4:3:5
+      iso_datetime: /\A\d{4}-\d{1,2}-\d{1,2}T\d{1,2}:\d{1,2}:\d{1,2}\z/, # 2023-12-25T14:30:45 或 2023-1-5T4:3:5
+
+      # 中文日期时间格式（支持个位数）
+      chinese_datetime: /\A\d{4}年\d{1,2}月\d{1,2}日\s\d{1,2}时\d{1,2}分\d{1,2}秒\z/, # 2023年12月25日 14时30分45秒 或 2023年1月5日 4时3分5秒
+      chinese_datetime_short: /\A\d{2}年\d{1,2}月\d{1,2}日\s\d{1,2}时\d{1,2}分\d{1,2}秒\z/, # 23年12月25日 14时30分45秒 或 23年1月5日 4时3分5秒
+
+      # 纯时间格式（支持个位数）
+      time_only: /\A\d{1,2}:\d{1,2}:\d{1,2}\z/, # 14:30:45 或 4:3:5
+    }.freeze
+  end
+end

data/lib/easy_tools/core.rb

@@ -0,0 +1,57 @@
+module EasyTools
+  # EasyTools is a collection of utility methods and classes for Ruby on Rails applications.
+  class Core
+    class << self
+      # 列表转树结构
+      # @params data Hash 列表数据
+      # 数据结构
+      # [{
+      #   id: 1,           # 主键id
+      #   parent_id: nil,  # 父id
+      #   order: 0,        # 排序
+      #   body: {title: '测试'},        # 主体内容
+      # },...]
+      # @return [Array] [{:title=>'测试', :children=>[]}]
+      #
+      def list_to_tree(data, parent_id = nil, sort_by: [:order])
+        nodes = data.select { |item| item[:parent_id] == parent_id }
+        # 多字段排序
+        nodes.sort_by! { |node| sort_by.map { |field| node[field] } }
+
+        nodes.map do |node|
+          {
+            **node[:body],
+            children: list_to_tree(data, node[:id], sort_by: sort_by),
+          }
+        end
+      end
+
+      # 循环查询全部数据
+      # @params page 开始页数
+      # @params per_apge 每条分页数据
+      def find_all(page: 1, per_page: 1000, max_size: 10_000, no_safe: false)
+        data = []
+        loop do
+          current_data = yield(page, per_page)
+          data.concat(current_data)
+          # 数据已经取完了，则跳出
+          break if per_page > current_data.size
+
+          # 10w条数据需要提示中止
+          if data.size > max_size && !no_safe
+            raise EasyTools::Error, '循环获取的数量过大，如果需要获取更多的数据可以调整 max_size参数或开启no_safe: true'
+          end
+
+          page += 1
+        end
+        data
+      end
+
+      # 创建自动嵌套的 Hash
+      # @return Hash
+      def auto_hash
+        Hash.new { |h, k| h[k] = auto_hash }
+      end
+    end
+  end
+end

data/lib/easy_tools/date_time.rb

@@ -0,0 +1,73 @@
+require 'time'
+module EasyTools
+  # 时间处理类
+  class DateTime
+    extend EasyTools::DateTimeExt::Validator
+
+    class << self
+      # 安全转成时间格式
+      # @params input [Integer|String] 输入参数【时间戳｜时间格式的字符串】
+      # @return DateTime 返回转换后的时间类型
+      def to_time(input)
+        case input
+        when Integer
+          # 处理毫秒级时间戳
+          input = input.to_s[0, 10].to_i
+          Time.at(input)
+        when String
+          raise EasyTools::Error, '请输入有效的日期时间格式' unless valid?(input)
+
+          Time.parse(normalize(input))
+        when DateTime, Date, Time
+          input
+        else
+          raise EasyTools::Error, '暂不支持此类型'
+        end
+      end
+
+      # 转成时间格式字符串
+      #
+      # @param input [String, Numeric, Time] 时间输入，可以是日期字符串、时间戳或Time对象
+      # @param format [String] 格式化时间字符串,同strftime方法参数
+      # @return [String] 格式化后日期
+      def strftime(input, format = '%Y-%m-%d %H:%M:%S')
+        time = to_time(input)
+        time.strftime(format)
+      end
+
+      # 时间转换方法：将时间转换为相对时间描述（如：几分钟前）
+      #
+      # @param input [String, Numeric, Time] 时间输入，可以是日期字符串、时间戳或Time对象
+      # @return [String] 相对时间描述或格式化日期
+      def format_relative_time(input)
+        time = input.is_a?(Time) ? input : to_time(input)
+        # 计算时间差
+        time_difference = (Time.now - time).to_i
+        # 根据时间差返回相应的描述
+        format_time_description(time_difference)
+      end
+
+      # 格式化时间描述
+      # @param difference [Integer] 秒数的差值
+      # @return [String] 格式化时间描述
+      def format_time_description(difference)
+        case difference
+        when 0...Constant::SECONDS_IN_MINUTE
+          "#{difference}秒前"
+        when Constant::SECONDS_IN_MINUTE...Constant::SECONDS_IN_HOUR
+          "#{difference / Constant::SECONDS_IN_MINUTE}分钟前"
+        when Constant::SECONDS_IN_HOUR...Constant::SECONDS_IN_DAY
+          "#{difference / Constant::SECONDS_IN_HOUR}小时前"
+        when Constant::SECONDS_IN_DAY...Constant::SECONDS_IN_WEEK
+          "#{difference / Constant::SECONDS_IN_DAY}天前"
+        when Constant::SECONDS_IN_WEEK...Constant::SECONDS_IN_MONTH
+          "#{difference / Constant::SECONDS_IN_WEEK}周前"  # 修复：除以周的秒数
+        when Constant::SECONDS_IN_MONTH...Constant::SECONDS_IN_YEAR
+          "#{difference / Constant::SECONDS_IN_MONTH}个月前"
+        else
+          "#{difference / Constant::SECONDS_IN_YEAR}年前"
+        end
+      end
+    end
+  end
+end

data/lib/easy_tools/date_time_ext/validator.rb

@@ -0,0 +1,362 @@
+require 'date'
+
+module EasyTools
+  module DateTimeExt
+    # DateTime 扩展模块，提供日期时间格式验证和转换功能
+    module Validator
+      # 验证日期时间字符串是否符合支持的格式
+      #
+      # @param datetime_string [String] 要验证的日期时间字符串
+      # @return [Boolean] 如果字符串符合任一支持的格式且日期时间组件有效，返回 true；否则返回 false
+      #
+      # @example
+      #   valid?("2023-12-25") #=> true
+      #   valid?("2023.1.1")   #=> true
+      #   valid?("invalid")    #=> false
+      def valid?(datetime_string)
+        return false unless datetime_string.is_a?(String)
+
+        # 检查是否符合任何一种格式
+        ::EasyTools::Constant::DATETIME_FORMATS.any? do |format_name, regex|
+          datetime_string.match?(regex) && valid_datetime_components?(datetime_string, format_name)
+        end
+      end
+
+      # 验证日期时间字符串的各个组件是否有效
+      #
+      # @param datetime_string [String] 日期时间字符串
+      # @param format_name [Symbol] 格式名称
+      # @return [Boolean] 如果所有组件都有效返回 true；否则返回 false
+      #
+      # @example
+      #   valid_datetime_components?("2023-13-01", :yyyy_mm_dd) #=> false (无效月份)
+      #   valid_datetime_components?("2023.1.1", :yyyy_dot_mm_dd) #=> true
+      def valid_datetime_components?(datetime_string, format_name)
+        components = extract_components(datetime_string, format_name)
+        return false unless components
+
+        year, month, day, hour, minute, second = components
+
+        # 校验日期部分
+        if year && month && day && !valid_date?(year, month, day)
+          return false
+        end
+
+        # 校验时间部分
+        if (hour || minute || second) && !valid_time?(hour, minute, second)
+          return false
+        end
+
+        true
+      end
+
+      # 从日期时间字符串中提取各个组件
+      #
+      # @param datetime_string [String] 日期时间字符串
+      # @param format_name [Symbol] 格式名称
+      # @return [Array<Integer, Integer, Integer, Integer, Integer, Integer>]
+      #   返回 [年, 月, 日, 时, 分, 秒] 数组，不存在的组件为 nil
+      # @return [nil] 如果格式不匹配返回 nil
+      #
+      # @example
+      #   extract_components("2023-12-25", :yyyy_mm_dd) #=> [2023, 12, 25, nil, nil, nil]
+      #   extract_components("2023.1.5", :yyyy_dot_mm_dd) #=> [2023, 1, 5, nil, nil, nil]
+      def extract_components(datetime_string, format_name)
+        case format_name
+        when :yyyymmdd
+          [datetime_string[0..3].to_i, datetime_string[4..5].to_i, datetime_string[6..7].to_i, nil, nil, nil]
+
+        when :yyyy_mm_dd, :yyyy_slash_mm_dd, :yyyy_dot_mm_dd
+          separator = get_separator(datetime_string)
+          parts = datetime_string.split(separator)
+          year = parts[0].to_i
+          month = parts[1].to_i
+          day = parts[2].to_i
+          [year, month, day, nil, nil, nil]
+
+        when :yy_mm_dd, :yy_slash_mm_dd, :yy_dot_mm_dd
+          separator = get_separator(datetime_string)
+          parts = datetime_string.split(separator)
+          year_str = parts[0].to_i
+          month = parts[1].to_i
+          day = parts[2].to_i
+          year = convert_two_digit_year(year_str)
+          [year, month, day, nil, nil, nil]
+
+        when :chinese_date
+          match = datetime_string.match(/\A(\d{4})年(\d{1,2})月(\d{1,2})日\z/)
+          [match[1].to_i, match[2].to_i, match[3].to_i, nil, nil, nil] if match
+
+        when :chinese_short_date
+          match = datetime_string.match(/\A(\d{2})年(\d{1,2})月(\d{1,2})日\z/)
+          year = convert_two_digit_year(match[1].to_i) if match
+          [year, match[2].to_i, match[3].to_i, nil, nil, nil] if match
+
+        when :yyyymmdd_hhmmss
+          date_part, time_part = datetime_string.split(' ')
+          hour, minute, second = time_part.split(':').map(&:to_i)
+          [date_part[0..3].to_i, date_part[4..5].to_i, date_part[6..7].to_i, hour, minute, second]
+
+        when :yyyy_mm_dd_hhmmss, :yyyy_slash_mm_dd_hhmmss
+          date_part, time_part = datetime_string.split(' ')
+          separator = get_separator(date_part)
+          parts = date_part.split(separator)
+          year = parts[0].to_i
+          month = parts[1].to_i
+          day = parts[2].to_i
+          hour, minute, second = time_part.split(':').map(&:to_i)
+          [year, month, day, hour, minute, second]
+
+        when :iso_datetime
+          date_part, time_part = datetime_string.split('T')
+          year, month, day = date_part.split('-').map(&:to_i)
+          hour, minute, second = time_part.split(':').map(&:to_i)
+          [year, month, day, hour, minute, second]
+
+        when :chinese_datetime
+          match = datetime_string.match(/\A(\d{4})年(\d{1,2})月(\d{1,2})日\s(\d{1,2})时(\d{1,2})分(\d{1,2})秒\z/)
+          [match[1].to_i, match[2].to_i, match[3].to_i, match[4].to_i, match[5].to_i, match[6].to_i] if match
+
+        when :chinese_datetime_short
+          match = datetime_string.match(/\A(\d{2})年(\d{1,2})月(\d{1,2})日\s(\d{1,2})时(\d{1,2})分(\d{1,2})秒\z/)
+          year = convert_two_digit_year(match[1].to_i) if match
+          [year, match[2].to_i, match[3].to_i, match[4].to_i, match[5].to_i, match[6].to_i] if match
+
+        when :time_only
+          hour, minute, second = datetime_string.split(':').map(&:to_i)
+          [nil, nil, nil, hour, minute, second]
+        end
+      end
+
+      # 获取字符串中的分隔符
+      #
+      # @param string [String] 包含分隔符的字符串
+      # @return [String] 分隔符字符（'-', '/', '.' 或空字符串）
+      #
+      # @example
+      #   get_separator("2023-12-25") #=> "-"
+      #   get_separator("2023/12/25") #=> "/"
+      #   get_separator("2023.1.1")   #=> "."
+      def get_separator(string)
+        if string.include?('-')
+          '-'
+        elsif string.include?('/')
+          '/'
+        elsif string.include?('.')
+          '.'
+        else
+          ''
+        end
+      end
+
+      # 将两位年份转换为四位年份
+      #
+      # 转换规则：00-79 转换为 2000-2079，80-99 转换为 1980-1999
+      #
+      # @param year [Integer] 两位年份
+      # @return [Integer] 四位年份
+      #
+      # @example
+      #   convert_two_digit_year(23) #=> 2023
+      #   convert_two_digit_year(85) #=> 1985
+      def convert_two_digit_year(year)
+        year < 80 ? year + 2000 : year + 1900
+      end
+
+      # 验证日期组件的有效性
+      #
+      # @param year [Integer] 年份
+      # @param month [Integer] 月份
+      # @param day [Integer] 日期
+      # @return [Boolean] 如果日期有效返回 true；否则返回 false
+      #
+      # @example
+      #   valid_date?(2023, 2, 29) #=> false (2023年不是闰年)
+      #   valid_date?(2024, 2, 29) #=> true  (2024年是闰年)
+      #   valid_date?(2023, 1, 1)  #=> true
+      def valid_date?(year, month, day)
+        return false unless month.between?(1, 12)
+        return false unless day.between?(1, days_in_month(year, month))
+
+        true
+      end
+
+      # 验证时间组件的有效性
+      #
+      # @param hour [Integer, nil] 小时
+      # @param minute [Integer, nil] 分钟
+      # @param second [Integer, nil] 秒
+      # @return [Boolean] 如果时间有效返回 true；否则返回 false
+      #
+      # @example
+      #   valid_time?(25, 30, 45) #=> false (小时无效)
+      #   valid_time?(14, 30, 45) #=> true
+      #   valid_time?(4, 3, 5)    #=> true
+      def valid_time?(hour, minute, second)
+        # 如果提供了时间部分，则验证所有时间组件
+        if hour || minute || second
+          if hour && !hour.between?(0, 23)
+            return false
+          end
+          if minute && !minute.between?(0, 59)
+            return false
+          end
+          if second && !second.between?(0, 59)
+            return false
+          end
+        end
+        true
+      end
+
+      # 获取指定年份和月份的天数
+      #
+      # @param year [Integer] 年份
+      # @param month [Integer] 月份
+      # @return [Integer] 该月的天数
+      #
+      # @example
+      #   days_in_month(2023, 2) #=> 28
+      #   days_in_month(2024, 2) #=> 29
+      def days_in_month(year, month)
+        case month
+        when 2
+          leap_year?(year) ? 29 : 28
+        when 4, 6, 9, 11
+          30
+        else
+          31
+        end
+      end
+
+      # 判断指定年份是否为闰年
+      #
+      # @param year [Integer] 年份
+      # @return [Boolean] 如果是闰年返回 true；否则返回 false
+      #
+      # @example
+      #   leap_year?(2023) #=> false
+      #   leap_year?(2024) #=> true
+      def leap_year?(year)
+        ((year % 4).zero? && year % 100 != 0) || (year % 400).zero?
+      end
+
+      # 将日期时间字符串标准化为指定格式
+      #
+      # @param datetime_string [String] 日期时间字符串
+      # @param format [Symbol] 输出格式，可选值：:iso, :chinese, :date_only, :time_only
+      # @return [String, nil] 标准化后的字符串，如果输入无效返回 nil
+      #
+      # @example
+      #   normalize("20231225", format: :iso)       #=> "2023-12-25"
+      #   normalize("2023.1.1", format: :iso)       #=> "2023-01-01"
+      #   normalize("2023-12-25", format: :chinese) #=> "2023年12月25日"
+      def normalize(datetime_string, format: :iso)
+        return nil unless valid?(datetime_string)
+
+        components = extract_components_from_string(datetime_string)
+        return nil unless components
+
+        year, month, day, hour, minute, second = components
+
+        case format
+        when :iso
+          format_iso(year, month, day, hour, minute, second)
+        when :chinese
+          format_chinese(year, month, day, hour, minute, second)
+        when :date_only
+          format_date_only(year, month, day)
+        when :time_only
+          format_time_only(hour, minute, second)
+        else
+          format_iso(year, month, day, hour, minute, second)
+        end
+      end
+
+      # 从字符串中提取日期时间组件
+      #
+      # @param datetime_string [String] 日期时间字符串
+      # @return [Array<Integer>, nil] 返回组件数组或 nil
+      #
+      # @private
+      def extract_components_from_string(datetime_string)
+        format_name = ::EasyTools::Constant::DATETIME_FORMATS.find do |name, regex|
+          datetime_string.match?(regex) && valid_datetime_components?(datetime_string, name)
+        end&.first
+
+        extract_components(datetime_string, format_name) if format_name
+      end
+
+      # 格式化为 ISO 格式的日期时间字符串
+      #
+      # @param year [Integer, nil] 年份
+      # @param month [Integer, nil] 月份
+      # @param day [Integer, nil] 日期
+      # @param hour [Integer, nil] 小时
+      # @param minute [Integer, nil] 分钟
+      # @param second [Integer, nil] 秒
+      # @return [String, nil] 格式化后的字符串
+      #
+      # @private
+      def format_iso(year, month, day, hour, minute, second)
+        date_part = "#{year}-#{month.to_s.rjust(2, '0')}-#{day.to_s.rjust(2, '0')}" if year && month && day
+        time_part = "#{hour.to_s.rjust(2, '0')}:#{minute.to_s.rjust(2, '0')}:#{second.to_s.rjust(2, '0')}" if hour && minute && second
+
+        if date_part && time_part
+          "#{date_part} #{time_part}"
+        elsif date_part
+          date_part
+        elsif time_part
+          time_part
+        end
+      end
+
+      # 格式化为中文格式的日期时间字符串
+      #
+      # @param year [Integer, nil] 年份
+      # @param month [Integer, nil] 月份
+      # @param day [Integer, nil] 日期
+      # @param hour [Integer, nil] 小时
+      # @param minute [Integer, nil] 分钟
+      # @param second [Integer, nil] 秒
+      # @return [String, nil] 格式化后的字符串
+      #
+      # @private
+      def format_chinese(year, month, day, hour, minute, second)
+        date_part = "#{year}年#{month}月#{day}日" if year && month && day
+        time_part = "#{hour}时#{minute}分#{second}秒" if hour && minute && second
+
+        if date_part && time_part
+          "#{date_part}#{time_part}"
+        elsif date_part
+          date_part
+        elsif time_part
+          time_part
+        end
+      end
+
+      # 格式化为仅日期字符串
+      #
+      # @param year [Integer] 年份
+      # @param month [Integer] 月份
+      # @param day [Integer] 日期
+      # @return [String] 格式化后的日期字符串
+      #
+      # @private
+      def format_date_only(year, month, day)
+        "#{year}-#{month.to_s.rjust(2, '0')}-#{day.to_s.rjust(2, '0')}" if year && month && day
+      end
+
+      # 格式化为仅时间字符串
+      #
+      # @param hour [Integer] 小时
+      # @param minute [Integer] 分钟
+      # @param second [Integer] 秒
+      # @return [String] 格式化后的时间字符串
+      #
+      # @private
+      def format_time_only(hour, minute, second)
+        "#{hour.to_s.rjust(2, '0')}:#{minute.to_s.rjust(2, '0')}:#{second.to_s.rjust(2, '0')}" if hour && minute && second
+      end
+    end
+  end
+end

data/lib/easy_tools/math.rb

@@ -0,0 +1,40 @@
+require 'bigdecimal'
+
+module EasyTools
+  # 数字方法
+  class Math
+    class << self
+      # @Notes: 精确除法并向上取整到指定小数位数
+      # @param dividend [Numeric, String] 被除数
+      # @param divisor [Numeric, String] 除数
+      # @param decimal_places [Integer] 保留的小数位数，默认为2
+      # @return [Float] 结果为向上取整后的浮点数
+      def precise_divide_and_ceil_percent(dividend, divisor, decimal_places = 2)
+        BigDecimal.mode(BigDecimal::ROUND_MODE, :up)  # 设置向上取整模式
+        BigDecimal.limit(decimal_places + 4)          # 设置足够精度
+
+        # 计算百分比（乘以100）
+        percent = (BigDecimal(dividend.to_s) / BigDecimal(divisor.to_s)) * 100
+
+        # 向上取整并格式化为指定小数位
+        ("%.#{decimal_places}f" % percent.ceil(decimal_places)).to_f
+      end
+
+      # @Notes: 精确除法并向上取整到指定小数位数
+      # @param dividend [Numeric, String] 被除数
+      # @param divisor [Numeric, String] 除数
+      # @param decimal_places [Integer] 保留的小数位数，默认为2
+      # @return [Float] 结果为向上取整后的浮点数
+      def precise_divide_and_round_percent(dividend, divisor, decimal_places = 2)
+        BigDecimal.mode(BigDecimal::ROUND_MODE, :half_up) # 设置向上取整模式
+        BigDecimal.limit(decimal_places + 4) # 设置足够精度
+
+        # 计算百分比（乘以100）
+        percent = (BigDecimal(dividend.to_s) / BigDecimal(divisor.to_s)) * 100
+
+        # 向上取整并格式化为指定小数位
+        ("%.#{decimal_places}f" % percent.round(decimal_places)).to_f
+      end
+    end
+  end
+end

data/lib/easy_tools/rails.rb

@@ -0,0 +1,24 @@
+module EasyTools
+  # EasyTools is a collection of utility methods and classes for Ruby on Rails applications.
+  class Rails
+    include EasyTools::RailsExt::Hash
+
+    def initialize
+      unless Object.const_defined?('ActiveSupport::HashWithIndifferentAccess')
+        raise EasyTools::Error,
+              'ActiveSupport::HashWithIndifferentAccess is not available. Please ensure you have ActiveSupport loaded.'
+      end
+    end
+
+    # 不存在方法时调用
+    def self.method_missing(method_name, *args, **hash_data, &block)
+      this.send(method_name, *args, **hash_data, &block)
+    end
+
+    class << self
+      def this
+        @this ||= new
+      end
+    end
+  end
+end

data/lib/easy_tools/rails_ext/hash.rb

@@ -0,0 +1,20 @@
+module EasyTools
+  module RailsExt
+    # 关于 Hash 的一些扩展方法
+    module Hash
+      # 对象转键值对
+      def to_kv(object, key, value = nil)
+        ActiveSupport::HashWithIndifferentAccess[object.map do |o|
+                                                   if o.is_a?(Hash)
+                                                     o = o.deep_symbolize_keys
+                                                     [o[key.to_sym], value.nil? ? o : o[value.to_sym]]
+                                                   else
+                                                     [o.try(key.to_sym), value.nil? ? o : o.try(value.to_sym)]
+                                                   end
+                                                 end]
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end

data/lib/easy_tools/version.rb

@@ -0,0 +1,3 @@
+module EasyTools
+  VERSION = '0.1.0'.freeze
+end

data/lib/easy_tools.rb

@@ -0,0 +1,43 @@
+require 'auto_load'
+AutoLoad.define_autoloads('lib/easy_tools', EasyTools)
+
+# 小小的帮助工具集合
+# 积累了实际生产场景中遇到问题的解决方法
+# 工具的目标为不一定通用，但一定好用
+module EasyTools
+  class Error < StandardError; end
+  # EasyTools is a collection of utility methods and classes for Ruby on Rails applications.
+  class << self
+    # Returns the version of the currently loaded EasyTools as a string.
+    def version
+      EasyTools::VERSION
+    end
+
+    # Provides a way to configure EasyTools.
+    #
+    # @yield [config] The configuration block.
+    # @yieldparam config [Configuration] The configuration object.
+    #
+    # @return [Configuration] The current configuration object.
+    def configure
+      yield(configuration)
+    end
+
+    # Returns the current configuration object.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # 加载Rails相关的扩展
+    def rails
+      EasyTools::Rails.this
+    end
+  end
+
+  # 配置相关
+  class Configuration
+    def initialize
+      @logger = Logger.new($stdout)
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: easy_tools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- andy.you
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+description: EasyTools provides a set of helper methods and classes to simplify common
+  tasks in Ruby on Rails applications, enhancing productivity and code maintainability.
+email:
+- andy.you@rccchina.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".travis.yml"
+- ".vscode/extensions.json"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- easy_tools.gemspec
+- lib/auto_load.rb
+- lib/easy_tools.rb
+- lib/easy_tools/batch_manager.rb
+- lib/easy_tools/constant.rb
+- lib/easy_tools/core.rb
+- lib/easy_tools/date_time.rb
+- lib/easy_tools/date_time_ext/validator.rb
+- lib/easy_tools/math.rb
+- lib/easy_tools/rails.rb
+- lib/easy_tools/rails_ext/hash.rb
+- lib/easy_tools/version.rb
+homepage: https://git.rccchina.com/leads-in/omnicrm
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://git.rccchina.com/leads-in/omnicrm
+  source_code_uri: https://git.rccchina.com/leads-in/omnicrm
+  changelog_uri: https://git.rccchina.com/leads-in/omnicrm
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: EasyTools is a collection of utility methods and classes for Ruby on Rails
+  applications.
+test_files: []