PRD: Customer profiles
| Module | Customer | PRD ID | PRD-CUS-001 |
| Status | Ready to dev | FEAT | CUS |
| Epic | — | Plane | BANA-1495 |
| Date | 2026-03-15 | Version | v1.0 |
| Packages | @nx/identity | URD | CUS |
| Surface | Client · Owner/MgrBO · Ops | ||
| Owner | Phát Nguyễn | ||
TL;DR
A brand-scoped directory of customers that staff can attach to a sale order at checkout, so every order ties back to a person instead of an anonymous ticket. Any captured customer can later be promoted into a sign-in account (credential optional), turning a walk-in into a returning, addressable customer.
1. Context & Problem
Today a checkout cannot be tied to a person, and a brand has no directory of who buys from it. Without a customer record, a merchant cannot recognise repeat buyers, reconcile an order against a person, or build any of the engagement features (loyalty, segmentation, campaigns) that depend on knowing the customer. This is the foundational increment of the Customer module: it introduces the customer record, a surface to manage it, and the link from a customer to a sale order - so later phases (loyalty points, outreach, analytics) have a person to attach to.
2. Goals & Non-Goals
Goals
- Introduce a customer record - a person's name, phone, and email, the merchant that owns it, and a link to a sign-in account - plus a surface to manage it.
- Let staff create and manage customers, and attach a customer to a sale order at checkout.
- Confine every customer to its brand (merchant); soft-delete keeps history intact.
- Promote a captured customer into a sign-in account, with the sign-in credential optional.
Non-Goals
- Customer segmentation and targeting (Planned).
- Email / SMS campaign engine (Planned).
- Loyalty points, point redemption, and loyalty tiers - owned by Loyalty Points.
- Customer lifetime-value analytics (Planned).
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Order attribution | Share of sale orders that carry a customer trends up |
| Brand isolation | Zero cross-brand customer reads (staff see only their own brand) |
| History preservation | Soft-deleted customers retain linked orders; no hard deletes |
| Promotion | Captured customers promoted to a sign-in account (where chosen) |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Owner | Keep a brand-scoped directory of customers; manage and soft-delete profiles |
| Cashier | Create a customer on the fly and attach it to an order at checkout |
| Customer | Be promoted into a sign-in account to access their own history later |
Core scenario: a cashier creates a customer at checkout → the customer is confined to the brand and attached to the sale order → staff manage the profile within their brand → the captured customer is optionally promoted into a sign-in account.
5. User Stories
- As a cashier, I want to create a customer in one step at checkout, so the order is tied to a known person.
- As a cashier, I want to attach an existing customer to a sale order, so the order is tied to that person.
- As an owner, I want customers confined to my brand, so staff see and manage only ours.
- As an owner, I want to update a customer's profile and soft-delete it, so the directory stays clean while history is preserved.
- As an owner, I want to promote a captured customer into a sign-in account, so a walk-in becomes a returning, addressable customer.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Create a customer; only the name is required, email and phone are optional | URD-CUS-001 |
| FR-2 | Confine every customer to its brand (merchant) | URD-CUS-002 |
| FR-3 | Update a customer's profile (name, email, phone, and other details) | URD-CUS-003 |
| FR-4 | Soft-delete a customer, preserving the record and its linked orders | URD-CUS-004 |
| FR-5 | Staff see and manage only customers within their own brand | URD-CUS-005 |
| FR-6 | Attach a customer to a sale order at checkout; the customer is returned on order change | URD-CUS-006 |
| FR-7 | Promote a captured customer into a sign-in account holding a fixed customer role; the sign-in credential is optional - promoting without one creates the account, but it cannot sign in yet | URD-CUS-007 |
Full requirement text and acceptance criteria live in the Customer URD. This PRD references them rather than restating them.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | Soft-delete preserves the record; deleting a customer never removes linked orders |
| Tenancy & authz | Every customer is confined to its own merchant/brand; staff cannot read or manage another brand's customers |
| Performance / scale | Looking up and attaching a customer at checkout adds no perceptible latency to the sale flow |
| Identity model | A captured customer is a standalone record with no sign-in account; once promoted it holds a fixed customer role, and has no sign-in credential by default |
| i18n | User-facing labels are bilingual (English / Vietnamese) |
8. UX & Flows
Key screens: the checkout customer picker/create, and the brand-scoped management surface. Management and promote-to-account live in the accounts area; order attachment happens in the sale flow.
9. Data & Domain
| Concept | Role |
|---|---|
| Customer record | The customer - name, phone, email, link to a sign-in account, owning merchant; soft-deletable |
| Sign-in account | A captured customer has no account until promoted; promotion creates one holding a fixed customer role, with an optional sign-in credential |
| Sale order | Carries an attached customer; the customer is returned on order change |
| Customer promotion | Turns a captured customer into a sign-in account; the credential is optional at promotion |
Conceptual only - full data model and invariants in the identity domain model.
10. Dependencies & Assumptions
Depends on
- User Management (User Management) - promotion turns a customer into a sign-in account.
- Commerce (Commerce) - customers are confined to the merchant/brand.
- Sale - the sale order attaches and returns the customer at checkout.
Assumptions
- A merchant/brand exists to confine the customer to.
- A sign-in credential may be supplied at promotion; without one, the account is created but cannot sign in yet (no one-time-code flow exists today).
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Cross-brand customer leakage | All reads/writes confined per merchant; staff limited to their own brand |
| Management ownership split across areas | The record lives in shared core data, but management actions are split between the sale flow and the accounts area; the URD names accounts as the CUS owner - consolidation tracked separately |
| Promotion duplicates an existing account | Identifier-conflict checks guard account creation; define the merge path if a phone or email already exists |
| Soft-delete vs. orders referencing the customer | Soft-delete preserves the record and its linked orders |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 (foundation) - see URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | None (new customer record) |
| Launch criteria | Create→attach→order-carries-customer verified end-to-end; brand isolation verified; promotion verified both with and without a sign-in credential |
| Monitoring | Customer creation volume per brand, order-attachment rate, promotion success rate |
13. FAQ
Is a customer a sign-in account? Not by default - a captured customer is a standalone record with no account. Promotion creates one holding a fixed customer role; the credential is optional, and without it the account exists but cannot sign in yet. There is no one-time-code registration flow today.
Can a customer be attached to an order after checkout starts? Yes - staff attach the customer to the sale order, and the customer is returned on the order change.
What happens to orders when a customer is soft-deleted? Nothing - the customer leaves the active list, but the record and its linked orders are preserved.
Does this PRD cover loyalty points? No - points are a separate increment (Loyalty Points); this one only introduces the customer record and its attachment to orders.
Are customers shared across brands? No - every customer is confined to its brand; staff see only their own brand's customers.
References
- URD: Customer - Customer Profiles
- Related: Loyalty Points · Newsletter Subscribers · Sales Inquiries
- Module: Customer - URD
- Developer: @nx/identity · @nx/sale · domain model