New plugin: monthly sales commission (SOP-OPS-013)

Reads the month's paid sales from QuickBooks Online (invoices paid in
full that month, sales receipts), deducts refund receipts, credit memos
and adjustments, works out the commission pool with the threshold and
marginal brackets, and records each sales rep's payout once the month
is approved for payroll.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-16 18:53:25 -05:00
commit 6fcd5f9b64
44 files changed
+2661

No files matched your search

+15
View File
@@ -0,0 +1,15 @@
<%= error_messages_for @rep %>
<% taken = CommissionRep.where.not(id: @rep.id).pluck(:user_id) %>
<% users = User.active.sorted.where.not(id: taken).to_a %>
<% users << @rep.user if @rep.user && !users.include?(@rep.user) %>
<div class="box tabular">
<p>
<%= f.select :user_id, users.map { |user| [user.name, user.id] }, { include_blank: true, required: true, label: :field_user },
{ disabled: @rep.persisted? } %>
</p>
<p>
<%= f.date_field :probation_until, label: :field_commission_rep_probation_until %>
<em class="info"><%= l(:text_commission_rep_probation) %></em>
</p>
<p><%= f.check_box :active %></p>
</div>
+8
View File
@@ -0,0 +1,8 @@
<h2><%= link_to l(:label_commission_rep_plural), commission_reps_path %> » <%= @rep.name %></h2>
<%= labelled_form_for @rep, url: commission_rep_path(@rep), method: :patch do |f| %>
<%= render partial: 'commission_reps/form', locals: { f: f } %>
<%= submit_tag l(:button_save) %>
<% end %>
<% html_title @rep.name %>
+41
View File
@@ -0,0 +1,41 @@
<div class="contextual">
<%= link_to sprite_icon('add', l(:label_commission_rep_new)), new_commission_rep_path, class: 'icon icon-add' %>
<%= link_to sprite_icon('settings', l(:label_settings)), plugin_settings_path('redmine_qbo_commission'), class: 'icon icon-settings' %>
</div>
<h2><%= l(:label_commission_rep_plural) %></h2>
<p><em class="info"><%= l(:text_commission_reps) %></em></p>
<% if @reps.empty? %>
<p class="nodata"><%= l(:label_no_data) %></p>
<% else %>
<div class="autoscroll">
<table class="list">
<thead>
<tr>
<th><%= l(:label_user) %></th>
<th><%= l(:field_commission_rep_probation_until) %></th>
<th><%= l(:field_active) %></th>
<th></th>
</tr>
</thead>
<tbody>
<% @reps.each do |rep| %>
<tr>
<td class="name"><%= link_to_user rep.user %></td>
<td><%= format_date(rep.probation_until) %></td>
<td><%= checked_image rep.active? %></td>
<td class="buttons">
<%= link_to sprite_icon('edit', l(:button_edit)), edit_commission_rep_path(rep), class: 'icon icon-edit' %>
<%= link_to sprite_icon('del', l(:button_delete)), commission_rep_path(rep), method: :delete,
data: { confirm: l(:text_are_you_sure) }, class: 'icon icon-del' %>
</td>
</tr>
<% end %>
</tbody>
</table>
</div>
<% end %>
<% html_title l(:label_commission_rep_plural) %>
+8
View File
@@ -0,0 +1,8 @@
<h2><%= link_to l(:label_commission_rep_plural), commission_reps_path %> » <%= l(:label_commission_rep_new) %></h2>
<%= labelled_form_for @rep, url: commission_reps_path do |f| %>
<%= render partial: 'commission_reps/form', locals: { f: f } %>
<%= submit_tag l(:button_create) %>
<% end %>
<% html_title l(:label_commission_rep_new) %>
@@ -0,0 +1,3 @@
<% content_for :header_tags do %>
<%= stylesheet_link_tag 'qbo_commission', plugin: 'redmine_qbo_commission' %>
<% end %>
@@ -0,0 +1,57 @@
<%= render partial: 'sales_commissions/styles' %>
<div class="contextual">
<% if User.current.admin? %>
<%= link_to sprite_icon('user', l(:label_commission_rep_plural)), commission_reps_path, class: 'icon icon-user' %>
<%= link_to sprite_icon('settings', l(:label_settings)), plugin_settings_path('redmine_qbo_commission'), class: 'icon icon-settings' %>
<% end %>
</div>
<h2><%= l(:label_sales_commission) %></h2>
<%= form_tag(sales_commissions_path, method: :get, id: 'sales-commission-month-picker', class: 'sales-commission-picker') do %>
<label for="sales_commission_month"><%= l(:label_sales_commission_month) %></label>
<%= select_tag 'month', options_for_select(@months.map { |month| [month.name, month.to_param] }, (@months.second || @months.first).to_param),
id: 'sales_commission_month' %>
<%= submit_tag l(:button_sales_commission_show), name: nil %>
<% end %>
<h3><%= l(:label_sales_commission_history) %></h3>
<% if @commission_months.empty? %>
<p class="nodata"><%= l(:label_no_data) %></p>
<% else %>
<div class="autoscroll">
<table class="list sales-commission-table">
<thead>
<tr>
<th><%= l(:label_sales_commission_month) %></th>
<th><%= l(:field_status) %></th>
<th><%= l(:label_sales_commission_net_sales) %></th>
<th><%= l(:label_sales_commission_pool) %></th>
<th><%= l(:label_sales_commission_payouts_total) %></th>
<th><%= l(:label_sales_commission_approved_by) %></th>
</tr>
</thead>
<tbody>
<% @commission_months.each do |record| %>
<tr>
<td class="name"><%= link_to record.month.name, sales_commission_month_path(record.month.to_param) %></td>
<td class="text">
<% if record.approved? %>
<span class="sales-commission-ok"><%= l(:label_sales_commission_status_approved) %></span>
<% else %>
<span class="sales-commission-miss"><%= l(:label_sales_commission_status_open) %></span>
<% end %>
</td>
<td><%= record.approved? ? commission_money(record.net_sales) : '' %></td>
<td><%= record.approved? ? commission_money(record.pool) : '' %></td>
<td><%= record.approved? ? commission_money(record.payouts_total) : '' %></td>
<td class="text"><%= record.approved_by ? link_to_user(record.approved_by) : '' %> <%= format_time(record.approved_at) if record.approved_at %></td>
</tr>
<% end %>
</tbody>
</table>
</div>
<% end %>
<% html_title l(:label_sales_commission) %>
+296
View File
@@ -0,0 +1,296 @@
<%= render partial: 'sales_commissions/styles' %>
<% report = @report %>
<% pool = report.pool %>
<% approved = @record&.approved? %>
<% editable = @can_approve && !approved %>
<% previous_month = @month - 1 %>
<% next_month = @month + 1 %>
<div class="contextual">
<%= link_to "« #{previous_month.label}", sales_commission_month_path(previous_month.to_param) %>
<% if next_month.start_date <= Date.current %>
| <%= link_to "#{next_month.label} »", sales_commission_month_path(next_month.to_param) %>
<% end %>
<% if approved && @can_approve %>
| <%= link_to sprite_icon('download', l(:label_sales_commission_payroll_csv)),
sales_commission_month_path(@month.to_param, format: 'csv'), class: 'icon icon-download' %>
<% end %>
<% if editable %>
| <%= link_to sprite_icon('reload', l(:button_sales_commission_refresh)), refresh_sales_commission_month_path(@month.to_param),
method: :post, class: 'icon icon-reload' %>
<% end %>
</div>
<h2><%= @can_approve ? link_to(l(:label_sales_commission), sales_commissions_path) : l(:label_sales_commission) %> » <%= @month.name %></h2>
<% if @error %>
<p class="conflict"><%= @error %></p>
<% end %>
<% if approved %>
<p class="sales-commission-approved">
<%= sprite_icon('checked', commission_approved_text(@record)) %>
<% if @can_approve %>
<%= link_to l(:button_sales_commission_reopen), reopen_sales_commission_month_path(@month.to_param), method: :post,
data: { confirm: l(:text_sales_commission_reopen_confirm) } %>
<% end %>
</p>
<% elsif !@month.completed? %>
<p class="warning"><%= l(:text_sales_commission_month_in_progress, date: format_date(@month.end_date)) %></p>
<% end %>
<% if !approved && @read_at %>
<p><em class="info"><%= l(:text_sales_commission_read_at, time: format_time(@read_at)) %></em></p>
<% end %>
<div class="sales-commission-summary">
<div class="box">
<%= l(:label_sales_commission_gross_sales) %>
<span class="value"><%= commission_money(report.gross_sales) %></span>
</div>
<div class="box">
<%= l(:label_sales_commission_deductions) %>
<span class="value"><%= commission_money(report.deductions_total) %></span>
</div>
<div class="box">
<%= l(:label_sales_commission_net_sales) %>
<span class="value <%= pool.threshold_met? ? 'sales-commission-ok' : 'sales-commission-miss' %>"><%= commission_money(report.net_sales) %></span>
<% percent = pool.threshold.positive? ? [[report.net_sales / pool.threshold * 100, 0].max, 100].min : 100 %>
<div class="sales-commission-progress" title="<%= l(:label_sales_commission_threshold) %> <%= commission_money(pool.threshold) %>"><span style="width: <%= percent.to_f.round(1) %>%"></span></div>
</div>
<div class="box">
<% if pool.threshold_met? %>
<%= l(:label_sales_commission_threshold) %>
<span class="value sales-commission-ok"><%= commission_money(pool.threshold) %></span>
<%= l(:text_sales_commission_threshold_met) %>
<% else %>
<%= l(:label_sales_commission_short_of_threshold) %>
<span class="value sales-commission-miss"><%= commission_money(pool.short_of_threshold) %></span>
<%= l(:text_sales_commission_threshold_of, amount: commission_money(pool.threshold)) %>
<% end %>
</div>
<div class="box">
<%= l(:label_sales_commission_pool) %>
<span class="value"><%= commission_money(pool.amount) %></span>
<%= l(:text_sales_commission_each_rep) %>
</div>
</div>
<% if pool.parts.any? %>
<div class="autoscroll">
<table class="list sales-commission-table">
<thead>
<tr>
<th><%= l(:label_sales_commission_bracket) %></th>
<th><%= l(:label_sales_commission_rate) %></th>
<th><%= l(:label_sales_commission_bracket_sales) %></th>
<th><%= l(:label_sales_commission_amount) %></th>
</tr>
</thead>
<tbody>
<% pool.parts.each do |part| %>
<tr>
<td class="name"><%= commission_money(part.from) %> – <%= commission_money(part.to) %></td>
<td><%= commission_rate(part.rate) %></td>
<td><%= commission_money(part.sales) %></td>
<td><%= commission_money(part.amount) %></td>
</tr>
<% end %>
</tbody>
<tfoot>
<tr><td class="name" colspan="3"><%= l(:label_sales_commission_pool) %></td><td><%= commission_money(pool.amount) %></td></tr>
</tfoot>
</table>
</div>
<% end %>
<%= form_tag(sales_commission_month_path(@month.to_param), method: :post, id: 'sales-commission-month') do %>
<%= hidden_field_tag 'shown', '1', id: nil if editable %>
<h3><%= l(:label_sales_commission_payouts) %></h3>
<% if report.payouts.empty? %>
<p class="nodata"><%= l(:text_sales_commission_no_reps) %>
<% if User.current.admin? %><%= link_to l(:label_commission_rep_new), new_commission_rep_path %><% end %></p>
<% else %>
<div class="autoscroll">
<table class="list sales-commission-table" id="sales-commission-payouts">
<thead>
<tr>
<th><%= l(:label_user) %></th>
<% if editable %><th title="<%= l(:text_sales_commission_eligible) %>"><%= l(:label_sales_commission_paid) %></th><% end %>
<th><%= l(:label_sales_commission_amount) %></th>
<th><%= l(:label_sales_commission_reason) %></th>
</tr>
</thead>
<tbody>
<% report.payouts.each do |payout| %>
<% unticked = editable && @record&.unpaid_user_ids&.include?(payout.user&.id) %>
<tr class="<%= 'ineligible' unless payout.eligible? %>">
<td class="name"><%= payout.user ? link_to_user(payout.user) : '' %></td>
<% if editable %>
<td class="check">
<% blocked = !payout.eligible? && !unticked %>
<% unless blocked %>
<%= hidden_field_tag 'shown_reps[]', payout.user.id, id: nil %>
<%= check_box_tag 'eligible[]', payout.user.id, !unticked, id: "eligible_#{payout.user.id}" %>
<% end %>
</td>
<% end %>
<td><%= commission_money(payout.amount) %></td>
<td class="text"><%= payout.ineligible_reason %></td>
</tr>
<% end %>
</tbody>
<tfoot>
<tr>
<td class="name"><%= l(:label_total) %></td>
<% if editable %><td></td><% end %>
<td><%= commission_money(report.payouts_total) %></td>
<td></td>
</tr>
</tfoot>
</table>
</div>
<% end %>
<h3><%= l(:label_sales_commission_deductions) %></h3>
<% if report.deductions.empty? && report.adjustments.empty? %>
<p class="nodata"><%= l(:label_no_data) %></p>
<% else %>
<div class="autoscroll">
<table class="list sales-commission-table" id="sales-commission-deductions">
<thead>
<tr>
<th><%= l(:label_sales_commission_deducted) %></th>
<th><%= l(:label_date) %></th>
<th><%= l(:field_type) %></th>
<th><%= l(:label_sales_commission_number) %></th>
<th><%= l(:label_sales_commission_customer) %></th>
<th><%= l(:label_sales_commission_total) %></th>
<th><%= l(:label_sales_commission_tax) %></th>
<th><%= l(:label_sales_commission_amount) %></th>
</tr>
</thead>
<tbody>
<% report.deductions.each do |txn| %>
<% included = report.included?(txn) %>
<tr class="<%= 'excluded' unless included %>">
<td class="check">
<% if editable %>
<%= hidden_field_tag 'shown_deductions[]', txn.key, id: nil %>
<%= check_box_tag 'included[]', txn.key, included, id: "included_#{txn.key.tr(':', '_')}" %>
<% else %>
<%= checked_image included %>
<% end %>
</td>
<td class="text"><%= format_date(txn.txn_date) %></td>
<td class="text"><%= txn.kind_name %></td>
<td class="text"><%= commission_txn_link(txn, @can_approve) %></td>
<td class="text"><%= txn.customer_name %></td>
<td><%= commission_money(txn.total) %></td>
<td><%= commission_money(txn.tax) %></td>
<td><%= commission_money(txn.net) %></td>
</tr>
<% end %>
<% report.adjustments.each do |adjustment| %>
<tr class="adjustment">
<td class="check">
<% if editable %>
<%= link_to sprite_icon('del', l(:button_delete)), sales_commission_adjustment_path(@month.to_param, adjustment),
method: :delete, data: { confirm: l(:text_are_you_sure) }, class: 'icon-only icon-del' %>
<% else %>
<%= checked_image true %>
<% end %>
</td>
<td class="text"><%= format_date(adjustment.created_at) %></td>
<td class="text"><%= l(:label_sales_commission_adjustment) %></td>
<td class="text"></td>
<td class="text"><%= adjustment.description %><% if adjustment.author %> <small>(<%= adjustment.author.name %>)</small><% end %></td>
<td></td>
<td></td>
<td><%= commission_money(adjustment.amount) %></td>
</tr>
<% end %>
</tbody>
<tfoot>
<tr><td class="name" colspan="7"><%= l(:label_sales_commission_deductions) %></td><td><%= commission_money(report.deductions_total) %></td></tr>
</tfoot>
</table>
</div>
<% end %>
<% if editable %>
<p>
<label for="sales_commission_notes"><%= l(:field_notes) %></label><br>
<%= text_area_tag 'notes', @record&.notes, id: 'sales_commission_notes', rows: 3, cols: 80 %>
</p>
<p>
<%= submit_tag l(:button_save), name: 'save' %>
<% if @month.completed? %>
<%= submit_tag l(:button_sales_commission_approve), name: 'approve',
data: { confirm: l(:text_sales_commission_approve_confirm) } %>
<% end %>
</p>
<% elsif @record&.notes.present? %>
<h3><%= l(:field_notes) %></h3>
<div class="wiki"><%= simple_format(h(@record.notes)) %></div>
<% end %>
<% end %>
<% if editable %>
<%= form_tag(sales_commission_adjustments_path(@month.to_param), method: :post, class: 'sales-commission-adjustment',
id: 'sales-commission-adjustment') do %>
<fieldset class="box">
<legend><%= l(:label_sales_commission_add_adjustment) %></legend>
<%= text_field_tag 'description', '', placeholder: l(:field_description), required: true, maxlength: 255 %>
<%= text_field_tag 'amount', '', placeholder: l(:label_sales_commission_amount), class: 'amount', required: true,
inputmode: 'decimal' %>
<%= submit_tag l(:button_add) %>
<br><em class="info"><%= l(:text_sales_commission_adjustment) %></em>
</fieldset>
<% end %>
<% end %>
<h3><%= l(:label_sales_commission_sales) %> (<%= report.sales.size %>)</h3>
<% if report.sales.empty? %>
<p class="nodata"><%= l(:label_no_data) %></p>
<% else %>
<div class="autoscroll">
<table class="list sales-commission-table" id="sales-commission-sales">
<thead>
<tr>
<th><%= l(:label_sales_commission_paid_on) %></th>
<th><%= l(:field_type) %></th>
<th><%= l(:label_sales_commission_number) %></th>
<th><%= l(:label_sales_commission_customer) %></th>
<th><%= l(:label_sales_commission_total) %></th>
<th><%= l(:label_sales_commission_tax) %></th>
<th><%= l(:label_sales_commission_amount) %></th>
</tr>
</thead>
<tbody>
<% report.sales.each do |txn| %>
<tr>
<td class="text"><%= format_date(txn.txn_date) %></td>
<td class="text"><%= txn.kind_name %></td>
<td class="text"><%= commission_txn_link(txn, @can_approve) %></td>
<td class="text"><%= txn.customer_name %></td>
<td><%= commission_money(txn.total) %></td>
<td><%= commission_money(txn.tax) %></td>
<td><%= commission_money(txn.net) %></td>
</tr>
<% end %>
</tbody>
<tfoot>
<tr>
<td class="name" colspan="4"><%= l(:label_total) %></td>
<td><%= commission_money(report.sales.sum(BigDecimal('0'), &:total)) %></td>
<td><%= commission_money(report.sales.sum(BigDecimal('0')) { |txn| txn.tax.to_d }) %></td>
<td><%= commission_money(report.gross_sales) %></td>
</tr>
</tfoot>
</table>
</div>
<p><em class="info"><%= l(:text_sales_commission_sales) %></em></p>
<% end %>
<% html_title "#{l(:label_sales_commission)} #{@month.label}" %>
@@ -0,0 +1,65 @@
<%# Settings for redmine_qbo_commission (Administration » Plugins » Configure) %>
<% s = RedmineQboCommission::Settings %>
<% field = ->(key) { "settings[#{key}]" } %>
<% plain = ->(number) { number.to_d == number.to_d.to_i ? number.to_d.to_i.to_s : number.to_d.to_s('F') } %>
<% brackets = s.brackets %>
<p>
<%= link_to sprite_icon('user', l(:label_commission_rep_plural)), commission_reps_path, class: 'icon icon-user' %>
<%= link_to sprite_icon('stats', l(:label_sales_commission)), sales_commissions_path, class: 'icon icon-stats' %>
</p>
<fieldset class="box tabular">
<legend><%= l(:label_sales_commission_rates) %></legend>
<p>
<label for="qbo_commission_threshold"><%= l(:label_sales_commission_threshold) %></label>
$<%= number_field_tag field.call('threshold'), plain.call(s.threshold), id: 'qbo_commission_threshold', min: 0, step: 0.01, style: 'width: 9em' %>
<em class="info"><%= l(:text_sales_commission_setting_threshold) %></em>
</p>
<p>
<label for="qbo_commission_base_rate"><%= l(:label_sales_commission_base_rate) %></label>
<%= number_field_tag field.call('base_rate'), plain.call(brackets[0][1]), id: 'qbo_commission_base_rate', min: 0, step: 0.01, style: 'width: 5em' %>%
<%= l(:label_sales_commission_up_to) %>
$<%= number_field_tag field.call('base_limit'), plain.call(brackets[0][0]), id: 'qbo_commission_base_limit', min: 0, step: 0.01, style: 'width: 9em' %>
</p>
<p>
<label for="qbo_commission_step_rate"><%= l(:label_sales_commission_step_rate) %></label>
<%= number_field_tag field.call('step_rate'), plain.call(brackets[1][1]), id: 'qbo_commission_step_rate', min: 0, step: 0.01, style: 'width: 5em' %>%
<%= l(:label_sales_commission_up_to) %>
$<%= number_field_tag field.call('step_limit'), plain.call(brackets[1][0]), id: 'qbo_commission_step_limit', min: 0, step: 0.01, style: 'width: 9em' %>
</p>
<p>
<label for="qbo_commission_top_rate"><%= l(:label_sales_commission_top_rate) %></label>
<%= number_field_tag field.call('top_rate'), plain.call(brackets[2][1]), id: 'qbo_commission_top_rate', min: 0, step: 0.01, style: 'width: 5em' %>%
<%= l(:label_sales_commission_above) %>
</p>
<p><em class="info"><%= l(:text_sales_commission_setting_brackets) %></em></p>
</fieldset>
<fieldset class="box tabular">
<legend><%= l(:label_sales_commission_counted) %></legend>
<p>
<label for="qbo_commission_sales_receipts"><%= l(:label_sales_commission_include_sales_receipts) %></label>
<%= hidden_field_tag field.call('include_sales_receipts'), '0', id: nil %>
<%= check_box_tag field.call('include_sales_receipts'), '1', s.include_sales_receipts?, id: 'qbo_commission_sales_receipts' %>
<em class="info"><%= l(:text_sales_commission_setting_sales_receipts) %></em>
</p>
<p>
<label for="qbo_commission_refund_receipts"><%= l(:label_sales_commission_deduct_refund_receipts) %></label>
<%= hidden_field_tag field.call('deduct_refund_receipts'), '0', id: nil %>
<%= check_box_tag field.call('deduct_refund_receipts'), '1', s.deduct_refund_receipts?, id: 'qbo_commission_refund_receipts' %>
</p>
<p>
<label for="qbo_commission_credit_memos"><%= l(:label_sales_commission_deduct_credit_memos) %></label>
<%= hidden_field_tag field.call('deduct_credit_memos'), '0', id: nil %>
<%= check_box_tag field.call('deduct_credit_memos'), '1', s.deduct_credit_memos?, id: 'qbo_commission_credit_memos' %>
</p>
<p>
<label for="qbo_commission_items"><%= l(:label_sales_commission_excluded_items) %></label>
<%= hidden_field_tag "#{field.call('excluded_item_ids')}[]", '', id: nil %>
<%= select_tag "#{field.call('excluded_item_ids')}[]",
options_from_collection_for_select(Item.order(:name), :id, :name, Array(s.values['excluded_item_ids']).map(&:to_s)),
multiple: true, size: 8, id: 'qbo_commission_items' %>
<em class="info"><%= l(:text_sales_commission_setting_excluded_items) %></em>
</p>
</fieldset>