PRD: Sale Channels

Module	Commerce	PRD ID	PRD-SC-001
Status	Ready to dev	FEAT	SC
Epic	—	Plane	BANA-1493
Date	2026-06-01	Version	v1.0
Packages	@nx/commerce	URD	SC
Surface	Client · Owner/MgrSale · POSBO · Ops
Owner	Phát Nguyễn

What a sale channel is

A merchant usually sells through several sale channels: dine-in, takeout, delivery. Each one operates differently - the takeout counter may pull stock from a different location than the dine-in area, print receipts on a different machine, or use a different print template. This PRD turns the sale channel into a real configuration unit.

Stock and print config now belong to each channel

Previously the channel was just a thin record: the stock location and print config lived at the merchant level, so two channels under the same merchant were forced to look identical. This increment moves the stock-pickup locations and terminal/print config fully onto each channel - each channel decides for itself which stock location to pull from, which terminal to print at, which print template to use, and config lookups run per individual channel instead of falling back to merchant-wide config.

One channel, from onboarding to deactivation

Onboarding creates default channels by industry: an F&B merchant gets Dine-in + Takeout, a retail merchant gets In-store + Online. A manager adds a new channel through the Edit-merchant screen or the standalone channel-management screen, then attaches a stock-pickup location and print config to it. To stop using a channel, the manager clicks Deactivate - but if the channel still has an in-flight order (one in Processing or Partially-paid status), the action is blocked immediately with a reason message; those orders have to be worked through first.

The easiest thing to get wrong

Deactivate and Delete share one condition, but not one consequence

Both Deactivate and Delete are blocked while the channel still has an in-flight order - the same guard, the same condition.

The consequence differs. Deactivate temporarily stops selling on the channel and it can be reactivated anytime. Delete removes the channel outright, cannot be undone, and cleans up that channel's product links.

1. Goals & Non-Goals

Goals

• Default channels created by industry right at onboarding, and channels managed on the Edit-merchant screen - where merchant info, categories, and sale channels are all saved together in a single action.
• Each channel can attach its own stock location(s) and carry its own terminal/print config.
• Each merchant has exactly one default sale channel.
• Deactivation is blocked while the channel still has active orders.

Non-Goals

• Redesigning the standalone channel-management screen - it already exists (list / create / edit); this increment only upgrades the configuration that those screens share.
• Parent-child channel hierarchy (e.g. splitting "Delivery" into "Grab", "Shopee") - URD-SC-006 is low priority, deferred for later.

2. Success Metrics

Metric	Target / signal
Channel-scoped config	100% of terminal/print lookups keyed to the individual channel (no fallback to merchant-wide config)
Onboarding coverage	Every onboarded merchant has at least one default channel
Slug integrity	No duplicate channel slugs within the same merchant
Order safety	Zero deactivations slip through while a channel still has active orders

3. Personas & Scenarios

Persona	Goal in this feature
Merchant owner	Have channels ready at registration; decide which stock location each channel pulls from and how it prints
Manager	Add/edit channels, attach stock locations, set the default channel, deactivate unused channels
Cashier	Sell against the right channel so stock is pulled from the right location and receipts print on the right machine with the right template

Core scenario: onboarding creates channels by industry → the manager adds new channels on the Edit-merchant screen or the standalone channel-management screen → attaches stock locations and print config to each channel → to stop using a channel, deactivates it (blocked if it still has active orders).

4. User Stories

#	As a	I want	So that
01	merchant owner	a default channel ready as soon as registration finishes	I can start selling right away
02	manager	to add several channels at once to a merchant that's already running, without re-registering	I can expand my sale channels without reconfiguring from scratch
03	manager	each channel to attach its own stock location	stock gets deducted from the right place
04	manager	terminal and print-template config to live on each channel	the takeout counter can print differently from the dine-in area
05	manager	to set one channel as default	the system picks the right channel automatically when none is specified
06	merchant owner	a channel with active orders to be undeactivatable	I don't leave a customer stranded mid-order

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Onboarding creates default channels by industry. • F&B gets Dine-in + Takeout. • Retail gets In-store + Online. • Other industries get none.	✅	URD-SC-001
FR-002	Channels are managed on the Edit-merchant screen: an item sent with details is updated, a new item is added, an item sent with only its identifier is removed. • All changes apply within one save. • A mid-save error leaves nothing changed.	✅	URD-SC-002
FR-003	Several channels can be added at once to an existing merchant via the Edit-merchant screen. The standalone channel-management screen creates one channel at a time.	✅	URD-SC-003
FR-004	Channel slug is unique within the same merchant. The slug auto-generates from the name and can be edited before saving.	✅	URD-SC-004
FR-005	A unique system identifier is generated on creation and cannot be edited.	✅	URD-SC-005
FR-006	A channel has three statuses: Active / Deactivated / Archived. Deactivating is blocked while the channel still has an in-flight order - one in Processing or Partially-paid status (Draft, Completed, Cancelled do not count).	✅	URD-SC-007
FR-007	Up to 50 stock locations can be attached to a channel. • Attachment order is the stock-pickup priority order (the first location is picked first). • A location can be attached to a channel at most once.	✅	URD-SC-002
FR-008	Terminal and print-template config live on the channel. Config lookups run per individual channel.	✅	URD-SC-002
FR-009	Each merchant has 1 default sale channel. When another channel is designated as default, the old one automatically loses the default flag and it transfers to the new channel.	🔶	URD-SC-008
FR-010	Deleting a channel requires the channel to have no in-flight orders (the same condition as Deactivating), for both the delete button on the channel-management screen and removing a channel on the Edit-merchant screen. On deletion, the channel's product links are cleaned up.	🔶	URD-SC-009

5.1 Acceptance Criteria

• Onboard an F&B merchant → Dine-in + Takeout channels are ready; onboard a Retail merchant → In-store + Online; every channel has an identifier and a slug.
• On the Edit-merchant screen: add 2 new channels, edit 1 channel, remove 1 channel in the same save → all four changes apply together; force a mid-save error → nothing changes.
• Create a channel with a duplicate slug in the same merchant → rejected.
• Attach the same stock location to a channel a second time → rejected; attach a 51st location → rejected.
• A channel with active orders → clicking Deactivate is blocked with a message; close out all orders and it can be deactivated.
• Channel A is currently default, set channel B as default → B becomes default and A automatically un-defaults; there is always exactly one default channel.
• Delete a channel with no in-flight orders → deletion succeeds; that channel's product links are cleaned up.
• Clicking the "set as default channel" button makes the selected channel the default, and the previous one automatically un-defaults.
• Deleting a channel with in-flight orders is rejected - on both the channel-management screen and the Edit-merchant screen.

6. Non-Functional Requirements

Aspect	Requirement
Data integrity	The channel and its attached stock locations are saved in one write; there is always exactly one default channel per merchant (enforced at the data layer)
Tenancy & authorization	All operations stay within the user's own merchant; controlled by sale-channel permissions (setting the default channel has its own permission)
Order safety	A channel with an in-flight order cannot be deactivated or deleted (checked before the status change or the delete)
i18n	Channel labels display bilingually (English / Vietnamese)

7. UX & Flows

Key screens: the channel-management screen (a 2-column list - name and status, both filterable; create; edit) sharing one form - the form splits into 2 tabs: General info (bilingual name, auto-generated slug, status, attached stock locations) and Print template (shown only when editing a channel, hidden on create); the sale-channel section inside the Edit-merchant screen; and the channel selector at the point of sale so the cashier sells against the right channel.

8. Data & Domain

Entity	Role
Sale channel	Bilingual name, per-merchant unique slug, system identifier, status (3 values), default flag, terminal & print config
Channel-location link	Connects a channel to up to 50 stock locations, order is stock-pickup priority
Channel configuration	Configuration looked up per individual channel

Conceptual only - full schema lives in the commerce domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	The Edit-merchant screen (URD-MER)	one of the paths for managing channels.
02	Onboarding (URD-ORG)	default channels are created together with the merchant.
03	Inventory locations (Inventory)	a location must exist before it can be attached to a channel.

Assumptions

#	Assumption	What breaks if it is wrong
01	The merchant exists (or is being created in the same save) before channels are managed.	If the merchant does not yet exist and is not being created in the same save, channel management has nothing to attach to and the operation cannot proceed.

10. Release Plan & Criteria

Aspect	Plan
Phase	P1 (foundation) - see URD feature catalog
Rollout	All merchants; no feature flag
Migration	Backfill so existing merchants each get a default channel; terminal & print config moved onto the channel
Release criteria	All of §5.1's acceptance criteria pass on real merchants
Monitoring	Channel count per merchant, deactivation-block count, per-channel config-lookup errors

References

• URD: Commerce - Sale Channels
• Related PRD: Organizer & Merchant
• Module: Commerce - URD
• Developer: @nx/commerce · domain model

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Deactivating a channel mid-sale	The guard rejects it while the channel still has active orders
02	Duplicate stock-location attachment on a channel	Each channel-location pairing is unique, duplicate attachment is rejected
03	Groundwork left for channel hierarchy: a parent-channel column and a filter that hides child channels already sit in the code	When channel hierarchy (URD-SC-006) is built, this filter must be re-checked, so a child channel isn't silently hidden from the list without anyone noticing

Frequently Asked Questions

#	Question	Answer
01	Where do I manage channels?	Two places: the standalone channel-management screen (creates one channel at a time, with both config tabs), or the sale-channel section inside the Edit-merchant screen, where several channels can be added at once in one save.
02	Does each channel have its own stock location?	Yes - a channel can attach up to 50 stock locations, and the attachment order is the stock-pickup priority order. Two channels under the same merchant can pull stock from two different locations.
03	What is the default channel used for?	When an operation doesn't specify a channel, the system uses the merchant's default channel. Each merchant always has exactly one default channel - setting a new one automatically un-defaults the old one.
04	Why can't I deactivate a channel?	Because it still has active orders. Close or reassign those orders first, then deactivate it.
05	How is deactivating different from deleting a channel?	They share the same condition: both are blocked while the channel still has an in-flight order. They differ in consequence: deactivating (Deactivated) temporarily stops selling on the channel and it can be reactivated; deleting removes the channel outright and cleans up that channel's product links.
06	Is parent-child channel hierarchy supported yet?	Not yet - it's low priority (URD-SC-006), deferred for later.