URD: Commerce

Module	CORE-03	Version	v0.4
Status	Built	Date	2026-05-30

1. Purpose

Commerce lets a business owner stand up and run their business structure: a single Organization (the brand) and one or more Merchants (the legal point-of-sale units), each with its own sale channels and product categories. The module delivers a one-step onboarding that creates the whole structure atomically, plus full lifecycle management of every entity afterwards.

2. Scope

Included	Excluded
Organization creation via onboarding	Employee lifecycle & login (→ User Management)
Organization profile, hierarchy, settings, attachments	Role/permission definition (→ Permissions)
Merchant creation (single, batch, aggregate)	Product catalog content (→ Products)
Business-type classification	Stock levels (→ Inventory)
Sale-channel management	Order / checkout processing (→ Orders)
Category management with add-on flag	Payment processing (→ Payment)
Per-merchant deletion policy	E-invoice issuance (→ Tax & Invoice)
Encrypted merchant configuration	Technical API specifications (→ developer docs)
Role-based data filtering

3. Definitions

Term	Definition
Organization	Top-level virtual brand entity. Parent container for merchants, users, and devices. Carries branding, not legal identity.
Merchant	A physical/legal point-of-sale unit under an organization where transactions occur. Holds tax info, invoice profile, and wallet.
Sale Channel	A selling channel within a merchant (e.g. dine-in, takeout, delivery). Supports hierarchy.
Category	A product grouping within a merchant. Can be flagged as add-on.
Business Type	Classification that drives the POS UI: DEFAULT, TICKET, FNB, THEATER.
Aggregate Operation	A single request that creates or updates a merchant together with its categories and sale channels, atomically.
Deletion Policy	Per-merchant configuration controlling cascade behavior on entity deletion.
Configuration	Encrypted key-value settings for a merchant (payment providers, integrations).
Slug	URL-friendly identifier. Globally unique for organizations; unique per organization for merchants; unique per merchant for sale channels.

4. Conceptual Model

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

5. Functional Requirements

One table per functional area. <AREA> codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).

5.1 Organization (ORG)

ID	P	Requirement
URD-ORG-001	M	User can create one organization via onboarding
URD-ORG-002	M	Onboarding atomically creates organization + default merchant + sale channels + access
URD-ORG-003	M	The creating user is automatically assigned as Owner
URD-ORG-004	M	Name (multilingual) and slug are required; all other fields optional
URD-ORG-005	M	A unique system identifier is generated on creation and is not editable
URD-ORG-006	M	Organization can be found by ID or by slug (cascading lookup)
URD-ORG-007	M	Owner can update organization profile
URD-ORG-008	M	Aggregate create/update supports file attachments
URD-ORG-009	S	Organization list/count is filtered by the user's role
URD-ORG-010	S	Organization can be deactivated (data preserved, reversible)
URD-ORG-011	S	Organization can designate a headquarter merchant
URD-ORG-012	S	Organization can be archived (permanently read-only)
URD-ORG-013	C	Organization can have child organizations (hierarchy)

5.2 Merchant (MER)

ID	P	Requirement
URD-MER-001	M	Default merchant created during onboarding
URD-MER-002	M	Owner can create additional merchants
URD-MER-003	M	Owner can batch-create multiple merchants
URD-MER-004	M	Owner can aggregate-create a merchant with categories + sale channels
URD-MER-005	M	Merchant slug is unique within the same organization
URD-MER-006	M	Merchant can be viewed with its channels and categories
URD-MER-007	M	Owner can update merchant information
URD-MER-008	M	Aggregate update: ID-only = delete, ID+data = update, no ID = create
URD-MER-009	M	Merchant can be found by ID or by slug (cascading lookup)
URD-MER-010	M	Merchant list is filtered by the user's role
URD-MER-011	M	Merchant count respects the same filtering as the list
URD-MER-012	S	Merchant can be deactivated (reversible)
URD-MER-013	S	Merchant can be archived (permanently read-only)
URD-MER-014	C	Merchant hierarchy (parent-child)
URD-MER-015	S	Explicit delete flag distinguishes "delete" from "leave unchanged" in aggregate update

5.3 Sale Channels (SC)

ID	P	Requirement
URD-SC-001	M	Default channel(s) created during onboarding
URD-SC-002	M	Channels managed as part of merchant aggregate operations
URD-SC-003	M	Channels can be batch-created for an existing merchant
URD-SC-004	M	Channel slug unique within the same merchant
URD-SC-005	M	A unique system identifier is generated on creation and is not editable
URD-SC-006	C	Channel hierarchy (parent-child)
URD-SC-007	S	Channels can be deactivated or archived

5.4 Categories (CAT)

ID	P	Requirement
URD-CAT-001	M	Categories managed as part of merchant aggregate operations
URD-CAT-002	M	Categories can be renamed via aggregate update without affecting their products
URD-CAT-003	M	Categories can be deleted via aggregate update (soft-delete)
URD-CAT-004	S	Category can be marked as add-on (and un-marked)

5.5 Deletion Policy (DEL)

ID	P	Requirement
URD-DEL-001	S	Each merchant has a configurable deletion policy
URD-DEL-002	S	strictCategoryDeletion: when true, blocked if category has linked products
URD-DEL-003	S	cascadeProductDeletion: when true, deleting a category cascades to its products
URD-DEL-004	S	Owner can view and update the deletion policy

5.6 Configuration (CFG)

ID	P	Requirement
URD-CFG-001	S	Merchants can store payment-provider credentials and integration settings
URD-CFG-002	S	Sensitive credentials are encrypted at rest
URD-CFG-003	S	Configurations are organized by group (system, table, integration)

5.7 Access (ACC)

ID	P	Requirement
URD-ACC-001	M	User access is managed via role-based policies (org-level or merchant-level)
URD-ACC-002	M	Employees can be assigned to specific merchants
URD-ACC-003	M	A user can be granted access to multiple organizations
URD-ACC-004	M	Owner sees only their own organization and merchants
URD-ACC-005	M	All list/count operations are filtered by the user's role (Admin bypasses)
URD-ACC-006	M	Owner can create, view, and update their organization
URD-ACC-007	M	Owner can create, update, and deactivate merchants
URD-ACC-008	M	Owner can manage channels and categories via aggregate operations
URD-ACC-009	M	Owner can assign an employee to a specific merchant
URD-ACC-010	M	Employee sees only assigned merchants
URD-ACC-011	M	Employee cannot access unassigned merchants
URD-ACC-012	M	A user with an unrecognized role is denied (no silent empty result)

6. Acceptance Criteria

AC-ORG-01: Onboarding is atomic

Given	When	Then
A new authenticated user with no organization	Onboarding completes with a valid name + slug	Organization (Activated) + default merchant + default channel(s) created; owner access granted; system & slug identifiers auto-generated
Any step fails	During onboarding	Entire operation rolls back — nothing persisted

AC-ORG-02: Slug uniqueness

Given	When	Then
An organization already uses slug "my-business"	Another user tries the same slug	Creation rejected — slug already in use

AC-MER-01: Aggregate create

Given	When	Then
An owner with an existing organization	Creates a merchant with categories + channels	Merchant, categories, channels all created atomically; identifiers generated
Any child is invalid	During aggregate create	Entire operation rolls back

AC-MER-02: Aggregate smart update

Given	When	Then
Child item with ID only	Aggregate update	Item deleted
Child item with ID + data	Aggregate update	Item updated
Child item without ID	Aggregate update	Item created

AC-DEL-01: Deletion policy

Given	When	Then
strictCategoryDeletion = true	Deleting a category that has products	Blocked
cascadeProductDeletion = true	Deleting a category	Its products are also deleted

AC-ACC-01: Role-based isolation

Given	When	Then
Owner A (Org X) and Owner B (Org Y)	Owner A requests organization/merchant data	Only Org X data returned; Org Y not visible
Employee assigned to Merchant X only	Requests merchant list	Only Merchant X returned

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	Organization must exist before creating merchants
C-02	Aggregate operations are atomic — all or nothing
C-03	All entities use soft-delete; nothing is physically removed
C-04	Slug uniqueness: global for organizations, per-org for merchants, per-merchant for channels
C-05	All operations require authentication
C-06	Payment credentials are encrypted at rest

Non-Goals

• Cross-organization access or sharing merchants between organizations
• Ownership transfer (Planned)
• Hard-delete of any entity
• Standalone sale-channel / category CRUD outside the merchant aggregate (Planned)

8. Version History

Date	Author	Description	Ver
2026-05-30	P. Nguyen	Migrated to module-docs convention; reconciled requirement IDs/areas with test cases	v0.4
2026-04-17	P. Nguyen	Merged Organization + Merchant into Commerce module	v0.3
2026-02-27	QE Assessment	QE findings	v0.2
2026-02-26	P. Do — Product Owner	Initial	v0.1