URD: CRM

Module	CORE-09	Version	v0.4
Status	In-progress	Date	2026-05-30

1. Purpose

Define user-facing requirements for Customer Relationship Management — keeping customer profiles under a brand, rewarding repeat buyers with loyalty points, growing a newsletter mailing list, and capturing sales inquiries for follow-up. The goal is a single place to know who a business's customers are and to engage them.

2. Scope

Included	Excluded
Customer profiles scoped to the brand	Customer segmentation (Planned)
Customer-to-user account linking	Email / SMS campaign engine (Planned)
Loyalty point earning on completed orders	Point redemption on orders (Planned)
Newsletter subscribe / unsubscribe / statistics	Loyalty tiers (Planned)
Sales-inquiry capture and lifecycle	Lifetime-value analytics (Planned)
	Technical API specifications (see developer docs)

3. Definitions

Term	Definition
Customer	A person known to a brand; modelled as a User with the fixed customer role, with no sign-in credentials by default
Brand (Organization)	The virtual brand layer a customer belongs to; customers are scoped to it, not to a single point-of-sale unit
Loyalty points	A point balance a customer earns when an order completes payment
Conversion rate	The per-merchant factor that turns an order total into points
Subscriber	An email address opted into the newsletter, with topics, locale, and a unique unsubscribe token
Inquiry	A lead captured from the public site, tracked through a NEW → assigned → replied → converted/lost lifecycle

4. Conceptual Model

Conceptual only. Full schema lives in the developer docs: Identity domain model, Sale — Customer Points, and Outreach 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 Customer Profiles (CUS)

ID	P	Requirement
URD-CUS-001	M	Create a customer with name, at least one email and one phone
URD-CUS-002	M	Scope every customer to the brand (Organization)
URD-CUS-003	M	Update a customer's profile (name, emails, phones, birthday, locale)
URD-CUS-004	M	Soft-delete a customer, preserving history
URD-CUS-005	S	Staff see and manage only customers within their own brand
URD-CUS-006	S	Attach a customer to a sale order at checkout
URD-CUS-007	C	Promote a customer to a full sign-in user account

5.2 Loyalty Points (PNT)

ID	P	Requirement
URD-PNT-001	S	Award points when an order completes payment
URD-PNT-002	S	Compute the award as order total × the per-merchant conversion rate
URD-PNT-003	S	Track a running point balance per customer
URD-PNT-004	S	Award points at most once per order, even on retry (idempotent)
URD-PNT-005	C	Award no points when the rate is unset/zero or no customer is attached

5.3 Newsletter Subscribers (SUB)

ID	P	Requirement
URD-SUB-001	S	Subscribe by email with topics and locale
URD-SUB-002	S	Keep email globally unique among subscribers
URD-SUB-003	S	Unsubscribe via a unique one-click token link
URD-SUB-004	S	Resubscribe reactivates a deactivated subscriber (idempotent)
URD-SUB-005	S	View subscriber statistics — totals, monthly new, counts by status

5.4 Sales Inquiries (INQ)

ID	P	Requirement
URD-INQ-001	S	Capture an inquiry with contact info, business info, and message
URD-INQ-002	S	Notify admins in real time when a new inquiry is submitted
URD-INQ-003	S	Track assignment, reply, conversion, and lost reason
URD-INQ-004	S	Move an inquiry through NEW → assigned → replied → converted/lost

6. Acceptance Criteria

AC-CUS-01: Customer profile lifecycle

Given	When	Then
A staff member of a brand	Creates a customer with name + phone + email	Customer is created and scoped to that brand
A customer of another brand	The staff member searches/opens it	It is not visible (brand isolation)
A customer with linked orders	The staff member soft-deletes it	Customer leaves the active list; record and orders are preserved

AC-PNT-01: Loyalty points

Given	When	Then
A customer attached to an order; rate configured	The order completes payment	Points = order total × rate are added to the balance
The same order payment event is redelivered	Points are awarded again	No double award — the balance is unchanged
No customer attached, or rate is zero/unset	The order completes payment	No points are awarded

AC-SUB-01: Newsletter subscribe / unsubscribe

Given	When	Then
A new email	Subscribe	Subscriber is created with topics, locale, and an unsubscribe token
An already-active email	Subscribe again	Returns the existing subscriber (idempotent)
A deactivated subscriber	Subscribe again	The subscriber is reactivated
A valid unsubscribe token	The link is clicked	The subscriber is deactivated

AC-INQ-01: Sales inquiry

Given	When	Then
A site visitor	Submits an inquiry	Status is NEW and admins are notified in real time
A sales rep	Assigns it to self	The inquiry shows the assignee
A sales rep	Replies	Reply author and timestamp are recorded
A sales rep	Marks converted (or lost with reason)	Outcome and timestamp are recorded

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	Customers are scoped to a brand (Organization), not a single point-of-sale unit
C-02	A customer has the fixed customer role and no sign-in credentials by default
C-03	Point award is idempotent — at most one award per order
C-04	Subscriber email is globally unique; unsubscribe token is globally unique
C-05	Subscribe is idempotent (returns existing or reactivates)
C-06	All records use soft-delete

Non-Goals

• Customer segmentation and targeting
• Email / SMS campaign engine
• Point redemption on orders, and loyalty tiers
• Customer lifetime-value analytics

8. Version History

Date	Author	Description	Ver
2026-02-26	P. Do — Product Owner	Initial customer profiles, points, subscribers, inquiries	v0.1
2026-04-16	P. Do — Product Owner	Reworked around subscribers and inquiries	v0.3
2026-05-30	Docs migration	Restructured to module convention; areas CUS/PNT/SUB/INQ aligned to built behavior; status-honest priorities	v0.4