From 4ac0fadcb915c59475c9221bd111136fd4fe1478 Mon Sep 17 00:00:00 2001
From: Stephen Hulme <sh51@sanger.ac.uk>
Date: Tue, 17 Dec 2024 12:28:51 +0000
Subject: [PATCH] feat: add work_completions to api v2

---
 .../api/v2/work_completions_controller.rb     | 12 +++
 .../api/v2/work_completion_resource.rb        | 84 +++++++++++++++++++
 config/routes.rb                              |  1 +
 3 files changed, 97 insertions(+)
 create mode 100644 app/controllers/api/v2/work_completions_controller.rb
 create mode 100644 app/resources/api/v2/work_completion_resource.rb

diff --git a/app/controllers/api/v2/work_completions_controller.rb b/app/controllers/api/v2/work_completions_controller.rb
new file mode 100644
index 0000000000..c5f7312bc1
--- /dev/null
+++ b/app/controllers/api/v2/work_completions_controller.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # Provides a JSON API controller for work completion
+    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    class WorkCompletionsController < JSONAPI::ResourceController
+      # By default JSONAPI::ResourceController provides most the standard
+      # behaviour, and in many cases this file may be left empty.
+    end
+  end
+end
diff --git a/app/resources/api/v2/work_completion_resource.rb b/app/resources/api/v2/work_completion_resource.rb
new file mode 100644
index 0000000000..7d45f33a65
--- /dev/null
+++ b/app/resources/api/v2/work_completion_resource.rb
@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # Provides a JSON:API representation of {WorkCompletion} which contains the QC data previously added to a piece of
+    # {Labware}. The file contents are stored in the database using the {DbFile} model.
+    #
+    # @note This resource cannot be modified after creation: its endpoint will not accept `PATCH` requests.
+    # @note Access this resource via the `/api/v2/work_completions/` endpoint.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
+    class WorkCompletionResource < BaseResource
+      ###
+      # Attributes
+      ###
+
+      # @!attribute [w] submission_uuids
+      #   This is declared for convenience where the submissions are not available to set as a relationship.
+      #   Setting this attribute alongside the `submissions` relationships will prefer the relationship value.
+      #   @deprecated Use the `submissions` relationship instead.
+      #   @param value [Array<String>] The UUIDs of the [{Submission}s] related to this WorkCompletion.
+      #   @return [Void]
+      #   @see #submissions
+      attribute :submission_uuids, writeonly: true
+
+      def submission_uuids=(value)
+        @model.submissions = value.map { |v| Submission.with_uuid(v).first }
+      end
+
+      # @!attribute [w] target_uuid
+      #   This is declared for convenience where the target {Labware} is not available to set as a relationship.
+      #   Setting this attribute alongside the `target` relationship will prefer the relationship value.
+      #   @deprecated Use the `target` relationship instead.
+      #   @param value [String] The UUID of the {Labware} that this work completion targets.
+      #   @return [Void]
+      #   @see #target
+      attribute :target_uuid, writeonly: true
+
+      def target_uuid=(value)
+        @model.target = Labware.with_uuid(value).first
+      end
+
+      # @!attribute [w] user_uuid
+      #   This is declared for convenience where the {User} is not available to set as a relationship.
+      #   Setting this attribute alongside the `user` relationship will prefer the relationship value.
+      #   @deprecated Use the `user` relationship instead.
+      #   @param value [String] The UUID of the {User} who initiated this plate creation.
+      #   @return [Void]
+      #   @see #user
+      attribute :user_uuid, writeonly: true
+
+      def user_uuid=(value)
+        @model.user = User.with_uuid(value).first
+      end
+
+      ###
+      # Relationships
+      ###
+
+      # @!attribute [rw] submissions
+      #   Setting this relationship alongside the `submission_uuids` attribute will override the attribute value.
+      #   @return [Array<SubmissionResource>] The Submissions related to this WorkCompletion.
+      #   @note This relationship is required.
+
+      # @!attribute [rw] target
+      #   Setting this relationship alongside the `target_uuid` attribute will override the attribute value.
+      #   @return [LabwareResource] The Labware which this WorkCompletion targets. @todo: reword to active sense
+      #   @note This relationship is required.
+      has_one :target, write_once: true
+
+      # @!attribute [rw] user
+      #   Setting this relationship alongside the `user_uuid` attribute will override the attribute value.
+      #   @return [UserResource] The User who initiated this WorkCompletion.
+      #   @note This relationship is required.
+      has_one :user, write_once: true
+    end
+  end
+end
diff --git a/config/routes.rb b/config/routes.rb
index 2be4715c9e..defb95bef1 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -82,6 +82,7 @@
       jsonapi_resources :users
       jsonapi_resources :volume_updates
       jsonapi_resources :wells
+      jsonapi_resources :work_completions, except: %i[update]
       jsonapi_resources :work_orders
 
       namespace :heron do