mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 15:50:36 -05:00
API: draft logbook entries for signing
- POST /aircraft/:id/draft_batches turns a visit's work items into one unsigned entry per logbook, signed in the app (by a user with a certificate, or a mechanic through a returned or emailed invitation link). - The squawks they resolve and inspections they complete (with their result) are held until every entry is signed, then applied, attributed to the last signer; draft_batch.completed webhook. A draft never clears a squawk alone. - Drafts are for owners (integrations act for one, drafts:write scope); unsigned drafts can be withdrawn; lookup by external_ref. - The signing and entry pages show where a draft came from and what signing will do. - The suggested recordkeeping procedures describe the API once it's in use. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
bffdea937c
commit
e4c27c6ff7
19 files changed
+495
-5
No files matched your search
@@ -35,6 +35,7 @@ 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) |
|
||||
|
||||
## Requests and answers
|
||||
|
||||
@@ -68,6 +69,11 @@ Squawks have an `external_ref`: your own id for them, such as `redmine:issue:451
|
||||
| `GET /squawks?external_ref=…` | Find squawks by your id for them |
|
||||
| `GET /squawks/:id` | One squawk |
|
||||
| `PATCH /squawks/:id` | Update a squawk |
|
||||
| `POST /aircraft/:id/draft_batches` | Send a visit's work as draft logbook entries for signing |
|
||||
| `GET /aircraft/:id/draft_batches` | Its drafts (`?status=awaiting_signature`, `completed` or `withdrawn`) |
|
||||
| `GET /draft_batches?external_ref=…` | Find drafts by your id for them |
|
||||
| `GET /draft_batches/:id` | One draft, with its entries and whether they're signed |
|
||||
| `DELETE /draft_batches/:id` | Withdraw a draft nothing in which is signed yet |
|
||||
|
||||
### Reporting a squawk
|
||||
|
||||
@@ -94,6 +100,46 @@ The answer is `201` with the 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.
|
||||
|
||||
## 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.
|
||||
|
||||
```
|
||||
POST /api/v1/aircraft/12/draft_batches
|
||||
{ "draft_batch": {
|
||||
"date": "2026-11-20",
|
||||
"aircraft_hours": 4321.4,
|
||||
"external_ref": "redmine:visit:77",
|
||||
"items": [
|
||||
{ "log": "ENG", "text": "Changed oil and filter, 7 qt Aeroshell W100.", "external_ref": "redmine:issue:4512" },
|
||||
{ "log": "AC", "text": "Replaced left brake linings.", "resolves_squawks": [88], "external_ref": "redmine:issue:4513" },
|
||||
{ "log": "AC", "text": "Annual inspection completed IAW Part 43 Appendix D.", "external_ref": "redmine:issue:4519" }
|
||||
],
|
||||
"completes_inspections": [ { "inspection_type_id": 3, "result": "approved" } ],
|
||||
"signer": { "email": "mechanic@example.com", "send_email": false }
|
||||
} }
|
||||
```
|
||||
|
||||
- **One entry per logbook.** Items are grouped by `log` (`AC`, `ENG`, `PROP` or `OTHER`) into one unsigned entry each, their texts in order, so a visit that touched the engine and the airframe makes two entries, signed one after the other.
|
||||
- **Inspections** (`completes_inspections`): each needs its `result`, `approved` (airworthy) or `discrepancies` (a list was given to the owner), and the draft needs `aircraft_hours`. The entry recording it is an inspection entry, in the logbook named by `log`, else the airframe log if an item is for it.
|
||||
- **Nothing is resolved until it's signed.** The squawks the items resolve and the inspections they complete are held until **every** entry of the draft is signed; then they're resolved and recorded, attributed to the person who signed last, and linked to the entry that described the work. A draft never clears a squawk on its own. The signer sees what signing will do before they sign.
|
||||
- **The signer.** Anyone with access to the aircraft and a certificate in their profile can sign, from each entry's `sign_url`. Give `signer.email` for someone else (a mechanic without an account): each entry then gets an `invitation_url`, a link that lets that person create an account for that address and sign that entry, for 14 days. Pass the link on yourself (for example inside Redmine), or set `send_email: true` to have SAM email it.
|
||||
|
||||
The answer (`201`):
|
||||
|
||||
```json
|
||||
{ "data": { "id": 301, "status": "awaiting_signature", "external_ref": "redmine:visit:77",
|
||||
"held": { "resolves_squawks": [88], "completes_inspections": [3] },
|
||||
"entries": [
|
||||
{ "id": 9001, "log": "AC", "entry_type": "INSPECTION", "text": "Replaced left brake linings.\n\nAnnual inspection…", "signed": false,
|
||||
"sign_url": "https://sam.example.com/aircraft/12/logbook_entries/9001/signature/new", "invitation_url": "https://sam.example.com/sign/…" },
|
||||
{ "id": 9002, "log": "ENG", "entry_type": "MAINTENANCE", "text": "Changed oil and filter…", "signed": false, … } ] } }
|
||||
```
|
||||
|
||||
When every entry is signed, the draft's `status` becomes `completed` and the `draft_batch.completed` webhook is sent: the moment to close the work order.
|
||||
|
||||
A draft can be withdrawn (`DELETE /draft_batches/:id`) while nothing in it is signed; its entries are removed, and the record history keeps them. Once an entry is signed it's a record: mistakes are fixed with a correction entry in the app, never through the API.
|
||||
|
||||
## Webhooks
|
||||
|
||||
An integration can be told about changes. In Admin → Integrations, give it a webhook address and choose the events. SAM then posts JSON there after each change:
|
||||
@@ -104,6 +150,7 @@ An integration can be told about changes. In Admin → Integrations, give it a w
|
||||
| `squawk.updated` | A squawk is changed |
|
||||
| `squawk.resolved` | A squawk is resolved |
|
||||
| `entry.signed` | A logbook entry is signed |
|
||||
| `draft_batch.completed` | Every entry of a draft is signed, and what it resolves is done |
|
||||
|
||||
Only events on the integration's aircraft are sent. The body:
|
||||
|
||||
|
||||
Reference in new issue
Block a user