Add an item to the session with snapshot (transaction-based). This is called when initializing the session, not during scanning.

Add multiple leftover items to an existing stock opname session. Only adds items that match the session's scope criteria.

Parameters

• session_id: The UUID of the stock opname session
• item_ids: List of item UUIDs to potentially add
• user: The user performing the operation

Returns

• on success
• on failure

Admin completes a librarian's assignment by assignment ID (Super Admin only).

Manually complete a librarian's work by admin.

Check if all assigned librarians have completed their work.

Approve a stock opname session.

Returns {:ok, session} immediately after marking the session as "applying". The actual bulk item updates (Steps 1-3) run in a supervised background task so the caller is never blocked.

Subscribers on the topic "stock_opname:session:<id>" will receive either:

• {:session_approved, %Session{}} on success
• {:session_approval_failed, reason} on failure

Use subscribe_session/1 to subscribe before calling this function if you need real-time completion feedback in a LiveView.

Assign a single librarian to an existing session. Only allowed for sessions in 'draft', 'initializing', or 'in_progress' status.

Assign librarians to a session. Creates LibrarianAssignment records for each user.

Cancel a librarian's work completion and reopen their session.

Cancel a stock opname session.

Mark an item as checked with changes recorded in JSONB.

Parameters

• session: The stock opname session
• opname_item_id: The ID of the stock_opname_item record
• changes: Map of changes found by librarian, e.g. %{"status" => "damaged", "condition" => "poor"}
• scanned_barcode: Optional barcode scanned by librarian
• notes: Optional notes about the check
• user: The librarian checking the item

Returns

• on success
• on failure

Check an item with collection updates during a stock opname session.

This function marks the item as checked and can update both item fields and collection metadata (title, author).

Parameters

• session: The stock opname session
• opname_item_id: The ID of the stock_opname_item record
• item_changes: Map of item field changes, e.g. %{"status" => "damaged"}
• collection_changes: Map of collection changes, e.g. %{"title" => "New Title", "author" => "Author Name"}
• notes: Optional notes about the check
• user: The librarian checking the item

Returns

• on success
• on failure

Complete a librarian's work session.

Complete a stock opname session (in_progress → pending_review). Flags unscanned items as missing within the session scope. Only Super Admin can complete sessions.

Count the number of items currently added to a session.

Creates a new stock opname session (Super Admin only).

Examples

iex> create_session(%{title: "Jan 2026 Inventory", ...}, admin_user)
{:ok, %Session{}}

Delete a stock opname session. Only allowed for 'approved' or 'cancelled' sessions.

Search for items by barcode, legacy_item_code, or item_code. Returns a list to handle duplicates.

Get librarian's progress in a session. Returns virtual assignment for super admins who aren't explicitly assigned.

Get a single stock opname session with all associations preloaded.

Get detailed report of all librarians' work in a session.

Get session review summary with detailed statistics.

Get session statistics.

Get a session without preloading items (for performance). Use this when you don't need the items list.

List librarians available for assignment to a session. Returns users with eligible staff roles who are not suspended, not already assigned to the session, and (if not super_admin) from the same node.

List items with changes for a session. Optimized query with database-level filtering.

List items with changes with pagination.

List missing items for a session. Optimized query with database-level filtering. Missing items are tracked by changes->>'availability' = 'missing'.

List missing items with pagination.

List recent checked items for a specific user with limit. Optimized query that limits at database level to avoid loading all items.

List session items filtered by check status.

List session items with pagination.

Get all librarians assigned to a session with their user details.

List stock opname sessions with pagination and filters.

Filter options:

• :status - Filter by session status
• :node_id - Filter by node
• :created_by_id - Filter by creator
• :from_date - Filter sessions created after this date
• :to_date - Filter sessions created before this date
• :user - Filter sessions the user can access (based on node membership)

List sessions pending review (Super Admin).

Recalculate and update session counters based on actual item states. Useful for fixing counter drift or after manual database updates.

Reject a stock opname session.

Remove a librarian from an existing session. Only allowed for sessions in 'draft', 'initializing', or 'in_progress' status. Cannot remove librarians who have completed their work.

Request revision on a session (send back to librarians).

Resets the session to "in_progress" and resets all librarian assignments back to "in_progress" so they can re-scan items. Also clears completed_at since the session is no longer complete.

Reset a session stuck in the "applying" state back to "pending_review".

Use this when the background approval task crashed without completing the rollback (e.g. a server restart during a long-running bulk update). The session will be returned to "pending_review" so the admin can retry approval.

Start a librarian's work session.

@doc """ Start a stock opname session (draft → in_progress). Only Super Admin can start sessions. Cannot start if status is "initializing".

Subscribe to real-time updates for a specific stock opname session.

Messages you will receive:

• {:session_approved, %Session{}} — background approval completed
• {:session_approval_failed, reason} — background approval failed

Update a stock opname session.