Ubiquitous Language

PM: "When someone stops paying..."
Dev: "What's the term for that? Cancelled? Inactive?"
PM: "We call them 'churned subscribers'"
✅ Term added to glossary: Churned Subscriber

QA: "What's the difference between 'guest' and 'user'?"
PM: "Guest hasn't registered. User has an account."
✅ Two distinct terms: Guest, User

Dev: "When exactly does an order become 'completed'?"
PM: "When payment clears and items ship."
✅ Term defined: Completed = Paid + Shipped

Feature: Subscription Management

  # Define domain terms upfront
  Background:
    """
    Domain Terms:
    - Subscriber: Customer with active subscription
    - Churned Subscriber: Cancelled within last 30 days
    - Lapsed Subscriber: Cancelled over 30 days ago
    - Winback Offer: Discount to re-activate churned subscriber
    """

  Scenario: Winback offer for churned subscriber
    Given a churned subscriber from 15 days ago
    When they visit the pricing page
    Then they should see the winback offer

  Scenario: No winback for lapsed subscriber
    Given a lapsed subscriber from 60 days ago
    When they visit the pricing page
    Then they should see standard pricing
    And they should not see the winback offer

Feature: User Account Management

  Scenario: User registers
    When a customer signs up
    Then a member account is created
    And the client receives confirmation email

Feature: Member Account Management

  Scenario: Member registers
    When a customer creates an account
    Then a member account is created
    And the member receives confirmation email

# Domain Glossary

## Order Lifecycle
- **Cart** - Temporary collection of items (not yet ordered)
- **Order** - Finalized purchase (payment may be pending)
- **Pending Order** - Order created, awaiting payment
- **Confirmed Order** - Payment received, awaiting fulfillment
- **Shipped Order** - Items dispatched to customer
- **Completed Order** - Items delivered successfully
- **Cancelled Order** - Order terminated before shipping
- **Returned Order** - Items sent back after delivery

## Membership
- **Guest** - Browsing without account
- **Customer** - Anyone (guest or member)
- **Member** - Registered account (free tier)
- **Subscriber** - Paid subscription
- **Premium Member** - Highest paid tier

## Inventory
- **In Stock** - Available for immediate purchase
- **Low Stock** - Less than 10 units remaining
- **Out of Stock** - Zero units, cannot purchase
- **Backordered** - Out of stock, but can pre-order
- **Discontinued** - No longer sold

// GOOD - Uses domain language
class Subscriber {
  churnDate?: Date;
  
  isChurned(): boolean {
    return this.churnDate !== undefined;
  }
  
  isEligibleForWinback(): boolean {
    if (!this.isChurned()) return false;
    const daysSinceChurn = daysBetween(this.churnDate, now());
    return daysSinceChurn <= 30;
  }
}

// AVOID - Technical jargon
class UserAccount {
  deactivationTimestamp?: number;
  
  isDeactivated(): boolean {
    return this.deactivationTimestamp !== undefined;
  }
}

// GOOD - Domain verbs
order.confirm();
order.ship();
order.complete();
subscription.churn();
subscriber.winback();

// AVOID - Generic CRUD
order.update({ status: 'confirmed' });
subscription.delete();
user.create();

// GOOD - Domain states
enum OrderStatus {
  Pending = 'PENDING',
  Confirmed = 'CONFIRMED',
  Shipped = 'SHIPPED',
  Completed = 'COMPLETED',
  Cancelled = 'CANCELLED',
}

// AVOID - Technical states
enum OrderStatus {
  State1 = 1,
  State2 = 2,
  State3 = 3,
}

# GOOD - Business domain language
Feature: Order Management

  Scenario: Checkout with insufficient inventory
    Given product "Laptop" is out of stock
    When customer tries to purchase "Laptop"
    Then they should see "Out of stock"
    And order should not be created

# AVOID - Technical implementation
Feature: Database Constraint Handling

  Scenario: Handle zero inventory constraint
    Given inventory.stock_count = 0 for product_id = 123
    When POST /api/orders with product_id = 123
    Then response should be 409 Conflict
    And orders table should have no new records

Feature: Subscription Billing

  Scenario: Monthly subscription renewal
    Given a subscriber with monthly billing cycle
    When their subscription renews on billing date
    Then they should be charged subscription fee
    And subscription expiry should extend 30 days

  # Use "subscriber" consistently, not:
  # - "user"
  # - "customer"  
  # - "member"
  # - "account"

When I POST to /api/auth with credentials
Then JWT token is stored in localStorage
And user_id foreign key is inserted

When I log in with valid credentials
Then I should be authenticated
And I should access my dashboard

Given the item is inactive
When I process the thing
Then the status should update

Given the product is discontinued
When I attempt to purchase the product
Then I should see "Product no longer available"

Scenario: Register new account
  When I sign up
  Then I create a profile
  And I complete onboarding

# "register", "sign up", "create profile", "onboarding" - which is it?

Scenario: Register new member
  When I complete registration
  Then my member account should be created
  And I should receive welcome email

Given a user is logged in      # Authenticated member?
And a user visits the page     # Anonymous visitor?
And a user account exists      # Member entity?

Given a member is logged in
And a guest visits the page
And a member account exists with email "test@example.com"

Scenario: Deactivate user
  When admin deactivates user
  Then user cannot login

Team realizes two types of deactivation:
- Temporary suspension (can be reversed)
- Permanent deletion (cannot be reversed)

Scenario: Suspend member account
  When admin suspends member
  Then member cannot login
  But member data is retained

Scenario: Permanently delete member account
  When admin deletes member
  Then member cannot login
  And member data is anonymized

- ~~Deactivate~~ (deprecated - ambiguous)
- **Suspend** - Temporarily disable login (reversible)
- **Delete** - Permanently remove member (irreversible)

What do we call someone who:
- Visits the site? → Visitor? Guest?
- Creates account? → User? Member? Customer?
- Pays subscription? → Subscriber? Premium Member?
- Cancels subscription? → Churned? Inactive? Lapsed?

Guest: Not logged in, browsing
Member: Free account, logged in
Subscriber: Paid monthly subscription
Churned Subscriber: Cancelled within 30 days
Lapsed Member: Cancelled over 30 days ago

# Terms

- **Guest** - Visitor without account
- **Member** - Registered free account
- **Subscriber** - Paid subscription
- **Churned** - Cancelled subscription (last 30 days)
- **Lapsed** - Cancelled subscription (30+ days ago)

Scenario: Guest browses products
  Given I am a guest
  When I view products
  Then I see public pricing

Scenario: Subscriber sees discounted pricing
  Given I am a subscriber
  When I view products
  Then I see subscriber pricing

class Guest extends Visitor {
  viewProducts(): Product[] {
    return this.catalog.getPublicProducts();
  }
}

class Subscriber extends Member {
  viewProducts(): Product[] {
    return this.catalog.getSubscriberProducts();
  }
}