afv-library/rules/commerce/README.md

# Commerce Rules

Rules and guardrails for developing B2B Commerce and B2C Commerce solutions on Salesforce.

## Overview

Commerce rules ensure developers understand the proper workflow for creating, deploying, and maintaining Commerce storefronts. These rules prevent common mistakes and enforce best practices specific to Commerce development.

## Critical Concepts

### Store vs Storefront

The most important concept in Commerce development is understanding the distinction:

| Aspect | Commerce Store | Storefront (LWR Site) |
|--------|---------------|----------------------|
| **What** | Backend configuration & data | Frontend buyer experience |
| **Created** | Via Commerce app UI | Auto-generated by Store wizard |
| **Stored** | As data records (WebStore, BuyerGroup, etc.) | As metadata (ExperienceBundle) |
| **Source Control** | ❌ Not source-controllable | ✅ Source-controllable |
| **Deployment** | Data APIs or manual recreation | Salesforce CLI metadata deploy |
| **Examples** | Pricing policies, payment settings | Product pages, cart, checkout UI |

## Available Rules

### Commerce Store Creation Requirements
**`commerce-store-requirements.md`**

**Apply when:** Developer is creating a new Commerce storefront

**Key Enforcements:**
- ❌ **DO NOT** create storefront metadata from scratch
- ✅ **MUST** create Commerce Store in org first via Setup → Commerce
- ✅ **MUST** retrieve auto-generated Experience metadata
- ✅ **MUST** create Store in target org before deploying storefront

**Prevents:**
- Broken storefronts missing critical configurations
- Failed deployments due to missing WebStore associations
- Wasted time manually creating complex JSON structures
- Confusion about what can/cannot be source-controlled

**Required Workflow:**
```
1. Create Commerce Store (org UI)
   ↓
2. Store wizard creates Digital Experience
   ↓
3. Retrieve Experience metadata to repo
   ↓
4. Customize and commit
   ↓
5. Deploy to other orgs (after creating Store in target)
```

## When to Apply These Rules

### Trigger: User asks to create Commerce storefront

**User says:**
- "Create a B2B Commerce store"
- "Build a B2C storefront"
- "Set up Commerce on Core"
- "Create an LWR Commerce site"
- "Build a digital storefront"

**Agent should:**
1. ✅ Cite `rules/commerce/commerce-store-requirements.md`
2. ✅ Explain Store vs Storefront distinction
3. ✅ Guide user to create Store in org first
4. ✅ Provide CLI commands to retrieve metadata
5. ❌ **DO NOT** create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch

### Trigger: User asks to deploy storefront

**User says:**
- "Deploy my Commerce storefront to sandbox"
- "How do I move my store to production"
- "Deploy B2B store to another org"

**Agent should:**
1. ✅ Verify Commerce Store exists in target org with same name
2. ✅ Warn that Store data must be recreated/migrated separately
3. ✅ Provide deployment commands for Experience metadata only
4. ✅ Remind about payment/tax/shipping configuration in target org

## Rule Violations to Prevent

### ❌ Creating Storefront from Scratch
```javascript
// WRONG - Don't manually create this
{
  "siteType": "LWR",
  "label": "My Store",
  // ... hundreds of lines of complex config ...
}
```

**Why it fails:**
- Missing WebStore associations
- Incorrect Commerce component configurations
- Missing default pages and routes
- Incomplete navigation structure

### ❌ Deploying Without Store
```bash
# WRONG - Will fail if Store doesn't exist in target
sf project deploy start --source-dir force-app/main/default/experiences/My_Store/
# Error: WebStore not found
```

**Correct:**
```bash
# 1. First create Store in target org (UI or API)
# 2. THEN deploy
sf project deploy start --source-dir force-app/main/default/experiences/My_Store/
```

### ❌ Trying to Version Control Store Data
```bash
# WRONG - WebStore is data, not metadata
sf project retrieve start --metadata WebStore
# Error: WebStore is not a valid metadata type
```

**Correct:**
```bash
# Use Data Loader, APIs, or manual recreation for Store data
# Only retrieve Experience metadata
sf project retrieve start --metadata ExperienceBundle:My_Store
```

## Enforcement Guidelines

### For AI Agents / Assistants

When processing Commerce-related requests:

1. **Detection Phase**
   - Parse user intent for Commerce keywords (store, storefront, B2B, B2C, Commerce)
   - Identify if request is for creation vs modification vs deployment

2. **Rule Application**
   - Load `commerce-store-requirements.md` into context
   - Cite relevant sections in response
   - Enforce the correct workflow order

3. **Guidance Phase**
   - Explain Store vs Storefront distinction upfront
   - Provide specific CLI commands
   - Include prerequisites checklist
   - Warn about common pitfalls

4. **Implementation Phase**
   - Create custom LWCs only (never core storefront files)
   - Follow LDS-first patterns
   - Document deployment dependencies

### For Developers

**Before starting any Commerce work:**

- [ ] Read `rules/commerce/commerce-store-requirements.md` completely
- [ ] Understand Store (data) vs Storefront (metadata)
- [ ] Have org access with Commerce licenses
- [ ] Have Commerce Admin permissions

**During development:**

- [ ] Always create Store in org first
- [ ] Retrieve (never create) core storefront metadata
- [ ] Follow LDS-first patterns for custom LWCs
- [ ] Test in Experience Builder before committing
- [ ] Document Store configuration steps

**Before deployment:**

- [ ] Verify target org has Commerce licenses
- [ ] Create Store in target org with matching name
- [ ] Deploy Experience metadata only
- [ ] Configure payment/tax/shipping in target
- [ ] Test buy flow end-to-end

## Integration with Other Rules

Commerce rules work together with:

### LWC Development Guardrails
**`rules/lwc-development/lwc-requirements.md`**

When creating custom Commerce components:
- Apply LDS-first approach (no Apex unless necessary)
- Use `lightning-` base components
- Expose `@api` properties for Experience Builder
- Follow SLDS design patterns
- Use `NavigationMixin` for routing

### Spec-Driven App Development Standards
**`rules/spec-driven-dev/app-dev.md`**

When building complete Commerce solutions:
- Document store configuration requirements
- Create permission sets for Commerce users
- Follow naming conventions
- Maintain architecture documentation

## Common Questions

### Q: Can I create a Commerce storefront entirely in source control?

**A:** No. You must create the Commerce Store in the org first (via UI or API), which auto-generates the storefront. You can then retrieve and customize that storefront metadata.

### Q: What if I want to automate Store creation?

**A:** Use Commerce APIs to create WebStore records programmatically. Then retrieve the generated Experience metadata. Still don't create storefront JSON manually.

### Q: How do I migrate a Store to production?

**A:**
1. Create Store in production org (via UI or API) with same name
2. Export/import Store data (WebStore, BuyerGroup, EntitlementPolicy records)
3. Deploy Experience metadata from source control
4. Configure payment/tax/shipping in production
5. Test thoroughly before going live

### Q: Can I have multiple Stores in one org?

**A:** Yes. Each Store gets its own WebStore record and associated Experience site. Retrieve each storefront separately and organize in different directories.

## Related Prompts

Rules work with these prompts:

- **`prompts/commerce/retrieve-commerce-storefront.md`** - Step-by-step retrieval workflow
- (Future) Create custom Commerce LWC components
- (Future) Commerce data seeding and migration
- (Future) Multi-store management

## Additional Resources

**Salesforce Help:**
- [Commerce Store Administration](https://help.salesforce.com/s/articleView?id=sf.comm_store_admin.htm)
- [Commerce Setup Guide](https://help.salesforce.com/s/articleView?id=sf.comm_setup_overview.htm)

**Developer Guides:**
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/)
- [Commerce APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce.htm)

**Community:**
- [Commerce on Core Trailblazer Community](https://trailhead.salesforce.com/trailblazer-community/topics/commerce)