mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 15:50:36 -05:00
Configurable roles: Owner, Mechanic, Pilot, Viewer and custom roles
What people can do on an aircraft now comes from their role there, and administrators set what each role allows (Admin → Roles). - Roles are installation-wide sets of permissions (31, grouped as flying, squawks and notes, maintenance records, imports and exports, the aircraft, notifications). Seeing an aircraft's records needs none. - Built in: Owner (always every permission, so an aircraft can always be managed), Mechanic (shop maintenance: logbook, signing, components, inspections, ADs, squawks, reminders), Pilot (what pilots could do before) and Viewer (view only). Administrators can change all but Owner's, and add their own; a role can be deleted once nobody has it. - Existing owners and pilots keep exactly what they could do. - Admin → Users → a user lists their role on every aircraft, to change, remove or add. On the aircraft's Access page, anyone who manages people hands out roles, but only an Owner can give or take away Owner, nobody changes their own (except administrators), and an aircraft always keeps an Owner (AircraftAccess). - Controllers declare the permission each action needs; a request that changes something with none declared is refused (and raises in development and tests), and a test walks every route to check. - Weekly reminders and overdue alerts go to roles that get reminders; the DRS reminder also needs Manage ADs. The API follows the person's role; its owners_only error is now not_permitted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
d2cd60c6a7
commit
d8cd462194
101 files changed
+1032
-232
No files matched your search
@@ -14,6 +14,18 @@ Admins see the **Admin** menu (on a phone, under ☰). Admins can see and edit e
|
||||
|
||||
With single sign-on, accounts can be created automatically at first sign-in, and admin rights can follow a group at the provider (see the main README).
|
||||
|
||||
## Roles
|
||||
|
||||
**Admin → Roles** sets what people can do on an aircraft. Each person has one role per aircraft; a role is a set of permissions, grouped as flying, squawks and notes, maintenance records, imports and exports, the aircraft itself, and notifications. Everyone can see the records of the aircraft they have a role on; the permissions are for changing things.
|
||||
|
||||
- **Owner** always has every permission, so every aircraft can always be managed. Its name and description can be changed.
|
||||
- **Mechanic**, **Pilot** and **Viewer** come with sensible permissions (the table in [Getting started](getting-started.md#roles)) that you can change.
|
||||
- **New role** adds your own, such as a partner, an instructor or an insurer. A role can be deleted once nobody has it.
|
||||
|
||||
Signing a logbook entry needs the **Sign logbook entries** permission *and* a current certificate on the person's profile. **Get reminders** decides who receives the weekly email of what's coming due and the alerts when something becomes overdue.
|
||||
|
||||
To give someone a role on any aircraft, open them in **Admin → Users**: **Aircraft access** lists their role on each aircraft, to change, remove or add.
|
||||
|
||||
## Account recovery from the command line
|
||||
|
||||
If nobody can sign in to fix an account in the app (a forgotten admin password, a lockout, a lost phone with no recovery codes, the only admin disabled), run these on the server. With Docker Compose, put `docker compose exec web` in front; in Portainer, open the container's **Console** and run them there. Anyone who can run commands on the server already has the data, so they ask for nothing else. Each one is written to the log.
|
||||
|
||||
+4
-4
@@ -35,14 +35,14 @@ Reading works without it (limited to the integration's aircraft). Every write ne
|
||||
|---|---|
|
||||
| `read` | Aircraft, parts, due items, inspections, ADs, squawks and logbook entries |
|
||||
| `squawks:write` | Reporting squawks and updating them |
|
||||
| `drafts:write` | Sending draft logbook entries for signing, and withdrawing them (acting for an owner of the aircraft) |
|
||||
| `drafts:write` | Sending draft logbook entries for signing, and withdrawing them (acting for someone who can write logbook entries on the aircraft) |
|
||||
|
||||
## Requests and answers
|
||||
|
||||
- Base address: `https://<your server>/api/v1`
|
||||
- JSON in and out. Times are ISO 8601 in UTC, hours are decimals, and values are codes (`ENG`, `IN-USE`) rather than translated labels.
|
||||
- Lists answer `{ "data": [ … ], "next_after": 123 }`. Ask for more with `?after=123`; `?limit=` sets the page size (up to 200, default 50); `?updated_since=2026-11-01T00:00:00Z` lists only what changed since then.
|
||||
- Errors answer `{ "error": { "code": "invalid", "message": "…", "fields": { "issue_reported": ["can't be blank"] } } }` with the matching HTTP status: 400 bad request, 401 no or wrong token, 403 not allowed (`missing_scope`, `owners_only`), 404 not found or not reachable with this token, 409 `idempotency_conflict`, 422 invalid, 429 too many requests (600 a minute per token).
|
||||
- Errors answer `{ "error": { "code": "invalid", "message": "…", "fields": { "issue_reported": ["can't be blank"] } } }` with the matching HTTP status: 400 bad request, 401 no or wrong token, 403 not allowed (`missing_scope`; `not_permitted` when the person's role on the aircraft doesn't allow it), 404 not found or not reachable with this token, 409 `idempotency_conflict`, 422 invalid, 429 too many requests (600 a minute per token).
|
||||
|
||||
### Safe retries
|
||||
|
||||
@@ -98,11 +98,11 @@ The answer is `201` with the squawk:
|
||||
|
||||
### Updating a squawk
|
||||
|
||||
`PATCH /squawks/:id` with `{ "squawk": { … } }`. Anyone who may write can set `external_ref`; changing `issue_reported`, `priority`, `component_id` or `notes` needs an owner of the aircraft, as in the app. A resolved squawk can't be changed. Squawks are resolved by a signed logbook entry, in the app.
|
||||
`PATCH /squawks/:id` with `{ "squawk": { … } }`. Anyone who may write can set `external_ref`; changing `issue_reported`, `priority`, `component_id` or `notes` needs the **Manage squawks** permission on the aircraft, as in the app. Reporting one needs **Report squawks**. A resolved squawk can't be changed. Squawks are resolved by a signed logbook entry, in the app.
|
||||
|
||||
## Draft entries
|
||||
|
||||
Another system that tracks the work, such as Redmine's issues, can send a finished visit to SAM as **draft logbook entries**: the person certifying the work then reviews and signs them in the app. Like writing entries in the app, sending drafts is for the aircraft's owners: an integration acts for an owner (`SAM-On-Behalf-Of`), such as the director of maintenance.
|
||||
Another system that tracks the work, such as Redmine's issues, can send a finished visit to SAM as **draft logbook entries**: the person certifying the work then reviews and signs them in the app. Like writing entries in the app, sending drafts needs the **Write logbook entries** permission (Owners and Mechanics have it): an integration acts for such a person (`SAM-On-Behalf-Of`), such as the director of maintenance.
|
||||
|
||||
```
|
||||
POST /api/v1/aircraft/12/draft_batches
|
||||
|
||||
@@ -19,7 +19,7 @@ Track and engine data files attached offline are kept and sent too.
|
||||
|
||||
## Correct a flight
|
||||
|
||||
Open the flight and choose **Edit**. Owners can correct any flight; a pilot, the flights they logged. The date, airports, route, notes, oil and fuel (its oil and fuel records follow), and the track and engine data files can always be changed.
|
||||
Open the flight and choose **Edit**. Owners can correct any flight; pilots, the flights they logged (the **Correct any flight** and **Correct own flights** permissions). The date, airports, route, notes, oil and fuel (its oil and fuel records follow), and the track and engine data files can always be changed.
|
||||
|
||||
The meter readings can be changed only on the latest flight, and only until the hours change again (another flight, an hours update or an import). The aircraft and its installed components then move by the difference: fixing a tach in of 1001.4 to 1001.6 adds 0.2 hours. On earlier flights the readings are locked, since the flights after them started from those readings; correct the aircraft's hours with **Update Hours** instead.
|
||||
|
||||
|
||||
@@ -16,20 +16,21 @@ The very first visit to a new installation asks for the administrator account in
|
||||
|
||||
## Roles
|
||||
|
||||
What you can do depends on your role on each aircraft:
|
||||
What you can do depends on your role on each aircraft. These are the built-in roles as they come; the administrator can change what each allows and add others (see [Administration](administration.md#roles)).
|
||||
|
||||
| | Pilot | Owner | Admin |
|
||||
|---|:-:|:-:|:-:|
|
||||
| See everything on the aircraft | ✓ | ✓ | ✓ |
|
||||
| Log flights, update hours, report squawks, add notes, oil and fuel | ✓ | ✓ | ✓ |
|
||||
| Defer a squawk as inoperative | ✓ | ✓ | ✓ |
|
||||
| Sign logbook entries (with your own certificate) | ✓ | ✓ | ✓ |
|
||||
| Edit squawks and notes, resolve squawks | | ✓ | ✓ |
|
||||
| Components, logbook, inspections, ADs, documents, major records, W&B | | ✓ | ✓ |
|
||||
| Edit the aircraft, manage people and share links | | ✓ | ✓ |
|
||||
| Users, settings, procedures and audits for the whole app | | | ✓ |
|
||||
| | Viewer | Pilot | Mechanic | Owner |
|
||||
|---|:-:|:-:|:-:|:-:|
|
||||
| See everything on the aircraft | ✓ | ✓ | ✓ | ✓ |
|
||||
| Log flights, correct the ones you logged | | ✓ | | ✓ |
|
||||
| Update hours, report and defer squawks, add notes, oil and fuel | | ✓ | ✓ | ✓ |
|
||||
| Sign logbook entries (with your own certificate) | | ✓ | ✓ | ✓ |
|
||||
| Write logbook entries; components, inspections, ADs, major records, W&B, documents | | | ✓ | ✓ |
|
||||
| Edit squawks and notes, resolve squawks; edit oil and fuel records | | | ✓ | ✓ |
|
||||
| Weekly reminders and overdue alerts | | | ✓ | ✓ |
|
||||
| Correct or delete any flight, imports, exports, restore from history | | | | ✓ |
|
||||
| Edit the aircraft, manage people and share links | | | | ✓ |
|
||||
|
||||
Anyone can add an aircraft and becomes its owner. You only see aircraft you have a role on; admins see all of them.
|
||||
Administrators can do everything on every aircraft, and manage users, roles, settings, procedures and audits for the whole app. Anyone can add an aircraft and becomes its Owner. You only see aircraft you have a role on; administrators see all of them.
|
||||
|
||||
## Finding your way around
|
||||
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# Access, sharing and transfer
|
||||
|
||||
**Access & sharing** is for the aircraft's owners: open it from **More** at the top of the aircraft's pages.
|
||||
**Access & sharing** is for people whose role lets them manage the aircraft's people, share links or exports (Owners): open it from **More** at the top of the aircraft's pages.
|
||||
|
||||
## People
|
||||
|
||||
Add people by email as **owner** or **pilot** (they need an account; ask the administrator). Change or remove their role at any time. See the roles table in [Getting started](getting-started.md).
|
||||
Add people by email with a role: **Owner**, **Mechanic**, **Pilot**, **Viewer**, or one the administrator added (they need an account; ask the administrator). Change or remove their role at any time; **What each role can do** on the page lists them. See the roles table in [Getting started](getting-started.md).
|
||||
|
||||
Only an Owner can give or take away the Owner role, nobody can change their own, and an aircraft always keeps at least one Owner. An administrator can also give people roles on any aircraft from **Admin → Users**.
|
||||
|
||||
## Share links
|
||||
|
||||
|
||||
Reference in new issue
Block a user