Fold redmine_qbo_billing into redmine_qbo

Estimates, invoices and payments written in Redmine, issues from estimates,
and the QuickBooks product/service list and accounts are now part of this
plugin (the RedmineQboBilling code, its controllers, views, strings and
permissions), so there's one plugin and one version instead of two that had
to match.

- The customer page, estimate and invoice lists and the issue page render the
  Create Estimate / Create invoice / Receive payment and Edit links directly;
  the hooks that only existed to let billing add them are gone. Users without
  the billing permissions still get the links to QuickBooks.
- Migrations 043-046 create the items and accounts tables and the estimate
  line links, skipping whatever an existing database already has
  (redmine_qbo_lineitems' tables are used as they are), and copy calendar's
  existing estimate line links in.
- The billing settings are a section of this plugin's settings page.
- The hooks other plugins use stay: qbo_billing_issue_values,
  qbo_billing_validate, qbo_billing_issue_defaults, qbo_billing_issues_created
  and view_qbo_estimate_contextual.
- rake redmine_qbo:relate_estimate_issues

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BiwYMjhoQvL7XsKKfRz4pM
This commit is contained in:
Claude committed 2026-10-30 23:47:01 -04:00
1 parent 48a4185c16
commit 9121e079a0
67 files changed
+5570 -19

No files matched your search

+401
View File
@@ -0,0 +1,401 @@
#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.
module RedmineQboBilling
# Reads QuickBooks invoices into an EstimateForm (document "invoice") and writes forms back as invoices.
# Lines, subtotals, discounts, custom fields and addresses work exactly as on estimates (EstimateWriter).
#
# On top of that an invoice can take lines from elsewhere:
# * an estimate converted to an invoice, or open estimates imported into it (e.g. the ones
# redmine_qbo_lineitems makes for parts that weren't quoted). Those estimates are linked to the invoice
# and closed when it's saved.
# * billable QuickBooks time activities (the ones redmine_qbo makes from an issue's time entries). Each
# becomes a line linked to its time activity, so QuickBooks marks the time as billed.
#
# An invoice with a payment applied to it is read-only, so a paid invoice can't be changed under the payment.
module InvoiceWriter
Error = EstimateWriter::Error
Conflict = EstimateWriter::Conflict
ESTIMATE = 'Estimate'.freeze
TIME_ACTIVITY = EstimateWriter::TIME_ACTIVITY
# Estimates in these states can still be imported (Converted/Closed ones are already invoiced, Rejected ones lost)
OPEN_ESTIMATE_STATUSES = ['', 'Pending', 'Accepted'].freeze
# How QuickBooks marks an invoiced estimate: Converted when it made the invoice, Closed when closed by hand
BILLED_ESTIMATE_STATUSES = %w[Converted Closed].freeze
# How far back to look for billable time if QuickBooks won't filter time activities by customer
TIME_LOOKBACK = 400
module_function
def writer
EstimateWriter
end
# The plugin setting "Replaced by imported time": only lines with these products/services are offered
# under Replace these lines when time is imported (e.g. an estimate's Labor lines); empty offers every line
def replaceable_item_ids
Array(Setting.plugin_redmine_qbo['replaceable_item_ids']).map(&:to_s).reject(&:blank?).uniq
rescue StandardError
[]
end
# A blank invoice for the customer, dated today
def new_form(customer: nil, user: User.current)
EstimateForm.new(
document: 'invoice',
customer_id: customer&.id,
customer_name: customer&.name,
email: writer.customer_email(customer),
billing_address: writer.customer_address(customer),
txn_date: user.today.iso8601,
sales_person: user.name,
customer_memo: Company.invoice_message,
lines: Array.new(2) { EstimateForm::Line.new(quantity: '', taxable: true) }
)
end
# A new invoice from an estimate, like QuickBooks' "Create invoice" on an estimate: the estimate's
# customer, lines, subtotals and VIN. The estimate is linked and closed when the invoice is saved.
def from_estimate(estimate_id, user: User.current)
remote = QboEstimateService.with_service { |service| service.fetch_by_id(estimate_id) }
raise Error, I18n.t(:notice_estimate_not_found) unless remote
# An estimate is billed once
billed = billing_error(remote)
raise Error, billed if billed
source = writer.form_from_remote(remote)
customer = Customer.find_by(id: source.customer_id)
new_form(customer: customer, user: user).tap do |form|
form.customer_name = source.customer_name if customer.nil?
form.customer_id = source.customer_id
form.email = source.email.presence || form.email
form.billing_address = source.billing_address.presence || form.billing_address
form.vin = source.vin
form.mileage = source.mileage
# The estimate's writer sells the job; with no one on the estimate, whoever writes the invoice
form.sales_person = source.sales_person.presence || user.name
form.private_note = source.private_note
form.lines = copy_lines(source.lines)
form.linked_estimate_ids = [source.id.to_s]
form.converted_from = source.doc_number
end
end
def load(id)
remote = QboInvoiceService.with_service { |service| service.fetch_by_id(id) }
raise Error, I18n.t(:notice_invoice_not_found) unless remote
form_from_remote(remote)
end
# Creates or updates the invoice in QuickBooks, closes the estimates it was made from, and returns the
# saved QuickBooks invoice. The sales person is the one on the estimate it was made from (the first linked
# estimate that names one), or else the user who creates it; editing keeps the original one.
def save(form, user: User.current)
customer = Customer.find_by(id: form.customer_id)
raise Error, I18n.t(:error_estimate_needs_customer) unless customer
saved = QboInvoiceService.with_service do |service|
if form.persisted?
remote = service.fetch_by_id(form.id)
raise Error, I18n.t(:notice_invoice_not_found) unless remote
raise Conflict, I18n.t(:error_invoice_changed_in_quickbooks) if remote.sync_token.to_s != form.sync_token.to_s
raise Error, I18n.t(:error_invoice_has_bundles) if writer.group_lines?(remote)
raise Error, I18n.t(:error_invoice_paid) if paid?(remote)
check_not_billed(form.linked_estimate_ids - linked_ids(remote, ESTIMATE))
invoice = Quickbooks::Model::Invoice.new
invoice.id = remote.id
invoice.sync_token = remote.sync_token
apply(form, invoice, customer: customer, remote: remote, user: user)
service.update(invoice, sparse: true)
else
check_not_billed(form.linked_estimate_ids)
invoice = Quickbooks::Model::Invoice.new
apply(form, invoice, customer: customer, remote: nil, user: user,
sales_person: estimate_sales_person(form.linked_estimate_ids))
service.create(invoice)
end
end
raise Error, I18n.t(:error_invoice_not_saved) unless saved
sync_local(saved)
close_estimates(linked_ids(saved, ESTIMATE).presence || form.linked_estimate_ids)
saved
end
def send_email(id, email)
sent = QboInvoiceService.with_service { |service| service.send_invoice(id, email) }
raise Error, I18n.t(:error_invoice_not_sent) unless sent
sent
end
# ---- QuickBooks invoice -> form ----
def form_from_remote(remote)
EstimateForm.new(
document: 'invoice',
id: remote.id.to_s,
sync_token: remote.sync_token.to_s,
customer_id: remote.customer_ref&.value.to_s,
customer_name: remote.customer_ref&.name.presence || Customer.find_by(id: remote.customer_ref&.value)&.name,
email: remote.bill_email&.address.to_s,
billing_address: writer.format_address(remote.billing_address),
txn_date: remote.txn_date&.iso8601,
due_date: remote.due_date&.iso8601,
doc_number: remote.doc_number.to_s,
sales_person: writer.custom_value(remote, Company.sales_person_field, Company::SALES_PERSON_NAME),
vin: writer.custom_value(remote, Company.vin_field, Company::VIN_NAME),
mileage: writer.custom_value(remote, Company.mileage_field, Company::MILEAGE_NAME),
customer_memo: remote.customer_memo.to_s,
private_note: remote.private_note.to_s,
lines: writer.tidy_subtotals(Array(remote.line_items).filter_map { |line| writer.line_from_remote(line) }),
linked_estimate_ids: linked_ids(remote, ESTIMATE),
total: remote.total,
total_tax: remote.txn_tax_detail&.total_tax,
discount: writer.discount_total(remote),
balance: remote.balance,
email_status: remote.email_status.to_s,
locked: (:bundles if writer.group_lines?(remote)) || (:paid if paid?(remote))
)
end
# A payment is applied once the balance is less than the total
def paid?(remote)
return false if remote.balance.nil? || remote.total.nil?
BigDecimal(remote.balance.to_s) < BigDecimal(remote.total.to_s)
end
def linked_ids(remote, type)
Array(remote&.linked_transactions).select { |t| t.txn_type.to_s == type }.map { |t| t.txn_id.to_s }.uniq
end
# ---- form -> QuickBooks invoice ----
def apply(form, invoice, customer:, remote:, user:, sales_person: nil)
invoice.customer_id = customer.id
if remote.nil? || remote.customer_ref&.value.to_s != customer.id.to_s
address = writer.customer_details(customer)&.billing_address
invoice.billing_address = address if address
end
invoice.bill_email = Quickbooks::Model::EmailAddress.new(form.email) if form.email.present?
invoice.txn_date = form.txn_date_value
# Left out when empty: QuickBooks works it out from the customer's terms
invoice.due_date = form.due_date_value if form.due_date_value
invoice.doc_number = writer.next_doc_number(Invoice) if remote.nil? && Company.custom_txn_numbers?
invoice.customer_memo = form.customer_memo.to_s
invoice.private_note = form.private_note.to_s
invoice.custom_fields = writer.build_custom_fields(form, remote, user, sales_person: sales_person)
invoice.line_items = writer.build_lines(form, remote)
invoice.linked_transactions = header_links(form, remote)
invoice
end
# The invoice-level links: the estimates it was made from, and every time activity a line bills
# (QuickBooks wants time linked both on the line and on the invoice)
def header_links(form, remote)
estimates = (linked_ids(remote, ESTIMATE) + form.linked_estimate_ids).uniq
times = form.filled_lines.filter_map(&:time_activity_id).map(&:to_s).uniq
estimates.map { |id| link(id, ESTIMATE) } + times.map { |id| link(id, TIME_ACTIVITY) }
end
def link(id, type)
Quickbooks::Model::LinkedTransaction.new(txn_id: id.to_s, txn_type: type)
end
# The sales person on the first of the estimates that names one (estimates redmine_qbo_lineitems makes
# have none), so the invoice credits whoever wrote the estimate
def estimate_sales_person(estimate_ids)
field = Company.sales_person_field
return nil if field.nil? || Array(estimate_ids).empty?
QboEstimateService.with_service do |service|
Array(estimate_ids).each do |id|
estimate = service.fetch_by_id(id)
name = estimate && writer.custom_value(estimate, field, Company::SALES_PERSON_NAME)
return name if name.present?
end
nil
end
rescue StandardError => e
Rails.logger.warn "[RedmineQboBilling] Could not read the estimate's sales person: #{e.message}"
nil
end
# ---- billing an estimate once ----
# Why the estimate can't be billed, or nil: it's already on an invoice (linked to one, or closed, which is
# how QuickBooks marks an invoiced estimate), or the customer rejected it
def billing_error(estimate)
number = estimate.doc_number.to_s
invoice_id = linked_ids(estimate, 'Invoice').first
if invoice_id
I18n.t(:error_estimate_already_invoiced, number: number, invoice: invoice_number(invoice_id))
elsif BILLED_ESTIMATE_STATUSES.include?(estimate.txn_status.to_s)
I18n.t(:error_estimate_closed_billed, number: number, status: estimate.txn_status.to_s)
elsif estimate.txn_status.to_s == 'Rejected'
I18n.t(:error_estimate_rejected, number: number)
end
end
# Checked against QuickBooks when saving, since an estimate can be invoiced elsewhere (another tab, another
# user, QuickBooks itself) after the invoice page was opened. Estimates already on this invoice aren't checked.
def check_not_billed(estimate_ids)
ids = Array(estimate_ids).map(&:to_s).reject(&:blank?).uniq
return if ids.empty?
errors = QboEstimateService.with_service do |service|
ids.filter_map do |id|
estimate = service.fetch_by_id(id)
estimate ? billing_error(estimate) : I18n.t(:notice_estimate_not_found)
end
end
raise Error, errors.join(' ') if errors.any?
end
# The invoice's number when it's synced locally, else its QuickBooks id
def invoice_number(invoice_id)
Invoice.find_by(id: invoice_id)&.doc_number.presence || invoice_id.to_s
rescue StandardError
invoice_id.to_s
end
# Marks the estimates as closed (invoiced), as QuickBooks does when it converts one. Done separately
# so it also happens if QuickBooks doesn't close a linked estimate by itself.
def close_estimates(ids)
Array(ids).uniq.each do |id|
QboEstimateService.with_service do |service|
estimate = service.fetch_by_id(id)
# Already Converted or Closed is left as QuickBooks set it
next if estimate.nil? || BILLED_ESTIMATE_STATUSES.include?(estimate.txn_status.to_s)
update = Quickbooks::Model::Estimate.new
update.id = estimate.id
update.sync_token = estimate.sync_token
update.customer_ref = estimate.customer_ref
update.txn_status = 'Closed'
service.update(update, sparse: true)
end
EstimateSyncService.new.sync_by_id(id)
rescue StandardError => e
Rails.logger.warn "[RedmineQboBilling] Could not close estimate #{id}: #{e.message}"
end
end
# ---- importing ----
# What can be pulled into an invoice for the customer: billable time and open estimates, and the VIN and
# mileage plugins give for their work orders (and for issues already on the invoice: issue_ids)
def import_options(customer, issue_ids: [])
times = open_time_activities(customer)
estimates = open_estimates(customer)
ids = (times.map { |t| t[:issue_id] } + estimates.map { |e| e[:issue_id] } + Array(issue_ids)).compact.map(&:to_s).uniq
issues = ids.empty? ? [] : Issue.where(id: ids).to_a
{ time_activities: times, estimates: estimates, issue_values: IssueValues.by_issue(issues) }
end
# The customer's QuickBooks time activities that are still billable (not yet on an invoice)
def open_time_activities(customer)
activities = QboConnectionService.with_qbo_service(entity: 'TimeActivity') do |service|
begin
service.query("SELECT * FROM TimeActivity WHERE CustomerRef = '#{customer.id.to_i}' ORDERBY TxnDate", per_page: 1000).entries
rescue StandardError
# Not every company lets time be filtered by customer: look at recent time instead
since = (Date.today - TIME_LOOKBACK).iso8601
service.query("SELECT * FROM TimeActivity WHERE TxnDate >= '#{since}' ORDERBY TxnDate", per_page: 1000).entries
end
end
Array(activities).select { |a| a.customer_ref&.value.to_s == customer.id.to_s && a.billable_status.to_s == 'Billable' }
.map { |a| time_activity_hash(a) }
end
def time_activity_hash(activity)
hours = activity_hours(activity)
rate = EstimateForm.decimal(activity.hourly_rate) || BigDecimal('0')
item = Item.find_by(id: activity.item_ref&.value) if activity.item_ref&.value.present?
{
id: activity.id.to_s,
date: activity.txn_date.to_s,
employee: activity.employee_ref&.name || activity.vendor_ref&.name,
item_id: activity.item_ref&.value.to_s.presence,
item_name: activity.item_ref&.name.presence || item&.name,
description: activity.description.to_s,
issue_id: issue_reference(activity.description),
quantity: writer.plain_number(hours),
rate: writer.plain_number(rate),
amount: (hours * rate).round(2).to_s('F'),
taxable: item ? item.taxable != false : false
}
end
# Hours and minutes, or start and end time less the break
def activity_hours(activity)
if activity.hours || activity.minutes
(BigDecimal(activity.hours.to_i.to_s) + BigDecimal(activity.minutes.to_i.to_s) / 60).round(4)
elsif activity.start_time && activity.end_time
minutes = ((activity.end_time.to_time - activity.start_time.to_time) / 60).round -
(activity.break_hours.to_i * 60 + activity.break_minutes.to_i)
(BigDecimal([minutes, 0].max.to_s) / 60).round(4)
else
BigDecimal('0')
end
end
# The customer's open estimates, each with its lines ready to add to an invoice
def open_estimates(customer)
estimates = QboEstimateService.with_service do |service|
service.query("SELECT * FROM Estimate WHERE CustomerRef = '#{customer.id.to_i}' ORDERBY TxnDate DESC", per_page: 100).entries
end
Array(estimates).select { |e| billing_error(e).nil? && OPEN_ESTIMATE_STATUSES.include?(e.txn_status.to_s) && !writer.group_lines?(e) }.map do |e|
lines = writer.tidy_subtotals(Array(e.line_items).filter_map { |line| writer.line_from_remote(line) })
linked_issue = writer.linked_issues(e.id).first
{
id: e.id.to_s,
doc_number: e.doc_number.to_s,
date: e.txn_date.to_s,
total: e.total.to_s,
issue: linked_issue&.then { |i| "#{i.tracker} ##{i.id}: #{i.subject}" },
# Lines from this estimate go next to the invoice's time for the same issue
issue_id: issue_reference(lines.detect { |l| l.description.present? }&.description) || linked_issue&.id&.to_s,
lines: lines.map { |l| line_hash(l) }
}
end
end
def issue_reference(text)
IssueValues.issue_reference(text)
end
def line_hash(line)
{ kind: line.kind, item_id: line.item_id, item_name: line.item_name, description: line.description,
quantity: line.quantity, rate: line.rate, taxable: line.taxable? }
end
# ---- helpers ----
# Lines copied to a new document: no line ids, everything else as it was
def copy_lines(lines)
lines.map do |line|
EstimateForm::Line.new(kind: line.kind, item_id: line.item_id, item_name: line.item_name,
description: line.description, quantity: line.quantity, rate: line.rate,
taxable: line.taxable, time_activity_id: line.time_activity_id)
end
end
def sync_local(saved)
InvoiceSyncService.new.sync_by_id(saved.id)
rescue StandardError => e
Rails.logger.warn "[RedmineQboBilling] Saved invoice #{saved.id} but could not sync it locally: #{e.message}"
end
end
end