Files
simple-aircraft-manager-rails/app/services/records_package.rb
T
rickyandClaude Opus 5.5 afaa1ca191 Records package: README explains viewing the data locally, links the source; includes viewer/docker-compose.yml
The viewer compose uses the published image (from docker-compose.image.yml)
and a throwaway secret key, plain HTTP on localhost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 07:05:43 -05:00

167 lines
8.8 KiB
Ruby

require "csv"
# Everything about an aircraft's records in one ZIP, for the FAA or NTSB on
# request (91.417(c), AC 120-78B 3.2.8.6) or a buyer at sale (91.419,
# 3.2.8.12): the logbook entries as a PDF with their electronic signatures,
# a signature register, the full change history, the status report, and the
# data archive (.sam.zip) to load into another system.
class RecordsPackage
def initialize(aircraft, source:)
@aircraft = aircraft
@source = source
@generated_at = Time.current
end
def filename = "#{@aircraft.tail_number.downcase}-records-#{@generated_at.to_date.iso8601}.zip"
def write_to(path)
entries = @aircraft.logbook_entries.includes(:component, :parts, :signature, inspection_records: :inspection_type).order(:date, :id).to_a
Zip::OutputStream.open(path) do |zip|
add(zip, "README.txt", readme(entries))
add(zip, "logbook-entries.pdf", LogbookEntryPdf.new(@aircraft, entries, layout: "letter").render) if entries.any?
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
add(zip, "viewer/docker-compose.yml", viewer_compose)
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")
File.open(archive.path, "rb") { IO.copy_stream(_1, zip) }
ensure
archive&.close!
end
path
end
private
# CSVs start with a UTF-8 byte order mark so Excel reads accents, dashes
# and quotes correctly (without it, it guesses another encoding).
def add(zip, name, content)
content = "\uFEFF#{content}" if name.end_with?(".csv") && !content.start_with?("\uFEFF")
zip.put_next_entry(name)
zip.write(content)
end
def readme(entries)
signed = entries.count(&:signed?)
check = IntegrityCheck.latest
<<~TXT
Maintenance records for #{@aircraft.tail_number} (#{[ @aircraft.make, @aircraft.model ].compact_blank.join(' ')}, S/N #{@aircraft.serial_number.presence || 'not recorded'})
Prepared #{@generated_at.utc.strftime('%Y-%m-%d %H:%M UTC')} by Simple Aircraft Manager (#{@source}), software version #{SystemInfo.new.revision}.
Electronic records since: #{@aircraft.electronic_records_since&.iso8601 || 'not stated'}. Earlier records are the paper logbooks#{' (scans marked "legacy record" are in the archive)' if @aircraft.documents.where(legacy_record: true).exists?}.
Contents
- logbook-entries.pdf All #{entries.size} logbook entries, oldest first. #{signed} are signed electronically: each shows
"Certified by" the signer and certificate, the time (UTC) and the first 16 characters of its fingerprint.
- signatures.csv Every electronic signature: signer, certificate, statement, time, status and full fingerprint.
- 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.
- viewer/docker-compose.yml Runs Simple Aircraft Manager on your own computer to browse the archive (below).
Signatures
Each electronic signature records who signed, with which certificate, what they certified, when, and a SHA-256
fingerprint of the entry's content at signing. A signed entry can't be edited; corrections are new signed entries
that supersede the original (both are included). Status "Valid" means the entry and signature are unchanged since
signing; "Superseded" means a later signed correction replaces it.
Last records integrity check: #{check ? "#{check.created_at.utc.strftime('%Y-%m-%d %H:%M UTC')}, #{check.ok ? 'no problems found' : "#{check.problems.size} problem(s) found"}" : 'not run yet'}.
Viewing the data in Simple Aircraft Manager
The PDF, CSV and HTML files above open on their own. To browse everything (components, logbook, ADs,
inspections, documents, flights, oil and fuel) the way the owner sees it, run the app on your own computer:
1. Install Docker Desktop (https://www.docker.com/products/docker-desktop/).
2. In a terminal, go to the "viewer" folder of this package and run: docker compose up -d
3. Open http://localhost:3000 and create the first (admin) account.
4. Choose Fleet -> Import and select #{@aircraft.tail_number.downcase}.sam.zip from this package (or this whole zip file).
The copy runs only on your computer and stays separate from the owner's system. Electronic signatures are
shown as imported: compare their fingerprints with signatures.csv and logbook-entries.pdf. To stop it:
docker compose down (add -v to delete the local copy).
#{"\nSimple Aircraft Manager is open source: #{repository}" if repository}
TXT
end
def repository = SystemInfo.new.repository_url
# The published image, as named in the project's docker-compose.image.yml
# (APP_IMAGE overrides it, e.g. for a fork's own image).
def viewer_image
ENV["APP_IMAGE"].presence ||
Rails.root.join("docker-compose.image.yml").then { _1.exist? ? _1.read[/^\s*image:\s*(\S+)/, 1] : nil }
end
# A ready-to-run local viewer, with its own throwaway secret key (never this
# installation's), plain HTTP on localhost.
def viewer_compose
image = viewer_image
<<~YAML
# Simple Aircraft Manager on your own computer, to browse #{@aircraft.tail_number.downcase}.sam.zip.
# docker compose up -d then open http://localhost:3000, create an account,
# and import #{@aircraft.tail_number.downcase}.sam.zip (Fleet -> Import). Stop: docker compose down
# Prepared with software version #{SystemInfo.new.revision}.#{" Source: #{repository}" if repository}
services:
web:
#{image ? "image: #{image}" : "build: . # no published image known: build from the source code"}
restart: "no"
ports:
- "3000:80"
environment:
SECRET_KEY_BASE: #{SecureRandom.hex(64)} # for this local copy only
APP_HOST: localhost:3000
FORCE_SSL: "false"
SOLID_QUEUE_IN_PUMA: "true"
volumes:
- viewer_storage:/rails/storage
volumes:
viewer_storage:
YAML
end
def signatures_csv(entries)
CSV.generate do |csv|
csv << %w[entry_date log entry_type signer certificate_kind certificate_number signed_at_utc status fingerprint statement corrects_entry_dated]
entries.select(&:signed?).each do |e|
s = e.signature
csv << [ e.date, LogbookEntry::LOG_TYPES[e.log_type], LogbookEntry::ENTRY_TYPES[e.entry_type], s.signer_name, s.certificate_label,
s.certificate_number, s.signed_at.utc.iso8601, s.imported? ? "imported from #{s.origin}" : s.status_label,
s.content_digest, s.statement, e.supersedes&.date ]
end
end
end
def history_csv
users = User.pluck(:id, :email_address).to_h
CSV.generate do |csv|
csv << %w[id at_utc record record_id event by changed_fields chain_hash]
RecordVersion.where(aircraft_id: @aircraft.id).chronological.find_each do |v|
csv << [ v.id, v.created_at.utc.iso8601, v.item_type.underscore.humanize, v.item_id, v.event, users[v.user_id] || "system",
v.event == "update" ? v.changed_fields.join(" ") : "", v.chain_hash ]
end
end
end
# The status report as one self-contained HTML file (styles inlined).
def status_report_html
inline_styles(ApplicationController.render("maintenance_reports/show", layout: "report", assigns: { report: MaintenanceReport.new(@aircraft), standalone: true }))
end
def standalone_html(body, title)
inline_styles(ApplicationController.render(html: body.html_safe, layout: "report", assigns: { standalone: true }).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")
# Block forms: a replacement string would treat "\\&" etc. in the CSS as back-references.
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*}, "")
end
end