rails_badgeable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdf33a8abbd83c9d997979dfb8e2a54db42bcb6d93d3330da510cfc25af16365
+  data.tar.gz: 718c6e9c4129ee455a4e1c8da84e7d8a09c5f417f0562ba5d51057bcba8752b1
+SHA512:
+  metadata.gz: 49607b5870779c82353a54f74712ece2a843f7eb0e1be2185615c1576430edf7316c1f323a7c7f571f411dc851825fbfd9ec3c130e45a7c585a663959f981afe
+  data.tar.gz: 977e2b6bdae4996c37a663679982f4ca223e9d794559fff527a230ac13031dc73abcf53294d78402f81eb7571c3b6dee6e1911a511338fb98b764867bc29c8ef

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright aric.zheng
+
+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,83 @@
+# rails_badgeable
+
+A lightweight, reusable Rails Engine for adding badges to any ActiveRecord model via polymorphic many-to-many relationships.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_badgeable'
+```
+
+Then run:
+```bash
+rails rails_badgeable:install:migrations
+rails db:migrate
+```
+
+## Usage
+
+Include the concern in any model:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsBadgeable::HasBadges
+end
+
+post = Post.create(title: "Hello")
+# 创建或查找一个名为 "Important" 的 badge
+badge = RailsBadgeable::Badge.find_or_create_by(name: "Important")
+
+# 将 badge 分配给 post
+post.badges << badge
+
+# 查询：这个 badge 分配给了哪些 posts？
+# 返回所有带有 "Important" badge 的 Post 记录
+badge.assigned_to(Post)  # => [post]
+
+# 查询：Post 模型使用过哪些 badges？
+# 返回所有曾经分配给 Post 的 badges（排除从未使用过的）
+RailsBadgeable::Badge.for_model(Post)  # => [badge]
+```
+
+## Using Short Alias (Optional)
+
+If you prefer using `Badge` instead of `RailsBadgeable::Badge`, use the generator to create an alias initializer:
+
+```bash
+rails generate rails_badgeable:alias
+```
+
+This creates `config/initializers/badgeable.rb` with the following:
+
+```ruby
+Badge = RailsBadgeable::Badge unless defined?(Badge)
+BadgeAssignment = RailsBadgeable::BadgeAssignment unless defined?(BadgeAssignment)
+```
+
+Then you can use the short form:
+
+```ruby
+# Instead of RailsBadgeable::Badge
+Badge.find_or_create_by(name: "Important")
+
+# Instead of RailsBadgeable::BadgeAssignment
+BadgeAssignment.all
+```
+
+## Available Methods
+
+### Instance Methods (on a Badge object)
+
+- `badge.assigned_to(klass)` - Returns all records of the given class that have this badge
+
+### Class Methods (on Badge class)
+
+- `RailsBadgeable::Badge.for_model(klass)` - Returns all badges ever used on the given model class
+
+### Model Methods (on models with HasBadges)
+
+- `post.badges` - Returns all badges assigned to this post
+- `post.badges << badge` - Assign a badge to this post
+- `post.badges.destroy(badge)` - Remove a badge from this post

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/models/concerns/rails_badgeable/has_badges.rb

@@ -0,0 +1,16 @@
+module RailsBadgeable
+  module HasBadges
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :rails_badgeable_assignments,
+               as: :assignable,
+               class_name: "RailsBadgeable::BadgeAssignment",
+               dependent: :destroy
+
+      has_many :badges,
+               through: :rails_badgeable_assignments,
+               class_name: "RailsBadgeable::Badge"
+    end
+  end
+end

data/app/models/rails_badgeable/badge.rb

@@ -0,0 +1,21 @@
+module RailsBadgeable
+  class Badge < ApplicationRecord
+    self.table_name = "rails_badgeable_badges"
+
+    has_many :assignments, class_name: "RailsBadgeable::BadgeAssignment", dependent: :destroy
+
+    validates :name, presence: true, uniqueness: true
+
+    # Returns all associated records of the given class that have this badge
+    def assigned_to(klass)
+      assignable_ids = assignments.where(assignable_type: klass.base_class.name).pluck(:assignable_id)
+      klass.where(id: assignable_ids)
+    end
+
+    # Class method: Returns all badges ever used on the given model class
+    def self.for_model(klass)
+      badge_ids = BadgeAssignment.where(assignable_type: klass.base_class.name).distinct.pluck(:badge_id)
+      where(id: badge_ids)
+    end
+  end
+end

data/app/models/rails_badgeable/badge_assignment.rb

@@ -0,0 +1,12 @@
+module RailsBadgeable
+  class BadgeAssignment < ApplicationRecord
+    self.table_name = "rails_badgeable_assignments"
+
+    belongs_to :badge, class_name: "RailsBadgeable::Badge"
+    belongs_to :assignable, polymorphic: true
+
+    validates :badge, presence: true
+    validates :assignable, presence: true
+    validates :badge_id, uniqueness: { scope: [:assignable_type, :assignable_id] }
+  end
+end

data/db/migrate/20250131000000_create_rails_badgeable_tables.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class CreateRailsBadgeableTables < ActiveRecord::Migration[6.0]
+  def change
+    # Create badges table
+    # To add custom fields to badges, add columns here, e.g.:
+    #   t.string :color, default: '#007bff'
+    #   t.string :icon
+    create_table :rails_badgeable_badges do |t|
+      t.string :name, null: false
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :rails_badgeable_badges, :name, unique: true
+
+    # Create join table for polymorphic associations
+    # To add custom fields to assignments, add columns here, e.g.:
+    #   t.string :reason
+    #   t.references :granted_by, foreign_key: { to_table: :users }
+    create_table :rails_badgeable_assignments do |t|
+      t.references :badge, null: false, foreign_key: { to_table: :rails_badgeable_badges }
+      t.references :assignable, polymorphic: true, null: false, index: false
+
+      t.timestamps
+    end
+
+    # Custom composite index with short name
+    add_index :rails_badgeable_assignments,
+              [:badge_id, :assignable_type, :assignable_id],
+              unique: true,
+              name: "index_badge_assignments"
+  end
+end

data/lib/generators/rails_badgeable/alias/USAGE

@@ -0,0 +1,34 @@
+Description:
+    Creates a short alias initializer for RailsBadgeable models.
+
+    This allows you to use `Badge` instead of `RailsBadgeable::Badge`
+    and `BadgeAssignment` instead of `RailsBadgeable::BadgeAssignment`.
+
+    The created initializer uses `unless defined?` guards to prevent
+    redefinition warnings if these constants already exist in your application.
+
+Example:
+    rails generate rails_badgeable:alias
+
+    This will create:
+        config/initializers/badgeable.rb
+
+Usage After Installation:
+    # Before (full namespace required):
+    RailsBadgeable::Badge.find_or_create_by(name: "Important")
+    RailsBadgeable::BadgeAssignment.all
+
+    # After (short alias available):
+    Badge.find_or_create_by(name: "Important")
+    BadgeAssignment.all
+
+To Remove:
+    Simply delete the generated file:
+        rm config/initializers/badgeable.rb
+
+    Then restart your server to use the full namespace again.
+
+Notes:
+    - This is completely optional - you can always use the full namespace
+    - The generator will not overwrite existing files (use --force to override)
+    - Restart your server after running this generator

data/lib/generators/rails_badgeable/alias/alias_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsBadgeable
+  module Generators
+    class AliasGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a short alias initializer for RailsBadgeable models.'
+
+      def create_alias_initializer
+        template 'badgeable.rb', 'config/initializers/badgeable.rb'
+      end
+    end
+  end
+end

data/lib/generators/rails_badgeable/alias/templates/badgeable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Short alias for RailsBadgeable models
+# This allows you to use `Badge` instead of `RailsBadgeable::Badge`
+#
+# Usage:
+#   Badge.find_or_create_by(name: "Important")
+#   BadgeAssignment.all
+
+Badge = RailsBadgeable::Badge unless defined?(Badge)
+BadgeAssignment = RailsBadgeable::BadgeAssignment unless defined?(BadgeAssignment)

data/lib/rails_badgeable/engine.rb

@@ -0,0 +1,5 @@
+module RailsBadgeable
+  class Engine < ::Rails::Engine
+    # Non-mountable engine - no isolate_namespace needed
+  end
+end

data/lib/rails_badgeable/version.rb

@@ -0,0 +1,3 @@
+module RailsBadgeable
+  VERSION = "0.1.0"
+end

data/lib/rails_badgeable.rb

@@ -0,0 +1,6 @@
+require "rails_badgeable/version"
+require "rails_badgeable/engine"
+
+module RailsBadgeable
+  # Models and concerns are autoloaded by Rails
+end

data/lib/tasks/rails_badgeable_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_badgeable do
+#   # Task goes here
+# end

data/llms.txt

@@ -0,0 +1,294 @@
+# Rails Badgeable
+
+> Rails Badgeable is a lightweight, reusable Rails Engine that enables any ActiveRecord model to associate with a finite set of predefined badges via polymorphic many-to-many relationships.
+
+It provides a clean, namespace-isolated way to add badge functionality to your Rails applications without polluting your models or database schema. The engine uses standard Rails conventions and is fully compatible with Rails 6.0+.
+
+**Important notes for AI agents:**
+- This is a Rails Engine, not a mountable engine (no routes, controllers, or views)
+- All models are namespaced under `RailsBadgeable` module
+- Table names are explicitly set to avoid conflicts: `rails_badgeable_badges` and `rails_badgeable_assignments`
+- The engine uses polymorphic associations, allowing badges to be assigned to ANY model
+- An optional generator is available for creating short aliases (e.g., `Badge` instead of `RailsBadgeable::Badge`)
+
+## Documentation
+
+- [GitHub Repository](https://github.com/afeiship/rails_badgeable): Source code and issue tracking
+- [README](README.md): Installation guide and basic usage examples
+- [Requirements](docs/01-requirement.md): Detailed project requirements and design specifications
+
+## Key Features
+
+- **Polymorphic Associations:** Assign badges to any ActiveRecord model (Post, User, Comment, etc.)
+- **Database-level Constraints:** Unique indexes prevent duplicate badge assignments
+- **Namespace Isolated:** All models under `RailsBadgeable` namespace to avoid conflicts
+- **Explicit Table Names:** No reliance on Rails auto-inflection
+- **Optional Short Aliases:** Generator for `Badge` and `BadgeAssignment` aliases
+- **Rails 6.0+ Compatible:** Works with modern Rails versions
+- **Zero Configuration:** Works out of the box after migration
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails_badgeable'
+```
+
+Run migrations:
+
+```bash
+rails rails_badgeable:install:migrations
+rails db:migrate
+```
+
+## Basic Usage
+
+### Include the Concern
+
+```ruby
+class Post < ApplicationRecord
+  include RailsBadgeable::HasBadges
+end
+
+class WorkLog < ApplicationRecord
+  include RailsBadgeable::HasBadges
+end
+```
+
+### Create and Assign Badges
+
+```ruby
+# Create or find a badge
+badge = RailsBadgeable::Badge.find_or_create_by(name: "Important", description: "Important content")
+
+# Assign to a post
+post = Post.create(title: "Hello World")
+post.badges << badge
+
+# Check if post has the badge
+post.badges.include?(badge) # => true
+```
+
+### Query Methods
+
+```ruby
+# Get all posts with a specific badge
+badge.assigned_to(Post)
+# => [#<Post id: 1, ...>, #<Post id: 3, ...>]
+
+# Get all badges ever used on Post model
+RailsBadgeable::Badge.for_model(Post)
+# => [#<RailsBadgeable::Badge name: "Important">, ...]
+```
+
+### Remove Badges
+
+```ruby
+# Remove a specific badge
+post.badges.destroy(badge)
+
+# Remove all badges
+post.badges.clear
+```
+
+## Optional Short Alias Generator
+
+For cleaner code, generate short aliases:
+
+```bash
+rails generate rails_badgeable:alias
+```
+
+This creates `config/initializers/badgeable.rb`:
+
+```ruby
+Badge = RailsBadgeable::Badge unless defined?(Badge)
+BadgeAssignment = RailsBadgeable::BadgeAssignment unless defined?(BadgeAssignment)
+```
+
+Then use short form:
+
+```ruby
+Badge.find_or_create_by(name: "Featured")
+BadgeAssignment.all
+```
+
+## Database Schema
+
+### badges table
+
+```ruby
+create_table :rails_badgeable_badges do |t|
+  t.string :name, null: false
+  t.text :description
+  t.timestamps
+end
+
+add_index :rails_badgeable_badges, :name, unique: true
+```
+
+### assignments table (join table)
+
+```ruby
+create_table :rails_badgeable_assignments do |t|
+  t.references :badge, null: false, foreign_key: { to_table: :rails_badgeable_badges }
+  t.references :assignable, polymorphic: true, null: false
+  t.timestamps
+end
+
+add_index :rails_badgeable_assignments,
+          [:badge_id, :assignable_type, :assignable_id],
+          unique: true,
+          name: "index_badge_assignments"
+```
+
+## Available Methods
+
+### Badge Instance Methods
+
+- `badge.assigned_to(klass)` - Returns all records of the given class that have this badge
+  ```ruby
+  badge.assigned_to(Post)  # => [post1, post2]
+  badge.assigned_to(User)  # => [user1, user3]
+  ```
+
+### Badge Class Methods
+
+- `RailsBadgeable::Badge.for_model(klass)` - Returns all badges ever used on the given model class
+  ```ruby
+  RailsBadgeable::Badge.for_model(Post)  # => [badge1, badge2]
+  ```
+
+### Model Methods (with HasBadges concern)
+
+- `model.badges` - Returns all badges assigned to this record
+- `model.badges << badge` - Assign a badge to this record
+- `model.badges.delete(badge)` - Remove a specific badge
+- `model.badges.clear` - Remove all badges
+- `model.rails_badgeable_assignments` - Direct access to join records
+
+## Advanced Usage
+
+### Custom Fields
+
+You can add custom fields to badges or assignments via migrations:
+
+```ruby
+# Add custom fields to badges
+add_column :rails_badgeable_badges, :color, :string, default: '#007bff'
+add_column :rails_badgeable_badges, :icon, :string
+
+# Add custom fields to assignments
+add_column :rails_badgeable_assignments, :reason, :text
+add_column :rails_badgeable_assignments, :granted_by_id, :integer
+add_column :rails_badgeable_assignments, :granted_at, :datetime
+```
+
+### Accessing Assignment Data
+
+```ruby
+# Get assignment metadata
+assignment = post.rails_badgeable_assignments.find_by(badge_id: 1)
+assignment.reason  # => "Community contribution"
+assignment.created_at  # => assignment time
+```
+
+### Conditional Scopes
+
+Add scopes to your models:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsBadgeable::HasBadges
+
+  scope :important, -> { joins(:badges).where(rails_badgeable_badges: { name: 'Important' }) }
+  scope :featured, -> { joins(:badges).where(rails_badgeable_badges: { name: 'Featured' }) }
+end
+
+# Usage
+Post.important  # All posts with "Important" badge
+Post.featured   # All posts with "Featured" badge
+```
+
+## API Example (with dummy app)
+
+The included dummy app demonstrates API usage:
+
+```bash
+# Start server
+cd test/dummy
+bin/rails server
+
+# API endpoints
+GET    /api/badges                          # List all badges
+POST   /api/badges                          # Create badge
+GET    /api/badges/:id                      # Get badge
+PUT    /api/badges/:id                      # Update badge
+DELETE /api/badges/:id                      # Delete badge
+GET    /api/badges/:id/assigned_to?model_type=Post  # Get records with badge
+
+GET    /api/posts                           # List posts
+POST   /api/posts                           # Create post
+GET    /api/posts/:id                       # Get post (includes badges)
+PUT    /api/posts/:id                       # Update post
+DELETE /api/posts/:id                       # Delete post
+GET    /api/posts/:id/badges                # Get post's badges
+POST   /api/posts/:id/badges?badge_id=X     # Add badge to post
+DELETE /api/posts/:post_id/badges/:badge_id # Remove badge from post
+```
+
+## Testing
+
+Run tests with:
+
+```bash
+cd test/dummy
+bin/rails test
+```
+
+## Project Structure
+
+```
+lib/
+├── rails_badgeable.rb              # Main entry point
+├── rails_badgeable/
+│   ├── engine.rb                   # Engine definition
+│   └── version.rb                  # Version info
+app/models/
+├── rails_badgeable/
+│   ├── badge.rb                    # Badge model
+│   └── badge_assignment.rb         # Join model
+└── models/concerns/
+    └── rails_badgeable/
+        └── has_badges.rb           # Concern for host models
+db/migrate/
+└── xxx_create_rails_badgeable_tables.rb  # Migration generator
+lib/generators/
+└── rails_badgeable/
+    └── alias/                      # Short alias generator
+        ├── USAGE
+        ├── alias_generator.rb
+        └── templates/
+            └── badgeable.rb
+```
+
+## Usage Notes for Agents
+
+- **Always use full namespace** unless alias generator was run: `RailsBadgeable::Badge`
+- **Badge names are unique** - `find_or_create_by(name: "Important")` is safe
+- **Polymorphic type stores class name** - uses `base_class.name` for STI support
+- **Database prevents duplicates** - unique index on `[badge_id, assignable_type, assignable_id]`
+- **No automatic top-level constants** - users must run alias generator for `Badge` constant
+- **Engine is not mountable** - no routes, controllers, or views included
+- **Migrations must be copied** - use `rails rails_badgeable:install:migrations`
+- **Custom fields require migration** - add columns directly to tables if needed
+- **Join table accessible** - `model.rails_badgeable_assignments` for metadata access
+
+## Development
+
+- Rails Engine (non-mountable)
+- Ruby 3.0+ required
+- Rails 6.0+ compatible
+- MIT License
+- Author: aric.zheng <1290657123@qq.com>

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: rails_badgeable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- aric.zheng
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A lightweight Rails Engine that enables any ActiveRecord model to associate
+  with predefined badges via polymorphic many-to-many relationships. Features database-level
+  constraints, namespace isolation, and optional short aliases.
+email:
+- 1290657123@qq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/concerns/rails_badgeable/has_badges.rb
+- app/models/rails_badgeable/badge.rb
+- app/models/rails_badgeable/badge_assignment.rb
+- db/migrate/20250131000000_create_rails_badgeable_tables.rb
+- lib/generators/rails_badgeable/alias/USAGE
+- lib/generators/rails_badgeable/alias/alias_generator.rb
+- lib/generators/rails_badgeable/alias/templates/badgeable.rb
+- lib/rails_badgeable.rb
+- lib/rails_badgeable/engine.rb
+- lib/rails_badgeable/version.rb
+- lib/tasks/rails_badgeable_tasks.rake
+- llms.txt
+homepage: https://github.com/afeiship/rails_badgeable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/afeiship/rails_badgeable
+  changelog_uri: https://github.com/afeiship/rails_badgeable/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/afeiship/rails_badgeable/blob/main/README.md
+  ai_assistant_uri: https://github.com/afeiship/rails_badgeable/blob/main/llms.txt
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Rails engine for polymorphic, reusable badges on any model.
+test_files: []