Merge branch 'quarter-postfactum-evaluation'

bibendi · bibendi · commit f32befbb5edb · 2026-04-15T11:55:02.000+03:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -44,9 +44,11 @@ Starmap is a corporate web application for managing technical team competencies,
 - Role-based validation and Quarter state constraints
 
 **Quarterly Cycles**
-- Automated creation of new cycles with copying of previous ratings
+- Quarters are created **retrospectively**, after the evaluated period has ended
+- Previous quarter's ratings are copied as a starting point when a quarter is activated
 - Status workflow: draft → active → closed → archived
-- Editing restrictions based on quarter state ensure data integrity
+- Evaluation window (`evaluation_start_date`..`evaluation_end_date`) opens **after** the quarter's `end_date`
+- Editing restrictions based on quarter state and evaluation period ensure data integrity
 
 **Analytics Dashboards**
 - **Overview Dashboard**: Unit-level metrics and risks for leadership
@@ -78,7 +80,7 @@ Status tracking of development plans linked to quarters and technologies.
 ## Role Interactions
 
 1. **Data Collection**: Engineer updates self-ratings → Team Lead validates and approves → data flows to metrics
-2. **Quarterly Cycle**: Admin/Unit Lead launches new quarter, copies past ratings, notifications sent
+2. **Quarterly Cycle**: Admin creates quarter retrospectively after period ends, activates it (copies past ratings as starting point), notifications sent
 3. **Analytics**: Unit Lead tracks Coverage/Maturity/Red Zones, Team Lead monitors team competencies, Engineer tracks personal progress
 4. **Risk Management**: Metrics signal gaps; Team Lead and Unit Lead plan expertise exchange
 5. **Development**: Action Plans link development goals to quarters, technologies, and employees
@@ -323,7 +325,7 @@ bundle exec brakeman
 
 **Role-based Authorization**: Four distinct roles with Pundit policies enforcing granular permissions.
 
-**Quarterly Data Model**: Immutable past quarters with draft/active states. Ratings editable only in non-archived quarters.
+**Quarterly Data Model**: Quarters created retrospectively after the period ends. Evaluation window opens after quarter's `end_date`. Ratings editable only during evaluation period of active quarters.
 
 ---
 
diff --git a/README.md b/README.md
@@ -89,11 +89,14 @@ Every rating answers the question: *"What can I practically do with this technol
 
 ### Quarterly Cycle
 
-The process repeats every quarter in three phases:
+Starmap evaluates competencies **retrospectively** — after a quarter ends, not while it's in progress. The process repeats every quarter:
 
-1. **Self-assessment** — engineers rate themselves asynchronously across team technologies
-2. **1-on-1 dialogue** — team lead and engineer discuss ratings, sync on levels, and build a development plan
-3. **Execution** — development goals are integrated into sprint planning, code reviews, and mentoring
+1. **Quarter creation** — an admin creates a new quarter (e.g. "2026 Q1") after it has ended, sets the evaluation window dates
+2. **Activation & self-assessment** — the admin activates the quarter; previous quarter's ratings are copied as a starting point. Engineers then rate themselves asynchronously across team technologies during the evaluation window
+3. **1-on-1 dialogue** — team lead and engineer discuss ratings, sync on levels, and build a development plan
+4. **Close** — the admin closes the quarter; all remaining draft/submitted ratings are auto-approved. The quarter becomes read-only
+
+Quarter lifecycle: `draft` → `active` → `closed` → `archived`
 
 ### User Roles
 
diff --git a/app/controllers/admin/quarters_controller.rb b/app/controllers/admin/quarters_controller.rb
@@ -117,12 +117,19 @@ def quarter_params
     end
 
     def set_default_year_and_quarter
-      current_year = Date.current.year
-      existing_quarters = Quarter.where(year: current_year).pluck(:quarter_number)
-      available_quarter = (1..4).find { |q| !existing_quarters.include?(q) }
+      today = Date.current
+      current_quarter_number = ((today.month - 1) / 3) + 1
 
-      @quarter.year = current_year
-      @quarter.quarter_number = available_quarter || 1
+      previous_quarter_year = (current_quarter_number == 1) ? today.year - 1 : today.year
+      previous_quarter_number = (current_quarter_number == 1) ? 4 : current_quarter_number - 1
+
+      if Quarter.exists?(year: previous_quarter_year, quarter_number: previous_quarter_number)
+        @quarter.year = today.year
+        @quarter.quarter_number = current_quarter_number
+      else
+        @quarter.year = previous_quarter_year
+        @quarter.quarter_number = previous_quarter_number
+      end
     end
 
     def load_quarter_metrics
diff --git a/app/models/quarter.rb b/app/models/quarter.rb
@@ -21,11 +21,11 @@ class Quarter < ApplicationRecord
   validates :status, presence: true, inclusion: {in: %w[draft active closed archived]}
   validates :quarter_number, uniqueness: {scope: :year}
 
-  validate :validate_year_is_current_or_future
   validate :validate_date_sequence
-  validate :validate_evaluation_dates
+  validate :validate_evaluation_after_quarter
 
   before_validation :set_quarter_name, on: :create
+  before_validation :set_quarter_dates, on: :create
   after_create :set_as_current_if_first
   after_update :handle_status_change
 
@@ -50,22 +50,19 @@ def self.current
 
   private
 
-  def validate_year_is_current_or_future
-    return if year.blank?
-
-    errors.add(:year, :current_or_future_only) if year < Date.current.year
-  end
-
   def validate_date_sequence
     return unless start_date.present? && end_date.present?
     errors.add(:end_date, :after_start_date) if end_date <= start_date
 
     return unless evaluation_start_date.present? && evaluation_end_date.present?
-    errors.add(:evaluation_start_date, :within_quarter) if evaluation_start_date < start_date || evaluation_start_date > end_date
-    errors.add(:evaluation_end_date, :within_quarter) if evaluation_end_date < start_date || evaluation_end_date > end_date
     errors.add(:evaluation_end_date, :after_eval_start) if evaluation_end_date <= evaluation_start_date
   end
 
+  def validate_evaluation_after_quarter
+    return unless evaluation_start_date.present? && end_date.present?
+    errors.add(:evaluation_start_date, :after_quarter_end) if evaluation_start_date < end_date
+  end
+
   def validate_evaluation_dates
     return unless evaluation_start_date.present? && evaluation_end_date.present?
 
@@ -78,6 +75,13 @@ def set_quarter_name
     self.name ||= full_name
   end
 
+  def set_quarter_dates
+    return unless year.present? && quarter_number.present?
+
+    self.start_date ||= Date.new(year, (quarter_number - 1) * 3 + 1, 1)
+    self.end_date ||= start_date.end_of_quarter
+  end
+
   def set_as_current_if_first
     update!(is_current: true) if Quarter.count == 1
   end
diff --git a/app/services/quarter_status_service.rb b/app/services/quarter_status_service.rb
@@ -18,6 +18,7 @@ def activate
         status: :active,
         is_current: true
       )
+      copy_previous_quarter_ratings
     end
 
     true
@@ -99,4 +100,11 @@ def current_quarter_exists?
   def deactivate_current_quarter
     Quarter.where(is_current: true).update_all(is_current: false)
   end
+
+  def copy_previous_quarter_ratings
+    previous = @quarter.previous_quarter
+    return unless previous
+
+    QuarterDataCopier.new(@quarter, previous).copy_from_previous
+  end
 end
diff --git a/app/views/admin/quarters/edit.html.erb b/app/views/admin/quarters/edit.html.erb
@@ -34,7 +34,7 @@
           <div>
             <%= f.label :year, t("activerecord.attributes.quarter.year"), class: "form-label" %>
             <div class="form-field">
-              <%= f.number_field :year, min: Date.current.year, required: true, class: "form-input" %>
+              <%= f.number_field :year, min: 2000, required: true, class: "form-input" %>
             </div>
           </div>
 
diff --git a/app/views/admin/quarters/new.html.erb b/app/views/admin/quarters/new.html.erb
@@ -34,7 +34,7 @@
           <div>
             <%= f.label :year, t("activerecord.attributes.quarter.year"), class: "form-label" %>
             <div class="form-field">
-              <%= f.number_field :year, min: Date.current.year, required: true, class: "form-input" %>
+              <%= f.number_field :year, min: 2000, required: true, class: "form-input" %>
             </div>
           </div>
 
diff --git a/config/locales/en.yml b/config/locales/en.yml
@@ -538,14 +538,11 @@ en:
           attributes:
             quarter_number:
               taken: "already exists for this year"
-            year:
-              current_or_future_only: "must be current or future year"
             end_date:
               after_start_date: "must be after start date"
             evaluation_start_date:
-              within_quarter: "must be within quarter period"
+              after_quarter_end: "must be on or after quarter end date"
             evaluation_end_date:
-              within_quarter: "must be within quarter period"
               after_eval_start: "must be after evaluation start date"
       messages:
         too_long_evaluation_period: "Evaluation period must not exceed 30 days"
diff --git a/config/locales/ru.yml b/config/locales/ru.yml
@@ -523,14 +523,11 @@ ru:
           attributes:
             quarter_number:
               taken: "уже существует для этого года"
-            year:
-              current_or_future_only: "может быть только текущим или будущим годом"
             end_date:
               after_start_date: "должна быть позже даты начала"
             evaluation_start_date:
-              within_quarter: "должна быть в периоде квартала"
+              after_quarter_end: "должна быть не раньше даты окончания квартала"
             evaluation_end_date:
-              within_quarter: "должна быть в периоде квартала"
               after_eval_start: "должна быть позже даты начала оценки"
       messages:
         too_long_evaluation_period: "период оценки не должен превышать 30 дней"
diff --git a/db/seeds.rb b/db/seeds.rb
@@ -202,8 +202,8 @@ def target_experts_for_criticality(criticality)
   quarter.status = "active"
   quarter.description = "Quarter #{current_q_num} #{current_year}"
   quarter.is_current = true
-  quarter.evaluation_start_date = current_start
-  quarter.evaluation_end_date = current_start + 14.days
+  quarter.evaluation_start_date = current_end
+  quarter.evaluation_end_date = current_end + 14.days
 end
 
 previous_quarter = Quarter.find_or_create_by!(
@@ -216,8 +216,8 @@ def target_experts_for_criticality(criticality)
   quarter.status = "closed"
   quarter.description = "Quarter #{prev_q_num} #{prev_year}"
   quarter.is_current = false
-  quarter.evaluation_start_date = prev_start
-  quarter.evaluation_end_date = prev_start + 14.days
+  quarter.evaluation_start_date = prev_end
+  quarter.evaluation_end_date = prev_end + 14.days
 end
 
 Rails.logger.debug "Creating test users..."
diff --git a/spec/factories/quarters.rb b/spec/factories/quarters.rb
@@ -1,16 +1,16 @@
 # Quarter factory for testing
 FactoryBot.define do
   sequence(:quarter_year) { |n| Date.current.year + (n / 4) }
-  sequence(:quarter_number_seq) { |n| ((n % 4) + 1) }
+  sequence(:quarter_number_seq) { |n| (n % 4) + 1 }
 
   factory :quarter do
     year { generate(:quarter_year) }
     quarter_number { generate(:quarter_number_seq) }
     name { "#{year} Q#{quarter_number}" }
     start_date { Date.new(year, (quarter_number - 1) * 3 + 1, 1) }
-    end_date { start_date.end_of_quarter }
-    evaluation_start_date { start_date }
-    evaluation_end_date { evaluation_start_date + 14.days }
+    end_date { start_date&.end_of_quarter }
+    evaluation_start_date { end_date }
+    evaluation_end_date { evaluation_start_date ? evaluation_start_date + 14.days : nil }
     status { "active" }
     is_current { false }
     description { "Test quarter #{name}" }
@@ -43,7 +43,7 @@
           quarter.name = "#{quarter.year} Q#{quarter.quarter_number}"
           quarter.start_date = Date.new(quarter.year, (quarter.quarter_number - 1) * 3 + 1, 1)
           quarter.end_date = quarter.start_date.end_of_quarter
-          quarter.evaluation_start_date = quarter.start_date
+          quarter.evaluation_start_date = quarter.end_date
           quarter.evaluation_end_date = quarter.evaluation_start_date + 14.days
         end
       end
diff --git a/spec/models/quarter_spec.rb b/spec/models/quarter_spec.rb
@@ -78,15 +78,33 @@
       expect(quarter.errors[:end_date]).to be_present
     end
 
-    it "validates evaluation_start_date within quarter period" do
+    it "validates evaluation_start_date must be on or after quarter end_date" do
       quarter = build(:quarter,
         start_date: Date.new(2026, 4, 1), end_date: Date.new(2026, 6, 30),
-        evaluation_start_date: Date.new(2026, 3, 1), evaluation_end_date: Date.new(2026, 4, 15))
+        evaluation_start_date: Date.new(2026, 6, 15), evaluation_end_date: Date.new(2026, 7, 15))
       quarter.valid?
 
       expect(quarter.errors[:evaluation_start_date]).to be_present
     end
 
+    it "accepts evaluation_start_date equal to end_date" do
+      quarter = build(:quarter,
+        start_date: Date.new(2026, 4, 1), end_date: Date.new(2026, 6, 30),
+        evaluation_start_date: Date.new(2026, 6, 30), evaluation_end_date: Date.new(2026, 7, 15))
+      quarter.valid?
+
+      expect(quarter.errors[:evaluation_start_date]).to be_empty
+    end
+
+    it "accepts evaluation dates after quarter end_date" do
+      quarter = build(:quarter,
+        start_date: Date.new(2026, 4, 1), end_date: Date.new(2026, 6, 30),
+        evaluation_start_date: Date.new(2026, 7, 1), evaluation_end_date: Date.new(2026, 7, 15))
+      quarter.valid?
+
+      expect(quarter.errors[:evaluation_start_date]).to be_empty
+    end
+
     it "validates evaluation_end_date after evaluation_start_date" do
       quarter = build(:quarter,
         start_date: Date.new(2026, 4, 1), end_date: Date.new(2026, 6, 30),
@@ -96,11 +114,11 @@
       expect(quarter.errors[:evaluation_end_date]).to be_present
     end
 
-    it "rejects past year" do
+    it "accepts past year" do
       quarter = build(:quarter, year: 2020)
       quarter.valid?
 
-      expect(quarter.errors[:year]).to be_present
+      expect(quarter.errors[:year]).to be_empty
     end
 
     it "accepts current year" do
@@ -126,6 +144,32 @@
       end
     end
 
+    describe "before_validation :set_quarter_dates, on: :create" do
+      it "auto-sets start_date and end_date from year and quarter_number" do
+        quarter = described_class.new(year: 2026, quarter_number: 1, evaluation_end_date: Date.new(2026, 4, 14))
+        quarter.valid?
+
+        expect(quarter.start_date).to eq(Date.new(2026, 1, 1))
+        expect(quarter.end_date).to eq(Date.new(2026, 3, 31))
+      end
+
+      it "auto-sets dates for Q3" do
+        quarter = described_class.new(year: 2026, quarter_number: 3, evaluation_end_date: Date.new(2026, 10, 14))
+        quarter.valid?
+
+        expect(quarter.start_date).to eq(Date.new(2026, 7, 1))
+        expect(quarter.end_date).to eq(Date.new(2026, 9, 30))
+      end
+
+      it "does not overwrite explicit start_date" do
+        explicit = Date.new(2026, 4, 15)
+        quarter = described_class.new(year: 2026, quarter_number: 2, start_date: explicit, evaluation_end_date: Date.new(2026, 7, 14))
+        quarter.valid?
+
+        expect(quarter.start_date).to eq(explicit)
+      end
+    end
+
     describe "after_create :set_as_current_if_first" do
       it "sets is_current when it is the first quarter" do
         quarter = create(:quarter)
diff --git a/spec/requests/admin/quarters_spec.rb b/spec/requests/admin/quarters_spec.rb
@@ -179,15 +179,16 @@
   end
 
   describe "POST /admin/quarters" do
+    let(:quarter_year) { Date.current.year + 50 }
     let(:valid_params) do
       {
         quarter: {
-          year: Date.current.year + 10,
+          year: quarter_year,
           quarter_number: 1,
-          start_date: "#{Date.current.year + 10}-01-01",
-          end_date: "#{Date.current.year + 10}-03-31",
-          evaluation_start_date: "#{Date.current.year + 10}-01-15",
-          evaluation_end_date: "#{Date.current.year + 10}-02-15"
+          start_date: "#{quarter_year}-01-01",
+          end_date: "#{quarter_year}-03-31",
+          evaluation_start_date: "#{quarter_year}-04-01",
+          evaluation_end_date: "#{quarter_year}-04-15"
         }
       }
     end
@@ -234,23 +235,26 @@
       end
 
       it "renders form with errors when quarter_number is invalid" do
-        invalid_params = {quarter: {year: valid_params[:quarter][:year], quarter_number: 5}}
+        invalid_params = {quarter: {year: quarter_year, quarter_number: 5, start_date: "#{quarter_year}-01-01", end_date: "#{quarter_year}-03-31"}}
         post admin_quarters_path, params: invalid_params
         expect(response).to have_http_status(:unprocessable_content)
         expect(response.body).to include("quarter_number")
       end
 
-      it "requires year to be current or future" do
-        invalid_params = {
+      it "accepts past year" do
+        past_params = {
           quarter: {
             year: 2020,
             quarter_number: 1,
             start_date: "2020-01-01",
-            end_date: "2020-03-31"
+            end_date: "2020-03-31",
+            evaluation_start_date: "2020-04-01",
+            evaluation_end_date: "2020-04-15"
           }
         }
-        post admin_quarters_path, params: invalid_params
-        expect(response).to have_http_status(:unprocessable_content)
+        expect {
+          post admin_quarters_path, params: past_params
+        }.to change(Quarter, :count).by(1)
       end
     end
 
diff --git a/spec/services/quarter_status_service_spec.rb b/spec/services/quarter_status_service_spec.rb
