Struct PosInvoiceRepository 

pub struct PosInvoiceRepository(/* private fields */);

Repository for PosInvoice entities.

All standard CRUD, soft-delete, pagination, and bulk methods are provided automatically via Deref to backbone_orm::GenericCrudRepository.

Implementations

impl PosInvoiceRepository

pub fn new(pool: PgPool) -> Self

Create a new repository instance.

impl PosInvoiceRepository

Hand-written counter-ticket SQL. Lives here (not in the write service) per the module’s 4-layer rule: services orchestrate and own the unit of work, repositories hold the SQL.

pub async fn insert_draft( &self, conn: &mut PgConnection, i: &NewDraftInvoiceRow<'_>, ) -> Result<(), Error>

Insert a rung ticket in draft.

Takes the CALLER’S connection so the header and its lines commit as one unit. The caller has already relayed the ambient org scope onto it — don’t re-bind here.

Returns the raw sqlx::Error deliberately: the caller inspects it for a unique violation to turn a re-used receipt number (or a re-used sync client_uuid) into a domain error.

pub async fn find_by_client_uuid( &self, pool: &PgPool, client_uuid: Uuid, ) -> Result<Option<SyncLookupRow>, Error>

Find the live ticket carrying an offline client uuid. The uuid only namespaces inside the caller’s scope: the ambient org scope’s fence is the whole guard — another unit’s ticket carrying the same uuid is simply not found.

pub async fn update_draft_from_sync( &self, conn: &mut PgConnection, pos_invoice_id: Uuid, opening_entry_id: Uuid, branch_id: Option<Uuid>, customer_id: Option<Uuid>, pos_table_id: Option<Uuid>, net_total: Decimal, tax_total: Decimal, grand_total: Decimal, rounding_adjustment: Decimal, rounded_total: Decimal, paid_total: Decimal, change_due: Decimal, ) -> Result<(), Error>

Rewrite a DRAFT ticket’s header for an offline replay: re-point it at the (possibly rescued) session, re-seat it at the replay’s table (a changed pos_table_id is a table TRANSFER), and replace its server-derived money + partner with the replay’s re-derived values. State-guarded on draft — a finalized ticket is never rewritten (the replay short-circuits before this). Takes the CALLER’S connection; the caller has already relayed the ambient scope. Returns the raw sqlx::Error so the caller can map the one-draft-per-table partial unique.

pub async fn find_draft_on_table( &self, conn: &mut PgConnection, pos_table_id: Uuid, exclude_invoice_id: Option<Uuid>, ) -> Result<Option<Uuid>, Error>

The draft ticket currently seated at a dining table — the friendly half of the one-draft-per-table guard (the DB partial unique idx_pos_invoices_pos_table_id is the backstop; this read turns the collision into a typed refusal naming the occupying ticket). exclude_invoice_id skips the ticket being re-seated (a replay that keeps its own table is not a collision). Ok(None) = the table is free. Takes the CALLER’S scope-relayed connection — the fence is the whole guard.

pub async fn find_draft_on_table_scoped( &self, pool: &PgPool, pos_table_id: Uuid, exclude_invoice_id: Option<Uuid>, ) -> Result<Option<Uuid>, Error>

The pool twin of Self::find_draft_on_table for the duplicate-mapping enrichment: after a failed insert the caller’s transaction is ABORTED, so the occupying ticket must be read on a fresh connection. Rides the ambient org scope (ADR-0029) — under a composed fence the read stays inside the acting unit, and a fence-blind read would enrich the 409 with a nil id.

pub async fn soft_delete_lines_for_ticket( &self, conn: &mut PgConnection, pos_invoice_id: Uuid, now: DateTime<Utc>, ) -> Result<(), Error>

Soft-delete a DRAFT ticket’s lines so an offline replay can rewrite the basket (full-snapshot semantics: the replay carries the complete ticket). Soft-delete keeps the audit trail and frees the partial-unique on client_uuid. Takes the CALLER’S connection.

pub async fn count_draft_orders_for_session( &self, pool: &PgPool, opening_entry_id: Uuid, ) -> Result<i64, Error>

Count a session’s DRAFT tickets — the close guard. ID-only: rides the ambient org scope.

pub async fn count_linked_unposted_for_session( &self, pool: &PgPool, opening_entry_id: Uuid, ) -> Result<i64, Error>

Count a session’s half-recognised tickets — billing linked but the draft→paid flip never landed (a settle failed after the invoice was raised). The close guard refuses on these: they need recognition retried, not skipped. ID-only scope as above.

pub async fn fetch_tender_header( &self, conn: &mut PgConnection, pos_invoice_id: Uuid, ) -> Result<Option<TenderHeaderRow>, Error>

Read the header add_tender gates on.

ID-only: rides the ambient org scope’s request-dedicated connection, so a ticket the scope cannot see simply is not found. The caller runs this on its own scope-relayed transaction (fetch_tender_header_on shape inlined: same statement, caller’s connection).

pub async fn update_tender_totals( &self, conn: &mut PgConnection, pos_invoice_id: Uuid, paid_total: Decimal, change_due: Decimal, ) -> Result<(), Error>

Write back a ticket’s recomputed tender totals. Takes the CALLER’S connection so this and the tender insert commit as one unit; the caller has already relayed the ambient scope on it.

pub async fn fetch_paid_state( &self, pool: &PgPool, pos_invoice_id: Uuid, ) -> Result<Option<PaidStateRow>, Error>

Read a ticket’s recognised state, for the recognise short-circuit. Same ID-only scope contract as Self::fetch_tender_header.

pub async fn fetch_for_recognition( &self, pool: &PgPool, pos_invoice_id: Uuid, ) -> Result<Option<RecognitionRow>, Error>

Read a DRAFT ticket joined to its register — everything recognition needs to drive billing, payment, and the optional stock issue. Ok(None) = absent, already recognised, or outside the caller’s scope.

ID-only: rides the ambient org scope. Under HTTP the request-dedicated connection carries the scope. When driven by an EVENT (the recognition sink subscribing to PosTenderCompleted), the caller MUST wrap this in the composing service’s org request scope — bound from the event’s company_id twin (the acting unit) — otherwise this read fails closed.

pub async fn link_billing_invoice( &self, pool: &PgPool, pos_invoice_id: Uuid, billing_invoice_id: Uuid, ) -> Result<(), Error>

Persist the raised Sales Invoice onto the STILL-DRAFT ticket, before settle.

This is billing’s at-most-once gate (council 2026-07-05): writing the link the instant raise_and_post returns makes a retry after a settle failure (declined card / closed period) REUSE the invoice instead of raising a second one — otherwise the counter’s ordinary decline-then-retry doubles the revenue journal. State-guarded on draft. Rides the ambient org scope.

pub async fn mark_paid( &self, pool: &PgPool, pos_invoice_id: Uuid, billing_invoice_id: Uuid, payment_entry_id: Uuid, ) -> Result<u64, Error>

Flip a ticket draft→paid, persisting both downstream refs. Returns the rows affected: the caller gates the PosInvoicePaid event and the stock issue on this being 1, so each happens exactly once even if recognise is retried.

Persisting payment_entry_id in the same flip is what lets a later return refund the tender from the ticket (no cross-schema lookup) and gives a crash-retry a durable skip-gate (ADR-001 settle-idempotency). Rides the ambient org scope.

pub async fn fetch_return_source( &self, pool: &PgPool, pos_invoice_id: Uuid, ) -> Result<Option<ReturnSourceRow>, Error>

Read the original ticket the returns path reverses and copies. Same ID-only scope contract as Self::fetch_tender_header.

pub async fn mark_returned( &self, pool: &PgPool, pos_invoice_id: Uuid, ) -> Result<u64, Error>

Flip the original ticket paid→returned. Returns the rows affected: the caller gates the return ticket and the PosInvoiceReturned event on this being 1, so a repeat return records at most once. Rides the ambient org scope.

pub async fn insert_return_ticket( &self, pool: &PgPool, r: &NewReturnInvoiceRow, ) -> Result<(), Error>

Insert the mirror return ticket, linked to the original via return_against. Rides the ambient org scope.

pub async fn find_return_ticket( &self, pool: &PgPool, original_pos_invoice_id: Uuid, ) -> Result<Option<Uuid>, Error>

Find the return ticket already recorded against an original — the idempotent-replay path when the paid→returned flip found nothing to do. Rides the ambient org scope.

pub async fn sum_change_due_for_session( &self, pool: &PgPool, opening_entry_id: Uuid, ) -> Result<Decimal, Error>

Sum the cash handed back as change across a session’s recognised tickets — it reduces the drawer. ID-only: rides the ambient org scope.

pub async fn session_totals( &self, pool: &PgPool, opening_entry_id: Uuid, ) -> Result<(Decimal, i64), Error>

A session’s recognised turnover + paid-ticket count, for the X/Z report. ID-only: rides the ambient org scope.

pub async fn fetch_receipt_header( &self, pool: &PgPool, pos_invoice_id: Uuid, ) -> Result<Option<ReceiptHeaderRow>, Error>

Read a ticket header joined to its register for the printed receipt. Ok(None) = no such ticket in the caller’s scope. Rides the ambient org scope — the fence is the whole guard.

Methods from Deref<Target = GenericCrudRepository<PosInvoice, SoftDelete>>

pub fn pool(&self) -> &Pool<Postgres>

pub fn table_name(&self) -> &str

pub async fn create(&self, entity: &T) -> Result<T, Error>

where T: Serialize + Send + Sync,

Insert a new entity row and return the created row.

pub async fn bulk_create(&self, entities: &[T]) -> Result<Vec<T>, Error>

where T: Serialize + Send + Sync,

Insert multiple entity rows inside a single transaction.

pub async fn run_filtered_query( &self, pagination: PaginationParams, base_condition: Option<&str>, filters: &HashMap<String, String>, column_types: &HashMap<String, String>, search_fields: &[&str], ) -> Result<PaginatedResult<T>, Error>

where T: Send + Sync,

Execute a filtered / paginated query against this entity’s table.

base_condition — when Some, it is inserted as the __base_condition filter key which the ORM injects verbatim into the WHERE clause. Use this to add soft-delete guards without touching the caller-supplied filters.

NOTE: prefer the *_scoped entry points for anything a client can reach — they compose the company fence into this condition. This raw form applies no fence and is for internal/job callers that have already established scope.

pub async fn run_aggregate_query( &self, spec: &AggregateSpec, base_condition: Option<&str>, filters: &HashMap<String, String>, column_types: &HashMap<String, String>, search_fields: &[&str], ) -> Result<AggregateResult, Error>

where T: EntityRepoMeta + Send + Sync,

The aggregate twin of Self::run_filtered_query.

Takes the same base_condition so an aggregate is computed over exactly the row set the matching list would return — a total that counted soft-deleted rows, or another tenant’s, would be wrong in a way no caller could see.

pub async fn find_by_text_field( &self, field: &str, value: &str, ) -> Result<Option<T>, Error>

Find an active entity by a unique text field.

Filters metadata->>'deleted_at' IS NULL automatically.

pub async fn exists_by_text_field( &self, field: &str, value: &str, ) -> Result<bool, Error>

Check existence by a unique text field (active records only).

pub async fn find_by_uuid_field( &self, field: &str, value: Uuid, ) -> Result<Option<T>, Error>

Find an active entity by a unique UUID field.

pub async fn exists_by_uuid_field( &self, field: &str, value: Uuid, ) -> Result<bool, Error>

Check existence by a unique UUID field (active records only).

pub async fn list_paginated_filtered( &self, pagination: PaginationParams, filters: Option<&HashMap<String, String>>, ) -> Result<PaginatedResult<T>, Error>

where T: EntityRepoMeta + Send + Sync,

Paginate active entities with filter and search support.

Requires T: EntityRepoMeta for column type hints and search fields.

pub async fn aggregate_filtered( &self, spec: &AggregateSpec, filters: Option<&HashMap<String, String>>, ) -> Result<AggregateResult, Error>

where T: EntityRepoMeta + Send + Sync,

Group and reduce active entities, skipping the soft-deleted.

pub async fn list_paginated_filtered_scoped( &self, pagination: PaginationParams, filters: Option<&HashMap<String, String>>, company: Option<Uuid>, ) -> Result<PaginatedResult<T>, Error>

where T: EntityRepoMeta + Send + Sync,

Paginate active entities, fenced to company.

The company-scoped counterpart of Self::list_paginated_filtered and the one any client-reachable read should use. Fails closed: a fenced entity with no company returns MissingCompanyScope rather than every company’s rows.

The fence is ANDed into the same __base_condition the soft-delete guard uses, so it lands in SQL — which is what keeps total honest. A post-filter in the handler would fetch limit rows and return the survivors, leaving callers unable to tell “end of data” from “filtered”, and could not fix COUNT at all.

pub async fn list_deleted_filtered_scoped( &self, pagination: PaginationParams, filters: Option<&HashMap<String, String>>, company: Option<Uuid>, ) -> Result<PaginatedResult<T>, Error>

where T: EntityRepoMeta + Send + Sync,

Paginate soft-deleted entities, fenced to company.

/trash is the worse leak of the two: it serves rows whose owners were told the data is gone. Same fence, same fail-closed contract.

pub async fn list_deleted_filtered( &self, pagination: PaginationParams, filters: Option<&HashMap<String, String>>, ) -> Result<PaginatedResult<T>, Error>

where T: EntityRepoMeta + Send + Sync,

Paginate soft-deleted entities with filter support.

pub async fn find_by_id(&self, id: &str) -> Result<Option<T>, Error>

Find an active (non-deleted) entity by primary key.

pub async fn find_all(&self) -> Result<Vec<T>, Error>

Return all active (non-deleted) entities.

pub async fn update(&self, id: &str, entity: &T) -> Result<Option<T>, Error>

where T: Serialize + Send + Sync,

Full update — skips silently if the record is already soft-deleted.

pub async fn delete(&self, id: &str) -> Result<bool, Error>

Soft-delete an entity (sets metadata.deleted_at).

pub async fn count(&self) -> Result<u64, Error>

Count active (non-deleted) entities.

pub async fn exists(&self, id: &str) -> Result<bool, Error>

Return true if an active entity with the given ID exists.

pub async fn list_paginated( &self, pagination: PaginationParams, ) -> Result<PaginatedResult<T>, Error>

Paginate active entities (most-recent-first by ID).

pub async fn soft_delete(&self, id: &str) -> Result<bool, Error>

Set metadata.deleted_at to NOW() (soft delete).

pub async fn restore(&self, id: &str) -> Result<Option<T>, Error>

Remove deleted_at from metadata, restoring the entity.

pub async fn list_deleted( &self, pagination: PaginationParams, ) -> Result<PaginatedResult<T>, Error>

Paginate soft-deleted entities (trash view).

pub async fn empty_trash(&self) -> Result<u64, Error>

Permanently delete all soft-deleted rows (empty trash).

pub async fn find_deleted_by_id(&self, id: &str) -> Result<Option<T>, Error>

Find a soft-deleted entity by primary key.

pub async fn permanent_delete(&self, id: &str) -> Result<bool, Error>

Permanently delete a soft-deleted entity by primary key.

pub async fn count_active(&self) -> Result<u64, Error>

Count active (non-deleted) entities.

pub async fn count_deleted(&self) -> Result<u64, Error>

Count soft-deleted entities.

pub async fn bulk_soft_delete(&self, ids: &[String]) -> Result<u64, Error>

Soft-delete many active rows atomically.

pub async fn bulk_restore(&self, ids: &[String]) -> Result<Vec<T>, Error>

Restore many soft-deleted rows atomically, returning the restored rows.

pub async fn bulk_permanent_delete(&self, ids: &[String]) -> Result<u64, Error>

Permanently delete many soft-deleted rows atomically.

pub async fn restore_all(&self) -> Result<Vec<T>, Error>

Restore every soft-deleted row, returning the restored rows. A single UPDATE ... RETURNING is atomic, and the returned rows let the service layer emit a Restored event per entity.

pub async fn bulk_update(&self, entities: &[T]) -> Result<Vec<T>, Error>

where T: Serialize + Send + Sync,

Update many active rows atomically. Every entity must reference an existing active (non-soft-deleted) row or the whole batch is rolled back.

Trait Implementations

impl CrudRepository<PosInvoice> for PosInvoiceRepository

fn fetch_related_json<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, table: &'life1 str, ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Vec<Value>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Hydrate ?include= relations: fetch rows from table by id list, as JSON (raw row_to_json). table comes from EntityRepoMeta::relations() (generator-emitted), never client input. Default: no expansion. The Postgres-backed generated repos override this via impl_crud_repository!.

fn create<'life0, 'async_trait>( &'life0 self, entity: PosInvoice, ) -> Pin<Box<dyn Future<Output = Result<PosInvoice, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Create a new entity

fn find_by_id<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Find entity by ID (excluding soft-deleted)

fn find_by_id_including_deleted<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Find entity by ID (including soft-deleted, for trash operations)

fn update<'life0, 'async_trait>( &'life0 self, entity: PosInvoice, ) -> Pin<Box<dyn Future<Output = Result<PosInvoice, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update an existing entity

fn soft_delete<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Soft delete an entity

fn restore<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Restore a soft-deleted entity

fn hard_delete<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Permanently delete an entity

fn list<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, ) -> Pin<Box<dyn Future<Output = Result<(Vec<PosInvoice>, u64), RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List entities with pagination (excluding soft-deleted)

fn list_filtered<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<PosInvoice>, u64), RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List entities with pagination and filters (excluding soft-deleted)

fn list_filtered_with_info<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<PosInvoice>, PaginationInfo), RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

list_filtered, carrying the pagination info (cursor positions included) so the HTTP layer can surface keyset paging. Default: the tuple form with the cursor fields absent; the generated Postgres repositories override this with the real keyset walk.

fn table_name(&self) -> Option<&str>

Group and reduce entities under the same filters as list_filtered.

fn aggregate_filtered<'life0, 'life1, 'async_trait>( &'life0 self, spec: &'life1 AggregateSpec, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<AggregateResult, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn list_deleted<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, ) -> Pin<Box<dyn Future<Output = Result<(Vec<PosInvoice>, u64), RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List soft-deleted entities with pagination

fn count<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count all entities (excluding soft-deleted)

fn count_deleted<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count soft-deleted entities

fn bulk_create<'life0, 'async_trait>( &'life0 self, entities: Vec<PosInvoice>, ) -> Pin<Box<dyn Future<Output = Result<Vec<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Bulk create entities

fn empty_trash<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Permanently delete all soft-deleted entities

fn bulk_soft_delete<'life0, 'life1, 'async_trait>( &'life0 self, ids: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<u64, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Soft-delete many entities by id. Returns the number affected.

fn bulk_restore<'life0, 'life1, 'async_trait>( &'life0 self, ids: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<Vec<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Restore many soft-deleted entities by id. Returns the restored entities.

fn bulk_hard_delete<'life0, 'life1, 'async_trait>( &'life0 self, ids: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<u64, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Permanently delete many entities by id. Returns the number affected.

fn restore_all<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Restore every soft-deleted entity. Returns the restored entities.

fn bulk_update<'life0, 'async_trait>( &'life0 self, entities: Vec<PosInvoice>, ) -> Pin<Box<dyn Future<Output = Result<Vec<PosInvoice>, RepositoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update many entities atomically. Returns the updated entities.

fn exists<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, RepositoryError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Check if an entity exists by ID

impl Deref for PosInvoiceRepository

type Target = GenericCrudRepository<PosInvoice>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.