@codebakers/mcp 5.6.1 → 5.7.0

package/templates/BUSINESS-RULES-TEMPLATE.md

@@ -0,0 +1,750 @@
+# Business Rules Documentation
+
+**Project:** [Your Project Name]
+**Domain:** [MLM / E-commerce / CRM / etc.]
+**Last Updated:** [Date]
+
+---
+
+## Purpose
+
+This file documents business logic that cannot be automatically inferred from schema or mockups.
+
+Use this to capture:
+- Computed field formulas
+- Conditional triggers
+- Cascade chains
+- Business rule enforcement
+- Complex calculations
+
+**This complements:**
+- `DEPENDENCY-MAP.md` (FK and read dependencies from codebakers_map_dependencies)
+- `MLM-DEPENDENCIES.md` (Upline cascades from codebakers_map_mlm_dependencies)
+
+Together, these provide **100% dependency coverage**.
+
+---
+
+## Computed Fields
+
+### [Entity].[field_name]
+
+**Formula:**
+```sql
+[SQL or pseudocode formula]
+```
+
+**Computed From:**
+- [List source tables/fields]
+
+**Update Triggers:**
+- [Action that triggers recalculation]
+- [Another trigger]
+
+**Cascades To:**
+- [What happens after this field updates]
+
+**Affected Stores:**
+- [StoreNames]
+
+**Affected Components:**
+- [ComponentNames]
+
+**Example:**
+```javascript
+// When this field changes:
+if ([condition]) {
+  [action]
+}
+```
+
+---
+
+**Template Example:**
+
+### user.personal_volume
+
+**Formula:**
+```sql
+SUM(sales.bonus_volume WHERE sales.user_id = user.id AND sales.status = 'completed')
+```
+
+**Computed From:**
+- sales table (bonus_volume column)
+- Filtered by user_id and status
+
+**Update Triggers:**
+- createSale (when status = 'completed')
+- updateSale (when status changes to/from 'completed')
+- deleteSale
+
+**Cascades To:**
+- rank_check (if personal_volume >= next threshold)
+- team_volume_recalc (for upline users)
+- commission_calculation
+
+**Affected Stores:**
+- UserStore (current user)
+- UserStore (all upline - for team_volume recalc)
+
+**Affected Components:**
+- User-Dashboard (shows personal_volume)
+- Team-View (used in team calculations)
+
+**Example:**
+```javascript
+// After createSale:
+user.personal_volume += sale.bonus_volume
+
+// Then check:
+if (user.personal_volume >= RANK_THRESHOLDS[nextRank]) {
+  promoteUser(user.id, nextRank)
+}
+```
+
+---
+
+## Conditional Triggers
+
+### [trigger_name]
+
+**Condition:**
+```
+[When this happens]
+```
+
+**Check:**
+```javascript
+if ([condition]) {
+  [action]
+}
+```
+
+**Cascades To:**
+- [What this triggers]
+
+**Affected Entities:**
+- [Entities that get updated]
+
+**Example Implementation:**
+```typescript
+[Code example]
+```
+
+---
+
+**Template Example:**
+
+### rank_promotion_check
+
+**Condition:**
+```
+When personal_volume OR team_volume changes
+```
+
+**Check:**
+```javascript
+if (user.personal_volume >= RANK_THRESHOLDS[nextRank] ||
+    user.team_volume >= TEAM_RANK_THRESHOLDS[nextRank]) {
+  promoteUser(user.id, nextRank)
+}
+```
+
+**Cascades To:**
+- Create rank_promotion record
+- Update user.rank
+- Recalculate commission_rate (based on new rank)
+- Trigger upline_bonus_recalc (sponsor's leadership bonus may change)
+- Send promotion notification
+
+**Affected Entities:**
+- user (rank updated)
+- rank_promotions (new record created)
+- commissions (rate changes for future commissions)
+- upline users (leadership bonuses recalculated)
+
+**Example Implementation:**
+```typescript
+async function checkRankPromotion(userId: string) {
+  const user = await getUser(userId)
+  const currentRank = user.rank
+  const nextRank = getNextRank(currentRank)
+
+  const threshold = RANK_THRESHOLDS[nextRank]
+  const teamThreshold = TEAM_RANK_THRESHOLDS[nextRank]
+
+  if (user.personal_volume >= threshold || user.team_volume >= teamThreshold) {
+    // Promote
+    await updateUser(userId, { rank: nextRank })
+    await createRankPromotion({ user_id: userId, old_rank: currentRank, new_rank: nextRank })
+
+    // Cascade: Update upline leadership bonuses
+    await recalculateUplineLeadershipBonuses(user.sponsor_id)
+
+    // Cascade: Send notification
+    await sendPromotionNotification(userId, nextRank)
+  }
+}
+```
+
+---
+
+## Cascade Chains
+
+### [cascade_name]
+
+**Trigger:** [Initial action]
+
+**Steps:**
+1. [First thing that happens]
+2. [Second thing]
+3. [If condition met] → [Branch action]
+4. [Continue...]
+
+**Entities Affected:**
+- [Entity 1]: [What changes]
+- [Entity 2]: [What changes]
+
+**Stores to Update:**
+- [Store 1]
+- [Store 2]
+
+**Components to Invalidate:**
+- [Component 1]
+- [Component 2]
+
+**Duration:** ~[Time estimate]
+
+**Example:**
+```javascript
+[Pseudocode of complete cascade]
+```
+
+---
+
+**Template Example:**
+
+### createSale_complete_cascade
+
+**Trigger:** User creates a sale (createSale mutation)
+
+**Steps:**
+1. Create sale record (sale_id, user_id, product_id, amount, bonus_volume)
+2. Update user.personal_volume += sale.bonus_volume
+3. Check rank promotion for user
+   - If promoted → Update rank, create rank_promotion record
+4. Traverse upline tree (sponsor_id chain, max 10 levels)
+5. For each upline user (level 1-10):
+   a. Calculate bonus: sale.bonus_volume * GENERATION_RATES[level]
+   b. Update upline_user.bonus_volume += calculated_bonus
+   c. Create bonus_volume record (user_id: upline_user.id, from_user_id: user.id, sale_id, volume, level)
+   d. Check rank promotion for upline_user
+   e. If promoted → Trigger another cascade (leadership bonuses)
+6. Recalculate team_volume for all upline users
+   - team_volume = SUM(all_downline.personal_volume + all_downline.team_volume)
+7. Create commission records:
+   a. User commission: sale.amount * COMMISSION_RATES[user.rank]
+   b. For each upline user:
+      - If upline_user.rank > downline_user.rank → Override commission
+      - commission = sale.amount * (COMMISSION_RATES[upline_rank] - COMMISSION_RATES[downline_rank])
+
+**Entities Affected:**
+- sale: Created
+- user: personal_volume updated, possibly rank updated
+- upline users (1-10): bonus_volume updated, possibly rank updated
+- bonus_volumes: 1-10 records created
+- commissions: 1-11 records created (user + upline)
+- rank_promotions: 0-11 records created (if promotions occurred)
+
+**Stores to Update:**
+- SaleStore
+- UserStore (user + 10 upline users = 11 total)
+- BonusVolumeStore
+- CommissionStore
+- RankPromotionStore (conditional)
+
+**Components to Invalidate:**
+- User-Dashboard (for user + all upline)
+- Team-View (for all upline)
+- Commission-Report
+
+**Duration:** ~500ms - 2s (depending on upline depth and promotions)
+
+**Example:**
+```typescript
+async function createSaleWithCascade(input: CreateSaleInput) {
+  // 1. Create sale
+  const sale = await db.sales.insert({
+    user_id: input.user_id,
+    product_id: input.product_id,
+    amount: input.amount,
+    bonus_volume: input.bonus_volume,
+  })
+
+  // 2. Update personal volume
+  await db.users.update(input.user_id, {
+    personal_volume: db.raw('personal_volume + ?', [sale.bonus_volume])
+  })
+
+  // 3. Check rank
+  await checkRankPromotion(input.user_id)
+
+  // 4-6. Upline cascade
+  const uplineUsers = await getUplineTree(input.user_id, 10)
+  for (const [level, uplineUser] of uplineUsers.entries()) {
+    const bonus = sale.bonus_volume * GENERATION_RATES[level]
+
+    // Update bonus volume
+    await db.users.update(uplineUser.id, {
+      bonus_volume: db.raw('bonus_volume + ?', [bonus])
+    })
+
+    // Create bonus record
+    await db.bonus_volumes.insert({
+      user_id: uplineUser.id,
+      from_user_id: input.user_id,
+      sale_id: sale.id,
+      volume: bonus,
+      level: level + 1,
+    })
+
+    // Check promotion
+    await checkRankPromotion(uplineUser.id)
+  }
+
+  // 7. Recalc team volume
+  for (const uplineUser of uplineUsers) {
+    await recalculateTeamVolume(uplineUser.id)
+  }
+
+  // 8. Create commissions
+  await createCommissionsForSale(sale.id, input.user_id, uplineUsers)
+
+  // 9. Invalidate stores
+  await invalidateStores([
+    'SaleStore',
+    'UserStore',
+    'BonusVolumeStore',
+    'CommissionStore',
+    'RankPromotionStore',
+  ])
+}
+```
+
+---
+
+## Business Rule Enforcement
+
+### [rule_name]
+
+**Rule:**
+```
+[Statement of the business rule]
+```
+
+**Enforced Where:**
+- [Location in code]
+
+**Validation:**
+```javascript
+[Validation logic]
+```
+
+**Error Handling:**
+```javascript
+[What happens if rule violated]
+```
+
+---
+
+**Template Example:**
+
+### minimum_personal_volume_for_commission
+
+**Rule:**
+```
+User must have at least $500 in personal_volume in current month to receive commissions
+```
+
+**Enforced Where:**
+- createCommission mutation
+- Monthly commission calculation job
+
+**Validation:**
+```javascript
+const currentMonthVolume = await getUserPersonalVolumeForMonth(userId, currentMonth)
+
+if (currentMonthVolume < 500) {
+  return { eligible: false, reason: 'minimum_volume_not_met' }
+}
+```
+
+**Error Handling:**
+```javascript
+// Don't create commission record
+// Log to audit trail
+await db.commission_holds.insert({
+  user_id: userId,
+  sale_id: saleId,
+  amount: commissionAmount,
+  hold_reason: 'minimum_volume_not_met',
+  current_volume: currentMonthVolume,
+  required_volume: 500,
+})
+
+// User will see in dashboard: "Commission on hold - reach $500 personal volume"
+```
+
+---
+
+## Aggregation Formulas
+
+### [aggregation_name]
+
+**Formula:**
+```sql
+[SQL aggregation]
+```
+
+**Recalculation Triggers:**
+- [When to recalculate]
+
+**Performance:**
+- Estimated rows: [N]
+- Estimated time: [Duration]
+- Optimization: [Any indexes or caching]
+
+**Example:**
+```typescript
+[Implementation code]
+```
+
+---
+
+**Template Example:**
+
+### team_volume_calculation
+
+**Formula:**
+```sql
+WITH RECURSIVE downline AS (
+  SELECT id, personal_volume, team_volume, 0 as depth
+  FROM users
+  WHERE id = $user_id
+  UNION ALL
+  SELECT u.id, u.personal_volume, u.team_volume, d.depth + 1
+  FROM users u
+  JOIN downline d ON u.sponsor_id = d.id
+  WHERE d.depth < 10
+)
+SELECT SUM(personal_volume) as total_team_volume
+FROM downline
+WHERE id != $user_id;
+```
+
+**Recalculation Triggers:**
+- When any downline user makes a sale (personal_volume changes)
+- When downline structure changes (user changes sponsor)
+- When downline user gets promoted (affects team calculations)
+
+**Performance:**
+- Estimated rows: 1-1000 (depending on team size)
+- Estimated time: 10-500ms
+- Optimization:
+  - Index on sponsor_id
+  - Cache team_volume, recalc only on changes
+  - Use materialized view for large teams (>100 members)
+
+**Example:**
+```typescript
+async function recalculateTeamVolume(userId: string) {
+  const result = await db.raw(`
+    WITH RECURSIVE downline AS (
+      SELECT id, personal_volume, team_volume, 0 as depth
+      FROM users
+      WHERE id = $1
+      UNION ALL
+      SELECT u.id, u.personal_volume, u.team_volume, d.depth + 1
+      FROM users u
+      JOIN downline d ON u.sponsor_id = d.id
+      WHERE d.depth < 10
+    )
+    SELECT SUM(personal_volume) as total_team_volume
+    FROM downline
+    WHERE id != $1
+  `, [userId])
+
+  const teamVolume = result.rows[0].total_team_volume || 0
+
+  await db.users.update(userId, { team_volume: teamVolume })
+
+  return teamVolume
+}
+```
+
+---
+
+## Constants / Configuration
+
+### Rank Thresholds (Personal Volume)
+
+```typescript
+const RANK_THRESHOLDS = {
+  'Associate': 0,
+  'Silver': 1000,
+  'Gold': 5000,
+  'Platinum': 10000,
+  'Diamond': 25000,
+}
+```
+
+### Team Volume Thresholds (Alternative Promotion Path)
+
+```typescript
+const TEAM_RANK_THRESHOLDS = {
+  'Associate': 0,
+  'Silver': 5000,
+  'Gold': 25000,
+  'Platinum': 100000,
+  'Diamond': 500000,
+}
+```
+
+### Generation Bonus Rates
+
+```typescript
+const GENERATION_RATES = [
+  1.0,   // Level 1 (direct sponsor): 100%
+  1.0,   // Level 2: 100%
+  0.5,   // Level 3: 50%
+  0.5,   // Level 4: 50%
+  0.25,  // Level 5: 25%
+  0.25,  // Level 6: 25%
+  0.25,  // Level 7: 25%
+  0.25,  // Level 8: 25%
+  0.25,  // Level 9: 25%
+  0.25,  // Level 10: 25%
+]
+```
+
+### Commission Rates (by Rank)
+
+```typescript
+const COMMISSION_RATES = {
+  'Associate': 0.10,   // 10%
+  'Silver': 0.15,      // 15%
+  'Gold': 0.20,        // 20%
+  'Platinum': 0.25,    // 25%
+  'Diamond': 0.30,     // 30%
+}
+```
+
+---
+
+## Edge Cases
+
+### [edge_case_name]
+
+**Scenario:**
+```
+[Description of edge case]
+```
+
+**Handling:**
+```javascript
+[How to handle it]
+```
+
+**Example:**
+```
+[Concrete example]
+```
+
+---
+
+**Template Example:**
+
+### circular_sponsor_reference
+
+**Scenario:**
+```
+User A sponsors User B sponsors User C sponsors User A (circular reference)
+```
+
+**Handling:**
+```javascript
+// Prevent at creation time
+async function updateUserSponsor(userId: string, newSponsorId: string) {
+  // Check if new sponsor is in user's downline
+  const downline = await getDownlineTree(userId, 100)
+  const downlineIds = downline.map(u => u.id)
+
+  if (downlineIds.includes(newSponsorId)) {
+    throw new Error('Cannot set sponsor - would create circular reference')
+  }
+
+  // Safe to update
+  await db.users.update(userId, { sponsor_id: newSponsorId })
+}
+
+// Also prevent in upline traversal (infinite loop protection)
+async function getUplineTree(userId: string, maxDepth: number) {
+  const visited = new Set<string>()
+  const upline = []
+
+  let currentId = userId
+  let depth = 0
+
+  while (depth < maxDepth) {
+    const user = await getUser(currentId)
+    if (!user.sponsor_id) break
+    if (visited.has(user.sponsor_id)) {
+      console.error(`Circular reference detected: ${user.sponsor_id}`)
+      break  // Stop traversal
+    }
+
+    visited.add(user.sponsor_id)
+    upline.push(await getUser(user.sponsor_id))
+    currentId = user.sponsor_id
+    depth++
+  }
+
+  return upline
+}
+```
+
+**Example:**
+```
+User ID: 123
+Sponsor ID: 456
+Sponsor's Sponsor ID: 789
+Sponsor's Sponsor's Sponsor ID: 123  // ❌ Circular!
+
+Prevention: Reject update when setting sponsor_id = 789
+```
+
+---
+
+## Testing Scenarios
+
+### [scenario_name]
+
+**Setup:**
+```
+[Initial state]
+```
+
+**Action:**
+```
+[What user does]
+```
+
+**Expected Result:**
+```
+[What should happen - all cascades]
+```
+
+**Assertions:**
+```javascript
+[Test assertions]
+```
+
+---
+
+**Template Example:**
+
+### sale_triggers_multiple_promotions
+
+**Setup:**
+```
+User A (Associate, personal_volume: 950)
+  ↳ Sponsor B (Silver, personal_volume: 4800, team_volume: 950)
+    ↳ Sponsor C (Gold, team_volume: 5750)
+```
+
+**Action:**
+```
+User A makes $100 sale (bonus_volume: 100)
+```
+
+**Expected Result:**
+```
+1. Sale created ($100)
+2. User A:
+   - personal_volume: 950 → 1050
+   - Promoted: Associate → Silver (threshold: 1000)
+   - rank_promotion record created
+3. Sponsor B:
+   - bonus_volume: +100
+   - team_volume: 950 → 1050
+   - personal_volume: 4800 + 100 = 4900
+   - Still Silver (needs 5000 for Gold)
+4. Sponsor C:
+   - bonus_volume: +100 (generation 2)
+   - team_volume: 5750 → 5850
+   - Still Gold
+5. Bonus records created:
+   - User B gets $100 (level 1, 100%)
+   - User C gets $100 (level 2, 100%)
+6. Commissions created:
+   - User A: $100 * 15% = $15 (Silver rate - promoted mid-sale)
+   - User B: $100 * (15% - 0%) = $15 (override)
+   - User C: $100 * (20% - 15%) = $5 (override)
+```
+
+**Assertions:**
+```typescript
+test('sale triggers multiple promotions', async () => {
+  // Setup
+  const userA = await createUser({ rank: 'Associate', personal_volume: 950 })
+  const userB = await createUser({ rank: 'Silver', personal_volume: 4800, team_volume: 950 })
+  const userC = await createUser({ rank: 'Gold', team_volume: 5750 })
+  await updateUser(userA.id, { sponsor_id: userB.id })
+  await updateUser(userB.id, { sponsor_id: userC.id })
+
+  // Action
+  await createSale({ user_id: userA.id, amount: 100, bonus_volume: 100 })
+
+  // Assertions
+  const updatedA = await getUser(userA.id)
+  expect(updatedA.personal_volume).toBe(1050)
+  expect(updatedA.rank).toBe('Silver')
+
+  const updatedB = await getUser(userB.id)
+  expect(updatedB.bonus_volume).toBe(100)
+  expect(updatedB.team_volume).toBe(1050)
+
+  const updatedC = await getUser(userC.id)
+  expect(updatedC.team_volume).toBe(5850)
+
+  const bonuses = await getBonusVolumes({ sale_id: sale.id })
+  expect(bonuses).toHaveLength(2)
+  expect(bonuses[0].user_id).toBe(userB.id)
+  expect(bonuses[0].volume).toBe(100)
+  expect(bonuses[1].user_id).toBe(userC.id)
+  expect(bonuses[1].volume).toBe(100)
+
+  const commissions = await getCommissions({ sale_id: sale.id })
+  expect(commissions).toHaveLength(3)
+  expect(commissions.find(c => c.user_id === userA.id)?.amount).toBe(15)
+  expect(commissions.find(c => c.user_id === userB.id)?.amount).toBe(15)
+  expect(commissions.find(c => c.user_id === userC.id)?.amount).toBe(5)
+})
+```
+
+---
+
+## Implementation Notes
+
+[Add any additional notes here about:
+- Performance considerations
+- Caching strategies
+- Queue vs immediate processing
+- Transaction boundaries
+- Error handling strategies
+- Monitoring / alerting
+]
+
+---
+
+**This document is maintained manually. Update when business rules change.**