API na nahrávání účtenek #28

Open
opened 2026-11-16 17:19:41 +01:00 by wikiker · 0 comments
Owner

Records should be enterable by piping document filenames (receipts, invoices, e-receipt photos) to a CLI script that uploads each file to Helenka and creates a draft record. Detected metadata pre-fills the record; the user completes the remaining details (event, type, tax fields) in the existing web form. Heuristics run server-side so that both the CLI and the web benefit from them and they are unit-testable without the client.

A staged flow (CLI uploads and creates drafts, web finalizes) reuses the existing RecordForm, record_detail and the bank-transaction merge flow, and follows the established pattern that machine-created entries (Fio statement import) are curated by a human.

Proposed behavior

  1. CLI: ls receipts/*.jpg | helenka-upload uploads each document via a token-authenticated multipart endpoint and prints the URL of the created draft record.
  2. Server creates a draft record (new Record.is_draft flag, default True for API-created records; cleared on first save through record_edit).

Server-side changes

  • New is_draft boolean field on Record; overview filter for drafts. (This can be reused for bank imports as well.)
  • Token authentication scoped to record creation only (minimal Authorization: Token check against a token field on the user profile; DRF not required unless already a dependency).
  • POST /budget/api/records/draft: multipart (document file plus optional fields), validated by a DraftRecordForm (subset of RecordForm). Returns record pk and finalization URL.
  • Authorization in the view: staff may attach drafts to any event; organizers and treasurers only to events of their seminars.
  • New module records/import_heuristics.py with the detection pipeline and unit tests.

Client-side changes

  • Single-file Python script (requests plus stdlib): reads filenames from stdin, performs a duplicate check via the existing lookup endpoint, uploads, prints result URLs, exits non-zero on failure.

Out of scope

  • OCR for photographed receipts (phase two).
  • Interactive terminal questionnaire; the web form remains the place for details.
  • Full CRUD API; only draft creation is exposed.

Acceptance criteria

  • A CLI user with a token can upload a batch of files; each creates a draft record with a linked document.
  • Filename-encoded dates are detected and pre-filled; files named outside the convention still upload, with empty detected fields.
  • Drafts appear in the overview drafts filter and can be completed through the existing record form, which clears the draft flag.
  • Duplicate check prevents re-uploading a document whose code already exists.
  • Token cannot be used for any action other than draft creation.
  • Heuristics module has unit tests covering the filename.
Records should be enterable by piping document filenames (receipts, invoices, e-receipt photos) to a CLI script that uploads each file to Helenka and creates a draft record. Detected metadata pre-fills the record; the user completes the remaining details (event, type, tax fields) in the existing web form. Heuristics run server-side so that both the CLI and the web benefit from them and they are unit-testable without the client. A staged flow (CLI uploads and creates drafts, web finalizes) reuses the existing RecordForm, record_detail and the bank-transaction merge flow, and follows the established pattern that machine-created entries (Fio statement import) are curated by a human. **Proposed behavior** 1. CLI: `ls receipts/*.jpg | helenka-upload` uploads each document via a token-authenticated multipart endpoint and prints the URL of the created draft record. 2. Server creates a draft record (new `Record.is_draft` flag, default True for API-created records; cleared on first save through record_edit). **Server-side changes** - New `is_draft` boolean field on `Record`; overview filter for drafts. (This can be reused for bank imports as well.) - Token authentication scoped to record creation only (minimal `Authorization: Token` check against a token field on the user profile; DRF not required unless already a dependency). - `POST /budget/api/records/draft`: multipart (document file plus optional fields), validated by a `DraftRecordForm` (subset of RecordForm). Returns record pk and finalization URL. - Authorization in the view: staff may attach drafts to any event; organizers and treasurers only to events of their seminars. - New module `records/import_heuristics.py` with the detection pipeline and unit tests. **Client-side changes** - Single-file Python script (requests plus stdlib): reads filenames from stdin, performs a duplicate check via the existing lookup endpoint, uploads, prints result URLs, exits non-zero on failure. **Out of scope** - OCR for photographed receipts (phase two). - Interactive terminal questionnaire; the web form remains the place for details. - Full CRUD API; only draft creation is exposed. **Acceptance criteria** - A CLI user with a token can upload a batch of files; each creates a draft record with a linked document. - Filename-encoded dates are detected and pre-filled; files named outside the convention still upload, with empty detected fields. - Drafts appear in the overview drafts filter and can be completed through the existing record form, which clears the draft flag. - Duplicate check prevents re-uploading a document whose code already exists. - Token cannot be used for any action other than draft creation. - Heuristics module has unit tests covering the filename.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
wikiker/helenka#28
No description provided.