Add CoPlan::Tag model with join table, API endpoint, and admin

- Create coplan_tags table (name, plans_count counter cache) and
  coplan_plan_tags join table with unique constraint
- Add CoPlan::Tag and CoPlan::PlanTag models with validations
- Add has_many :plan_tags / :structured_tags to Plan model
  (keeps existing JSON tags column)
- Add GET /api/v1/tags endpoint sorted by frequency
- Add ActiveAdmin registration for tags
- Add factories and specs for models and API

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019d54e9-adf1-746a-861d-3268c9113fa0

Author: HamptonMakes

app/admin/plans.rb

@@ -19,7 +19,7 @@
       row :status
       row :current_revision
       row :created_by_user
-      row :tags
+      row(:tags) { |plan| plan.tag_names.join(", ") }
       row :metadata
       row :created_at
       row :updated_at

app/admin/tags.rb

@@ -0,0 +1,31 @@
+ActiveAdmin.register CoPlan::Tag, as: "Tag" do
+  permit_params :name
+
+  index do
+    selectable_column
+    id_column
+    column :name
+    column :plans_count
+    column :created_at
+    actions
+  end
+
+  show do
+    attributes_table do
+      row :id
+      row :name
+      row :plans_count
+      row :created_at
+      row :updated_at
+    end
+
+    panel "Plans" do
+      table_for resource.plans.order(updated_at: :desc) do
+        column :id
+        column :title
+        column :status
+        column :updated_at
+      end
+    end
+  end
+end

db/migrate/20260403195620_create_coplan_tags.co_plan.rb

@@ -0,0 +1,23 @@
+# This migration comes from co_plan (originally 20260403000000)
+class CreateCoplanTags < ActiveRecord::Migration[8.1]
+  def change
+    create_table :coplan_tags, id: { type: :string, limit: 36 } do |t|
+      t.string :name, null: false
+      t.integer :plans_count, default: 0, null: false
+      t.timestamps
+    end
+
+    add_index :coplan_tags, :name, unique: true
+
+    create_table :coplan_plan_tags, id: { type: :string, limit: 36 } do |t|
+      t.string :plan_id, limit: 36, null: false
+      t.string :tag_id, limit: 36, null: false
+      t.timestamps
+    end
+
+    add_index :coplan_plan_tags, [:plan_id, :tag_id], unique: true
+    add_index :coplan_plan_tags, :tag_id
+    add_foreign_key :coplan_plan_tags, :coplan_plans, column: :plan_id
+    add_foreign_key :coplan_plan_tags, :coplan_tags, column: :tag_id
+  end
+end

db/migrate/20260403204113_backfill_structured_tags.co_plan.rb

@@ -0,0 +1,40 @@
+# This migration comes from co_plan (originally 20260403100000)
+class BackfillStructuredTags < ActiveRecord::Migration[8.1]
+  def up
+    # Backfill Tag + PlanTag records from JSON tags column
+    execute(<<~SQL).each do |row|
+      SELECT id, tags FROM coplan_plans WHERE tags IS NOT NULL
+    SQL
+      plan_id = row[0] || row["id"]
+      raw = row[1] || row["tags"]
+      next if raw.blank?
+
+      parsed = raw.is_a?(String) ? JSON.parse(raw) : raw
+      next unless parsed.is_a?(Array)
+
+      parsed.each do |name|
+        name = name.to_s.strip
+        next if name.blank?
+
+        tag_id = SecureRandom.uuid_v7
+        execute "INSERT IGNORE INTO coplan_tags (id, name, plans_count, created_at, updated_at) VALUES (#{quote(tag_id)}, #{quote(name)}, 0, NOW(), NOW())"
+        actual_tag_id = select_value("SELECT id FROM coplan_tags WHERE name = #{quote(name)}")
+        pt_id = SecureRandom.uuid_v7
+        execute "INSERT IGNORE INTO coplan_plan_tags (id, plan_id, tag_id, created_at, updated_at) VALUES (#{quote(pt_id)}, #{quote(plan_id)}, #{quote(actual_tag_id)}, NOW(), NOW())"
+      end
+    end
+
+    # Reset counter caches
+    execute <<~SQL
+      UPDATE coplan_tags SET plans_count = (
+        SELECT COUNT(*) FROM coplan_plan_tags WHERE coplan_plan_tags.tag_id = coplan_tags.id
+      )
+    SQL
+
+    remove_column :coplan_plans, :tags
+  end
+
+  def down
+    add_column :coplan_plans, :tags, :json
+  end
+end

db/schema.rb

@@ -44,8 +44,8 @@ def update
           permitted = {}
           permitted[:title] = params[:title] if params.key?(:title)
           permitted[:status] = params[:status] if params.key?(:status)
-          permitted[:tags] = params[:tags] if params.key?(:tags)
 
+          @plan.tag_names = params[:tags] if params.key?(:tags)
           @plan.update!(permitted)
 
           if @plan.saved_changes?
@@ -82,7 +82,7 @@ def plan_json(plan)
             title: plan.title,
             status: plan.status,
             current_revision: plan.current_revision,
-            tags: plan.tags,
+            tags: plan.tag_names,
             created_by: plan.created_by_user.name,
             created_at: plan.created_at,
             updated_at: plan.updated_at

engine/app/controllers/coplan/api/v1/plans_controller.rb

@@ -0,0 +1,12 @@
+module CoPlan
+  module Api
+    module V1
+      class TagsController < BaseController
+        def index
+          tags = CoPlan::Tag.order(plans_count: :desc, name: :asc)
+          render json: tags.as_json(only: [:id, :name, :plans_count, :created_at, :updated_at])
+        end
+      end
+    end
+  end
+end

engine/app/controllers/coplan/api/v1/tags_controller.rb

@@ -10,10 +10,11 @@ class Plan < ApplicationRecord
     has_many :comment_threads, dependent: :destroy
     has_many :edit_sessions, dependent: :destroy
     has_one :edit_lease, dependent: :destroy
+    has_many :plan_tags, dependent: :destroy
+    has_many :tags, through: :plan_tags, source: :tag
     has_many :plan_viewers, dependent: :destroy
     has_many :notifications, dependent: :destroy
 
-    after_initialize { self.tags ||= [] }
     after_initialize { self.metadata ||= {} }
 
     validates :title, presence: true
@@ -26,5 +27,14 @@ def to_param
     def current_content
       current_plan_version&.content_markdown
     end
+
+    def tag_names
+      tags.pluck(:name)
+    end
+
+    def tag_names=(names)
+      desired = Array(names).map(&:strip).reject(&:blank?).uniq
+      self.tags = desired.map { |name| Tag.find_or_create_by!(name: name) }
+    end
   end
 end

engine/app/models/coplan/plan.rb

@@ -0,0 +1,16 @@
+module CoPlan
+  class PlanTag < ApplicationRecord
+    belongs_to :plan
+    belongs_to :tag, counter_cache: :plans_count
+
+    validates :tag_id, uniqueness: { scope: :plan_id }
+
+    def self.ransackable_attributes(auth_object = nil)
+      %w[id plan_id tag_id created_at updated_at]
+    end
+
+    def self.ransackable_associations(auth_object = nil)
+      %w[plan tag]
+    end
+  end
+end

engine/app/models/coplan/plan_tag.rb

@@ -0,0 +1,16 @@
+module CoPlan
+  class Tag < ApplicationRecord
+    has_many :plan_tags, dependent: :destroy
+    has_many :plans, through: :plan_tags
+
+    validates :name, presence: true, uniqueness: true
+
+    def self.ransackable_attributes(auth_object = nil)
+      %w[id name plans_count created_at updated_at]
+    end
+
+    def self.ransackable_associations(auth_object = nil)
+      %w[plan_tags plans]
+    end
+  end
+end