hr_lite 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8202157b6f35309884c9df17895d711553e114a57925c8c2e381e51a7be863ba
-  data.tar.gz: 3cb55e413c6bcc70bd3aa39a5c212690a21c9cf747b17bfdf5894ef6d73945de
+  metadata.gz: ec0aa9dccb203487f12a0e30cbbae7567da32b9589af4046fe86795c9a3cb5a4
+  data.tar.gz: 0e5b02a62ea2925115f71279dd9772f12a103b6cc17fb6d192f0225a3c95504e
 SHA512:
-  metadata.gz: 0ddf504c20a84c58a712fd4efe695e9b90b27eea8acc8883bfb37d33df398778169c35eb2c11f37830e91c9ceec63560df57c631246b2b22381b52df5ce30144
-  data.tar.gz: 4a724d4a55068129237e010aca71ce94c392656bb56953a6f1ec5329ddf5d33b6ffd91f76c82229a152f85d134a60ca29308634133f0a3a72779cff3cc6dafdb
+  metadata.gz: e1877020700a05db3f7a5a4a715be0c1e8e7f4ad447d3c42eaf6d17b60e0252ef68968eb58f431e7373e43d3452bae468d6e211eac64c3f4e9ca71703920d412
+  data.tar.gz: 28d5a185fd3af1373efb3b2db1e3d53d8b64e66ec676a7cfed01c15ffbb8ed2a07b0a921d4351ac6afca41db18e683ae9ad984e99b5ffbf6eeac32209e108af0

data/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-08-18
+
+The screens for three features that shipped as tables nobody could reach. No
+migration — the data layer was already there.
+
+### Fixed
+
+- **Documents, tax declarations and loans had no UI at all.** 0.13.0 and
+  0.14.0 shipped their models, tables, payroll integration and an expiry job,
+  and every one of them passed its specs — but there was no controller, no
+  route and no view. An employee could not upload a passport, HR could not
+  verify a PAN, and nobody could file an 80C declaration. Loans at least
+  reached a payslip; the other two were unreachable rows.
+- **A tax declaration 500ed when a real browser saved it.** The form posts a
+  line for every section, because that is what a list of claimable things
+  looks like, and the blank ones violated a NOT NULL amount. The specs had
+  only ever posted the lines they filled in. Blank sections are now dropped,
+  and clearing an existing amount withdraws that claim.
+- `TaxDeclaration` and `ApprovalFlow` were missing `inverse_of` on their
+  nested associations. The foreign key is not derived from the class name, so
+  a nested item on an unsaved parent could not see it — every first save
+  failed with "declaration must exist".
+
+### Added
+
+- **Documents.** Employees upload, see what is expiring and remove anything
+  not yet verified; HR sees what is waiting, whose file is missing which
+  category, and verifies or sends one back with a reason. Downloads go
+  through the row's own `readable_by?` and every one is audited — a file
+  leaving the building is the event worth recording.
+- **Tax declarations.** A section-by-section claim the employee files
+  themselves, replacing an admin typing one lump sum into the profile. HR
+  records what the proof actually supported, which is often less than the
+  claim. Until it is verified payroll deducts against the CLAIM: making
+  somebody overpay tax all year because paperwork is slow is its own kind of
+  wrong.
+- **Loans.** Employees see what they owe and what comes out of the next
+  payslip; the money tier records a loan, closes it, or cancels one that has
+  not been deducted from yet. Cancelling after an instalment has been taken
+  is refused — that money has already left somebody's salary.
+- Nav entries for all three, employee and admin.
+
+### Changed
+
+- Verifying a document requires being able to OPEN it. Attesting to a scan
+  you are not allowed to look at is not verification, and it keeps an
+  Aadhaar with the money tier rather than with whoever happens to run HR.
+- The spec suite deletes its sqlite file before every run. The role and
+  rate-card migrations SEED rows, and seeds never overwrite what exists —
+  right in production, wrong in a test database, where a leftover file kept
+  yesterday's definitions and a change to `RoleSeeds` silently did not apply.
+
+## [0.14.0] - 2026-08-18
+
+The admin half, plus the two ends of employment that were still manual.
+**Adds one migration.**
+
+### Added
+
+- **Admin screens for everything shipped since 0.11.0**: decide a claim and
+  record the payroll month it was paid with, answer or hand on a help-desk
+  request, hand out and take back an asset. The engine had all of this; there
+  was no way to do any of it.
+- **Assets.** One live holder at a time, enforced by a partial unique index —
+  two open assignments would mean the laptop is in two places, which it is
+  not. Assignments are append-only and record what condition it came back in,
+  because "screen cracked" is the difference between an asset returned and an
+  asset written off.
+- **Joining and leaving checklists**, from templates. The joining list opens
+  when a profile is created and the leaving list when an exit date is
+  stamped — the checklist nobody remembers to start is the one that does not
+  happen. Opening is idempotent, so adding a template later adds only what is
+  new. A failure to build one can never stop an employee being created.
+- Each step names the permission its owner should hold, so IT taking back a
+  laptop and HR collecting a document are not the same person by accident.
+- Permissions `asset.view`, `asset.manage`, `checklist.manage`.
+
+### Why it matters
+
+An asset that is never returned is a cost nobody notices, and access that is
+never revoked is a security problem that outlives the employment. Both were
+previously somebody's memory.
+
 ## [0.13.0] - 2026-08-18
 
 The screens. No migration.
@@ -762,7 +845,9 @@ Initial release.
   bus with per-event channel matrix (bell, email, leadership email/bell),
   daily leadership digest and an append-only audit trail.
 
-[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/kshtzkr/hr_lite/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/kshtzkr/hr_lite/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/kshtzkr/hr_lite/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/kshtzkr/hr_lite/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/kshtzkr/hr_lite/compare/v0.10.0...v0.11.0

data/app/controllers/hr_lite/admin/assets_controller.rb

@@ -0,0 +1,53 @@
+module HrLite
+  module Admin
+    # Who has the laptop.
+    class AssetsController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_assets!
+
+      def index
+        @assets = paginate(Asset.order(:status, :name).includes(asset_assignments: :user))
+        @outstanding = AssetAssignment.live.includes(:asset, :user)
+      end
+
+      def new
+        @asset = Asset.new
+      end
+
+      def create
+        @asset = Asset.new(asset_params)
+        if @asset.save
+          redirect_to admin_assets_path, notice: "#{@asset.name} added."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def assign
+        asset = Asset.find(params[:id])
+        user = HrLite.user_klass.find(params[:user_id])
+        asset.assign_to!(user, actor: hr_current_user)
+        redirect_to admin_assets_path, notice: "#{asset.name} given to #{HrLite.display_name(user)}."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to admin_assets_path, alert: "#{asset.name} is already with somebody."
+      end
+
+      def take_back
+        asset = Asset.find(params[:id])
+        asset.return!(actor: hr_current_user, condition: params[:condition_note],
+                      status: params[:status].presence_in(Asset::STATUSES) || "available")
+        redirect_to admin_assets_path, notice: "#{asset.name} taken back."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to admin_assets_path, alert: "#{asset.name} is not with anybody."
+      end
+
+      private
+
+      def require_assets! = hr_require_permission!("asset.manage", scope: :all)
+
+      def asset_params
+        params.require(:asset).permit(:name, :category, :serial_number, :purchased_on, :notes)
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/admin/checklists_controller.rb

@@ -0,0 +1,32 @@
+module HrLite
+  module Admin
+    # Joining and leaving, step by step, with what is overdue at the top.
+    class ChecklistsController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_checklists!
+
+      def index
+        @kind = params[:kind].presence_in(ChecklistTemplate::KINDS) || "onboarding"
+        @items = ChecklistItem.for_kind(@kind).outstanding.includes(:user)
+                              .order(Arel.sql("due_on IS NULL, due_on"))
+        @overdue = @items.select(&:overdue?)
+      end
+
+      def complete
+        item = ChecklistItem.find(params[:id])
+        item.complete!(actor: hr_current_user, note: params[:note])
+        redirect_to admin_checklists_path(kind: item.kind), notice: "#{item.title} — done."
+      end
+
+      def reopen
+        item = ChecklistItem.find(params[:id])
+        item.reopen!(actor: hr_current_user)
+        redirect_to admin_checklists_path(kind: item.kind), notice: "#{item.title} — reopened."
+      end
+
+      private
+
+      def require_checklists! = hr_require_permission!("checklist.manage", scope: :all)
+    end
+  end
+end

data/app/controllers/hr_lite/admin/documents_controller.rb

@@ -0,0 +1,63 @@
+module HrLite
+  module Admin
+    # HR's side: whose documents are missing, and verifying the ones that
+    # arrived. Reaching a person's list is `document.view`; opening the file
+    # still goes through the row's own visibility.
+    class DocumentsController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_document_access!
+
+      def index
+        @category = params[:category].presence
+        scope = hr_scope(Document.includes(:user).recent_first, "document.view")
+        scope = scope.where(category: @category) if @category
+        @pending = scope.where(verification: "pending").limit(50).to_a
+        @documents = paginate(scope)
+        @categories = Document.distinct.order(:category).pluck(:category)
+      end
+
+      def show
+        @employee = HrLite.user_klass.find(params[:user_id])
+        hr_require_reach!("document.view", @employee)
+        @documents = Document.for_user(@employee).recent_first
+        @missing = Document::SENSITIVE_CATEGORIES - @documents.map(&:category)
+      end
+
+      def verify
+        document = find_manageable
+        document.verify!(actor: hr_current_user, note: params[:note])
+        redirect_back fallback_location: admin_documents_path,
+                      notice: "#{document.title} verified."
+      end
+
+      def reject
+        document = find_manageable
+        note = params[:note].to_s.strip
+        if note.blank?
+          return redirect_back fallback_location: admin_documents_path,
+                               alert: "Say what is wrong with it — the employee has to re-upload."
+        end
+
+        document.reject!(actor: hr_current_user, note: note)
+        redirect_back fallback_location: admin_documents_path, notice: "#{document.title} rejected."
+      end
+
+      private
+
+      def require_document_access!
+        hr_require_permission!("document.view", scope: :team)
+      end
+
+      # You may verify a document you can OPEN. Attesting to a scan you are
+      # not allowed to look at is not verification, and the row's visibility
+      # is what keeps an Aadhaar with the money tier rather than with
+      # whoever happens to run HR.
+      def find_manageable
+        document = Document.find(params[:id])
+        raise ActiveRecord::RecordNotFound unless document.readable_by?(hr_current_user)
+
+        document
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/admin/employees_controller.rb

@@ -93,6 +93,10 @@ module HrLite
         exit_date = params[:date_of_exit].present? ? parse_date_param(params[:date_of_exit]) : Date.current
 
         @profile.update!(date_of_exit: exit_date)
+        # The last day has a list too — and it is the one that matters most,
+        # since an unreturned laptop and un-revoked access both outlive the
+        # employment.
+        ChecklistItem.open_for!(@profile.user, kind: "offboarding", anchor_date: exit_date)
         begin
           HrLite.config.offboard_user.call(@profile.user)
         rescue => e

data/app/controllers/hr_lite/admin/expenses_controller.rb

@@ -0,0 +1,45 @@
+module HrLite
+  module Admin
+    # The other side of the claim: decide it, then say when it was paid.
+    class ExpensesController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_deciding!
+
+      def index
+        @status = params[:status].presence_in(Expense::STATUSES) || "submitted"
+        scope = Expense.where(status: @status).includes(:user, :category).recent_first
+        @expenses = paginate(hr_scope(scope, "expense.approve"))
+      end
+
+      def approve
+        expense = decidable.find(params[:id])
+        expense.approve!(actor: hr_current_user, note: params[:decision_note].presence)
+        redirect_to admin_expenses_path, notice: "Claim approved."
+      end
+
+      def reject
+        expense = decidable.find(params[:id])
+        note = params[:decision_note].to_s.strip
+        return redirect_to admin_expenses_path, alert: "A note is required to reject." if note.blank?
+
+        expense.reject!(actor: hr_current_user, note: note)
+        redirect_to admin_expenses_path, notice: "Claim rejected."
+      end
+
+      def reimburse
+        expense = decidable.find(params[:id])
+        month = parse_month_param(params[:period_month])
+        expense.reimburse!(actor: hr_current_user, period_month: month)
+        redirect_to admin_expenses_path, notice: "Marked reimbursed with #{month.strftime('%B %Y')}."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to admin_expenses_path, alert: "Only an approved claim can be reimbursed."
+      end
+
+      private
+
+      def require_deciding! = hr_require_permission!("expense.approve", scope: :team)
+
+      def decidable = hr_scope(Expense.all, "expense.approve")
+    end
+  end
+end

data/app/controllers/hr_lite/admin/hr_requests_controller.rb

@@ -0,0 +1,38 @@
+module HrLite
+  module Admin
+    # The desk itself.
+    class HrRequestsController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_desk!
+
+      def index
+        @status = params[:status].presence_in(HrRequest::STATUSES) || "open"
+        @requests = paginate(HrRequest.where(status: @status).includes(:user, :assigned_to)
+                                      .recent_first)
+      end
+
+      def show
+        @request = HrRequest.find(params[:id])
+      end
+
+      def assign
+        request = HrRequest.find(params[:id])
+        assignee = HrLite.user_klass.find(params[:assignee_id])
+        request.assign!(actor: hr_current_user, assignee: assignee)
+        redirect_to admin_hr_request_path(request), notice: "Assigned to #{HrLite.display_name(assignee)}."
+      end
+
+      def resolve
+        request = HrRequest.find(params[:id])
+        request.resolve!(actor: hr_current_user, resolution: params[:resolution].to_s.strip)
+        redirect_to admin_hr_requests_path, notice: "Answered."
+      rescue ArgumentError
+        redirect_to admin_hr_request_path(request), alert: "Write an answer before resolving."
+      end
+
+      private
+
+      def require_desk! = hr_require_permission!("hr_request.manage", scope: :all)
+    end
+  end
+end

data/app/controllers/hr_lite/admin/loans_controller.rb

@@ -0,0 +1,59 @@
+module HrLite
+  module Admin
+    # Loans and salary advances. Money tier: the instalment lands as a
+    # deduction on a payslip, so whoever sets it is setting somebody's pay.
+    class LoansController < SuperadminController
+      def index
+        @status = params[:status].presence_in(Loan::STATUSES) || "active"
+        @loans = paginate(Loan.includes(:user).where(status: @status).order(starts_on: :desc))
+        @outstanding = Loan.active.includes(:loan_repayments).sum(BigDecimal(0), &:outstanding)
+      end
+
+      def new
+        @loan = Loan.new(starts_on: Date.current.next_month.beginning_of_month)
+      end
+
+      def create
+        @loan = Loan.new(loan_params.merge(approved_by_id: hr_current_user.id))
+        if @loan.save
+          redirect_to admin_loans_path,
+                      notice: "Loan recorded for #{HrLite.display_name(@loan.user)} — " \
+                              "deductions start #{@loan.starts_on.strftime('%b %Y')}."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def show
+        @loan = Loan.includes(:loan_repayments).find(params[:id])
+      end
+
+      # Closing stops the deduction. It does NOT delete the repayments —
+      # those are on published payslips and are what the outstanding balance
+      # is derived from.
+      def close
+        loan = Loan.find(params[:id])
+        loan.update!(status: "closed")
+        redirect_to admin_loans_path, notice: "Closed — no further deductions."
+      end
+
+      def cancel
+        loan = Loan.find(params[:id])
+        if loan.loan_repayments.exists?
+          return redirect_to admin_loan_path(loan),
+                             alert: "Instalments have already been deducted. Close it instead — " \
+                                    "cancelling would deny money that has left somebody's salary."
+        end
+
+        loan.update!(status: "cancelled")
+        redirect_to admin_loans_path, notice: "Cancelled before any deduction."
+      end
+
+      private
+
+      def loan_params
+        params.require(:loan).permit(:user_id, :principal, :monthly_instalment, :starts_on, :reason)
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/admin/tax_declarations_controller.rb

@@ -0,0 +1,75 @@
+module HrLite
+  module Admin
+    # HR checking the proof behind a declaration, line by line. The verified
+    # amount is what payroll deducts against once this is done, so it is
+    # entered per section rather than accepted wholesale.
+    class TaxDeclarationsController < BaseController
+      skip_before_action :require_operations_access!
+      before_action :require_tax_access!
+
+      def index
+        @status = params[:status].presence_in(TaxDeclaration::STATUSES) || "submitted"
+        @declarations = paginate(
+          hr_scope(TaxDeclaration.includes(:user, :tax_declaration_items), "tax.view")
+            .where(status: @status).order(created_at: :desc)
+        )
+      end
+
+      def show
+        @declaration = find_visible
+      end
+
+      def update
+        @declaration = find_manageable
+        # Recording what the proof supported is a separate act from deciding
+        # — an amount can be corrected while the decision is still pending.
+        if @declaration.update(verification_params)
+          redirect_to admin_tax_declaration_path(@declaration), notice: "Amounts recorded."
+        else
+          render :show, status: :unprocessable_entity
+        end
+      end
+
+      def verify
+        declaration = find_manageable
+        declaration.verify!(actor: hr_current_user, note: params[:note])
+        redirect_to admin_tax_declarations_path, notice: "Verified — payroll will use the checked amounts."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to admin_tax_declaration_path(declaration), alert: "Only a submitted declaration can be verified."
+      end
+
+      def reject
+        declaration = find_manageable
+        declaration.reject!(actor: hr_current_user, note: params[:note].to_s.strip)
+        redirect_to admin_tax_declarations_path, notice: "Sent back to the employee."
+      rescue ArgumentError
+        redirect_to admin_tax_declaration_path(declaration),
+                    alert: "Say what is missing — they have to know what to fix."
+      end
+
+      private
+
+      def require_tax_access!
+        hr_require_permission!("tax.view", scope: :all)
+      end
+
+      def find_visible
+        declaration = TaxDeclaration.includes(:tax_declaration_items).find(params[:id])
+        hr_require_reach!("tax.view", declaration.user)
+        declaration
+      end
+
+      def find_manageable
+        declaration = TaxDeclaration.find(params[:id])
+        hr_require_reach!("tax.manage", declaration.user)
+        declaration
+      end
+
+      def verification_params
+        params.require(:tax_declaration).permit(
+          tax_declaration_items_attributes: %i[id verified_amount]
+        )
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/documents_controller.rb

@@ -0,0 +1,69 @@
+module HrLite
+  # An employee's own documents, and the download itself.
+  #
+  # The FILE is the sensitive part, so every read goes through
+  # `Document#readable_by?` rather than through the scope that found the row.
+  # A passport is not a payslip: HR can see that one exists without being
+  # handed the scan.
+  class DocumentsController < ApplicationController
+    def index
+      @documents = Document.for_user(hr_current_user).recent_first
+      @document = Document.new
+      @expiring = @documents.select { |d| d.expires_on && d.expires_on <= 60.days.from_now.to_date }
+    end
+
+    def create
+      @document = Document.new(document_params)
+      @document.user_id = hr_current_user.id
+      @document.uploaded_by_id = hr_current_user.id
+
+      if @document.save
+        redirect_to documents_path, notice: "#{@document.title} uploaded."
+      else
+        @documents = Document.for_user(hr_current_user).recent_first
+        @expiring = []
+        render :index, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      document = Document.for_user(hr_current_user).find(params[:id])
+      # A verified identity document is evidence HR acted on; removing it
+      # quietly would leave their verification pointing at nothing.
+      if document.verified?
+        return redirect_to documents_path, status: :see_other,
+                           alert: "#{document.title} has been verified — ask HR to replace it."
+      end
+
+      document.destroy!
+      redirect_to documents_path, notice: "#{document.title} removed.", status: :see_other
+    end
+
+    # The one place a file leaves the building. Scoped by nothing — the
+    # permission check is the row's own, because a document may be readable
+    # by its owner, by HR, or by nobody but the money tier.
+    def download
+      document = Document.find(params[:id])
+      unless document.readable_by?(hr_current_user)
+        raise ActiveRecord::RecordNotFound
+      end
+
+      AuditLog.record!(
+        action: "document.downloaded", subject: document, actor: hr_current_user,
+        changes: { "title" => document.title, "category" => document.category,
+                   "owner" => HrLite.display_name(document.user) }
+      )
+      # rails_blob_path, not url_for: an engine controller has no default
+      # host and url_for(attachment) raises without one.
+      redirect_to Rails.application.routes.url_helpers.rails_blob_path(
+        document.file, disposition: "attachment", only_path: true
+      ), allow_other_host: false
+    end
+
+    private
+
+    def document_params
+      params.require(:document).permit(:category, :title, :reference_number, :issued_on, :expires_on, :file)
+    end
+  end
+end

data/app/controllers/hr_lite/loans_controller.rb

@@ -0,0 +1,11 @@
+module HrLite
+  # What an employee owes and what is coming out of the next payslip. Read
+  # only: a loan is agreed with the company, not self-served.
+  class LoansController < ApplicationController
+    def index
+      @loans = Loan.where(user_id: hr_current_user.id).order(starts_on: :desc)
+      @outstanding = @loans.sum(BigDecimal(0), &:outstanding)
+      @next_month = Date.current.next_month.beginning_of_month
+    end
+  end
+end

data/app/controllers/hr_lite/tax_declarations_controller.rb

@@ -0,0 +1,100 @@
+module HrLite
+  # The employee's own declaration for a financial year. Replaces an admin
+  # typing one lump sum into the profile: the whole year's TDS is projected
+  # from this, so the person whose money it is fills it in.
+  class TaxDeclarationsController < ApplicationController
+    def show
+      @declaration = current_declaration || build_declaration
+      @regime = @declaration.regime
+    end
+
+    def update
+      # A bare record, not the form's scaffold: `build_declaration` fills in
+      # one blank line per section so the form is a list rather than an empty
+      # box, and saving those blanks fails a NOT NULL amount.
+      @declaration = current_declaration ||
+                     TaxDeclaration.new(user_id: hr_current_user.id,
+                                        financial_year: financial_year, regime: employee_regime)
+      # A verified declaration is what payroll is deducting against; changing
+      # it would silently re-open a decision HR has already made.
+      if @declaration.verified?
+        return redirect_to tax_declaration_path,
+                           alert: "This year's declaration is verified. Ask HR to reopen it."
+      end
+
+      if @declaration.update(declaration_params)
+        redirect_to tax_declaration_path, notice: "Saved."
+      else
+        # Re-render needs the full set of lines back, or the form loses the
+        # sections the person had not filled in yet.
+        fill_missing_sections(@declaration)
+        render :show, status: :unprocessable_entity
+      end
+    end
+
+    def submit
+      @declaration = current_declaration
+      return redirect_to tax_declaration_path, alert: "Nothing to submit yet." if @declaration.nil?
+
+      @declaration.submit!(actor: hr_current_user)
+      redirect_to tax_declaration_path, notice: "Submitted — HR will check the proof."
+    rescue ActiveRecord::RecordInvalid
+      redirect_to tax_declaration_path, alert: "Only a draft can be submitted."
+    end
+
+    private
+
+    def financial_year
+      FinancialYear.start_for(params[:financial_year].present? ? Date.parse(params[:financial_year]) : Date.current)
+    rescue Date::Error
+      FinancialYear.start_for(Date.current)
+    end
+
+    def current_declaration
+      TaxDeclaration.find_by(user_id: hr_current_user.id, financial_year: financial_year)
+    end
+
+    def build_declaration
+      declaration = TaxDeclaration.new(user_id: hr_current_user.id, financial_year: financial_year,
+                                       regime: employee_regime)
+      # One blank line per section, so the form is a list of the things a
+      # person can actually claim rather than an empty box and a plus button.
+      fill_missing_sections(declaration)
+      declaration
+    end
+
+    # Every section gets a line, whether or not it has been claimed yet.
+    def fill_missing_sections(declaration)
+      present = declaration.tax_declaration_items.map(&:section)
+      (TaxDeclarationItem::SECTIONS - present).each do |section|
+        declaration.tax_declaration_items.build(section: section)
+      end
+    end
+
+    def employee_regime
+      EmployeeProfile.find_by(user_id: hr_current_user.id)&.tax_regime.presence || "new"
+    end
+
+    # The form posts a line for every section, because that is what a list of
+    # claimable things looks like. Most of them are blank — a section with no
+    # amount is not a claim, and saving it violates a NOT NULL amount.
+    # An EXISTING line blanked out is a claim being withdrawn, so it is
+    # destroyed rather than skipped.
+    def declaration_params
+      permitted = params.require(:tax_declaration).permit(
+        :regime,
+        tax_declaration_items_attributes: %i[id section label declared_amount _destroy]
+      )
+      items = permitted[:tax_declaration_items_attributes]
+      return permitted if items.blank?
+
+      permitted[:tax_declaration_items_attributes] = items.to_h.filter_map { |key, row|
+        next [ key, row.merge("_destroy" => "1") ] if row["declared_amount"].blank? && row["id"].present?
+        next if row["declared_amount"].blank?
+
+        [ key, row ]
+      }.to_h
+      permitted
+    end
+  end
+end