01 · SHARED SYSTEM VIEW
One order, two experiences
The customer sees a simple journey. The platform coordinates reservations, verified payments, physical scans, approvals, notifications, and immutable records.
Customer
Choose product→Review checkout→Pay→Track order→Receive
Platform + team
Validate cart→Reserve stock→Verify provider→Scan & ship→Close window
Boundary ruleThe browser can request a transition, but only validated server-side events and authorized staff can finalize sensitive states.
02 · CUSTOMER SIDE
Purchase journey
The public experience keeps decision-making calm while continuously validating product availability, pricing, promotions, and account eligibility.
CF-01Discover and select
Primary storefront path
EntryHomepage, campaign, search
→
BrowseCategory, filter, sort
→
Product detailMedia, fit, size, stock
→
Variant available?Color + size + quantity
Yes → Add to cartNo → Restock alert / wishlist
CF-02Cart to order creation
Editable until final review
Active cartMerge identical SKU quantities
→
CheckoutAddress, shipping, payment, promo
→
Final reviewRead-only confirmation
→
Order createdPending payment
Every cart editRecalculate price, stock, promo, voucher, points, and shipping.
Final reviewNo inline changes. Customer goes back to checkout to edit.
Order creationReserve stock, voucher, points, and physical reward inventory.
03 · CUSTOMER SIDE
Payment and order status
The order number remains stable across retries. Customers see only the latest active payment attempt.
ORDERPENDING PAYMENT24-hour reservation
Provider processing→PROCESSINGExpiry paused
→PAIDInvoice created
Attempt failed→FAILEDOrder stays pending
↺CONTINUE PAYMENTReuse or renew session
Cancel / 24h expiry→EXPIREDAll reservations released
PaidProcessingPackedShippedCompleted
Completion is customer-confirmed or automatic four days after shipment. The first completed timestamp is authoritative.
04 · CUSTOMER SIDE
Return, exchange, or refund
A request must be submitted within three days of completion and include all required evidence.
Unboxing videoProduct photoAttached-tag photoWritten reason
RequestEligibility + evidence
→
CS reviewCompleteness and context
→
Owner decisionAll returns require approval
ExchangeSame product, another available color/size
RefundManual transfer + proof
RejectedCustomer-facing reason required
05 · SHARED CUSTOMER + BACKEND
Referral qualification and review
Customers share only a stable code. The platform links one code, follows the first paid order, and reveals no friend or order history to the referrer.
Code boundRegistration or eligible OAuth callback
→
First orderPaid, fulfilled, completed
→
Return windowThree days; open return holds
→
Anti-abuse resultName, phone, email, address
Clean → award both benefitsSuspicious → hold benefits for staff review
AttributionOne referred customer can bind only one code and cannot use their own code.
Order safetyA suspicious referral never blocks payment, fulfillment, delivery, or return handling.
Staff decisionApprove or reject both pending benefits with a reason and immutable audit event.
Customer privacyThe customer referral page shows no referral history. Awarded point history uses only “Referral Reward,” without the friend’s identity or order.
06 · SHARED CUSTOMER + BACKEND
Wishlist, restock, and demand
Wishlist and restock are exact-variant records but separate customer decisions. Saving an unavailable item never subscribes the customer automatically.
Exact variant savedProduct + colour + size
→
Available now?Authoritative inventory balance
Yes → Quick Add to cartNo → Customer may subscribe
Active subscriptionOne customer + one variant
→
Stock crosses above zeroAtomic inventory trigger
→
Email + WhatsAppVariant-preselected PDP link
→
NotifiedSubscribe again after a later sell-out
Wishlist campaignsAt most one alert per campaign and channel; suppressed when every variant of the product is unavailable.
Staff analyticsCurrent subscribers, historical trend, and demand versus production sales; no automatic purchase recommendation.
Identity boundaryExports contain variant and subscriber count only. Name, email, and phone require the Owner permission.
Notification ruleRestock and wishlist campaign alerts intentionally use separate idempotency records. Neither flow adds an item to cart automatically.
07 · SHARED CUSTOMER + BACKEND
Verified reviews and merchandising
A review starts with an authoritative completed-order line. A badge starts as a system recommendation. Neither becomes public without the required proof or human decision.
Customer
Order completed→Rating + text→Pending→Published on PDP
Backend
Verify order item→Lock content→Staff moderation→Refresh summary
Rule signalNew · sales · stock · sale
→
Badge candidatePending, never public
→
Admin decisionPublish or reject
→
Storefront badgePublished only
Review integrityOne review per completed-order item. Rating and text cannot be edited or deleted after submission.
Public privacyThe PDP feed exposes rating, text, and time only—no customer, order, or verified-purchase label.
Homepage orderManual pins sort first; system ranking then fills Hottest New, Best Seller, and Newest rails.
08 · STAFF CATALOG
Bulk product import and export
Staff use one official CSV/XLSX structure for every category. Validation may create staging evidence, but no product or SKU changes until every row passes and the validation token is committed.
Official templateUniversal columns · no media
→
Upload + previewUp to 5,000 rows
→
All rows valid?Errors require re-upload
→
Atomic commitEverything or nothing
Catalog staff
Download template→Prepare file→Correct errors→Commit
Database
Stage rows→Validate all→Recheck snapshot→Audit changes
Stock firewallStock, quantity, available, reserved, media, and image fields are rejected. Inventory changes remain inside receiving, opname, adjustments, sales, and returns.
Blank is safeAn empty existing-product field means keep the live value. It is never interpreted as a delete instruction.
Price approvalChanges within ±10% apply with the batch. Larger moves create a Manager/Owner request while the old price stays active.
Concurrency ruleCommit recalculates the preview fingerprint. If a product or SKU changed after validation, the complete batch stops and must be uploaded again.
09 · STAFF ANALYTICS
From customer action to trusted report
The browser records a small, non-sensitive journey event. Paid purchases and commerce totals always come from authoritative order records.
Storefront
Product view→Add to cart→Begin checkout→Payment
Database
Validate event→Store immutable row→Derive paid purchase→Aggregate report
Privacy boundaryNames, email, phone, address, password, token, card, and bank-account fields are rejected from browser event payloads.
Production boundaryRevenue, orders, AOV, product sales, and customer segments exclude test orders.
Role boundaryOwner/Manager see all reports. Marketing excludes funnel. Product & Inventory Admin sees SKU analytics only.
Product viewUnique first-party session
→
Add to cartExact product + variant
→
Begin checkoutSelected cart items
→
Paid orderServer-derived only
Phase boundaryCampaign and traffic-source attribution plus Google, Meta, and TikTok pixels remain in Phase 14 until consent, provider IDs, and compliance review are ready.
06 · BACKEND SIDE
Order operations
Payment, warehouse, and shipping transitions are gated by proof—not merely by an admin click.
01Payment verification
Receive provider callback, validate signature and amount, apply idempotency, then transition to Paid.
ProducesPayment attempt · paid timestamp · invoice
02Processing
Lock address and variants. Prepare the fulfillment queue from verified paid orders.
ProducesPick task · packing context
03Packing
Scan every required SKU. A mismatch blocks completion; successful scans resolve reservations and reduce on-hand stock.
ProducesScan events · inventory movements
04Shipment
Generate or enter tracking, then verify order, package, and resi with a final package scan.
ProducesShipment · tracking history · shipped timestamp
Payment ruleA customer redirect never marks an order Paid. Only a verified server-side provider status may do so.
07 · BACKEND SIDE
Receiving and inventory
Pending deliveries and failed QC quantities stay outside sellable inventory until the required approval is recorded.
ReceivedDocuments + quantities
→
QC in progressPass / hold / reject per SKU
→
Pending approvalManager or Owner
→
ApprovedCreate batch + increase stock
On-hand30
−Reserved2
=Available28
Manual adjustmentAdmin proposes; Manager or Owner approves. Stock may never fall below zero.
Stock opnameBlind count, counted-at time, movement reconciliation, then automatic adjustment.
Return QCPass routes to exchange/refund. Failure routes to Owner review.
08 · BACKEND SIDE
Roles and approvals
Access follows least privilege. Sensitive financial, inventory, and customer actions have explicit ownership.
RolePrimary responsibilityCritical boundary
OwnerFull authority, refunds, returns, overrides, sensitive auditReason + audit required for bypass or rollback
ManagerOperational approvals, customer edits, analytics, content orderCannot perform Owner-only actions
Inventory adminProducts, receiving input, counts, adjustment requestsCannot self-approve controlled stock changes
Customer serviceCustomer data, internal notes, first return review, WhatsAppNo final return or refund approval
FulfillmentPicking, SKU scans, packing, package verificationCannot bypass scan prerequisites
MarketingArticles, banners, merchandising, promotionsApproval rules still apply to promotions
09 · SYSTEM CONTROLS
Non-negotiable invariants
These constraints must hold across UI, API, background jobs, manual operations, imports, and recovery procedures.
InventoryStock never becomes negative.
PaymentPaid requires verified server-side confirmation.
ReceivingUnapproved goods are not active inventory.
PackingEvery required SKU must scan successfully.
ShippingOrder, package, and tracking must match.
ReturnsEvery return requires Owner approval.
RefundFinal refund requires transfer proof.
AuditCritical financial and stock history is never deleted.
PermissionsLower roles cannot execute Owner-only operations.
ReviewsOnly completed purchases qualify; publication always requires moderation.
BadgesSystem candidates never publish themselves.
ImportsAny row error blocks the full batch; bulk files can never modify stock or media.
10 · TRACEABILITY
Records produced by each flow
Every material transition leaves enough context to reconstruct what happened, who initiated it, and which approval or external event authorized it.
CommerceCart · order · order items · price snapshot · invoice
PaymentAttempts · provider references · webhook result · timestamps
InventoryReservations · movements · batches · QC · opname results
FulfillmentPick/pack task · SKU scans · package · shipment · tracking
ReturnsEvidence · reviews · approval · QC · exchange/refund proof
ReferralCode · attribution · campaign snapshot · qualifying order · review event · paired benefits
ReviewsSubmission · moderation event · rating summary · badge decision · merchandising pin
Catalog importBatch · staged rows · validation errors · price approval · immutable import events
GovernanceActor · before/after · reason · approval context · outcome
