Offer Cart (CAP-4002)

Plan, not built · builds on branch CAP-4002-dev · backendApi, capExpertApp, dbMigrations · 16 Oct 2026

On this page

• Decisions
• How it works
• Why a new table, and no parent
• Database
• API
• The cart page
• Other front-end changes
• Edge cases
• Scale: 1k vendors, 1M rows
• Build order
• Checks
• Still to confirm

Decisions

How it works

Vendor

1. Opens a listing and clicks Add to Cart, or ticks several on Browse Market and clicks Add to cart.
2. Opens the cart from the header cart icon: one card per facility, each with its items.
3. On a card, sends for all items or just the ticked ones. The existing offer dialog asks for one price.
4. The offer is created, and those items leave the cart in the same transaction.

Admin

1. Picks the vendor when adding (the same vendor picker as Send Offer).
2. Opens the Offer Cart tab in the marketplace tabs, and selects a vendor before anything loads.
3. Sends from a card exactly as a vendor does. The offer goes out as that vendor, with no second vendor pick.

Why a new table, and no parent

Not the purchase cart's cart_items

The purchase cart fits structurally (one carts row per buyer and seller), but the code treats every cart_items row as a facility reserving a listing to buy it. A vendor's cart row would be read the same way:

A type column would need a filter in every one of the ~40 API files that read these tables, and missing one fails silently. Reuse also gains nothing: everything on the carts row (shipping quote, PO, bill of sale, self-shipping) is checkout state an offer never uses.

No parent table

• No cart-level state. The price is typed into the dialog at send time and saved on the offer.
• The grouping can always be worked out from existing data. The vendor is vendor_id, and the facility is the listing's account_id, joined when the cart is read, so it never goes out of date.
• Once sent, a parent already exists: the grouped offer's thread (marketplace_offer_associations) with its marketplace_offer_items.

Add a parent only if something per cart or per facility needs storing, such as a draft price, several named carts per vendor, or a cart status. That is an additive migration later.

Database (dbMigrations), one migration

CREATE TABLE marketplace_offer_cart_items (
  id             SERIAL PRIMARY KEY,
  vendor_id      INTEGER NOT NULL REFERENCES accounts(id)    ON DELETE CASCADE,
  marketplace_id INTEGER NOT NULL REFERENCES marketplace(id) ON DELETE CASCADE,
  created_by     INTEGER NOT NULL REFERENCES users(id),
  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  CONSTRAINT uq_marketplace_offer_cart_items_vendor_listing UNIQUE (vendor_id, marketplace_id)
);
CREATE INDEX idx_marketplace_offer_cart_items_marketplace_id ON marketplace_offer_cart_items (marketplace_id);

• The unique key stops duplicates, and serves every per-vendor query because vendor_id is its first column.
• The marketplace_id index keeps listing deletes and the clean-up job fast on a large table.
• The migration's down drops the table. The file name uses the real current timestamp.

API (backendApi, primary role)

New files

• shared/entity/marketplace-offer-cart-item.entity.ts, linked to its listing (marketPlaceData), its vendor (vendorDetails) and the user who added it (createdByUser). It is registered in the entity index, database.providers.ts and providers.constant.ts, as MarketplaceOfferItems was.
• primary/modules/vendor-offers/offer-cart/: controller, service, DTOs, and the cart SQL with a spec. Registered in vendor-offers.module.ts.
• The controller has its own offer-cart route prefix, like grouped-offers (under vendor-offer/, the /:marketplaceId route would capture these paths), with the same FeatureGuard and @RequireFeature(MARKETPLACE.ROOT).

Limits

Whose cart a request touches

One helper, with the same rule as Browse Market's offerVendorId():

• a vendor always gets its own account, whatever vendorId it sends;
• an admin must name the vendor;
• anyone else gets 403.

Endpoints

How GET builds a page (always limited to the selected vendors)

1. One page of facility cards. Each card is one vendor and facility pair, ordered by vendor name then facility name. The grouping and counting run in SQL, and count is the number of cards.
2. The items on those cards only. Each item has its listing and inventory (through the existing getInventoryInclude), the same childCount the purchase cart computes, and an offerable flag. fairMarketValue is included only when checkNotVendorAndVendorLevel(reqUser) passes, the same check as Browse Market's list. offerableCount is computed here, for these cards only.
3. The vendor and facility accounts on the page, through getAccountInclude: name, default address, primary user and contact.

The service then nests the rows into that shape.

Changes to existing code

The cart page: marketplace/offer-cart

It lives at modules/market-place/offer-cart/. Each area maps to the current purchase cart (modules/cart):

Dark mode and phone widths, like the existing page.

Shared pieces, so it really matches

• Two display blocks move out of cart.component.html into common/components/cart/, and the purchase cart uses them with identical output:
  • app-cart-item-details: the left side of an item row.
  • app-cart-party: name, city/state, contact name, email and phone with copy buttons.
• The thumbnail helper, the components modal, app-button, the shared checkbox, cs-filter-toolbar and the confirmation dialog are reused as they are.

The trade-off: the purchase cart's template changes structure but not output. The alternative is copying about 300 lines of markup that would drift apart.

Sending from a card

• The cart page plugs into MarketplaceGroupedOffer (GroupedOfferHost), as Browse Market and My Listing already do, and calls makeGroupedOfferFor(rows). It gets the same address check, the same dialog and the same send-offer call.
• MarketplaceGroupedOffer gains two small options:
  • a fixed vendor, taken from the card, so an admin isn't asked to pick again and the address check runs for that vendor;
  • one item allowed, which goes out as an individual offer. The API already does this for one id.
• After a send, the page reloads and the header count refreshes.

Other front-end changes

Edge cases

Scale: 1k vendors, 1M rows

Every query is scoped to the selected vendor through the unique key's first column, so a vendor's speed doesn't depend on the table's total size. With the plan's fixes in place:

Without the fixes, an admin opening the page with no vendor selected would group all 1M rows and run the offerable check a million times, taking seconds per load. Listing deletes would also scan the whole table. These figures are estimates from the query shapes; Checks lists how to measure them.

Build order (the app works after every step)

1. Migration, entity and the three endpoints, plus a spec for the cart SQL.
2. Remove-after-send, cartItemsCount, inOfferCart, and the clean-up job.
3. Regenerate swagger and restart the front end.
4. Move app-cart-item-details and app-cart-party out, and switch the purchase cart to them with no visible change.
5. The offer cart page, including sending from a card.
6. offer-cart-actions.ts and Add to Cart in the detail view.
7. Browse Market and My Listing: the bulk button becomes Add to cart.
8. The vendor header icon and the admin Offer Cart tab.

Commits go on CAP-4002-dev: one in dbMigrations, and one or two each in backendApi and capExpertApp.

Checks

• Run the migration up and down on the local database.
• API: typecheck, lint:layering, and the specs.
• Swagger before and after, per role: the only additions are the three offer-cart routes and inOfferCart, and nothing is removed.
• Front end: ng build with the raised heap. No browser.
• Scale: insert 1M synthetic rows in a transaction on the local database, run EXPLAIN ANALYZE on the count, add, both page reads and a listing delete, then roll back. This needs database access.
• Confirm that cart_items.marketplace_id has an index. The offerable check looks it up for every item, and no migration was found that creates one.

Still to confirm