# `PhoenixKitWarehouse.DocRefs`
[🔗](https://github.com/BeamLabEU/phoenix_kit_warehouse/blob/0.4.0/lib/phoenix_kit_warehouse/doc_refs.ex#L1)

Resolves warehouse document UUIDs to human-readable labels and admin paths.

All functions come in single (ref) and batch (refs) variants to avoid N+1
queries when rendering index pages.

Returned maps have the shape:
  %{label: "#IO-N", path: "/admin/warehouse/internal-orders/<uuid>",
    uuid: "<uuid>", kind: :internal_order}

`label`, `uuid`, and `kind` are always present; `path` is always absolute.
`kind` is one of `:order`, `:sub_order`, `:internal_order`, `:supplier_order`,
`:goods_receipt`, `:goods_issue` — useful for grouping a resolved list by tier.
Functions return `nil` when the UUID is nil or the document does not exist.

# `goods_issue_ref`

Resolves a single goods issue UUID to a label/path map.
Returns `nil` when `uuid` is nil or not found.

# `goods_issue_refs`

Batch resolves a list of goods issue UUIDs.
Returns `%{uuid => ref_map}`.

# `goods_issue_refs_for_internal_order`

Returns all non-deleted goods issue refs where internal_order_uuid = the given uuid.
Returns a list of ref maps `[%{label, path}]`.

# `goods_receipt_ref`

Resolves a single goods receipt UUID to a label/path map.
Returns `nil` when `uuid` is nil or not found.

# `goods_receipt_refs`

Batch resolves a list of goods receipt UUIDs.
Returns `%{uuid => ref_map}`.

# `goods_receipt_refs_for_supplier_order`

Returns all non-deleted goods receipt refs where supplier_order_uuid = the given uuid.
Returns a list of ref maps `[%{label, path}]`.

# `internal_order_ref`

Resolves a single internal order UUID to a label/path map.
Returns `nil` when `uuid` is nil or not found.

# `internal_order_refs`

Batch resolves a list of internal order UUIDs.
Returns `%{uuid => ref_map}` (absent uuids are omitted).

# `order_ref`

Resolves a top-level order UUID to a label/path map.

Returns `nil` when `uuid` is nil, not found, or the record is a sub-order
(has a `parent_uuid`).

# `refs_for`

Resolves a list of source_ref maps to label/path maps.

Each element must have shape `%{"type" => type, "uuid" => uuid}` where
`type` is one of:
  - `"order"`          — host-registered order kind
  - `"sub_order"`      — host-registered sub-order kind
  - `"internal_order"` — warehouse internal order
  - `"supplier_order"` — warehouse supplier order
  - `"goods_receipt"`  — warehouse goods receipt
  - `"goods_issue"`    — warehouse goods issue

Returns a list of `%{label, path}` maps, omitting any that resolve to nil
(e.g. deleted or not-found documents).

# `sub_order_ref`

Resolves a sub-order UUID to a label/path map via `SourceKinds.resolve/2`.

Returns `nil` when `uuid` is nil or SourceKinds returns `:error` (no host
registered a `"sub_order"` resolver, or the document was not found).

# `sub_order_refs`

Batch resolves a list of sub-order UUIDs.
Returns `%{uuid => ref_map}`.

Note: resolves via individual `sub_order_ref/1` calls (one `SourceKinds.resolve/2`
per uuid) rather than a single batched query, due to the SourceKinds single-uuid
contract (Plan 2). Acceptable given typical list sizes; revisit in Plan 5 if
query count becomes a problem in practice.

# `supplier_order_ref`

Resolves a single supplier order UUID to a label/path map.
Returns `nil` when `uuid` is nil or not found.

# `supplier_order_refs`

Batch resolves a list of supplier order UUIDs.
Returns `%{uuid => ref_map}`.

# `supplier_order_refs_for_internal_order`

Returns all non-deleted supplier order refs where internal_order_uuid = the given uuid.
Returns a list of ref maps `[%{label, path}]`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*