Recordkeeping procedures, QC audits and user instructions (AC 120-78B)

- Admin → Recordkeeping Procedures: generated procedures document
  (2.2.11 / 3.2.8) from the system setup plus owner-entered details;
  adopted as numbered, immutable revisions; included in the records package
- Admin → Records Audits: periodic QC checklist (3.2.8.5) combining app
  checks with a restore test, sampled entries vs. source documents and a
  user review; next due date on About and in admins' weekly reminder
- User instructions at /help/records, linked from the logbook and signing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-07 13:30:46 -05:00
1 parent 68a1719db2
commit 761f381679
27 files changed
+668 -10

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
# The QC audit checklist (AC 120-78B 3.2.8.5): items the app checks itself,
# and items the auditor confirms (restore test, comparing a sample of entries
# with their source documents, reviewing users).
class RecordsAudit
Item = Data.define(:key, :title, :auto, :passed, :detail)
MANUAL = {
"restore_test" => "Restored the latest off-site backup somewhere separate and opened it (records readable, counts plausible)",
"sample" => "Compared the sampled entries below with their work orders, receipts or other source documents; they match",
"users" => "Reviewed the users and roles below; accounts of people who no longer need access are disabled",
"legacy" => "The paper (legacy) logbooks are kept, complete and accounted for"
}.freeze
def initialize(since: AuditRun.latest&.performed_at)
@since = since
@policy = RecordkeepingPolicy.current
end
def auto_items
check = IntegrityCheck.latest
backup = BackupRun.latest
revision = ProceduresRevision.current
expired = UserCertificate.joins(:user).merge(User.active).where(expires_on: ...Date.current)
[
Item.new("integrity", "Records integrity check passed in the last 2 days", true,
check.present? && check.ok && check.created_at > 2.days.ago,
check ? "#{check.created_at.to_date}: #{check.ok ? 'no problems' : check.problems.first(3).join('; ')}" : "Never run"),
Item.new("backup", "A verified database backup was made in the last 2 days", true,
backup.present? && backup.ok && backup.created_at > 2.days.ago,
backup ? "#{backup.created_at.to_date}: #{backup.message}" : "Never run"),
Item.new("procedures", "The procedures document is adopted and its details filled in", true,
revision.present? && @policy.complete?,
revision ? "Revision #{revision.number}, adopted #{revision.adopted_at.to_date}" : "Not adopted yet"),
Item.new("signatures", "Electronic signatures since the last audit are intact", true,
check.present? && check.ok, "#{signatures_since.count} signed since #{since_label}"),
Item.new("certificates", "No active user is relying on an expired certificate", true, true,
expired.any? ? "Expired (can't sign until renewed): #{expired.map { "#{_1.user.display_name} #{_1.short_label}" }.join(', ')}" : "None expired"),
Item.new("versions", "Software versions since the last audit", true, true,
versions_since.map(&:revision).join(", ").presence || "No changes")
]
end
# Entries to compare with source documents: a random few since the last audit, signed ones first.
def sample
pool = LogbookEntry.where(created_at: (@since || Time.at(0))..).includes(:aircraft, :signature)
signed = pool.joins(:signature).order(Arel.sql("RANDOM()")).limit(@policy.audit_sample_size).to_a
(signed + pool.where.not(id: signed.map(&:id)).order(Arel.sql("RANDOM()")).limit(@policy.audit_sample_size - signed.size).to_a).first(@policy.audit_sample_size)
end
def users = User.order(:email_address).includes(:certificates, aircraft_roles: :aircraft)
# Saves the audit from the auditor's answers: { key => { "passed" => "1", "note" => … } }.
def record!(user:, answers:, notes:, sample_ids:)
autos = auto_items
manual = MANUAL.map do |key, title|
a = answers.fetch(key, {})
{ "key" => key, "title" => title, "auto" => false, "passed" => a["passed"] == "1", "detail" => a["note"].to_s.strip.first(1000) }
end
results = autos.map { { "key" => _1.key, "title" => _1.title, "auto" => true, "passed" => _1.passed, "detail" => _1.detail } } + manual
results << { "key" => "sample_entries", "title" => "Entries sampled", "auto" => true, "passed" => true,
"detail" => LogbookEntry.where(id: sample_ids).includes(:aircraft).map { "#{_1.aircraft.tail_number} #{_1.date}" }.join(", ") }
AuditRun.create!(performed_by: user, performed_at: Time.current, passed: results.all? { _1["passed"] }, results: results, notes: notes.to_s.strip.first(5000))
end
private
def since_label = @since ? @since.to_date.to_s : "the start"
def signatures_since = EntrySignature.where(signed_at: (@since || Time.at(0))..)
def versions_since = AppRevision.where(first_seen_at: (@since || Time.at(0))..).order(:first_seen_at)
end
+12 -2
View File
@@ -22,6 +22,9 @@ class RecordsPackage
add(zip, "signatures.csv", signatures_csv(entries))
add(zip, "record-history.csv", history_csv)
add(zip, "status-report.html", status_report_html)
if (revision = ProceduresRevision.current)
add(zip, "recordkeeping-procedures.html", standalone_html(revision.content, "Recordkeeping procedures, revision #{revision.number}"))
end
archive = Tempfile.new([ "archive", ".sam.zip" ])
AircraftArchive::Exporter.new(@aircraft, source: @source).write_to(archive.path)
zip.put_next_entry("#{@aircraft.tail_number.downcase}.sam.zip")
@@ -55,6 +58,7 @@ class RecordsPackage
- record-history.csv Every change to the maintenance records (created, changed, deleted), with who and when.
- status-report.html Maintenance status per 14 CFR 91.417(a)(2): times, life-limited parts, inspections, ADs, alterations.
- #{@aircraft.tail_number.downcase}.sam.zip All records and files as data, to load into another system.
- recordkeeping-procedures.html How these electronic records and signatures are kept (AC 120-78B), current adopted revision.
Signatures
Each electronic signature records who signed, with which certificate, what they certified, when, and a SHA-256
@@ -91,8 +95,14 @@ class RecordsPackage
# The status report as one self-contained HTML file (styles inlined).
def status_report_html
html = ApplicationController.render("maintenance_reports/show", layout: "report",
assigns: { report: MaintenanceReport.new(@aircraft) })
inline_styles(ApplicationController.render("maintenance_reports/show", layout: "report", assigns: { report: MaintenanceReport.new(@aircraft) }))
end
def standalone_html(body, title)
inline_styles(ApplicationController.render(html: body.html_safe, layout: "report", assigns: {}).sub(%r{<title>.*?</title>}m, "<title>#{ERB::Util.h(title)}</title>"))
end
def inline_styles(html)
css = %w[tailwind.css application.css].filter_map { Rails.application.assets.load_path.find(_1)&.content }.join("\n")
html.gsub(%r{<link rel="stylesheet"[^>]*>\s*}, "").sub("</head>", "<style>#{css}</style></head>")
.gsub(%r{<script\b[^>]*>.*?</script>}m, "").gsub(%r{<link rel="modulepreload"[^>]*>\s*}, "")