activemodel_object_info 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57c5e5b167d779ecddc9ef0880eae2eb80a1e5a5cfea65a041900952d105e746
-  data.tar.gz: 305b684a599a961fd454c06a9fb234abab64def44b629fc85ea53413973f9c93
+  metadata.gz: 80913d0545f39b6b56ea20826e6c5da37c3fbec7645f988c5439f85f6ac2eedc
+  data.tar.gz: 8f839ed3448156219e6c4da35c9eb69d9eb7d4dca97ef48f1c89b937ea2a782e
 SHA512:
-  metadata.gz: a787ba950b878f3fc7e40955a4cc5cf50a55ad0e8c783891c74e3c0fcee8d2f9f2630bec312717bb52c13ee52c63b41ea2f61efd19da03396ace20ea7f859e6a
-  data.tar.gz: 2fafd8e49b9ad0e1b1a4cef8ef813f8ea0a57b1e60f23588d617bada644eb50302af6fa395ebd041aac86b2b97c8de53ae8a4e206259495ada4dc13c9185652c
+  metadata.gz: a8c1005c3e1887dd377deb8ab79d1d9bad079dea09ac81e24ff484e59efdb44c3e3c6c7ba4741237954d944f0b5780ff00f9e7530ebe465c603eedc9f0aeb5a1
+  data.tar.gz: 5bd16bc43f2c13b58bfa037ee6505777d80a97d455b7744d75f32cd928348a1d2d0e0cc638acc0070662b42792f83972c365ccd00c81860980f05196afc6bd32

data/.ruby-version

@@ -1 +1 @@
-2.6.7
+2.7.7

data/CHANGELOG

@@ -1 +1,9 @@
-First Version
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## [0.4.0] - 2026-07-28
+### Fixed
+- Fixed Ruby 3.x keyword arguments compatibility issue for `instance_info` method, while keeping 100% backward compatibility for existing usages.
+
+## [0.3.4] - 2021-04-19
+- First Version

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activemodel_object_info (0.2.0)
+    activemodel_object_info (0.4.0)
       activesupport
 
 GEM

data/README.md

@@ -1,43 +1,173 @@
 # Activemodel::Object::Info
 
-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/activemodel/object/info`. To experiment with that code, run `bin/console` for an interactive prompt.
+[English](README.md) | [中文文档](README.zh-CN.md)
 
-TODO: Delete this and the text above, and describe your gem
+**Activemodel::Object::Info** is a Ruby Gem designed to extend `ActiveModel` and `ActiveRecord`. It provides an elegant and standardized way to handle common business requirements such as API data formatting, audit trails generation in database migrations, and soft-delete capabilities.
+
+## Table of Contents
+
+- [Features](#features)
+- [Applicable Scenarios](#applicable-scenarios)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [1. Data Formatting (Base)](#1-data-formatting-base)
+  - [2. Migration Macros (TableDefinition)](#2-migration-macros-tabledefinition)
+  - [3. Soft Delete (DeletedOperation)](#3-soft-delete-deletedoperation)
+- [Development & Testing](#development--testing)
+- [License](#license)
+
+## Features
+
+1. **Model Data Formatting (`Base`)**: Safely and flexibly format `ActiveRecord` instances into Hashes (JSON ready) with whitelisting, blacklisting, aliasing, and custom formatting.
+2. **Database Migration Macros (`TableDefinition`)**: One-click generation of audit fields (e.g., `created_by`, `updated_by`, `deleted_by`) and their corresponding timestamps.
+3. **Soft Delete (`DeletedOperation`)**: Standardized soft-delete implementation using an integer flag, coupled with automatic `default_scope` injection and audit trail recording.
+
+## Applicable Scenarios
+
+- **RESTful API Development**: When you need a unified and configurable way to serialize ActiveRecord models into JSON responses, avoiding sensitive data leakage.
+- **Enterprise / B2B Systems**: When strict data audit trails are required (tracking exactly *who* performed the creation, update, or deletion and *when*).
+- **Data Retention Requirements**: Systems that prohibit hard deletion (destroy) and require records to be marked as deleted (Soft Delete) instead.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'activemodel-object-info'
+gem 'activemodel-object-info', '~> 0.4.0'
 ```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle install
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install activemodel-object-info
+### 1. Data Formatting (Base)
 
-## Usage
+The `ActivemodelObjectInfo::Base` module adds the `instance_info` method to your models. It allows you to output formatted hashes based on predefined or runtime configurations.
 
-TODO: Write usage instructions here
+**Setup in Model:**
 
-## Development
+```ruby
+class User < ApplicationRecord
+  include ActivemodelObjectInfo::Base
+
+  # Define default output configuration
+  INSTANCE_INFO = {
+    only: [:id, :name, :status, :created_at],
+    attributes: [
+      :id,
+      { name: :name, as: :user_name }, # Aliasing
+      { name: :status, filter: ->(v) { v == 1 ? 'Active' : 'Inactive' } }, # Custom lambda filter
+      { name: :created_at, format: :date }, # Date formatting ('%Y-%m-%d')
+      { name: :virtual_field, type: :abstract, filter: ->(*) { "#{id}-#{name}" } } # Virtual field
+    ]
+  }.freeze
+end
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+**Usage:**
 
-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).
+```ruby
+user = User.first
 
-## Contributing
+# Use the default INSTANCE_INFO constant
+user.instance_info 
+# => { id: 1, user_name: "John", status: "Active", created_at: "2026-07-28", virtual_field: "1-John" }
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/activemodel-object-info. 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.
+# Override at runtime (Supports Ruby 2.x Hash and Ruby 3.x Keyword Arguments)
+user.instance_info(only: [:id, :name])
+# => { id: 1, name: "John" }
+```
 
-## License
+### 2. Migration Macros (TableDefinition)
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The `ActivemodelObjectInfo::TableDefinition` module extends ActiveRecord's migration capabilities to generate audit fields effortlessly.
+
+**Setup:**
+This is usually loaded automatically, but you can explicitly extend it if needed in your initializers.
+
+**Usage in Migrations:**
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[6.1]
+  def change
+    create_table :users do |t|
+      t.string :name
+      
+      # Generates full audit suite:
+      # created_by, created_at, updated_by, updated_at, deleted(int), deleted_by, deleted_at
+      t.generate_operations
+      
+      # Or generate specific custom audit fields:
+      # Generates: audit_by (bigint), audit_at (datetime)
+      t.operation_columns(:audit)
+      
+      # Generates: my_review_user (bigint), my_review_time (datetime)
+      t.operation_columns(:review, operator_prefix: 'my_', operator_suffix: '_user', timestamp_suffix: '_time')
+    end
+  end
+end
+```
+
+### 3. Soft Delete (DeletedOperation)
+
+The `ActivemodelObjectInfo::DeletedOperation` module provides an out-of-the-box soft deletion feature that works perfectly with the fields generated by `TableDefinition`.
+
+**Setup in Model:**
+
+```ruby
+class User < ApplicationRecord
+  include ActivemodelObjectInfo::DeletedOperation
+  
+  # Optional: Override default column names and values if your database uses different conventions
+  # DELETED_FIELD = 'is_deleted'
+  # DELETED_VALID_VALUE = false
+  # DELETED_INVALID_VALUE = true
+end
+```
+
+**Usage:**
 
-## Code of Conduct
+```ruby
+# 1. Automatic Scope: 
+# The module automatically injects a `default_scope` to hide deleted records.
+User.all # => SELECT * FROM users WHERE deleted = 0
+
+# 2. Perform Soft Delete:
+user = User.find(1)
+
+# You MUST provide the `user_id` of the operator performing the deletion
+user.soft_delete(user_id: current_user.id)
+# This will:
+# - Set `deleted` to 1
+# - Set `deleted_by` to current_user.id
+# - Set `deleted_at` to Time.now
+# - Call `save`
+
+# 3. Soft Delete and refresh updated_at:
+user.soft_delete(user_id: current_user.id, refresh_updated: true)
+
+# 4. Strict Soft Delete (raises exception on failure):
+user.soft_delete!(user_id: current_user.id)
+```
 
-Everyone interacting in the Activemodel::Object::Info project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/activemodel-object-info/blob/master/CODE_OF_CONDUCT.md).
+## Development & Testing
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+To run tests:
+```bash
+$ bundle exec rspec
+```
+
+To run code style checks:
+```bash
+$ bundle exec rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/README.zh-CN.md

@@ -0,0 +1,171 @@
+# Activemodel::Object::Info
+
+[English](README.md) | [中文文档](README.zh-CN.md)
+
+**Activemodel::Object::Info** 是一个用于扩展 `ActiveModel` 和 `ActiveRecord` 的 Ruby Gem。它为日常业务开发中常见的数据输出格式化、数据库迁移中的审计追踪字段生成、以及软删除（Soft Delete）功能提供了优雅且标准化的解决方案。
+
+## 目录
+
+- [核心特性](#核心特性)
+- [适用场景](#适用场景)
+- [安装指南](#安装指南)
+- [详细使用方法](#详细使用方法)
+  - [1. 模型数据格式化输出 (Base)](#1-模型数据格式化输出-base)
+  - [2. 数据库迁移宏 (TableDefinition)](#2-数据库迁移宏-tabledefinition)
+  - [3. 软删除机制 (DeletedOperation)](#3-软删除机制-deletedoperation)
+- [开发与测试](#开发与测试)
+- [开源协议](#开源协议)
+
+## 核心特性
+
+1. **模型数据格式化 (`Base`)**：安全、灵活地将 `ActiveRecord` 实例转换为 Hash（便于输出为 JSON）。支持字段白名单、黑名单、字段别名、自定义转换逻辑以及时间格式化。
+2. **数据库迁移宏 (`TableDefinition`)**：在创建数据库表时，一键生成常见的审计字段（例如 `created_by`, `updated_by`, `deleted_by`）以及配套的时间戳。
+3. **软删除机制 (`DeletedOperation`)**：基于整型标记字段的标准软删除实现，自动注入隐藏已删除数据的 `default_scope`，并在删除时强制记录操作人及时间。
+
+## 适用场景
+
+- **RESTful API 开发**：当你需要统一且高度可配置的方式，将 ActiveRecord 模型序列化为 JSON 响应并过滤掉敏感数据时。
+- **企业级 / B2B 系统后台**：业务上对数据的审计追踪（Audit Trails）要求极其严格，必须精准记录每一条数据是谁在什么时候创建、修改和删除的。
+- **数据留存要求高的系统**：严禁在数据库中执行硬删除（Destroy），要求所有的删除操作均采用软删除（Soft Delete）以备后续追溯。
+
+## 安装指南
+
+将以下代码添加到你项目中的 Gemfile 里：
+
+```ruby
+gem 'activemodel-object-info', '~> 0.4.0'
+```
+
+然后执行依赖安装：
+
+```bash
+$ bundle install
+```
+
+## 详细使用方法
+
+### 1. 模型数据格式化输出 (Base)
+
+`ActivemodelObjectInfo::Base` 模块为你的模型注入了 `instance_info` 方法。它能让你基于类中预定义的常量或运行时传入的参数，将实例对象输出为格式化的 Hash。
+
+**在模型中配置：**
+
+```ruby
+class User < ApplicationRecord
+  include ActivemodelObjectInfo::Base
+
+  # 定义默认的输出配置选项
+  INSTANCE_INFO = {
+    only: [:id, :name, :status, :created_at],
+    attributes: [
+      :id,
+      { name: :name, as: :user_name }, # 使用 as 设定别名
+      { name: :status, filter: ->(v) { v == 1 ? '活跃' : '停用' } }, # 使用 lambda 自定义转换逻辑
+      { name: :created_at, format: :date }, # 格式化日期为 ('%Y-%m-%d')
+      { name: :virtual_field, type: :abstract, filter: ->(*) { "#{id}-#{name}" } } # 根据其他字段合成的虚拟字段
+    ]
+  }.freeze
+end
+```
+
+**实际调用：**
+
+```ruby
+user = User.first
+
+# 不传参时，默认使用模型中的 INSTANCE_INFO 常量配置
+user.instance_info 
+# => { id: 1, user_name: "John", status: "活跃", created_at: "2026-07-28", virtual_field: "1-John" }
+
+# 运行时覆盖配置（完美兼容 Ruby 2.x 的 Hash 传参和 Ruby 3.x 的关键字参数）
+user.instance_info(only: [:id, :name])
+# => { id: 1, name: "John" }
+```
+
+### 2. 数据库迁移宏 (TableDefinition)
+
+`ActivemodelObjectInfo::TableDefinition` 模块对 ActiveRecord 的 Migration 进行了扩展，让你能够毫不费力地生成审计字段。
+
+**在迁移文件中的使用：**
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[6.1]
+  def change
+    create_table :users do |t|
+      t.string :name
+      
+      # 1. 批量生成全套生命周期审计字段：
+      # 将会自动生成: created_by, created_at, updated_by, updated_at, deleted(int), deleted_by, deleted_at
+      t.generate_operations
+      
+      # 2. 或者生成指定的自定义审计字段：
+      # 将会自动生成: audit_by (bigint), audit_at (datetime)
+      t.operation_columns(:audit)
+      
+      # 3. 甚至高度自定义前后缀：
+      # 将会自动生成: my_review_user (bigint), my_review_time (datetime)
+      t.operation_columns(:review, operator_prefix: 'my_', operator_suffix: '_user', timestamp_suffix: '_time')
+    end
+  end
+end
+```
+
+### 3. 软删除机制 (DeletedOperation)
+
+`ActivemodelObjectInfo::DeletedOperation` 模块提供了一套开箱即用的软删除功能，并且与 `TableDefinition` 宏生成的底层字段完美契合。
+
+**在模型中配置：**
+
+```ruby
+class User < ApplicationRecord
+  include ActivemodelObjectInfo::DeletedOperation
+  
+  # 可选：如果你的遗留数据库使用了其他命名习惯，可以覆盖以下常量
+  # DELETED_FIELD = 'is_deleted'
+  # DELETED_VALID_VALUE = false
+  # DELETED_INVALID_VALUE = true
+end
+```
+
+**实际调用：**
+
+```ruby
+# 1. 自动查询作用域：
+# 引入该模块后，会自动注入 `default_scope` 隐藏已被删除的记录。
+User.all # 实际执行 => SELECT * FROM users WHERE deleted = 0
+
+# 2. 执行软删除：
+user = User.find(1)
+
+# 出于安全和审计规范，你【必须】提供执行删除操作的用户 ID (user_id)
+user.soft_delete(user_id: current_user.id)
+# 这一步将自动执行以下操作：
+# - 将 `deleted` 标记设为 1
+# - 将 `deleted_by` 设为 current_user.id
+# - 将 `deleted_at` 设为当前时间 Time.now
+# - 调用 `save` 保存到数据库
+
+# 3. 软删除并同时刷新更新时间 (updated_at):
+user.soft_delete(user_id: current_user.id, refresh_updated: true)
+
+# 4. 强校验软删除 (底层调用 save!，失败时抛出异常):
+user.soft_delete!(user_id: current_user.id)
+```
+
+## 开发与测试
+
+克隆本仓库后，运行 `bin/setup` 安装开发依赖。
+
+运行 RSpec 单元测试：
+```bash
+$ bundle exec rspec
+```
+
+运行 RuboCop 代码风格静态检查：
+```bash
+$ bundle exec rubocop
+```
+
+## 开源协议
+
+本项目遵循 [MIT License](https://opensource.org/licenses/MIT) 开源协议。

data/lib/activemodel_object_info/base.rb

@@ -4,8 +4,37 @@ module ActivemodelObjectInfo
   #
   # 通用的设置操作项相关的模型方法和处理。
   #
+  # 核心作用与职责：
+  # 提供模型实例数据格式化输出能力。主要用于将 ActiveRecord 或 ActiveModel 的实例安全、灵活地转换为 Hash，
+  # 方便后续转化为 JSON 等格式输出给前端，支持字段过滤、重命名、自定义处理及日期格式化。
+  #
+  # @example 详细使用方法与示例
+  #   class User
+  #     include ActivemodelObjectInfo::Base
+  #     attr_accessor :id, :name, :created_at
+  #
+  #     INSTANCE_INFO = {
+  #       only: [:id, :name, :created_at],
+  #       attributes: [
+  #         :id,
+  #         { name: :name, as: :user_name },
+  #         { name: :created_at, format: :date }
+  #       ]
+  #     }.freeze
+  #   end
+  #
+  #   user = User.new(id: 1, name: "test", created_at: Time.now)
+  #   user.instance_info # => { id: 1, user_name: "test", created_at: "2026-07-28" }
+  #
+  # 核心重要方法：
+  # - {#instance_info}：核心输出方法，返回处理后的散列。
+  #
   # @author shiner527 <shiner527@hotmail.com>
   #
+  # [Changelog]
+  #   [2026-07-28] 补充完整 YARD 文档及核心注释，重构 instance_info 签名以兼容 Ruby 3.x 关键字参数 (shiner527)
+  #   [2021-04-19] 创建基础模块，提供 instance_info 数据格式化输出功能 (shiner527)
+  #
   module Base
     # ===== 常量定义 =====
 
@@ -25,22 +54,32 @@ module ActivemodelObjectInfo
     #
     # 对象信息输出。主要返回给前端一个可用的散列（会被转化为JSON格式）格式的信息并传递给前端。
     #
-    # @param [Hash] options 设置选项
-    # @option options [Array<Symbol, Hash>] :attributes 具体每一项输出的设置数组。每个元素既可以是标识符实例也可以是一个散列实例。
+    # @param [Hash] options_hash 设置选项（传统位置参数 Hash），如果传入将被与 keyword_options 合并
+    # @param [Hash] keyword_options 设置选项（Ruby 3 关键字参数）
+    # @option keyword_options [Array<Symbol, Hash>] :attributes 具体每一项输出的设置数组。每个元素既可以是标识符实例也可以是一个散列实例。
     #  如果是标识符实例，则表示输出该属性。如果是一个散列实例，则按照散列中的设定值去生成对应的内容。
-    # @option options [Array<Symbol>] :only 给出具体可以用来输出的字段属性名数组。
+    # @option keyword_options [Array<Symbol>] :only 给出具体可以用来输出的字段属性名数组。
+    # @option keyword_options [Array<Symbol>] :except 给出需要被排除输出的字段属性名数组。
+    # @option keyword_options [String, Symbol] :datetime_format 全局的时间格式设置。
     #
     # @return [Hash] 返回的处理过的该对象的信息散列。
     #
-    def instance_info(**options)
-      # puts "ARGS: #{args}, OPTIONS: #{options}"
-      # 参考默认的 options
+    def instance_info(options_hash = nil, **keyword_options)
+      # 合并传统参数与关键字参数，完美兼容 Ruby 2.x 的 Hash 传参和 Ruby 3.x 的 **kwargs 传参
+      options = (options_hash || {}).merge(keyword_options)
+
+      # 尝试获取当前类上配置的 INSTANCE_INFO 常量作为默认选项
       options = "#{self.class}::INSTANCE_INFO".safe_constantize || {} if options.blank?
+
+      # 将 options 的 key 转为 symbol，避免传入字符串 key 导致匹配不到
+      options = options.deep_symbolize_keys
+
       result = {}
-      # 仅包含的字段
+
+      # 1. 整理包含字段和排除字段
       only_attributes = (options[:only] || []).map(&:to_sym)
-      # 要排除的字段
-      # 默认不包含 :deleted, :deleted_by 和 :deleted_at 三个字段
+
+      # 默认排除逻辑：如果不特意指定，系统会默认排除 deleted 等敏感字段，防止软删除数据泄漏
       default_deleted_column = ::Constants::Base::TABLE_COLUMN_DELETE_COLUMN rescue 'deleted'
       default_except_attrs = [
         default_deleted_column,
@@ -48,42 +87,48 @@ module ActivemodelObjectInfo
         "#{default_deleted_column}_at",
       ]
       except_attributes = (options[:except] || default_except_attrs).map(&:to_sym)
-      # 字段的具体属性设置
+
+      # 2. 从当前类所有属性中计算出最终要输出的属性名集合
       attribute_configs = options[:attributes] || []
-      # 计算要输出的参数名称
       output_attributes = attribute_names.map(&:to_sym)
       output_attributes &= only_attributes if only_attributes.present?
       output_attributes -= except_attributes
 
-      # puts "Excepts: #{except_attributes}, Only: #{only_attributes}, Output: #{output_attributes}"
+      # 3. 遍历并处理属性配置（attribute_configs）
       # 这里保证了要引入的类中含有 attributes 方法，且为 Hash 类型
+
+      # 补丁：如果传入了 only_attributes，但是 options[:attributes] 是空（即调用方没传），
+      # 我们需要将 only_attributes 中的字段视为基础配置，以确保只包含这几个字段的正常输出
+      attribute_configs = only_attributes.map { |attr| { name: attr } } if attribute_configs.empty? && only_attributes.present?
+
       attribute_configs.each do |attr_config|
-        # 如果设置项单纯是字符串或者标识符的情况
+        # 根据配置项的类型（Symbol/String 或 Hash）提取字段名称和具体配置
         if [::String, ::Symbol].any? { |attr_class| attr_config.is_a?(attr_class) }
           attribute_name = attr_config.to_sym
           current_attr_config = {}
-        elsif attr_config.is_a?(::Hash) # 如果设置项为一个散列
+        elsif attr_config.is_a?(::Hash)
           current_attr_config = attr_config.deep_symbolize_keys
           attribute_name = current_attr_config[:name]
-        else # 如果不是指定的类型，则跳过进行下一项
+        else
+          # 如果配置格式非法则直接跳过
           next
         end
-        # 输出的参数名称，如果用户给出了 as 指定，优先用用户给定的，否则默认用属性名
+
+        # 确定实际取值的属性名，支持通过 as 别名取值
         raw_name = current_attr_config[:as].present? ? current_attr_config[:as].to_sym : attribute_name
-        # 过滤器输出字段，如果给定了一个块，则使用用户指定的，否则默认为没有过滤器
         filter = current_attr_config[:filter]
 
-        # 获取真正对应的属性的名称和其值
+        # 取出对象中的实际值
         k = raw_name
-        # 当类型为抽象类时，是不会有对应的方法和属性的，因此直接设置为 nil 并期待之后的 filter 等规则来生成实际值。
+        # 特殊处理 abstract 类型：当类型为抽象类时，由于可能没有对应的真实属性方法，直接赋值为 nil，后续依赖 filter 来生成实际值
         v = current_attr_config[:type] == :abstract ? nil : __send__(k)
 
-        # puts "instance attributes #{k}: #{v}(#{v.class.name})"
-        # 如果不是要输出的字段则跳过，或者如果不是给出type设置项为 :method 或者 :abstract 也跳过。
+        # 跳过条件：既不在最终输出名单中，也不是显式声明的 abstract/method 虚拟字段
         next unless output_attributes.include?(k) || %i[abstract method].include?(current_attr_config[:type])
 
-        # 赋值。如果有过滤器，优先使用过滤器
+        # 4. 根据类型或 filter 对值进行格式化转换
         if filter.present?
+          # 如果配置了 filter，通过 Proc、Symbol(调用同名方法) 或 直接常量 的形式进行过滤转换
           result[attribute_name] = case filter
                                    when ::Proc
                                      instance_exec(v, &filter)
@@ -92,28 +137,29 @@ module ActivemodelObjectInfo
                                    else
                                      filter
                                    end
-        # 如果值是时间类别的字段，默认转换为时间日期格式的字符串
         elsif [::Date, ::Time, ::DateTime].any? { |time_class| v.is_a?(time_class) }
-          # 时间日期格式设定，优先使用当前字段自定义，否则使用通用自定义，最后使用默认格式
+          # 对时间类型的字段进行格式化，优先级：字段级自定义 format > 全局 datetime_format > 默认全格式
           attribute_format = current_attr_config[:format].present? ? current_attr_config[:format] : options[:datetime_format]
-          result[attribute_name] = if attribute_format.to_s == 'standard' # 会被转换为标准时间日期格式
-                                     v
-                                   elsif attribute_format.present? # 按照设定时间日期方法的格式
-                                     # 旧有格式匹配支持
+          result[attribute_name] = if attribute_format.to_s == 'standard'
+                                     v # standard 保持时间对象原生格式
+                                   elsif attribute_format.present?
+                                     # 匹配内置的别名格式 (full/min/date/month/year)，否则作为自定义 strftime 字符串处理
                                      if %i[full min date month year].include?(attribute_format.to_sym)
                                        v.strftime("::#{self.class}::DATETIME_#{attribute_format.to_s.upcase}".constantize)
-                                     else # 否则认为直接传递的是 strftime 支持的自定义格式
+                                     else
                                        v.strftime(attribute_format)
                                      end
-                                   else # 默认使用 'yyyy-MM-dd hh:mm:ss' 的格式
+                                   else
+                                     # 缺省转换为 '%Y-%m-%d %H:%M:%S'
                                      v.strftime(DATETIME_FULL)
                                    end
-        else # 其他值类型默认赋值自己
+        else
+          # 普通值直接赋值
           result[attribute_name] = v
         end
       end
 
-      # 过滤第一层键名为符号并返回
+      # 统一将结果第一层的键名转化为 Symbol 格式并返回
       result.symbolize_keys!
     end
   end

data/lib/activemodel_object_info/deleted_operation.rb

@@ -4,59 +4,97 @@ module ActivemodelObjectInfo
   #
   # 用来进行和删除操作相关的数据库模型的功能模组。主要结合了使用 +:deleted+ 字段标识数据软删除的功能。
   #
+  # 核心作用与职责：
+  # 为 ActiveRecord 模型提供标准化的“软删除（Soft Delete）”功能。
+  # 引入该模块后，会自动通过 `default_scope` 过滤掉已标记为删除的记录，
+  # 并注入 `soft_delete` / `soft_delete!` 方法。在执行软删除时，会自动更新
+  # 相关的审计字段（如 deleted_by, deleted_at, updated_by）。
+  #
+  # @example 详细使用方法与示例
+  #   class User < ApplicationRecord
+  #     include ActivemodelObjectInfo::DeletedOperation
+  #
+  #     # 可选：覆盖默认的配置常量
+  #     DELETED_FIELD = 'is_deleted'
+  #     DELETED_VALID_VALUE = false
+  #     DELETED_INVALID_VALUE = true
+  #   end
+  #
+  #   # 查询数据时会自动应用 default_scope: WHERE is_deleted = false
+  #   User.all
+  #
+  #   # 软删除一条记录（必须要传入 user_id）
+  #   user = User.find(1)
+  #   user.soft_delete(user_id: current_user.id, refresh_updated: true)
+  #
+  # 核心重要方法：
+  # - {#soft_delete}：执行软删除并调用 save 更新数据。
+  # - {#soft_delete!}：执行软删除并调用 save! 更新数据（抛出异常）。
+  # - {#delete_block}：底层通用的删除字段赋值逻辑块。
+  #
   # @author shiner527 <shiner527@hotmail.com>
   #
+  # [Changelog]
+  #   [2026-07-28] 补充完整 YARD 文档、行内注释，清理尾随空格 (shiner527)
+  #   [2021-04-19] 创建基础模块，提供软删除与作用域注入功能 (shiner527)
+  #
   module DeletedOperation
     extend ::ActiveSupport::Concern
 
     # 当被 include 关键字引入后的处理
     included do |_|
-      # 定义好默认的删除查询语句
+      # 1. 提取常量配置：如果宿主类定义了覆盖常量，则使用宿主类的，否则使用默认值
       deleted_field = const_defined?(:DELETED_FIELD) ? DELETED_FIELD : 'deleted'
       deleted_value_valid = const_defined?(:DELETED_VALID_VALUE) ? DELETED_VALID_VALUE : 0
       deleted_value_invalid = const_defined?(:DELETED_INVALID_VALUE) ? DELETED_INVALID_VALUE : 1
-      # 如果定义了删除标记字段则默认搜索自动排除该内容
+
+      # 2. 注入 default_scope 默认查询作用域：如果模型拥有删除标记字段，则默认查询自动排除被标记的数据
       default_scope do
         _current_model = try(:name).to_s.safe_constantize
-        where(deleted_field.to_sym => deleted_value_valid) if _current_model.method_defined?(deleted_field)
+        where(deleted_field.to_sym => deleted_value_valid) if _current_model.has_attribute?(deleted_field)
       end
 
-      # 通用的删除过程
+      # 3. 定义底层的删除逻辑块 (给实例对象的内存属性赋值)
       define_method(:delete_block) do |**options|
-        # 处理可选项参数
+        # 处理可选项参数：默认不刷新 updated_at 字段
         options[:refresh_updated] = options[:refresh_updated].nil? ? false : options[:refresh_updated]
 
-        # 必须要传递操作的用户ID信息
+        # 必须要传递操作的用户ID信息，强制审计规范
         raise ArgumentError, 'Must give user id!' if options[:user_id].blank?
 
-        # 获取更新人字段，删除人字段
+        # 提取字段名配置
         updated_by_field = (options[:updated_by_field] || 'updated_by').to_sym
         deleted_by_field = (options[:deleted_by_field] || 'deleted_by').to_sym
         deleted_at_field = (options[:deleted_at_field] || 'deleted_at').to_sym
-        # 设置删除状态为已失效
+
+        # 核心：设置删除状态为已失效标记值
         __send__("#{deleted_field}=", deleted_value_invalid)
-        # 设置删除人、删除时间和更新人
+
+        # 审计：如果模型存在对应的审计字段，则设置删除人、删除时间，以及根据配置选择性地设置更新人
         __send__("#{deleted_by_field}=", options[:user_id]) if respond_to?(deleted_by_field)
         __send__("#{deleted_at_field}=", Time.now.localtime) if respond_to?(deleted_at_field)
         __send__("#{updated_by_field}=", options[:user_id]) if respond_to?(updated_by_field) && options[:refresh_updated]
       end
 
-      # 定义删除方法，但是不覆盖 ActiveRecord 的同名方法。
+      # 4. 暴露的常规软删除方法 (使用 save 存储，返回 boolean)
       define_method(:soft_delete) do |**options|
         opts = options.deep_symbolize_keys
-        # 如果没有定义删除标记字段则不执行
+        # 安全防范：如果没有定义删除标记字段则直接返回，不执行任何操作
         return unless respond_to?(deleted_field)
+
         delete_block(**opts)
-        # 根据设置决定是否刷更新时间
+
+        # 调用 ActiveRecord 内置方法持久化，根据 refresh_updated 参数决定是否让系统自动更新 updated_at
         save(touch: opts[:refresh_updated])
       end
 
-      # 定义删除方法，区别为最终调用 save! 方法更新数据，所以遇到异常会抛出异常
+      # 5. 暴露的强校验软删除方法 (使用 save! 存储，失败抛出异常)
       define_method(:soft_delete!) do |**options|
         opts = options.deep_symbolize_keys
         return unless respond_to?(deleted_field)
+
         delete_block(**opts)
-        # 根据设置决定是否刷更新时间
+
         save!(touch: opts[:refresh_updated])
       end
     end

data/lib/activemodel_object_info/table_definition.rb

@@ -5,8 +5,38 @@ module ActivemodelObjectInfo
   # 重新扩展一些方法，用来方便在创建迁移文件的时候进行一些通用类的设定。
   # 从 @version 0.3.0 开始支持了自动创建的时间戳字段增加索引
   #
+  # 核心作用与职责：
+  # 在 ActiveRecord 数据库迁移（Migration）建表时，提供便捷的宏方法，
+  # 一键生成通用的审计追踪字段（如操作人、操作时间）及软删除字段。
+  #
+  # @example 详细使用方法与示例
+  #   class CreateUsers < ActiveRecord::Migration[6.1]
+  #     def change
+  #       create_table :users do |t|
+  #         t.string :name
+  #
+  #         # 示例1: 生成指定的自定义操作字段
+  #         t.operation_columns(:audit, with_operator: true, operator_prefix: 'my_', operator_suffix: '_user')
+  #         # => 将会生成 my_audit_user (bigint) 和 audit_at (datetime) 字段
+  #
+  #         # 示例2: 生成常用的创建、更新、删除字段套装
+  #         t.generate_operations
+  #         # => 将会生成 created_by, created_at, updated_by, updated_at, deleted_by, deleted_at, 以及 deleted(integer)
+  #       end
+  #     end
+  #   end
+  #
+  # 核心重要方法：
+  # - {#operation_columns}：生成指定操作的审计字段（含前缀、后缀配置）。
+  # - {#generate_operations}：批量生成创建、更新、删除相关的全套审计字段。
+  #
   # @author shiner527 <shiner527@hotmail.com>
   #
+  # [Changelog]
+  #   [2026-07-28] 补充完整 YARD 文档、行内注释，清理尾随空格 (shiner527)
+  #   [2021-04-20] 支持自动创建的时间戳字段增加索引 (@version 0.3.0) (shiner527)
+  #   [2021-04-19] 创建基础模块，提供 operation_columns 与 generate_operations (shiner527)
+  #
   module TableDefinition
     #
     # 生成操作相关的字段。包含操作人、操作时间等信息。
@@ -38,21 +68,23 @@ module ActivemodelObjectInfo
     #
     def operation_columns(*fields, **options)
       # puts "operation_columns(#{fields}, #{options})"
-      # 初始化设置选项
+      # 1. 提取并初始化各种设置选项，对于布尔值优先取用户配置，未配置则默认为 true
       with_operator = options[:with_operator].nil? ? true : options[:with_operator]
       with_timestamp = options[:with_timestamp].nil? ? true : options[:with_timestamp]
       operator_prefix = options[:operator_prefix]
       operator_suffix = options[:operator_suffix] || '_by'
       timestamp_prefix = options[:timestamp_prefix]
       timestamp_suffix = options[:timestamp_suffix] || '_at'
-      # 依照每个字段进行设置
+
+      # 2. 遍历每一个需要生成的操作标识符
       fields.each do |field|
-        # 如果要生成操作人信息
+        # 3. 动态拼接并生成操作人记录字段 (默认为 bigint 类型并添加索引)
         if with_operator
           operator_column_name = operator_prefix.to_s + field.to_s + operator_suffix.to_s
           column(operator_column_name, :bigint, index: true, comment: '操作人') if operator_column_name.present?
         end
-        # 如果要生成操作时间戳信息
+
+        # 4. 动态拼接并生成操作时间戳字段 (默认为 datetime 类型并添加索引)
         if with_timestamp
           timestamp_column_name = timestamp_prefix.to_s + field.to_s + timestamp_suffix.to_s
           column(timestamp_column_name, :datetime, index: true, comment: '操作时间戳') if timestamp_column_name.present?
@@ -70,10 +102,16 @@ module ActivemodelObjectInfo
     def generate_operations(*operations)
       # puts "generate_operations(#{operations})"
       action_fields = operations
-      # 默认只有创建、更新和删除相关的字段
+
+      # 1. 如果没有给出具体的动作名称，默认配置为创建、更新和删除这三个常规生命周期动作
       action_fields = %w[created updated deleted] if action_fields.empty?
+
+      # 2. 遍历所有的动作名称以生成相应的字段
       action_fields.each do |operation|
+        # 3. 特殊逻辑：当遇到 deleted 动作时，除了生成审计字段外，还需要额外部署一个整型的标记字段，用于承载软删除状态
         column(operation.to_s, :integer, default: 0, comment: '删除标记') if operation.to_sym == :deleted
+
+        # 4. 复用 operation_columns 方法来生成对应的 xxx_by 操作人和 xxx_at 操作时间字段
         operation_columns(operation)
       end
     end

data/lib/activemodel_object_info/version.rb

@@ -2,6 +2,6 @@
 
 module ActivemodelObjectInfo
   module Version
-    VERSION = '0.3.3'
+    VERSION = '0.4.0'
   end
 end

data/lib/activemodel_object_info.rb

@@ -7,9 +7,25 @@ require 'activemodel_object_info/table_definition'
 require 'activemodel_object_info/deleted_operation'
 
 #
-# 扩展模组。
+# 扩展模组主入口。
+#
+# 核心作用与职责：
+# 这是 activemodel-object-info Gem 的主命名空间和入口文件。
+# 它负责统一加载所有相关的依赖库（ActiveSupport）和内部子模块（Base, TableDefinition, DeletedOperation）。
+#
+# @example 详细使用方法
+#   require 'activemodel_object_info'
+#
+# 包含的核心模块：
+# - {ActivemodelObjectInfo::Base}：提供模型对象信息格式化输出能力。
+# - {ActivemodelObjectInfo::TableDefinition}：提供数据库迁移时自动生成审计字段的能力。
+# - {ActivemodelObjectInfo::DeletedOperation}：提供记录软删除及其作用域管理的能力。
 #
 # @author shiner527 <shiner527@hotmail.com>
 #
+# [Changelog]
+#   [2026-07-28] 补充完整 YARD 文档 (shiner527)
+#   [2021-04-19] 创建基础模块结构及入口文件 (shiner527)
+#
 module ActivemodelObjectInfo
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activemodel_object_info
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - shiner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-30 00:00:00.000000000 Z
+date: 2026-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -156,6 +156,7 @@ files:
 - Gemfile.lock
 - LICENSE
 - README.md
+- README.zh-CN.md
 - Rakefile
 - activemodel_object_info.gemspec
 - bin/console
@@ -185,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Build a hash based on active record attributes.