Create Validations table and associations

** Why are these changes being introduced:

We need a Validations model that will be attached to the actions taken
by TACOS (the Detections and Categorizations that are created during
normal operation).

Validation records will allow library staff to review and give feedback
about the actions taken by the application. This feedback will be used
to improve the operation of the tool, as well as to guide future
development.

** Relevant ticket(s):

* https://mitlibraries.atlassian.net/browse/tco-8

** How does this address that need:

This defines the migration to create the Validations table, and updates
the references to it from related classes. It also runs `make annotate`
to keep some minimal documentation going.

The model itself has no methods, and I'm not sure yet how it will be
flushed out. The most notable aspect is that it has a polymorphic
association with _both_ the Detections and Categorizations models, via
the :validatable construct, because all of those records will need to be
given feedback. The (probably poorly named) "judgement" field is meant
to store the postive / negative feedback about the action that TACOS
took.

** Document any side effects to this change:

Because TACOS only records positive actions (detections that were made,
and categorization scores that were calculated), this model currently
can only provide negative feedback (this detection should not have
fired, or this categorization should not have been performed). There
is not yet a way to say "this detector should have fired" or "this
category should have been assigned."

Further, there is a slight awkwardness approaching because the UI is
going to focus on the Term, but that term is potentially subject to
many Detections and Categorizations - so the form in the next commit
is going to need to take one input and spawn multiple Validation
records.

app/models/categorization.rb

@@ -19,10 +19,13 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 class Categorization < ApplicationRecord
   belongs_to :term
   belongs_to :category
+  has_many :validations, as: :validatable, dependent: :destroy
 
   # These scopes allow for easy filtering of Categorization records by a single parameter.
   scope :current, -> { where(detector_version: ENV.fetch('DETECTOR_VERSION', 'unset')) }

app/models/detection.rb

@@ -18,10 +18,13 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 class Detection < ApplicationRecord
   belongs_to :term
   belongs_to :detector
+  has_many :validations, as: :validatable, dependent: :destroy
 
   # These scopes allow for easy filtering of Detection records by a single parameter.
   scope :current, -> { where(detector_version: ENV.fetch('DETECTOR_VERSION', 'unset')) }

app/models/user.rb

@@ -14,6 +14,8 @@
 class User < ApplicationRecord
   include FakeAuthConfig
 
+  has_many :validations, dependent: :destroy
+
   if FakeAuthConfig.fake_auth_enabled?
     devise :omniauthable, omniauth_providers: [:developer]
   else

app/models/validation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: validations
+#
+#  id               :integer          not null, primary key
+#  validatable_type :string
+#  validatable_id   :integer
+#  user_id          :integer          not null
+#  detector_version :string
+#  judgement        :integer
+#  created_at       :datetime         not null
+#  updated_at       :datetime         not null
+#
+class Validation < ApplicationRecord
+  belongs_to :validatable, polymorphic: true
+end

db/migrate/20241021184739_create_validations.rb

@@ -0,0 +1,17 @@
+class CreateValidations < ActiveRecord::Migration[7.1]
+  def change
+    create_table :validations do |t|
+      t.references :validatable, polymorphic: true
+      t.belongs_to :user, null: false, foreign_key: true
+      t.string :detector_version
+      t.integer :judgement
+
+      t.timestamps
+    end
+
+    add_index :validations, [:validatable_id, :validatable_type, :user_id, :detector_version], unique: true
+
+    add_reference :detections, :validatable, polymorphic: true
+    add_reference :categorizations, :validatable, polymorphic: true
+  end
+end

docs/reference/classes.md

@@ -7,6 +7,7 @@ The application includes the following entities, most of which an be broken into
   between the two which TACOS defines and maintains, and which is consulted during categorization; and
 * The <font style="color:#8da0cb;border:1px dashed #8da0cb;padding:2px;">linkages between these search terms and the graph</font>, which record which signals are
   detected in each term, and how those signals are interpreted to place the term into a category.
+* The validations
 
 ```mermaid
 classDiagram
@@ -24,6 +25,10 @@ classDiagram
 
   Detector "1" --> "0..*" DetectorCategory
 
+  Validation --> Detection: polymorphic
+  Validation --> Categorization: polymorphic
+  User --> Validation : provides many
+
   class User
     User: +String uid
     User: +String email
@@ -93,6 +98,12 @@ classDiagram
     DetectorSuggestedResource: record()
     DetectorSuggestedResource: update_fingerprint()
 
+  class Validation
+    Validation: +Integer id
+    Validation: +Integer user_id
+    Validation: +Polymorphic action_id
+    Validation: +String detector_version
+    Validation: +Integer judgement
 
   namespace SearchActivity{
     class Term
@@ -113,6 +124,12 @@ classDiagram
     class DetectorSuggestedResource["Detector::SuggestedResource"]
   }
 
+  namespace UserActivity {
+    class Validation
+    class User
+
+  }
+
   style SearchEvent fill:#000,stroke:#66c2a5,color:#66c2a5,stroke-width:4px;
   style Term fill:#000,stroke:#66c2a5,color:#66c2a5,stroke-width:4px;
 
@@ -126,4 +143,7 @@ classDiagram
 
   style Categorization fill:#000,stroke:#8da0cb,color:#8da0cb,stroke-dasharray: 3 5;
   style Detection fill:#000,stroke:#8da0cb,color:#8da0cb,stroke-dasharray: 3 5;
+
+  style Validation fill:#000,stroke:#ffd407
+  style User fill:#000,stroke:#ffd407
 ```

test/fixtures/categorizations.yml

@@ -9,6 +9,8 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 one:
   category: transactional

test/fixtures/detections.yml

@@ -8,6 +8,8 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 one:
   term: doi

test/models/categorization_test.rb

@@ -11,6 +11,8 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 require 'test_helper'
 

test/models/detection_test.rb

@@ -10,6 +10,8 @@
 #  detector_version :string
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
+#  validatable_type :string
+#  validatable_id   :integer
 #
 require 'test_helper'