PRD: Category Template Configuration (Back Office)

Module	Commerce	PRD ID	PRD-CAT-002
Status	Ready to dev	FEAT	CAT · BANA-1437
Epic	BANA-1337	Plane	BANA-1769
Date	2026-07-07	Version	v1.1
Packages	@nx/commerce	URD	CAT
Surface	BO · Ops
Owner	Tinh Nguyễn

TL;DR

• Operations authors the starter-category list for each industry from the Back Office - bilingual name, description, icon, and color per category - with no code change and no deploy.
• For F&B and Retail, the list is split further by sector, using a shared multi-sector picker.
• Onboarding copies the list matching a new F&B or Retail merchant's industry/sector onto it, once, as its own independent, editable categories - not a live reference.
• A Merchant Override tab lets an operator author a category list scoped to one specific, already-onboarded merchant (🚧 not yet consumed by onboarding or category logic).
• Two Back Office screens - Category Template and Onboarding Templates - both read and write this same configuration today; this PRD targets consolidating them into a single entry point, retiring the redundant screen (🚧 not yet built).

1. Context & Problem

Every merchant onboards with a starting set of categories matching its industry: URD-ORG-017 seeds it at onboarding, URD-MER-018 ties it to the merchant's sector, and the Retail Business Type increment confirmed it live for F&B and all 7 retail sectors.

Before this increment, that starter list was hardcoded in a seed script - changing an icon, renaming a category, or adjusting what a sector receives required an engineer to edit code and ship a deploy. URD-BOP-002 calls for the Back Office to let Operations configure this directly. This PRD specifies the capability that replaces the hardcoded seed: Operations authors the starter-category list per industry (and sector, for F&B and Retail) as ordinary configuration data.

This is a distinct mechanism from system categories (URD-CAT-006) - shared, ownerless categories every merchant sees read-only, live. A starter-category list is copied once, at onboarding, and becomes the merchant's own, fully editable data from that point on. The two are unrelated.

2. Goals & Non-Goals

Goals

• Operations authors the starter-category list for each industry (F&B, Retail, Ticket) from the Back Office - bilingual name, description, icon, and color per category.
• For F&B and Retail, the list is split by sector, using the same multi-sector picker shared with the sale-channel template.
• The category form reuses the icon-color picker from the merchant Categories screen (URD-CAT-004).
• Onboarding copies the resolved industry/sector list onto a new F&B or Retail merchant as its own categories, once, at signup.
• An operator authors a category list scoped to one specific merchant, independent of the shared industry/sector list.
• Consolidate the Category Template and Onboarding Templates screens into one - retire the redundant screen/route, leaving a single Back Office entry point for category-template configuration (see FR-006).

Non-Goals

• Multiple named, versioned templates to choose between - there is one shared list per industry/sector, not a library of alternatives with their own status.
• Reordering or disabling individual starter categories - items are added or removed only.
• Seeding categories for industries beyond F&B and Retail - Operations can author content for other industries; onboarding does not copy it today (FR-003).
• The Merchant Override tab changing what a specific merchant sees - built in the Back Office, not yet consumed by onboarding or category logic (FR-004, §11).
• System categories (URD-CAT-006) - a separate, unrelated mechanism.
• Bulk Excel import - covered by the broader bulk-import capability (URD-BOP-004) if extended here.

3. Success Metrics

Metric	Target / signal
No-code changes	Operations adds, edits, or removes a starter category without an engineer or a deploy
Onboarding parity	An F&B or Retail merchant's starting categories exactly match the authored list for its industry/sector at signup
Copy isolation	Editing the shared list produces zero changes on a merchant that has already onboarded

4. Personas & Scenarios

Persona	Goal in this feature
Operations team	Maintain each industry's starter categories without engineering support
Owner / operator onboarding a merchant	Receives their industry/sector's authored categories as a starting point

Core scenario: an Operations user opens the Back Office, selects the Retail industry, adds the Grocery sector, and adds categories to it - name, icon, color. Any merchant that subsequently onboards as Retail/Grocery receives exactly those categories as its own, ready to edit further.

5. User Stories

• As Operations, I want to author the starter categories for an industry/sector myself, so a new merchant's starting catalog reflects real category structure instead of a hardcoded seed.
• As Operations, I want the category form to use the same icon-color picker as a merchant's own Categories screen, so authoring is familiar.
• As Operations, I want to know which industries onboarding actually seeds, so I focus authoring effort where it takes effect.
• As Operations, I want editing the shared list to never affect a merchant that already onboarded, so I can improve it safely.
• As Operations, I want to author a category list for one specific merchant, so I can support a merchant that needs a different starting set than its industry's default.

6. Functional Requirements

#	Requirement	Status	URD ref
FR-001	The screen opens on an industry chip picker: F&B, Retail, Ticket (Other hidden). • F&B and Retail are the only sector-bearing industries: selecting either exposes an "add sector" action that opens a checklist of that industry's sectors, filtered to exclude ones already added. • Each added sector becomes an expandable card showing its item count, with a delete action. • Ticket (and any other non-sectored industry) presents a single flat item list instead of sector cards. • Two Back Office screens present this picker today - the original Category Template screen and the newer Onboarding Templates screen, which unifies category and sale-channel authoring in one page; both read and write the same underlying configuration (see §11 for the consolidation plan).	✅	URD-CAT-008
FR-002	Within a sector (or the flat list), Operations adds items one at a time. • Required: a bilingual name. Optional: a bilingual description. • Icon + color chosen through the picker shared with the merchant Categories screen, with suggested icons available up front and full-library search behind it. • Items are added or removed; there is no reordering and no per-item enable/disable. • Saving writes directly to the configuration onboarding reads - there is no draft or staging step.	✅	URD-CAT-008 · URD-CAT-004
FR-003	At merchant creation, the system resolves the starter-category list for the merchant's industry and copies it onto the merchant once, as independent category records. • The list is matched against the sector(s) the merchant selected, and categories appearing in more than one matching sector are de-duplicated. • Wired for F&B and Retail merchants only. • Other industries do not receive categories at onboarding, regardless of whether Operations has authored a list for them.	🔶	URD-CAT-009 · URD-ORG-017 · URD-MER-018
FR-004	The Onboarding Templates screen's second tab lets an operator select a specific, already-onboarded merchant and author a category list scoped to that merchant (a configuration record tagged to the merchant rather than shared globally). • The authoring UI is complete and the save succeeds. • No onboarding or category logic reads a merchant-scoped record today, so this has no observable effect on the merchant - wiring a consumer for this record is open work (see §11).	🚧	URD-CAT-011
FR-005	Reading and saving the list requires the same permission used for configuration management generally.	✅	-
FR-006	Confirm Onboarding Templates (Category tab - System Template/Merchant Override - plus the Sale Channel tab) covers every operation the standalone Category Template screen provided, then retire that screen from the Back Office. • Also retire the standalone Sale Channel Template screen, if in the same scope; remove the unused menu entry and route for both. • From that point, Onboarding Templates is the sole entry point for category-template configuration - no more two screens editing the same shared configuration.	🚧	URD-CAT-012

6.1 Acceptance criteria

• Add the Grocery sector under Retail, add three categories with icons/colors, save, reload the screen → the same three categories are present.
• Onboard a new merchant selecting Retail + Grocery → the merchant's own category list matches those three categories exactly (name, icon, color).
• Author categories under the Ticket industry, then onboard a Ticket merchant → the merchant receives no categories (FR-003).
• Edit a category's icon in the shared Retail/Grocery list after a merchant has already onboarded with it → the already-onboarded merchant's own category is unchanged.
• Author and save a category via the Merchant Override tab for a specific merchant → that merchant's Categories screen is unaffected (FR-004).
• Confirm Onboarding Templates covers the standalone Category Template screen's functionality → retire the Category Template screen (and Sale Channel Template) from the Back Office; no standalone menu entry or route points to them anymore (FR-006).

7. Non-Functional Requirements

Aspect	Requirement
Data integrity	Onboarding copies the shared list into independent category records - editing the shared list afterward cannot reach an already-onboarded merchant
Tenancy & authz	The shared list has no merchant scope; access is gated by the general configuration read/update permission
Consistency	Exactly one shared list resolves per industry/sector - there is no draft or staging step, so a save takes effect on the very next onboarding
i18n	Category names and descriptions are bilingual (EN/VI)

8. UX & Flows

How Operations authors the shared starter-category list:

How onboarding consumes it:

The screens live in the Back Office "System Configuration" section, alongside Tax Group Configuration.

9. Data & Domain

Concept	Role
Category-template configuration	Shared, system-scoped record: industry → sector → list of items (name, description, icon, color)
Merchant-override configuration	Same shape, scoped to one specific merchant via the Merchant Override tab; not yet read by onboarding or category logic
Merchant category	The result of copying the shared list onto a merchant at onboarding - independent from that point on

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

10. Dependencies & Assumptions

Depends on

• Sale Categories (PRD-CAT-001) - the icon-color picker reused for starter-category items.
• Onboarding (URD-ORG-017, URD-MER-018) - the step that copies the shared list onto a new merchant.
• Retail Business Type (PRD-RTL-001) - owns the sector list this screen's F&B/Retail sector picker draws from.

Assumptions

• The merchant's industry/sector is decided by onboarding (Client or BO) before the category-copy step runs.
• An industry onboarding does not copy from (Ticket, Other) results in no categories seeded, regardless of authored content.

11. Risks & Open Questions

Risk / question	Mitigation / status
The Merchant Override tab persists data that no consumer reads, which can lead an operator to believe they changed a specific merchant's categories	Wire onboarding/category logic to read merchant-scoped records, or remove the tab until it does - decision pending
The Category Template and Onboarding Templates screens both edit the same shared configuration, with neither marked authoritative	🚧 Now a goal of this PRD (FR-006) - retire the Category Template and Sale Channel Template screens once Onboarding Templates is confirmed to cover their functionality
Ticket (and any future non-F&B/Retail) merchants never receive seeded categories, even when Operations authors a list for them	Confirm whether this is intentional or should be extended - open question
Saves take effect on the very next onboarding immediately, with no draft/staging step	Acceptable given current edit frequency; revisit if edit mistakes reach real merchants

12. Release Plan & Criteria

Aspect	Plan
Phase	P2 - part of the Backoffice Portal epic's June configuration slice
Rollout	Back-Office operators with the configuration permission; no feature flag
Migration	A one-time seed migration (commerce-0007-seed-category-templates) authored the initial F&B + 7 retail-sector lists as configuration data, matching the previous hardcoded seed
Launch criteria	All §6.1 acceptance criteria pass, except items marked 🚧/🔶 (non-F&B/Retail seeding, Merchant Override consumption, screen consolidation under FR-006) - these are built as part of this same PRD
Monitoring	Category-list edit volume; onboarding category-copy success rate for F&B/Retail

13. FAQ

Is this a library of named templates to pick between? No - there is one shared starter-category list per industry, split by sector for F&B and Retail.

Does editing the Merchant Override tab change a merchant's categories? Not today - no onboarding or category logic reads a merchant-scoped record yet (FR-004).

Does editing the shared list change a merchant that already onboarded? No - it is copied once, at onboarding; a merchant's categories are its own from that point on.

Which Back Office screen is authoritative - Category Template or Onboarding Templates? Onboarding Templates - this PRD targets consolidating the two into one (FR-006), retiring the Category Template screen (and Sale Channel Template) from the Back Office once Onboarding Templates is confirmed to cover their functionality. Until that consolidation lands, both still edit the same configuration (§11).

Will a Ticket merchant receive categories authored for the Ticket industry? Not today - onboarding copies categories only for F&B and Retail merchants (FR-003).

Is this the same as a "system category" (URD-CAT-006)? No - system categories are shared and read-only across every merchant, live. A starter-category list is copied once into a merchant's own, editable categories.

References

• URD: Commerce - CAT Categories · BOP Backoffice Portal · ORG · MER
• Related: PRD-CAT-001 - Sale Categories · PRD-RTL-001 - Retail Business Type · PRD-BOP-001 - Merchant Onboarding · PRD-GRP-001 - Tax Group Configuration (same "BO-authored config" shape)
• Module: Commerce - URD · Roadmap: Phase 2 - By Month
• Developer: @nx/commerce