mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 23:50:36 -05:00
User guide in docs/guide, shown in the app under Help
- 16 Markdown pages covering every area for pilots, owners, mechanics and admins, readable on GitHub - /help renders them with a page list; links between pages work in both places; only listed pages can be opened - The electronic records instructions (AC 120-78B user instructions) are now the guide's records page, also used as the procedures appendix - Help link in the main menu Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
761f381679
commit
fe3fba1736
28 files changed
+599
-32
No files matched your search
@@ -130,6 +130,10 @@
|
||||
.markdown table { display: block; max-width: 100%; overflow-x: auto; border-collapse: collapse; font-size: 0.85em; }
|
||||
.markdown th, .markdown td { border: 1px solid var(--color-slate-200); padding: 0.25rem 0.5rem; text-align: left; }
|
||||
.markdown th { background: var(--color-slate-50); font-weight: 600; }
|
||||
.markdown.guide { line-height: 1.6; }
|
||||
.markdown.guide h1 { font-size: 1.5rem; font-weight: 700; }
|
||||
.markdown.guide h2 { font-size: 1.15rem; margin-top: 1.25em; }
|
||||
.markdown.guide h3 { margin-top: 1em; }
|
||||
}
|
||||
|
||||
/* ---- Phones ---------------------------------------------------------- */
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
# User instructions for electronic records and signatures (AC 120-78B 2.2.12, 3.2.9).
|
||||
# The user guide (docs/guide), including the instructions for electronic
|
||||
# records and signatures (AC 120-78B 2.2.12, 3.2.9).
|
||||
class HelpController < ApplicationController
|
||||
def records; end
|
||||
def show
|
||||
@page = HelpGuide.find(params[:page] || "README") or raise ActionController::RoutingError, "Not found"
|
||||
@pages = HelpGuide.pages
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,10 @@
|
||||
module HelpHelper
|
||||
def help_page_url_for(slug, anchor = nil)
|
||||
slug == "README" ? help_path(anchor: anchor) : help_page_path(slug, anchor: anchor)
|
||||
end
|
||||
|
||||
def guide_html(page, links: true, title: true)
|
||||
html = HelpGuide.html(page, title: title, link: (links ? method(:help_page_url_for) : nil))
|
||||
tag.div(html.html_safe, class: "markdown guide") # rubocop:disable Rails/OutputSafety -- sanitized in HelpGuide
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,39 @@
|
||||
# The user guide: Markdown files in docs/guide (readable on GitHub too),
|
||||
# shown in the app under /help. Only the pages listed here can be opened.
|
||||
class HelpGuide
|
||||
DIR = Rails.root.join("docs/guide")
|
||||
ORDER = %w[README getting-started profile aircraft flights squawks oil-and-fuel components logbook records
|
||||
inspections ads documents major-records sharing administration].freeze
|
||||
OPTIONS = {
|
||||
parse: { smart: true },
|
||||
render: { hardbreaks: false, unsafe: false },
|
||||
extension: { strikethrough: true, tagfilter: true, table: true, autolink: true, header_ids: "" }
|
||||
}.freeze
|
||||
TAGS = %w[p br strong em del a ul ol li blockquote code pre h1 h2 h3 h4 hr table thead tbody tr th td].freeze
|
||||
ATTRIBUTES = %w[href id align].freeze
|
||||
|
||||
Page = Data.define(:slug, :title, :markdown)
|
||||
|
||||
def self.pages = ORDER.filter_map { find(_1) }
|
||||
|
||||
def self.find(slug)
|
||||
return unless ORDER.include?(slug.to_s)
|
||||
path = DIR.join("#{slug}.md")
|
||||
return unless path.file?
|
||||
markdown = path.read
|
||||
Page.new(slug: slug.to_s, title: markdown[/\A# (.+)$/, 1] || slug.to_s.titleize, markdown: markdown)
|
||||
end
|
||||
|
||||
# Sanitized HTML. Links to other guide pages ("records.md#mistakes") go
|
||||
# through `link` (slug, anchor) -> URL, or become plain text when nil.
|
||||
def self.html(page, link:, title: true)
|
||||
source = title ? page.markdown : page.markdown.sub(/\A# .+\n+/, "")
|
||||
html = Commonmarker.to_html(source, options: OPTIONS, plugins: { syntax_highlighter: nil })
|
||||
html = Rails::HTML5::SafeListSanitizer.new.sanitize(html, tags: TAGS, attributes: ATTRIBUTES)
|
||||
html.gsub(%r{<a href="([a-z-]+|README)\.md(?:#([a-z0-9-]+))?">(.*?)</a>}m) do
|
||||
slug, anchor, text = $1, $2, $3
|
||||
next text unless link && ORDER.include?(slug)
|
||||
%(<a href="#{ERB::Util.h(link.call(slug, anchor))}">#{text}</a>)
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -97,7 +97,7 @@
|
||||
|
||||
<h2 class="<%= h2 %>">13. User instructions and training</h2>
|
||||
<p class="<%= p_ %>">Every user who keeps or signs records reads these instructions (also in the system under “How electronic records work”) before signing (2.2.12, 3.2.9).</p>
|
||||
<div class="mt-2 rounded border border-slate-200 p-3"><%= render "help/records_content" %></div>
|
||||
<div class="mt-2 rounded border border-slate-200 p-3"><%= guide_html(HelpGuide.find("records"), links: false, title: false) %></div>
|
||||
|
||||
<% if policy.additional_procedures.present? %>
|
||||
<h2 class="<%= h2 %>">14. Additional procedures</h2>
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
<%# User instructions for electronic records (also an appendix of the procedures document). %>
|
||||
<div class="space-y-3 text-sm leading-relaxed">
|
||||
<h3 class="font-semibold">Writing an entry</h3>
|
||||
<p>On the aircraft's Logbook tab, choose <strong>+ New Entry</strong>. Give the date, the logbook (aircraft, engine, propeller), the airframe total time, and what was done; for an engine or propeller entry pick the component (its times fill in) and tick any sub-components. A template can start the wording. An entry isn't a signed record until it's signed.</p>
|
||||
<h3 class="font-semibold">Signing</h3>
|
||||
<ol class="list-decimal space-y-1 pl-5">
|
||||
<li>Add your certificate (kind and number) once, on your profile.</li>
|
||||
<li>Open the entry and choose <strong>Sign</strong>. Read the entry as shown: your signature covers exactly that.</li>
|
||||
<li>Pick the certificate you're signing with. The statement you'll certify is shown with it (return to service, or the inspection statement).</li>
|
||||
<li>Re-enter your password, or sign in again with single sign-on, tick the confirmation and choose <strong>Sign entry</strong>. You'll see a confirmation and get an email.</li>
|
||||
</ol>
|
||||
<p>Never share your password or let someone else sign while you're signed in: a signature is yours alone. If you think someone has, tell the administrator straight away.</p>
|
||||
<h3 class="font-semibold">Mistakes</h3>
|
||||
<p>A signed entry can't be edited or deleted. Open it and choose <strong>Correct this entry</strong>: a new entry starts from the original; fix it, save, and sign it. The original stays, marked “Superseded by a correction”.</p>
|
||||
<h3 class="font-semibold">Someone else did the work</h3>
|
||||
<p>The owner can choose <strong>Ask someone to sign</strong> on the entry: the mechanic gets a one-time email link, signs in or creates their own account, adds their certificate and signs. If they prefer paper, print the entry (<strong>Print for logbook</strong>), have it signed in ink, and keep the paper with the logbooks (scan it into Documents).</p>
|
||||
<h3 class="font-semibold">Checking a record</h3>
|
||||
<p>A signed entry shows who certified it, with which certificate, when (UTC), what they certified, and its status. <strong>Valid</strong> means nothing has changed since signing. The fingerprint (a SHA-256 of the entry) is printed on paper copies so a copy can be matched to the record. Every change to any record is kept under <strong>Activity → Record history</strong>.</p>
|
||||
<h3 class="font-semibold">If the system is down</h3>
|
||||
<p>Make the entry on paper and sign it in ink. When the system is back, add the entry and scan the signed paper into Documents; the paper itself stays with the logbooks and remains the signed record for that entry.</p>
|
||||
</div>
|
||||
@@ -1,6 +0,0 @@
|
||||
<% content_for :title, "How electronic records work" %>
|
||||
<section class="card card-body max-w-3xl">
|
||||
<h1 class="text-2xl font-bold">How electronic records work</h1>
|
||||
<p class="mb-4 mt-1 text-sm text-slate-600">Instructions for everyone who keeps or signs maintenance records here.</p>
|
||||
<%= render "help/records_content" %>
|
||||
</section>
|
||||
@@ -0,0 +1,14 @@
|
||||
<% content_for :title, "Help: #{@page.title}" %>
|
||||
<div class="grid gap-5 lg:grid-cols-[14rem_1fr]">
|
||||
<nav aria-label="Help pages" class="lg:order-none">
|
||||
<details class="card lg:hidden">
|
||||
<summary class="card-header cursor-pointer"><span class="card-title">Help: <%= @page.title %></span></summary>
|
||||
<ul class="p-2 text-sm"><% @pages.each do |p| %><li><%= link_to p.title, help_page_url_for(p.slug), class: [ "block rounded px-3 py-2 hover:bg-slate-100", ("bg-slate-100 font-semibold text-sky-700" if p == @page) ] %></li><% end %></ul>
|
||||
</details>
|
||||
<ul class="sticky top-4 hidden space-y-0.5 text-sm lg:block">
|
||||
<% @pages.each do |p| %><li><%= link_to p.title, help_page_url_for(p.slug), class: [ "block rounded px-3 py-1.5 hover:bg-slate-100", ("bg-slate-100 font-semibold text-sky-700" if p == @page) ],
|
||||
aria: { current: (p == @page ? "page" : nil) } %></li><% end %>
|
||||
</ul>
|
||||
</nav>
|
||||
<article class="card card-body min-w-0 max-w-3xl"><%= guide_html(@page) %></article>
|
||||
</div>
|
||||
@@ -35,6 +35,7 @@
|
||||
<div class="absolute right-0 z-30 mt-2 w-56 rounded-md bg-surface py-1 text-slate-700 shadow-lg ring-1 ring-slate-200">
|
||||
<p class="truncate px-4 pt-2 pb-1 text-xs text-slate-500"><%= current_user.email_address %></p>
|
||||
<%= link_to "Profile", edit_profile_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
|
||||
<%= link_to "Help", help_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
|
||||
<% if current_user.admin? %>
|
||||
<p class="border-t border-slate-100 px-4 pt-2 pb-1 text-xs font-semibold text-slate-500">Admin</p>
|
||||
<% [ [ "Users", admin_users_path ], [ "Component Types", admin_component_types_path ], [ "Airports", admin_airports_path ], [ "Logbook Templates", admin_logbook_templates_path ], [ "Settings", edit_admin_settings_path ], [ "Recordkeeping Procedures", admin_procedures_path ], [ "Records Audits", admin_audits_path ], [ "About", admin_about_path ] ].each do |label, path| %>
|
||||
@@ -59,6 +60,7 @@
|
||||
</div>
|
||||
</details>
|
||||
<% end %>
|
||||
<%= link_to "Help", help_path, class: "hover:text-sky-300" %>
|
||||
<%= link_to current_user.display_name, edit_profile_path, class: "text-white/70 hover:text-sky-300 hidden sm:inline" %>
|
||||
<%= render "shared/theme_toggle" %>
|
||||
<%= button_to "Sign out", session_path, method: :delete, class: "rounded bg-white/10 px-2 py-1 hover:bg-white/20" %>
|
||||
|
||||
Reference in new issue
Block a user