mirror of
https://github.com/rickbarrette/redmine_qbo.git
synced 2026-11-17 18:20:36 -05:00
Cache totals, man-hours and payments; add a business report
- Estimates now keep their total; estimates and invoices keep their man-hours: the quantities of the products/services set as "Replaced by imported time" (bundles included; the estimate item codes while that setting is blank). Filled in by the webhook and the sync. - Payment model (QboBaseModel) caching each payment's customer, date, amount and unapplied amount, kept current by the webhook, the sync and the Receive payment page. - Business report (View business reports permission, top menu): estimates written vs. invoices written vs. payments received, and estimated hours on estimates and issues vs. invoiced and spent hours, for a period, with a month-by-month breakdown. - Fix two keyword arguments that defaulted to themselves (QboSyncDispatcher.enque_jobs, PdfService), which newer Ruby refuses to parse. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BiwYMjhoQvL7XsKKfRz4pM
This commit is contained in:
20 files changed
+590
-5
No files matched your search
@@ -0,0 +1,22 @@
|
||||
#The MIT License (MIT)
|
||||
#
|
||||
#Copyright (c) 2026 rick barrette
|
||||
#
|
||||
#Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
#The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
#
|
||||
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
# Business report: estimates and invoices written and payments received, and estimated, invoiced and spent
|
||||
# hours, for a period (RedmineQboBilling::BusinessReport)
|
||||
class QboReportsController < ApplicationController
|
||||
|
||||
before_action :authorize_global
|
||||
|
||||
def index
|
||||
@report = RedmineQboBilling::BusinessReport.new(period: params[:period].presence || 'this_year',
|
||||
from: params[:from], to: params[:to], today: User.current.today)
|
||||
end
|
||||
end
|
||||
@@ -14,7 +14,8 @@ class QboSyncDispatcher
|
||||
Customer,
|
||||
Estimate,
|
||||
Invoice,
|
||||
Employee
|
||||
Employee,
|
||||
Payment
|
||||
].freeze
|
||||
|
||||
# Dispatches all synchronization jobs to perform a full sync of QuickBooks entities with the local database.
|
||||
@@ -27,7 +28,7 @@ class QboSyncDispatcher
|
||||
private
|
||||
|
||||
# Dynamically enques all sync jobs
|
||||
def self.enque_jobs(full_sync: full_sync)
|
||||
def self.enque_jobs(full_sync: false)
|
||||
jobs = SYNC_JOBS.dup
|
||||
|
||||
# Allow other plugins to add addtional sync jobs via Hooks
|
||||
|
||||
@@ -17,6 +17,7 @@ class WebhookProcessJob < ActiveJob::Base
|
||||
Invoice
|
||||
Estimate
|
||||
Employee
|
||||
Payment
|
||||
].freeze
|
||||
|
||||
# Process incoming QBO webhook notifications and sync relevant data to Redmine
|
||||
|
||||
@@ -16,6 +16,7 @@ class Customer < QboBaseModel
|
||||
has_many :issues
|
||||
has_many :invoices
|
||||
has_many :estimates
|
||||
has_many :payments
|
||||
validates_presence_of :name
|
||||
before_validation :normalize_phone_numbers
|
||||
self.primary_key = :id
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
#The MIT License (MIT)
|
||||
#
|
||||
#Copyright (c) 2026 rick barrette
|
||||
#
|
||||
#Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
#The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
#
|
||||
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
# A customer payment, cached from QuickBooks for reporting: id, customer, date and amount. Kept current by the
|
||||
# webhook and the sync; payments are received through the Receive payment page (RedmineQboBilling::PaymentWriter).
|
||||
class Payment < QboBaseModel
|
||||
|
||||
belongs_to :customer, optional: true
|
||||
validates :id, presence: true, uniqueness: true
|
||||
self.primary_key = :id
|
||||
qbo_sync push: false
|
||||
|
||||
def to_s
|
||||
"#{txn_date} #{total_amount}"
|
||||
end
|
||||
|
||||
end
|
||||
@@ -26,6 +26,9 @@ class EstimateSyncService < SyncServiceBase
|
||||
end
|
||||
|
||||
map_attributes :doc_number, :txn_date
|
||||
map_attribute :total_amount, :total
|
||||
# Man-hours: quantities of the products/services set as "Replaced by imported time"
|
||||
map_attribute(:hours) { |remote| RedmineQboBilling::ManHours.hours(remote) }
|
||||
map_belongs_to :customer
|
||||
|
||||
end
|
||||
@@ -24,6 +24,8 @@ class InvoiceSyncService < SyncServiceBase
|
||||
|
||||
map_attributes :balance, :doc_number, :due_date, :txn_date
|
||||
map_attribute :total_amount, :total
|
||||
# Man-hours: quantities of the products/services set as "Replaced by imported time"
|
||||
map_attribute(:hours) { |remote| RedmineQboBilling::ManHours.hours(remote) }
|
||||
map_attribute :qbo_updated_at, "meta_data.last_updated_time"
|
||||
map_belongs_to :customer
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
#The MIT License (MIT)
|
||||
#
|
||||
#Copyright (c) 2026 rick barrette
|
||||
#
|
||||
#Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
#The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
#
|
||||
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
# Reads a payment's details from QuickBooks for the Payment model (payments are only cached here, never pushed)
|
||||
class PaymentService < ServiceBase
|
||||
|
||||
private
|
||||
|
||||
def build_qbo_remote
|
||||
Quickbooks::Model::Payment.new
|
||||
end
|
||||
|
||||
end
|
||||
@@ -0,0 +1,32 @@
|
||||
#The MIT License (MIT)
|
||||
#
|
||||
#Copyright (c) 2026 rick barrette
|
||||
#
|
||||
#Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
#The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
#
|
||||
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
# Caches QuickBooks payments: customer, date, amount and what's still unapplied
|
||||
class PaymentSyncService < SyncServiceBase
|
||||
|
||||
private
|
||||
|
||||
# Specify the local model this service syncs
|
||||
def self.model_class
|
||||
Payment
|
||||
end
|
||||
|
||||
map_attributes :txn_date
|
||||
map_attribute :total_amount, :total
|
||||
map_attribute :unapplied_amount
|
||||
map_attribute :qbo_updated_at, "meta_data.last_updated_time"
|
||||
# A payment whose customer hasn't synced yet keeps none until the next sync
|
||||
map_attribute :customer do |remote|
|
||||
id = remote.customer_ref&.value
|
||||
id.present? ? Customer.find_by(id: id) : nil
|
||||
end
|
||||
|
||||
end
|
||||
@@ -12,7 +12,7 @@ class PdfService
|
||||
require 'combine_pdf'
|
||||
|
||||
# Subclasses should initialize with a QBO client instance
|
||||
def initialize(entity: entity)
|
||||
def initialize(entity:)
|
||||
raise "An entity to sync is required" unless entity
|
||||
@entity = entity
|
||||
end
|
||||
|
||||
@@ -0,0 +1,148 @@
|
||||
<% html_title l(:label_business_report) %>
|
||||
<% money = @report.money %>
|
||||
<% hours = @report.hours %>
|
||||
<% ratios = @report.ratios %>
|
||||
<% max_money = [money[:estimates][:total], money[:invoices][:total], money[:payments][:total]].max.to_f %>
|
||||
<% max_hours = hours.values.max.to_f %>
|
||||
<% bar = ->(value, max) { max > 0 ? (value.to_f / max * 100).round(1) : 0 } %>
|
||||
<% fmt_hours = ->(h) { format('%.1f', h.to_f) } %>
|
||||
<% pct = ->(v) { v.nil? ? '–' : "#{v}%" } %>
|
||||
|
||||
<h2><%= l(:label_business_report) %></h2>
|
||||
|
||||
<%= form_tag qbo_reports_path, method: :get, id: 'qbo-report-form' do %>
|
||||
<fieldset class="box">
|
||||
<legend><%= l(:label_report_period) %></legend>
|
||||
<%= select_tag 'period',
|
||||
options_for_select(RedmineQboBilling::BusinessReport::PERIODS.map { |p| [l("label_report_period_#{p}"), p] }, @report.period),
|
||||
id: 'qbo-report-period' %>
|
||||
<span id="qbo-report-dates">
|
||||
<%= date_field_tag 'from', @report.from.iso8601, id: 'qbo-report-from' %>
|
||||
–
|
||||
<%= date_field_tag 'to', @report.to.iso8601, id: 'qbo-report-to' %>
|
||||
</span>
|
||||
<%= submit_tag l(:button_apply), name: nil %>
|
||||
</fieldset>
|
||||
<% end %>
|
||||
|
||||
<p class="qbo-report-range"><%= format_date(@report.from) %> – <%= format_date(@report.to) %></p>
|
||||
|
||||
<% if @report.unsynced_count > 0 %>
|
||||
<p class="warning"><%= l(:text_report_needs_sync, count: @report.unsynced_count) %></p>
|
||||
<% end %>
|
||||
|
||||
<div class="splitcontent">
|
||||
<div class="splitcontentleft">
|
||||
<h3><%= l(:label_report_money) %></h3>
|
||||
<table class="list qbo-report">
|
||||
<tbody>
|
||||
<% [[:estimates, l(:label_report_estimates_written)], [:invoices, l(:label_report_invoices_written)],
|
||||
[:payments, l(:label_report_payments_received)]].each do |key, label| %>
|
||||
<tr>
|
||||
<td class="name"><%= label %> <span class="count">(<%= money[key][:count] %>)</span></td>
|
||||
<td class="bar"><div class="qbo-bar qbo-bar-<%= key %>" style="width: <%= bar.call(money[key][:total], max_money) %>%"></div></td>
|
||||
<td class="value"><%= number_to_currency(money[key][:total]) %></td>
|
||||
</tr>
|
||||
<% end %>
|
||||
</tbody>
|
||||
</table>
|
||||
<p class="qbo-report-ratios">
|
||||
<%= l(:label_report_invoiced_of_estimated) %>: <strong><%= pct.call(ratios[:invoiced_of_estimated]) %></strong><br />
|
||||
<%= l(:label_report_collected_of_invoiced) %>: <strong><%= pct.call(ratios[:collected_of_invoiced]) %></strong><br />
|
||||
<%= l(:label_report_open_balance) %>: <strong><%= number_to_currency(money[:invoices][:balance]) %></strong>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="splitcontentright">
|
||||
<h3><%= l(:label_report_hours) %></h3>
|
||||
<table class="list qbo-report">
|
||||
<tbody>
|
||||
<% [[:estimate_hours, l(:label_report_estimate_hours)], [:issue_hours, l(:label_report_issue_hours)],
|
||||
[:invoice_hours, l(:label_report_invoice_hours)], [:spent_hours, l(:label_report_spent_hours)]].each do |key, label| %>
|
||||
<tr>
|
||||
<td class="name"><%= label %></td>
|
||||
<td class="bar"><div class="qbo-bar qbo-bar-<%= key %>" style="width: <%= bar.call(hours[key], max_hours) %>%"></div></td>
|
||||
<td class="value"><%= fmt_hours.call(hours[key]) %></td>
|
||||
</tr>
|
||||
<% end %>
|
||||
</tbody>
|
||||
</table>
|
||||
<p class="qbo-report-ratios">
|
||||
<%= l(:label_report_invoiced_of_spent) %>: <strong><%= pct.call(ratios[:invoiced_of_spent]) %></strong><br />
|
||||
<%= l(:label_report_spent_of_estimated) %>: <strong><%= pct.call(ratios[:spent_of_estimated]) %></strong>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h3><%= l(:label_report_by_month) %></h3>
|
||||
<div class="autoscroll">
|
||||
<table class="list qbo-report-months">
|
||||
<thead>
|
||||
<tr>
|
||||
<th class="month"><%= l(:label_month) %></th>
|
||||
<th><%= l(:label_report_estimates_written) %></th>
|
||||
<th><%= l(:label_report_invoices_written) %></th>
|
||||
<th><%= l(:label_report_payments_received) %></th>
|
||||
<th class="hours-start"><%= l(:label_report_estimate_hours) %></th>
|
||||
<th><%= l(:label_report_issue_hours) %></th>
|
||||
<th><%= l(:label_report_invoice_hours) %></th>
|
||||
<th><%= l(:label_report_spent_hours) %></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<% @report.months.each do |row| %>
|
||||
<tr>
|
||||
<td class="month"><%= ::I18n.t('date.abbr_month_names')[row[:month].month] %> <%= row[:month].year %></td>
|
||||
<td><%= number_to_currency(row[:estimates]) %></td>
|
||||
<td><%= number_to_currency(row[:invoices]) %></td>
|
||||
<td><%= number_to_currency(row[:payments]) %></td>
|
||||
<td class="hours-start"><%= fmt_hours.call(row[:estimate_hours]) %></td>
|
||||
<td><%= fmt_hours.call(row[:issue_hours]) %></td>
|
||||
<td><%= fmt_hours.call(row[:invoice_hours]) %></td>
|
||||
<td><%= fmt_hours.call(row[:spent_hours]) %></td>
|
||||
</tr>
|
||||
<% end %>
|
||||
</tbody>
|
||||
<tfoot>
|
||||
<tr class="total">
|
||||
<td class="month"><strong><%= l(:label_total) %></strong></td>
|
||||
<td><strong><%= number_to_currency(money[:estimates][:total]) %></strong></td>
|
||||
<td><strong><%= number_to_currency(money[:invoices][:total]) %></strong></td>
|
||||
<td><strong><%= number_to_currency(money[:payments][:total]) %></strong></td>
|
||||
<td class="hours-start"><strong><%= fmt_hours.call(hours[:estimate_hours]) %></strong></td>
|
||||
<td><strong><%= fmt_hours.call(hours[:issue_hours]) %></strong></td>
|
||||
<td><strong><%= fmt_hours.call(hours[:invoice_hours]) %></strong></td>
|
||||
<td><strong><%= fmt_hours.call(hours[:spent_hours]) %></strong></td>
|
||||
</tr>
|
||||
</tfoot>
|
||||
</table>
|
||||
</div>
|
||||
<p class="info"><%= l(:text_report_notes) %></p>
|
||||
|
||||
<style>
|
||||
table.qbo-report td { padding: 6px 4px; }
|
||||
table.qbo-report td.name { text-align: left; white-space: nowrap; width: 1%; }
|
||||
table.qbo-report td.name .count { color: #888; }
|
||||
table.qbo-report td.bar { width: 100%; }
|
||||
table.qbo-report td.value { text-align: right; white-space: nowrap; font-weight: bold; width: 1%; }
|
||||
.qbo-bar { height: 14px; border-radius: 2px; min-width: 1px; background: #628db6; }
|
||||
.qbo-bar-invoices, .qbo-bar-invoice_hours { background: #e8a33d; }
|
||||
.qbo-bar-payments, .qbo-bar-spent_hours { background: #5aa05a; }
|
||||
.qbo-bar-issue_hours { background: #9b7fc0; }
|
||||
.qbo-report-ratios { margin: 8px 4px; line-height: 1.7; }
|
||||
.qbo-report-range { color: #666; margin: 4px 0 10px; }
|
||||
table.qbo-report-months td, table.qbo-report-months th { text-align: right; white-space: nowrap; }
|
||||
table.qbo-report-months .month { text-align: left; }
|
||||
table.qbo-report-months .hours-start { border-left: 2px solid #ddd; }
|
||||
table.qbo-report-months tfoot td { border-top: 2px solid #ccc; }
|
||||
#qbo-report-form select, #qbo-report-form input { vertical-align: middle; }
|
||||
</style>
|
||||
|
||||
<%= javascript_tag do %>
|
||||
$(function() {
|
||||
var $period = $('#qbo-report-period'), $dates = $('#qbo-report-from, #qbo-report-to');
|
||||
// Picking a preset fills its dates on Apply; changing a date switches to Custom
|
||||
$dates.on('change', function() { $period.val('custom'); });
|
||||
$period.on('change', function() { if ($period.val() !== 'custom') { $('#qbo-report-form').submit(); } });
|
||||
});
|
||||
<% end %>
|
||||
Reference in new issue
Block a user