rails_templatable 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a6b1d092af3d36bb5050dc292d447db84040459eff960a6fb4f7e6d012ef07c
-  data.tar.gz: 0115da00cf3adc178efaccdacf79c1942894886931543f81d5620aa5467ecf2f
+  metadata.gz: 1dc98737cfeeef797928b4f4c51fdeccbda1c4418a44232af9c856d7aab646e3
+  data.tar.gz: 97c2a8611ac44f12ca03b69461fa287e8da5ff978008af045087dfa56e915b18
 SHA512:
-  metadata.gz: d2ec972556b40651aecfaba05b9a23ec0321126838fda933adef084baea0003e474d1b1f0e3dccd7d23c20ac836fb1ce55052ec32f2689ccf9cd1dc7bad9feb7
-  data.tar.gz: af8843f690fa3b1c6c2bef5e982d540c00f7ef44d573ff9976b80c3601bbd5c02b2799c62118a6a74425334d08c383f077909059eca7af1f0f5c96d1f38dff11
+  metadata.gz: cebaebeec326a51b9e21cd53076845094f22f04b73f99afd672dc1eb2c9223ff01950698dcdc177d8b9923aae3e8dec64875f9e1e134a030ec80d4553a6171e8
+  data.tar.gz: 01357a634728a3243afa4e3919d6bd2c8333e5ec51a67f79194d27add6ae214f03ab4a835b3e2f2b14dbbd7f4a69eec5463f4917da90b421752f917e35527fb9

data/README.md

@@ -1,14 +1,13 @@
 # RailsTemplatable
 
-A lightweight Rails Engine that enables any ActiveRecord model to associate with templates for content management. Built with a polymorphic many-to-many relationship, allowing any model to have multiple templates.
+A lightweight Rails Engine that enables any ActiveRecord model to use predefined templates for content management. Built with a simple one-to-many relationship, allowing each model instance to have one template while templates can be reused across multiple instances.
 
 ## Features
 
-- 🎯 **Polymorphic Associations** - Attach templates to any ActiveRecord model
+- 🎯 **Simple 1:N Relationship** - Each record has one template, templates can be reused
 - 📝 **Multiple Content Formats** - Support for HTML, Markdown, and plain text
-- 🔗 **Many-to-Many Relationship** - Models can have multiple templates, templates can be used by multiple models
-- 🏷️ **Flexible Categories** - User-defined template categories (no hardcoded types)
-- 🔒 **Database Constraints** - Unique constraints at database level
+- 🏷️ **Flexible Categories** - Pre-defined categories (feature_request, bug_report, etc.) or custom
+- 🔗 **Direct Foreign Key** - No join table needed, cleaner database schema
 - 🚀 **Easy Integration** - Simple concern-based inclusion
 
 ## Installation
@@ -26,54 +25,90 @@ $ bin/rails railties:install:migrations FROM=rails_templatable
 $ bin/rails db:migrate
 ```
 
+For each model that will use templates, add a foreign key:
+
+```ruby
+add_reference :posts, :template,
+              foreign_key: { to_table: :rails_templatable_templates },
+              index: false
+```
+
 ## Quick Start
 
 ### 1. Enable templates in your models
 
 ```ruby
 class Post < ApplicationRecord
-  include RailsTemplatable::HasTemplates
+  include RailsTemplatable::HasTemplate
 end
 
 class WorkLog < ApplicationRecord
-  include RailsTemplatable::HasTemplates
+  include RailsTemplatable::HasTemplate
 end
 ```
 
 ### 2. Create templates
 
 ```ruby
-# HTML template
-email_template = RailsTemplatable::Template.create!(
-  category: "email_template",
-  content: "<h1>Welcome!</h1><p>Hello {{name}}</p>",
-  content_format: :html
+# Feature request template
+feature_template = RailsTemplatable::Template.create!(
+  category: "feature_request",
+  content: "# Feature Request\n\n## Description\n\n## Acceptance Criteria",
+  content_format: :markdown
 )
 
-# Markdown template
-doc_template = RailsTemplatable::Template.create!(
-  category: "documentation",
-  content: "# Documentation\n\nThis is a **markdown** template.",
+# Bug report template
+bug_template = RailsTemplatable::Template.create!(
+  category: "bug_report",
+  content: "## Bug Description\n\n## Steps to Reproduce\n\n## Expected Behavior",
   content_format: :markdown
 )
 ```
 
-### 3. Associate templates with models
+### 3. Assign templates to records
 
 ```ruby
-post = Post.create(title: "My Post", content: "Content here")
+post = Post.create!(
+  title: "Add user authentication",
+  content: "Implement OAuth2 login",
+  template: feature_template
+)
+
+# View template
+post.template.category  # => "feature_request"
+post.template.content   # => "# Feature Request..."
+```
+
+## Template Categories
+
+Common template categories included:
+
+| Category | Description |
+|----------|-------------|
+| `feature_request` | Feature requests |
+| `bug_report` | Bug reports |
+| `tech_improvement` | Technical improvements |
+| `meeting_note` | Meeting notes |
+| `api_design` | API designs |
 
-# Add templates
-post.templates << email_template
-post.templates << doc_template
+You can create any custom category as needed.
 
-# Query templates
-post.templates.where(category: "email_template")
+## Relationship Model
+
+**One-to-Many (1:N)**
+- One Post/WorkLog instance → One Template
+- One Template → Many instances
+
+Example:
+```
+Post 1 → Template A (feature_request)
+Post 2 → Template B (bug_report)
+Post 3 → Template A (feature_request)  # Reusable
 ```
 
 ## Content Formats
 
-The engine supports three content formats out of the box:
+Three content formats are supported:
 
 - `html` (0) - HTML content
 - `markdown` (1) - Markdown content
@@ -87,6 +122,22 @@ RailsTemplatable::Template.create!(
 )
 ```
 
+## Query Examples
+
+```ruby
+# Get a record's template
+post.template
+
+# Query by category
+Post.joins(:template).where(rails_templatable_templates: { category: 'feature_request' })
+
+# Get all records using a specific template
+Post.where(template: feature_template)
+
+# Query by content format
+Post.joins(:template).where(rails_templatable_templates: { content_format: 1 })
+```
+
 ## Database Schema
 
 ### rails_templatable_templates
@@ -99,41 +150,49 @@ RailsTemplatable::Template.create!(
 | `created_at` | datetime | Creation timestamp |
 | `updated_at` | datetime | Update timestamp |
 
-### rails_templatable_assignments
+### Target models (e.g., posts)
+
+Add `template_id` foreign key:
 
 | Column | Type | Description |
 |--------|------|-------------|
-| `template_id` | integer | Foreign key to template |
-| `templatable_id` | integer | Polymorphic foreign key ID |
-| `templatable_type` | string | Polymorphic foreign key type |
-| `created_at` | datetime | Creation timestamp |
-| `updated_at` | datetime | Update timestamp |
+| `template_id` | integer | Foreign key to rails_templatable_templates |
 
 ## Advanced Usage
 
-### Query helper methods
+### Change template
 
 ```ruby
-# Get all objects using a specific template
-template.assigned_to(Post)
-
-# Get all templates used on a specific model class
-RailsTemplatable::Template.for_model(Post)
+# Assigning a new template replaces the old one
+post.update(template: bug_template)
+post.template.category  # => "bug_report"
 ```
 
-### Checking template associations
+### Remove template
 
 ```ruby
-# Check if a post has email templates
-post.templates.where(category: "email_template").exists?
+post.update(template: nil)
+post.template  # => nil
+```
+
+### Assign template after creation
 
-# Get all HTML format templates
-post.templates.html
+```ruby
+post = Post.create(title: "New post")
+post.update(template: feature_template)
 ```
 
-## Why `category` instead of `type`?
+## Migration Example
 
-We use `category` instead of `type` to avoid conflicts with Rails' Single Table Inheritance (STI) feature, which reserves the `type` column for storing class names.
+```ruby
+class AddTemplateToPosts < ActiveRecord::Migration[6.0]
+  def change
+    add_reference :posts, :template,
+                  foreign_key: { to_table: :rails_templatable_templates },
+                  index: false
+  end
+end
+```
 
 ## Development
 
@@ -144,45 +203,20 @@ cd test/dummy
 ruby test_templatable.rb
 ```
 
-### Database schema
-
-After running migrations, your schema will include:
-
-```ruby
-create_table "rails_templatable_templates" do |t|
-  t.string "category", null: false
-  t.text "content"
-  t.integer "content_format", default: 2, null: false
-  t.index ["category"], name: "index_rails_templatable_templates_on_category"
-end
-
-create_table "rails_templatable_assignments" do |t|
-  t.integer "template_id", null: false
-  t.string "templatable_type", null: false
-  t.integer "templatable_id", null: false
-  t.index ["template_id", "templatable_type", "templatable_id"],
-          name: "index_templatable_assignments", unique: true
-end
-```
-
 ## Architecture
 
-This engine follows the same pattern as [rails_badgeable](https://github.com/afeiship/rails_badgeable):
+- **Direct Foreign Key** - No join table needed
+- **Simple & Clean** - One record = One template
+- **Flexible** - Templates can be changed anytime
+- **Efficient Queries** - Direct JOIN without intermediate table
 
-- **Isolated namespace** - All models namespaced under `RailsTemplatable`
-- **Polymorphic associations** - Using `templatable` for flexible model associations
-- **Concern-based inclusion** - Simple `include RailsTemplatable::HasTemplates` to enable
-- **Database-level constraints** - Unique indexes prevent duplicate associations
+## Comparison with N:N Design
 
-## Comparison with rails_badgeable
+If you need "one record has multiple templates", consider using a tag system or polymorphic many-to-many associations instead.
 
-| Feature | rails_badgeable | rails_templatable |
-|---------|-----------------|-------------------|
-| Main Model | Badge | Template |
-| Fields | name, description | category, content, content_format |
-| Enum Support | No | Yes (content_format) |
-| Polymorphic Name | assignable | templatable |
-| Concern | HasBadges | HasTemplates |
+## Why `category` instead of `type`?
+
+We use `category` instead of `type` to avoid conflicts with Rails' Single Table Inheritance (STI) feature, which reserves the `type` column for storing class names.
 
 ## Future Enhancements
 

data/app/models/concerns/rails_templatable/has_template.rb

@@ -0,0 +1,12 @@
+module RailsTemplatable
+  module HasTemplate
+    extend ActiveSupport::Concern
+
+    included do
+      # Each model instance can have only one template
+      belongs_to :template,
+                 class_name: "RailsTemplatable::Template",
+                 optional: true
+    end
+  end
+end

data/app/models/rails_templatable/template.rb

@@ -2,24 +2,21 @@ module RailsTemplatable
   class Template < ApplicationRecord
     self.table_name = "rails_templatable_templates"
 
-    has_many :assignments, class_name: "RailsTemplatable::TemplateAssignment", dependent: :destroy
-
     enum :content_format, { html: 0, markdown: 1, txt: 2 }
 
     validates :category, presence: true
     validates :content, presence: true
     validates :content_format, presence: true
 
-    # Returns all associated records of the given class that have this template
-    def assigned_to(klass)
-      templatable_ids = assignments.where(templatable_type: klass.base_class.name).pluck(:templatable_id)
-      klass.where(id: templatable_ids)
-    end
-
-    # Class method: Returns all templates ever used on the given model class
-    def self.for_model(klass)
-      template_ids = TemplateAssignment.where(templatable_type: klass.base_class.name).distinct.pluck(:template_id)
-      where(id: template_ids)
-    end
+    # Note: This template can be referenced by any model that includes HasTemplate concern.
+    # Target models should define their own has_many relationship if needed.
+    #
+    # Example in target model:
+    #   class Post < ApplicationRecord
+    #     include RailsTemplatable::HasTemplate
+    #
+    #     # Optional: define reverse association
+    #     has_many :feature_posts, class_name: "Post", foreign_key: :template_id
+    #   end
   end
 end

data/db/migrate/20250207000000_create_rails_templatable_tables.rb

@@ -16,21 +16,14 @@ class CreateRailsTemplatableTables < ActiveRecord::Migration[6.0]
 
     add_index :rails_templatable_templates, :category
 
-    # Create join table for polymorphic associations
-    # To add custom fields to assignments, add columns here, e.g.:
-    #   t.integer :priority
-    #   t.boolean :active, default: true
-    create_table :rails_templatable_assignments do |t|
-      t.references :template, null: false, foreign_key: { to_table: :rails_templatable_templates }
-      t.references :templatable, polymorphic: true, null: false, index: false
-
-      t.timestamps
-    end
-
-    # Custom composite index with short name
-    add_index :rails_templatable_assignments,
-              [:template_id, :templatable_type, :templatable_id],
-              unique: true,
-              name: "index_templatable_assignments"
+    # Note: No join table needed.
+    # Target models (posts, work_logs, etc.) should add their own template_id foreign key:
+    #
+    #   add_reference :posts, :template,
+    #                 foreign_key: { to_table: :rails_templatable_templates },
+    #                 index: false
+    #   add_reference :work_logs, :template,
+    #                 foreign_key: { to_table: :rails_templatable_templates },
+    #                 index: false
   end
 end

data/lib/rails_templatable/version.rb

@@ -1,3 +1,3 @@
 module RailsTemplatable
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/llms.txt

@@ -1,14 +1,14 @@
 # Rails Templatable
 
-> Rails Templatable is a lightweight, reusable Rails Engine that enables any ActiveRecord model to associate with templates for content management via polymorphic many-to-many relationships.
+> Rails Templatable is a lightweight, reusable Rails Engine that enables any ActiveRecord model to use predefined templates for content management via a simple one-to-many relationship.
 
 It provides a clean, namespace-isolated way to add template 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 `RailsTemplatable` module
-- Table names are explicitly set to avoid conflicts: `rails_templatable_templates` and `rails_templatable_assignments`
-- The engine uses polymorphic associations, allowing templates to be assigned to ANY model
+- Uses 1:N relationship (one record has one template, one template can have many records)
+- No join table - uses direct foreign key `template_id` on target models
 - Uses `category` instead of `type` to avoid Rails STI (Single Table Inheritance) conflicts
 - Supports three content formats: HTML (0), Markdown (1), and TXT (2)
 - The `content_format` field uses Rails enum with new syntax: `enum :content_format, { html: 0, markdown: 1, txt: 2 }`
@@ -17,18 +17,17 @@ It provides a clean, namespace-isolated way to add template functionality to you
 
 - [GitHub Repository](https://github.com/afeiship/rails_templatable): Source code and issue tracking
 - [README](README.md): Installation guide and basic usage examples
-- [PRD](docs/01-prd.md): Detailed product requirements and design specifications
+- [Design Document](docs/01-design.md): Detailed design specifications
 - [Usage Guide](docs/02-usage.md): Comprehensive usage examples
-- [Implementation Summary](docs/03-implementation-summary.md): Implementation details and testing results
+- [Redesign Summary](docs/03-redesign-summary.md): Architecture redesign from N:N to 1:N
 
 ## Key Features
 
-- **Polymorphic Associations:** Assign templates to any ActiveRecord model (Post, WorkLog, User, etc.)
-- **Multiple Content Formats:** Support for HTML, Markdown, and plain text templates
-- **Database-level Constraints:** Unique indexes prevent duplicate template assignments
-- **Namespace Isolated:** All models under `RailsTemplatable` namespace to avoid conflicts
-- **Explicit Table Names:** No reliance on Rails auto-inflection
-- **Flexible Categories:** User-defined template categories (no hardcoded types)
+- **Simple 1:N Relationship:** Each record has one template, templates can be reused
+- **Multiple Content Formats:** Support for HTML, Markdown, and plain text
+- **Flexible Categories:** User-defined template categories (feature_request, bug_report, etc.)
+- **Direct Foreign Key:** No join table needed, cleaner database schema
+- **Namespace Isolated:** All models under `RailsTemplatable` namespace
 - **Rails 6.0+ Compatible:** Works with modern Rails versions (tested on Rails 8.1.2)
 - **Zero Configuration:** Works out of the box after migration
 
@@ -47,79 +46,147 @@ rails railties:install:migrations FROM=rails_templatable
 rails db:migrate
 ```
 
+Add foreign key to each model that will use templates:
+
+```ruby
+add_reference :posts, :template,
+              foreign_key: { to_table: :rails_templatable_templates },
+              index: false
+```
+
 ## Basic Usage
 
 ### Include the Concern
 
 ```ruby
 class Post < ApplicationRecord
-  include RailsTemplatable::HasTemplates
+  include RailsTemplatable::HasTemplate
 end
 
 class WorkLog < ApplicationRecord
-  include RailsTemplatable::HasTemplates
+  include RailsTemplatable::HasTemplate
 end
 ```
 
-### Create and Assign Templates
+### Create Templates
 
 ```ruby
-# Create an HTML template
-email_template = RailsTemplatable::Template.create!(
-  category: "email_template",
-  content: "<h1>Welcome!</h1><p>Hello {{name}}</p>",
-  content_format: :html
+# Feature request template
+feature_template = RailsTemplatable::Template.create!(
+  category: "feature_request",
+  content: "# Feature Request\n\n## Description\n\n## Acceptance Criteria",
+  content_format: :markdown
+)
+
+# Bug report template
+bug_template = RailsTemplatable::Template.create!(
+  category: "bug_report",
+  content: "## Bug Description\n\n## Steps to Reproduce\n\n## Expected Behavior",
+  content_format: :markdown
 )
 
-# Create a Markdown template
-doc_template = RailsTemplatable::Template.create!(
-  category: "documentation",
-  content: "# Documentation\n\nThis is a **markdown** template.",
+# Meeting note template
+meeting_template = RailsTemplatable::Template.create!(
+  category: "meeting_note",
+  content: "# Meeting: {title}\n\nDate: {date}\n\n## Attendees\n\n## Agenda",
   content_format: :markdown
 )
 
-# Assign to a post
-post = Post.create(title: "Hello World")
-post.templates << email_template
-post.templates << doc_template
+# Tech improvement template
+tech_template = RailsTemplatable::Template.create!(
+  category: "tech_improvement",
+  content: "## Current State\n\n## Proposed Improvement\n\n## Benefits",
+  content_format: :markdown
+)
 
-# Check if post has the template
-post.templates.include?(email_template) # => true
+# API design template
+api_template = RailsTemplatable::Template.create!(
+  category: "api_design",
+  content: "## Endpoint\n\n## Request\n\n## Response",
+  content_format: :markdown
+)
 ```
 
-### Query Methods
+### Assign Templates to Records
 
 ```ruby
-# Get all posts with a specific template
-template.assigned_to(Post)
-# => [#<Post id: 1, ...>, #<Post id: 3, ...>]
+# Create with template
+post = Post.create!(
+  title: "Add user authentication",
+  content: "Implement OAuth2",
+  template: feature_template
+)
 
-# Get all templates ever used on Post model
-RailsTemplatable::Template.for_model(Post)
-# => [#<RailsTemplatable::Template category: "email_template">, ...]
+# Assign template later
+work_log = WorkLog.create!(title: "Daily standup")
+work_log.update(template: meeting_template)
 
-# Filter templates by category
-post.templates.where(category: "email_template")
+# View template
+post.template.category  # => "feature_request"
+post.template.content   # => "# Feature Request..."
+```
+
+### Query Templates
+
+```ruby
+# Get a record's template
+post.template
 
-# Filter templates by content format
-post.templates.html      # HTML templates only
-post.templates.markdown  # Markdown templates only
-post.templates.txt       # Plain text templates only
+# Query by category
+Post.joins(:template).where(rails_templatable_templates: { category: 'feature_request' })
+
+# Get all records using a specific template
+Post.where(template: feature_template)
+
+# Query by content format
+Post.joins(:template).where(rails_templatable_templates: { content_format: 1 })
 ```
 
-### Remove Templates
+### Change Template
 
 ```ruby
-# Remove a specific template
-post.templates.destroy(email_template)
+# Assigning a new template replaces the old one
+post.update(template: bug_template)
+post.template.category  # => "bug_report"
+```
+
+### Remove Template
+
+```ruby
+post.update(template: nil)
+post.template  # => nil
+```
+
+## Template Categories
+
+Common template categories:
 
-# Remove all templates
-post.templates.clear
+| Category | Description |
+|----------|-------------|
+| `feature_request` | Feature requests |
+| `bug_report` | Bug reports |
+| `tech_improvement` | Technical improvements |
+| `meeting_note` | Meeting notes |
+| `api_design` | API designs |
+
+Users can create any custom category.
+
+## Relationship Model
+
+**One-to-Many (1:N)**
+- One Post/WorkLog instance → One Template
+- One Template → Many instances
+
+Example:
+```
+Post 1 → Template A (feature_request)
+Post 2 → Template B (bug_report)
+Post 3 → Template A (feature_request)  # Reusable
 ```
 
 ## Database Schema
 
-### templates table
+### rails_templatable_templates
 
 ```ruby
 create_table :rails_templatable_templates do |t|
@@ -133,27 +200,22 @@ add_index :rails_templatable_templates, :category
 ```
 
 **Field Details:**
-- `category` (string) - User-defined template category (e.g., "email_template", "documentation")
+- `category` (string) - User-defined template category
 - `content` (text) - Template content (static text, no variable replacement)
 - `content_format` (integer) - Content format: 0=HTML, 1=Markdown, 2=TXT (default)
 - Index on `category` for fast lookups
 
-### assignments table (join table)
+### Target Models (e.g., posts)
 
-```ruby
-create_table :rails_templatable_assignments do |t|
-  t.references :template, null: false, foreign_key: { to_table: :rails_templatable_templates }
-  t.references :templatable, polymorphic: true, null: false
-  t.timestamps
-end
+Add `template_id` foreign key:
 
-add_index :rails_templatable_assignments,
-          [:template_id, :templatable_type, :templatable_id],
-          unique: true,
-          name: "index_templatable_assignments"
+```ruby
+add_reference :posts, :template,
+              foreign_key: { to_table: :rails_templatable_templates },
+              index: false
 ```
 
-**Constraint:** Unique composite index prevents duplicate template assignments to the same record.
+**Constraint:** Each record can have only one template (foreign key is single, not array).
 
 ## Content Formats
 
@@ -170,7 +232,12 @@ enum :content_format, {
 **Usage:**
 
 ```ruby
-# Create different format templates
+# Query by format
+post.template.html?      # => true/false
+post.template.markdown?  # => true/false
+post.template.txt?       # => true/false
+
+# Create different formats
 html_template = RailsTemplatable::Template.create!(
   category: "email",
   content: "<h1>Welcome</h1>",
@@ -179,116 +246,19 @@ html_template = RailsTemplatable::Template.create!(
 
 markdown_template = RailsTemplatable::Template.create!(
   category: "docs",
-  content: "# Guide\n\nInstructions here",
+  content: "# Guide\n\nInstructions",
   content_format: :markdown
 )
-
-txt_template = RailsTemplatable::Template.create!(
-  category: "notification",
-  content: "Simple text message",
-  content_format: :txt
-)
-
-# Query by format
-post.templates.html      # => [#<RailsTemplatable::Template content_format: 0>]
-post.templates.markdown  # => [#<RailsTemplatable::Template content_format: 1>]
-post.templates.txt       # => [#<RailsTemplatable::Template content_format: 2>]
 ```
 
 ## Available Methods
 
-### Template Instance Methods
-
-- `template.assigned_to(klass)` - Returns all records of the given class that have this template
-  ```ruby
-  template.assigned_to(Post)     # => [post1, post2]
-  template.assigned_to(WorkLog)  # => [work_log1, work_log3]
-  ```
-
-### Template Class Methods
-
-- `RailsTemplatable::Template.for_model(klass)` - Returns all templates ever used on the given model class
-  ```ruby
-  RailsTemplatable::Template.for_model(Post)  # => [template1, template2]
-  ```
-
-### Model Methods (with HasTemplates concern)
-
-- `model.templates` - Returns all templates assigned to this record
-- `model.templates << template` - Assign a template to this record
-- `model.templates.delete(template)` - Remove a specific template
-- `model.templates.clear` - Remove all templates
-- `model.rails_templatable_assignments` - Direct access to join records
-- `model.templates.where(category: "email_template")` - Filter by category
-- `model.templates.html` - Get HTML format templates only
-- `model.templates.markdown` - Get Markdown format templates only
-- `model.templates.txt` - Get plain text templates only
-
-## Advanced Usage
+### Model Methods (with HasTemplate concern)
 
-### Custom Fields
-
-You can add custom fields to templates or assignments via migrations:
-
-```ruby
-# Add custom fields to templates
-add_column :rails_templatable_templates, :name, :string
-add_column :rails_templatable_templates, :description, :text
-add_column :rails_templatable_templates, :locale, :string, default: 'en'
-
-# Add custom fields to assignments
-add_column :rails_templatable_assignments, :priority, :integer, default: 0
-add_column :rails_templatable_assignments, :active, :boolean, default: true
-add_column :rails_templatable_assignments, :assigned_at, :datetime
-```
-
-### Accessing Assignment Data
-
-```ruby
-# Get assignment metadata
-assignment = post.rails_templatable_assignments.find_by(template_id: 1)
-assignment.priority  # => 1
-assignment.created_at  # => assignment time
-```
-
-### Conditional Scopes
-
-Add scopes to your models:
-
-```ruby
-class Post < ApplicationRecord
-  include RailsTemplatable::HasTemplates
-
-  scope :with_email_template, -> {
-    joins(:templates)
-      .where(rails_templatable_templates: { category: 'email_template' })
-  }
-
-  scope :with_html_templates, -> {
-    joins(:templates)
-      .where(rails_templatable_templates: { content_format: 0 })
-  }
-end
-
-# Usage
-Post.with_email_template  # All posts with email templates
-Post.with_html_templates  # All posts with HTML templates
-```
-
-### Checking Template Existence
-
-```ruby
-# Check if a post has templates from a specific category
-post.templates.where(category: "email_template").exists?  # => true/false
-
-# Check if a post has HTML templates
-post.templates.html.any?  # => true/false
-
-# Count templates by format
-post.templates.html.count      # => 2
-post.templates.markdown.count  # => 1
-post.templates.txt.count       # => 0
-```
+- `model.template` - Returns the assigned template or nil
+- `model.template=(template)` - Assign a template (replaces existing)
+- `model.update(template: template)` - Update template
+- `model.update(template: nil)` - Remove template association
 
 ## Testing
 
@@ -301,27 +271,23 @@ ruby test_templatable.rb
 
 Expected output:
 ```
-🚀 Testing Rails Templatable Engine
-==================================================
+🚀 Testing Rails Templatable Engine (1:N Relationship)
+============================================================
 
 📝 Creating templates...
-✓ Created HTML email template
-✓ Created Markdown documentation template
-✓ Created text notification template
-
-📄 Creating Posts and WorkLogs...
-✓ Created 2 Posts and 2 WorkLogs
-
-🔗 Associating templates with models...
-✓ Templates associated successfully
-
-🔍 Testing queries...
-  Post1 has 2 templates
-  Post1 templates: email_template, documentation
-  ...
+✓ Created feature_request template
+✓ Created bug_report template
+...
 
 ✅ All tests passed successfully!
-==================================================
+============================================================
+
+📊 Summary:
+  - Created 5 templates
+  - Created 6 posts
+  - Created 3 work logs
+  - 1:N relationship verified: one record → one template
+  - 1:N relationship verified: one template → many records
 ```
 
 ## Project Structure
@@ -335,75 +301,78 @@ lib/
 app/models/
 ├── rails_templatable/
 │   ├── application_record.rb         # Base AR class
-│   ├── template.rb                   # Template model
-│   └── template_assignment.rb        # Join model
+│   └── template.rb                   # Template model
 └── models/concerns/
     └── rails_templatable/
-        └── has_templates.rb          # Concern for host models
+        └── has_template.rb           # Concern for host models
 db/migrate/
 └── 20250207000000_create_rails_templatable_tables.rb  # Migration
 test/dummy/
 ├── app/models/
-│   ├── post.rb                       # Example: Post with HasTemplates
-│   └── work_log.rb                   # Example: WorkLog with HasTemplates
-├── db/schema.rb                      # Database schema
+│   ├── post.rb                       # Example: Post with HasTemplate
+│   └── work_log.rb                   # Example: WorkLog with HasTemplate
+├── db/migrate/
+│   ├── xxx_add_template_to_posts.rb  # Add template_id to posts
+│   └── xxx_add_template_to_work_logs.rb  # Add template_id to work_logs
 └── test_templatable.rb               # Integration test script
 docs/
-├── 01-prd.md                         # Product Requirements Document
-├── 02-usage.md                       # Usage Guide
-└── 03-implementation-summary.md      # Implementation Summary
+├── 01-design.md                      # Design document
+├── 02-usage.md                      # Usage guide
+└── 03-redesign-summary.md            # Architecture redesign summary
 ```
 
+## Architecture Decisions
+
+### Why 1:N instead of N:N?
+
+The original design used N:N (many-to-many) with a join table, but this was changed to 1:N (one-to-many) because:
+- In practice, a document/post typically needs only one template
+- Simpler database schema (no join table)
+- More efficient queries (direct foreign key)
+- Clearer semantics: "This post uses which template?"
+
+### Why `category` instead of `type`?
+
+Rails reserves the `type` column for Single Table Inheritance (STI). To avoid conflicts:
+- We use `category` for template classification
+- Users can define any category string
+- No hardcoded enum or predefined types
+
+### Why explicit table names?
+
+To prevent any naming conflicts:
+- `rails_templatable_templates` - Template storage
+- No reliance on Rails auto-inflection
+- Clear namespace isolation
+
 ## Comparison with rails_badgeable
 
 | Feature | rails_badgeable | rails_templatable |
 |---------|-----------------|-------------------|
 | Main Model | Badge | Template |
+| Relationship | N:N (many-to-many) | 1:N (one-to-many) |
+| Join Table | badge_assignments | None (direct foreign key) |
+| Model Association | has_many :badges | belongs_to :template |
 | Fields | name, description | category, content, content_format |
-| Enum Support | No | Yes (content_format: html/markdown/txt) |
-| Polymorphic Name | assignable | templatable |
-| Concern | HasBadges | HasTemplates |
-| STI Conflict Handling | N/A | Uses `category` to avoid `type` conflict |
+| Enum Support | No | Yes (content_format) |
+| Polymorphic Name | assignable | N/A (not polymorphic) |
+| Concern | HasBadges | HasTemplate |
 
 ## Usage Notes for Agents
 
-- **Always use full namespace:** `RailsTemplatable::Template` (no alias generator yet)
+- **Always use full namespace:** `RailsTemplatable::Template` (no alias generator)
 - **Categories are user-defined:** No predefined categories, use any string value
 - **Content formats are enforced:** Use symbols: `:html`, `:markdown`, `:txt`
-- **Polymorphic type stores class name:** Uses `base_class.name` for STI support
-- **Database prevents duplicates:** Unique index on `[template_id, templatable_type, templatable_id]`
+- **One record = One template:** Assigning a new template replaces the old one
+- **Direct foreign key:** Each model needs its own `template_id` column
+- **No join table:** Simpler schema than rails_badgeable
 - **Engine is not mountable:** No routes, controllers, or views included
 - **Migrations must be copied:** Use `rails railties:install:migrations FROM=rails_templatable`
 - **Custom fields require migration:** Add columns directly to tables if needed
-- **Join table accessible:** `model.rails_templatable_assignments` for metadata access
 - **`category` field is indexed:** Efficient queries by category
 - **Default content_format is TXT:** New templates default to plain text (2)
 - **Rails 8.x enum syntax:** Must use `enum :content_format, { ... }` not `enum content_format: { ... }`
 
-## Architecture Decisions
-
-### Why `category` instead of `type`?
-
-Rails reserves the `type` column for Single Table Inheritance (STI). To avoid conflicts:
-- We use `category` for template classification
-- Users can define any category string (email_template, documentation, etc.)
-- No hardcoded enum or predefined types
-
-### Why explicit table names?
-
-To prevent any naming conflicts:
-- `rails_templatable_templates` - Template storage
-- `rails_templatable_assignments` - Polymorphic join table
-- No reliance on Rails auto-inflection
-
-### Why enum for content_format?
-
-Using Rails enum provides:
-- Type safety (only valid formats)
-- Helper methods (`html`, `markdown`, `txt`)
-- Integer storage for efficiency
-- Easy to extend with new formats
-
 ## Development
 
 - Rails Engine (non-mountable)
@@ -411,17 +380,16 @@ Using Rails enum provides:
 - Rails 6.0+ compatible (tested on Rails 8.1.2)
 - MIT License
 - Author: aric.zheng <1290657123@qq.com>
-- Version: 0.1.0
+- Version: 0.1.1
 
 ## Future Enhancements
 
 Planned features for future versions:
 - Template variable interpolation (replace `{{name}}` with actual data)
 - Template versioning system
-- Template inheritance and overriding
 - Template preview functionality
 - I18n multi-language support
-- Short alias generator (like rails_badgeable)
+- Template validation based on structure
 
 ## Contributing
 
@@ -431,3 +399,4 @@ When contributing to rails_templatable:
 3. Add tests for new features
 4. Update this llms.txt file with API changes
 5. Ensure Rails 6.0+ compatibility
+6. Remember: 1:N relationship, not N:N

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_templatable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - aric.zheng
@@ -31,7 +31,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '9.0'
 description: A lightweight Rails Engine that enables any ActiveRecord model to use
-  templates for content generation and management.
+  predefined templates via a simple one-to-many relationship. Each record has one
+  template, templates can be reused across multiple records. Supports HTML, Markdown,
+  and plain text formats with flexible categories.
 email:
 - 1290657123@qq.com
 executables: []
@@ -41,16 +43,9 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/assets/stylesheets/rails_templatable/application.css
-- app/controllers/rails_templatable/application_controller.rb
-- app/helpers/rails_templatable/application_helper.rb
-- app/jobs/rails_templatable/application_job.rb
-- app/mailers/rails_templatable/application_mailer.rb
-- app/models/concerns/rails_templatable/has_templates.rb
+- app/models/concerns/rails_templatable/has_template.rb
 - app/models/rails_templatable/application_record.rb
 - app/models/rails_templatable/template.rb
-- app/models/rails_templatable/template_assignment.rb
-- app/views/layouts/rails_templatable/application.html.erb
 - config/routes.rb
 - db/migrate/20250207000000_create_rails_templatable_tables.rb
 - lib/rails_templatable.rb
@@ -84,5 +79,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: A Rails engine for templatable models.
+summary: A Rails engine for template management with 1:N relationship.
 test_files: []

data/app/assets/stylesheets/rails_templatable/application.css

@@ -1,15 +0,0 @@
-/*
- * This is a manifest file that'll be compiled into application.css, which will include all the files
- * listed below.
- *
- * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
- * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
- *
- * You're free to add application-wide styles to this file and they'll appear at the bottom of the
- * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
- * files in this directory. Styles in this file should be added after the last require_* statement.
- * It is generally better to create a new file per style scope.
- *
- *= require_tree .
- *= require_self
- */

data/app/controllers/rails_templatable/application_controller.rb

@@ -1,4 +0,0 @@
-module RailsTemplatable
-  class ApplicationController < ActionController::Base
-  end
-end

data/app/helpers/rails_templatable/application_helper.rb

@@ -1,4 +0,0 @@
-module RailsTemplatable
-  module ApplicationHelper
-  end
-end

data/app/jobs/rails_templatable/application_job.rb

@@ -1,4 +0,0 @@
-module RailsTemplatable
-  class ApplicationJob < ActiveJob::Base
-  end
-end

data/app/mailers/rails_templatable/application_mailer.rb

@@ -1,6 +0,0 @@
-module RailsTemplatable
-  class ApplicationMailer < ActionMailer::Base
-    default from: "from@example.com"
-    layout "mailer"
-  end
-end

data/app/models/concerns/rails_templatable/has_templates.rb

@@ -1,16 +0,0 @@
-module RailsTemplatable
-  module HasTemplates
-    extend ActiveSupport::Concern
-
-    included do
-      has_many :rails_templatable_assignments,
-               as: :templatable,
-               class_name: "RailsTemplatable::TemplateAssignment",
-               dependent: :destroy
-
-      has_many :templates,
-               through: :rails_templatable_assignments,
-               class_name: "RailsTemplatable::Template"
-    end
-  end
-end

data/app/models/rails_templatable/template_assignment.rb

@@ -1,12 +0,0 @@
-module RailsTemplatable
-  class TemplateAssignment < ApplicationRecord
-    self.table_name = "rails_templatable_assignments"
-
-    belongs_to :template, class_name: "RailsTemplatable::Template"
-    belongs_to :templatable, polymorphic: true
-
-    validates :template, presence: true
-    validates :templatable, presence: true
-    validates :template_id, uniqueness: { scope: [:templatable_type, :templatable_id] }
-  end
-end

data/app/views/layouts/rails_templatable/application.html.erb

@@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Rails templatable</title>
-  <%= csrf_meta_tags %>
-  <%= csp_meta_tag %>
-
-  <%= yield :head %>
-
-  <%= stylesheet_link_tag    "rails_templatable/application", media: "all" %>
-</head>
-<body>
-
-<%= yield %>
-
-</body>
-</html>