effective_work_experience 0.0.1

data/app/datatables/effective_work_experience_projects_datatable.rb

@@ -0,0 +1,38 @@
+# My work experience projects
+class EffectiveWorkExperienceProjectsDatatable < Effective::Datatable
+  datatable do
+    order :start_on
+
+    col :updated_at, visible: false
+    col :created_at, visible: false
+    col :id, visible: false
+
+    col :start_on
+    col :end_on
+
+    col :name
+    col :description
+
+    unless attributes[:skip_actions]
+      actions_col
+    end
+  end
+
+  collection do
+    scope = Effective::WorkExperienceProject.deep.all
+    scope = scope.where(user_id: attributes[:user_id], user_type: attributes[:user_type]) if attributes[:user_id].present?
+
+    if work_experience_summary.present?
+      scope = scope.during(work_experience_summary.months)
+    end
+
+    scope
+  end
+
+  def work_experience_summary
+    @work_experience_summary ||= if attributes[:work_experience_summary_id].present?
+      EffectiveWorkExperience.WorkExperienceSummary.find_by_id(attributes[:work_experience_summary_id])
+    end
+  end
+
+end

data/app/datatables/effective_work_experience_records_datatable.rb

@@ -0,0 +1,61 @@
+# My work experience records
+class EffectiveWorkExperienceRecordsDatatable < Effective::Datatable
+  datatable do
+    order :month, :desc
+
+    col :updated_at, visible: false
+    col :created_at, visible: false
+    col :id, visible: false
+
+    col(:month) do |work_experience_record|
+      work_experience_record.month&.strftime('%F') || 'Backdated'
+    end
+
+    col(:total_hours, label: 'Hours') do |work_experience_record|
+      work_experience_hours_to_s(work_experience_record.total_hours)
+    end.aggregate do |work_experience_records|
+      total = work_experience_records.sum { |work_experience_record| work_experience_record.total_hours }
+      work_experience_hours_to_s(total)
+    end
+
+    col(:status) do |work_experience_record|
+      work_experience_record.status unless work_experience_record.backdated?
+    end
+
+    col(:submitted_at, label: 'Submitted') do |work_experience_record|
+      unless work_experience_record.backdated?
+        work_experience_record.submitted_at&.strftime('%F') || 'Not yet submitted'
+      end
+    end
+
+    col(:reviewed_at, label: 'Reviewed', as: :date) do |work_experience_record|
+      unless work_experience_record.backdated?
+        work_experience_record.reviewed_at&.strftime('%F') || 'Not yet reviewed'
+      end
+    end
+
+    aggregate :total
+
+    unless attributes[:skip_actions]
+      actions_col
+    end
+  end
+
+  collection do
+    scope = Effective::WorkExperienceRecord.deep.all
+    scope = scope.where(user_id: attributes[:user_id], user_type: attributes[:user_type]) if attributes[:user_id].present?
+
+    if work_experience_summary.present?
+      scope = scope.during(work_experience_summary.months)
+    end
+
+    scope
+  end
+
+  def work_experience_summary
+    @work_experience_summary ||= if attributes[:work_experience_summary_id].present?
+      EffectiveWorkExperience.WorkExperienceSummary.find_by_id(attributes[:work_experience_summary_id])
+    end
+  end
+
+end

data/app/datatables/effective_work_experience_reports_review_datatable.rb

@@ -0,0 +1,15 @@
+# The work experience reports of the interns I am a mentor for
+class EffectiveWorkExperienceReportsReviewDatatable < Effective::Datatable
+  datatable do
+    col :user, label: 'Intern'
+
+    actions_col do |user|
+      dropdown_link_to("Show #{et(Effective::WorkExperienceReport)}", effective_work_experience.work_experience_report_path(user))
+    end
+  end
+
+  collection do
+    current_user.work_experience_mentees.map { |user| [user, user] }
+  end
+
+end

data/app/datatables/effective_work_experience_summaries_datatable.rb

@@ -0,0 +1,49 @@
+# My work experience summaries
+class EffectiveWorkExperienceSummariesDatatable < Effective::Datatable
+  datatable do
+    order :created_at
+
+    col :token, visible: false
+    col :created_at, visible: false
+
+    col :start_on
+    col :end_on, visible: false
+    col :period
+
+    col :mentor
+
+    col(:total_hours, label: 'Hours') do |work_experience_summary|
+      work_experience_hours_to_s(work_experience_summary.total_hours)
+    end
+
+    col(:total_hours_to_date, as: :decimal) do |work_experience_summary|
+      work_experience_hours_to_s(work_experience_summary.total_hours_to_date)
+    end
+
+    col :status
+
+    col(:submitted_at, label: 'Submitted') do |work_experience_summary|
+      work_experience_summary.submitted_at&.strftime('%F') || 'Incomplete'
+    end
+
+    col(:reviewed_at, label: 'Reviewed', as: :date) do |work_experience_summary|
+      work_experience_summary.reviewed_at&.strftime('%F') || 'Not yet reviewed'
+    end
+
+    actions_col(show: false) do |work_experience_summary|
+      if work_experience_summary.draft?
+        dropdown_link_to('Continue', effective_work_experience.work_experience_summary_build_path(work_experience_summary, work_experience_summary.next_step), 'data-turbolinks' => false)
+        dropdown_link_to('Delete', effective_work_experience.work_experience_summary_path(work_experience_summary), 'data-confirm': "Really delete #{work_experience_summary}?", 'data-method': :delete)
+      else
+        dropdown_link_to('Show', effective_work_experience.work_experience_summary_path(work_experience_summary))
+      end
+    end
+  end
+
+  collection do
+    scope = EffectiveWorkExperience.WorkExperienceSummary.deep.all
+    scope = scope.where(user_id: attributes[:user_id], user_type: attributes[:user_type]) if attributes[:user_id].present?
+    scope
+  end
+
+end

data/app/datatables/effective_work_experience_summaries_review_datatable.rb

@@ -0,0 +1,43 @@
+# The mentor's work experience summaries to review
+class EffectiveWorkExperienceSummariesReviewDatatable < Effective::Datatable
+  datatable do
+    order :created_at
+
+    col :token, visible: false
+    col :created_at, visible: false
+
+    col(:submitted_at, label: 'Submitted') do |work_experience_summary|
+      work_experience_summary.submitted_at&.strftime('%F') || 'Incomplete'
+    end
+
+    col :user, label: 'Intern'
+    col :period
+    col :start_on, visible: false
+    col :end_on, visible: false
+
+    col(:total_hours) do |work_experience_summary|
+      work_experience_hours_to_s(work_experience_summary.total_hours)
+    end
+
+    col :status
+
+    col :recommendation, search: :string, visible: false
+    col :comments, visible: false
+
+    actions_col(show: false) do |work_experience_summary|
+      if work_experience_summary.submitted?
+        dropdown_link_to('Start Review', effective_work_experience.work_experience_summary_build_path(work_experience_summary, work_experience_summary.next_step), 'data-turbolinks' => false)
+      else
+        dropdown_link_to('Show', effective_work_experience.work_experience_summary_path(work_experience_summary))
+        dropdown_link_to('Review again', effective_work_experience.work_experience_summary_build_path(work_experience_summary, :review), 'data-turbolinks' => false)
+      end
+    end
+  end
+
+  collection do
+    scope = EffectiveWorkExperience.WorkExperienceSummary.deep.where.not(status: :draft)
+    scope = scope.where(mentor_id: attributes[:mentor_id], mentor_type: attributes[:mentor_type]) if attributes[:mentor_id].present?
+    scope
+  end
+
+end

data/app/helpers/effective_work_experience_helper.rb

@@ -0,0 +1,46 @@
+module EffectiveWorkExperienceHelper
+
+  # Display hours with one decimal place
+  def work_experience_hours_to_s(hours)
+    return if hours.blank?
+    "%0.1f" % hours
+  end
+
+  # Display a collection of every summary period going back 10 years
+  def work_experience_summary_start_on_collection(work_experience_summary = nil)
+    disabled = if work_experience_summary.present?
+      work_experience_summary.user.work_experience_summaries.where.not(id: work_experience_summary.id).pluck(:start_on)
+    end
+
+    disabled ||= []
+
+    date = Time.zone.now.beginning_of_quarter
+    end_date = (date - 10.years).beginning_of_year
+
+    collection = []
+
+    while date >= end_date
+      start_on = date.beginning_of_quarter
+      end_on = date.end_of_quarter
+
+      collection << [
+        "#{start_on.strftime('%B %Y')} to #{end_on.strftime('%B %Y')}",
+        date.strftime('%Y-%m-%d'),
+        disabled: disabled.include?(date)
+      ]
+
+      date -= 3.months
+    end
+
+    collection
+  end
+
+  def work_experience_summary_status_collection
+    EffectiveWorkExperience.WorkExperienceSummary::STATUSES
+  end
+
+  def work_experience_recommendation_collection
+    Array(EffectiveWorkExperience.recommendations)
+  end
+
+end

data/app/mailers/effective/work_experience_mailer.rb

@@ -0,0 +1,39 @@
+module Effective
+  class WorkExperienceMailer < EffectiveWorkExperience.parent_mailer_class
+
+    include EffectiveMailer
+    include EffectiveEmailTemplatesMailer if EffectiveWorkExperience.use_effective_email_templates
+
+    def work_experience_summary_submitted(resource, opts = {})
+      @assigns = work_experience_summary_assigns(resource)
+      mail(to: resource.mentor.email, **headers_for(resource, opts))
+    end
+
+    def work_experience_summary_reviewed(resource, opts = {})
+      @assigns = work_experience_summary_assigns(resource)
+      mail(to: resource.user.email, **headers_for(resource, opts))
+    end
+
+    protected
+
+    def assigns_for(resource)
+      return work_experience_summary_assigns(resource) if resource.class.try(:effective_work_experience_summary?)
+      raise('unexpected resource')
+    end
+
+    def work_experience_summary_assigns(resource)
+      raise('expected a work experience summary') unless resource.class.try(:effective_work_experience_summary?)
+
+      user = resource.user
+      mentor = resource.mentor
+
+      {
+        user: { name: user.try(:email_to_s) || user.to_s, email: user.email },
+        mentor: { name: mentor.try(:email_to_s) || mentor.to_s, email: mentor.try(:email) },
+        period: resource.period,
+        url: link_to(effective_work_experience.work_experience_summary_url(resource))
+      }
+    end
+
+  end
+end

data/app/models/concerns/effective_work_experience_summary.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+# EffectiveWorkExperienceSummary
+#
+# Mark your model with effective_work_experience_summary to get all the includes
+#
+# The summary of an intern's work experience for one period, usually 3 months.
+# Submitted by the intern, and reviewed by their mentor.
+
+module EffectiveWorkExperienceSummary
+  extend ActiveSupport::Concern
+
+  module Base
+    def effective_work_experience_summary
+      include ::EffectiveWorkExperienceSummary
+    end
+  end
+
+  module ClassMethods
+    def effective_work_experience_summary?; true; end
+  end
+
+  included do
+    # The intern
+    belongs_to :user, polymorphic: true
+
+    # The mentor reviews the submitted work experience summary
+    belongs_to :mentor, polymorphic: true, optional: true
+
+    # The supervisor is responsible for the intern's day to day work
+    belongs_to :supervisor, polymorphic: true, optional: true
+
+    acts_as_tokened
+
+    log_changes(to: :user) if respond_to?(:log_changes)
+
+    acts_as_statused(
+      :draft,       # In-progress submission
+      :submitted,   # Submitted by intern
+      :reviewed     # Reviewed by mentor
+    )
+
+    acts_as_wizard(
+      # Intern steps
+      start: 'Start',
+      records: 'Work Experience Hours',
+      projects: 'Work Experience Projects',
+      submit: 'Submit',
+
+      # Intern and mentor step
+      submitted: 'Submitted',
+
+      # Mentor steps
+      review: 'Mentor Review',
+      reviewed: 'Reviewed'
+    )
+
+    # The mentor review step
+    attr_accessor :approve_work_experience_summary
+
+    # Set to true when importing historic data. Skips sending emails.
+    attr_accessor :importing
+
+    effective_resource do
+      start_on              :date
+      end_on                :date
+
+      total_hours           :decimal    # The total number of hours worked this period
+
+      recommendation        :string
+      comments              :text       # Private rolling comments displayed to the mentor
+
+      # Acts as Statused
+      status                :string
+      status_steps          :text
+
+      submitted_at          :datetime
+      reviewed_at           :datetime
+
+      # Acts as Wizard
+      wizard_steps          :text, permitted: false
+
+      # Acts as Tokened
+      token                 :string
+
+      timestamps
+    end
+
+    scope :sorted, -> { order(:start_on) }
+    scope :deep, -> { includes(:user, :mentor, :supervisor) }
+
+    scope :in_progress, -> { where(status: :draft) }
+    scope :in_progress_for, ->(user) { where(user: user, status: :draft) }
+    scope :done, -> { where(status: [:submitted, :reviewed]) }
+
+    before_validation do
+      # Only assign from the user when they have the association. Otherwise leave whatever was assigned.
+      assign_attributes(mentor: user.work_experience_mentor) if user.respond_to?(:work_experience_mentor)
+      assign_attributes(supervisor: user.supervisor) if user.respond_to?(:supervisor)
+    end
+
+    before_validation do
+      # The admin forms assign the mentor and supervisor id without the polymorphic type
+      assign_attributes(mentor_type: (mentor_type.presence || user&.class&.name)) if mentor_id.present?
+      assign_attributes(supervisor_type: (supervisor_type.presence || user&.class&.name)) if supervisor_id.present?
+
+      assign_attributes(mentor_type: nil) if mentor_id.blank?
+      assign_attributes(supervisor_type: nil) if supervisor_id.blank?
+    end
+
+    before_validation do
+      assign_attributes(start_on: start_on&.beginning_of_quarter, end_on: start_on&.end_of_quarter)
+      assign_attributes(total_hours: calculate_total_hours)
+    end
+
+    before_validation do
+      assign_attributes(recommendation: recommendations.first) if approve_work_experience_summary
+    end
+
+    validates :start_on, presence: true, uniqueness: { scope: [:user_id, :user_type] }
+    validates :end_on, presence: true
+    validates :total_hours, numericality: { greater_than_or_equal_to: 0.0, allow_blank: true }
+
+    validate(if: -> { user.present? }) do
+      errors.add(:user, 'must have a mentor') unless mentor_present?
+    end
+
+    validate(if: -> { start_on.present? && end_on.present? }) do
+      errors.add(:end_on, 'must be after start date') unless end_on > start_on
+      errors.add(:end_on, "must be #{summary_months} months after start date") unless (end_on.month - start_on.month) == (summary_months - 1)
+    end
+
+    with_options(if: -> { current_step == :review }) do
+      validates :approve_work_experience_summary, acceptance: true
+      validates :recommendation, presence: true
+    end
+  end
+
+  def to_s
+    start_on&.strftime('%B %Y') || model_name.human
+  end
+
+  # The intern completes the first half of the wizard, the mentor completes the second half
+  def intern_steps
+    [:start, :records, :projects, :submit, :submitted, :reviewed]
+  end
+
+  def mentor_steps
+    [:submitted, :review, :reviewed]
+  end
+
+  def recommendations
+    Array(EffectiveWorkExperience.recommendations)
+  end
+
+  def summary_months
+    (EffectiveWorkExperience.summary_months || 3)
+  end
+
+  # The first day of each month in this summary period
+  def months
+    @months ||= start_on.all_quarter.to_a.select { |month| month.day == 1 }
+  end
+
+  def period
+    return if start_on.blank?
+    "#{months.first.strftime('%B %Y')} to #{months.last.strftime('%B %Y')}"
+  end
+
+  # An intern with an outside mentor has no mentor user. Their summaries are automatically reviewed.
+  def mentor_present?
+    mentor.present? || user.try(:work_experience_outside_mentor?).present?
+  end
+
+  def can_visit_step?(current_step)
+    return false if current_user == user && intern_steps.exclude?(current_step)
+    return false if current_user == mentor && mentor_steps.exclude?(current_step)
+
+    # Once submitted, the intern cannot go back and submit again
+    if was_submitted?
+      return false if [:start, :records, :projects, :submit].include?(current_step)
+    end
+
+    # Once reviewed, the mentor can go back and review again
+    if was_reviewed?
+      return [:review, :reviewed].include?(current_step)
+    end
+
+    can_revisit_completed_steps(current_step)
+  end
+
+  def total_hours_to_date
+    user.work_experience_total_hours_to_date(month: end_on)
+  end
+
+  def status_label
+    (status_was || status).to_s.gsub('_', ' ').titleize
+  end
+
+  def summary
+    case status_was
+    when 'draft'
+      "Work experience summary has not yet been submitted."
+    when 'submitted'
+      "Work experience summary has been submitted."
+    when 'reviewed'
+      "Work experience summary has been reviewed."
+    else
+      raise("unexpected status #{status}")
+    end.html_safe
+  end
+
+  def work_experience_subcategories
+    Effective::WorkExperienceSubcategory.all.sorted
+  end
+
+  def work_experience_records
+    @work_experience_records ||= user.work_experience_records.where(month: months)
+  end
+
+  def work_experience_projects
+    @work_experience_projects ||= user.work_experience_projects.during(months)
+  end
+
+  def submit!
+    raise('already submitted') if was_submitted?
+
+    wizard_steps[:submit] ||= Time.zone.now
+    wizard_steps[:submitted] = Time.zone.now
+
+    if mentor.present? && !importing
+      after_commit { EffectiveWorkExperience.mailer_class.work_experience_summary_submitted(self).deliver }
+    end
+
+    work_experience_records.reject(&:was_submitted?).each { |work_experience_record| work_experience_record.submitted! }
+    submitted!
+
+    # Auto review summaries for interns without a mentor user
+    review! if mentor.blank?
+
+    true
+  end
+
+  def review!
+    wizard_steps[:review] ||= Time.zone.now
+    wizard_steps[:reviewed] = Time.zone.now
+
+    # If it was previously reviewed, or there is no mentor, we don't want to send an email
+    unless was_reviewed? || mentor.blank? || importing
+      after_commit { EffectiveWorkExperience.mailer_class.work_experience_summary_reviewed(self).deliver }
+    end
+
+    work_experience_records.reject(&:was_reviewed?).each { |work_experience_record| work_experience_record.reviewed! }
+    reviewed!
+  end
+
+  private
+
+  def calculate_total_hours
+    return if user.blank? || start_on.blank? || end_on.blank?
+    user.work_experience_records.where(month: months).sum { |work_experience_record| work_experience_record.total_hours.to_f }.round(2)
+  end
+
+end

data/app/models/concerns/effective_work_experience_user.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# EffectiveWorkExperienceUser
+#
+# Mark your user model with effective_work_experience_user to get the work experience associations
+# and the hours calculations used by the records, summaries and reports.
+#
+# Requires a work_experience_mentor_id column on your users table.
+#
+# Your user model may also define:
+# - supervisor        the user responsible for this intern's day to day work
+
+module EffectiveWorkExperienceUser
+  extend ActiveSupport::Concern
+
+  module Base
+    def effective_work_experience_user
+      include ::EffectiveWorkExperienceUser
+    end
+  end
+
+  module ClassMethods
+    def effective_work_experience_user?; true; end
+  end
+
+  included do
+    # The user who reviews my work experience summaries
+    belongs_to :work_experience_mentor, class_name: name, optional: true
+
+    # The interns I am a mentor for
+    has_many :work_experience_mentees, -> { order(:id) }, class_name: name, foreign_key: :work_experience_mentor_id, inverse_of: :work_experience_mentor, dependent: :nullify
+
+    # There is only ever one. The has_many is for the admin form fields.
+    # reject_if so the blank one built by the form is ignored unless it's filled in.
+    has_one :work_experience_outside_mentor, as: :user, class_name: 'Effective::WorkExperienceOutsideMentor'
+    has_many :work_experience_outside_mentors, as: :user, dependent: :destroy, class_name: 'Effective::WorkExperienceOutsideMentor'
+    accepts_nested_attributes_for :work_experience_outside_mentors, allow_destroy: true, reject_if: :all_blank
+
+    # Virtual. The admin form checkbox that toggles the outside mentor fields.
+    attr_accessor :work_experience_outside_mentor_present
+
+    # An intern has a mentor user or an outside mentor. Never both.
+    before_validation(if: -> { work_experience_outside_mentor_present.present? }) do
+      if EffectiveResources.truthy?(work_experience_outside_mentor_present)
+        assign_attributes(work_experience_mentor: nil)
+      else
+        work_experience_outside_mentors.each { |outside_mentor| outside_mentor.mark_for_destruction }
+      end
+    end
+
+    has_many :work_experience_records, -> { order(:month) }, as: :user, dependent: :destroy, class_name: 'Effective::WorkExperienceRecord'
+    has_many :work_experience_entries, -> { order(:id) }, as: :user, dependent: :destroy, class_name: 'Effective::WorkExperienceEntry'
+    has_many :work_experience_projects, -> { order(:start_on) }, as: :user, dependent: :destroy, class_name: 'Effective::WorkExperienceProject'
+
+    has_many :work_experience_summaries, -> { order(:start_on) }, as: :user, dependent: :destroy, class_name: EffectiveWorkExperience.class_name(name, :work_experience_summaries)
+
+    # I'm the mentor for these work experience summaries
+    has_many :mentee_work_experience_summaries, -> { order(:start_on) }, as: :mentor, class_name: EffectiveWorkExperience.class_name(name, :work_experience_summaries)
+
+    scope :work_experience_mentors, -> { where(id: unscoped.select(:work_experience_mentor_id)) }
+
+    scope :deep_work_experience, -> {
+      includes(:work_experience_mentor)
+      .includes(work_experience_records: [work_experience_entries: { work_experience_subcategory: :work_experience_category }])
+    }
+  end
+
+  def work_experience_intern?
+    return true if try(:intern?)
+    work_experience_records.present? || work_experience_summaries.present?
+  end
+
+  def work_experience_mentor?
+    work_experience_mentees.present? || mentee_work_experience_summaries.present?
+  end
+
+  # This intern's mentor does not have an account. Their summaries are reviewed automatically.
+  def work_experience_outside_mentor?
+    work_experience_outside_mentor.present?
+  end
+
+  def work_experience_subcategories
+    @work_experience_subcategories ||= Effective::WorkExperienceSubcategory.all.sorted
+  end
+
+  # One subcategory and month
+  def work_experience_hours(month:, work_experience_subcategory: nil)
+    work_experience_record = work_experience_records.find { |record| record.month == month }
+    return 0.0 if work_experience_record.blank?
+
+    hours = if work_experience_subcategory.present?
+      work_experience_record.work_experience_entry(work_experience_subcategory: work_experience_subcategory).hours
+    else
+      work_experience_record.work_experience_entries.sum { |work_experience_entry| work_experience_entry.hours }
+    end
+
+    hours.round(2)
+  end
+
+  # One subcategory for every month in this year
+  def work_experience_hours_by_year(year:, work_experience_subcategory: nil)
+    work_experience_records_in_year = work_experience_records.select { |record| record.month.present? && record.month.year == year }
+    return 0.0 if work_experience_records_in_year.blank?
+
+    hours = if work_experience_subcategory.present?
+      work_experience_records_in_year.sum { |record| record.work_experience_entry(work_experience_subcategory: work_experience_subcategory).hours }
+    else
+      work_experience_records_in_year.sum { |record| record.work_experience_entries.sum { |work_experience_entry| work_experience_entry.hours } }
+    end
+
+    hours.round(2)
+  end
+
+  # One subcategory for all months up to and including this month
+  def work_experience_total_hours_to_date(month:, work_experience_subcategory: nil)
+    work_experience_records_to_date = if month.blank?
+      work_experience_records.select { |record| record.backdated? }
+    else
+      work_experience_records.select { |record| record.backdated? || record.month <= month }
+    end
+
+    return 0.0 if work_experience_records_to_date.blank?
+
+    hours = work_experience_records_to_date.sum do |work_experience_record|
+      if work_experience_subcategory.present?
+        work_experience_record.work_experience_entry(work_experience_subcategory: work_experience_subcategory).hours
+      else
+        work_experience_record.work_experience_entries.sum { |work_experience_entry| work_experience_entry.hours }
+      end
+    end
+
+    hours.round(2)
+  end
+
+end