Enterprise Rule Forge

---
description: Enforce strict distributed transactions, idempotency keys, and zero unhandled Promise rejections across microservices.
globs: src/services/**/*.ts, src/controllers/**/*.ts
alwaysApply: false
---

# Team Microservice & Transaction Standard

## Architectural Purpose
Enforce strict distributed transactions, idempotency keys, and zero unhandled Promise rejections across microservices.

## Strict Negative Guardrails (NEVER DO)
- NEVER perform database writes inside payment endpoints without a verified idempotency key.
- NEVER catch and swallow errors without logging structured correlation IDs to Sentry/Datadog.
- NEVER return raw database error messages or internal stack traces to HTTP clients.

## Required Standards (ALWAYS ENFORCE)
- ALWAYS wrap multi-table state transitions in explicit database transactions.
- ALWAYS validate all incoming request bodies with strict Zod schemas before business logic.
- ALWAYS use UUIDv7 or KSUID for distributed entity primary keys.

## Anti-Pattern vs Production Implementation

```typescript
// ❌ Unacceptable Anti-Pattern
export async function chargeOrder(req, res) {
  try {
    await db.order.update({ where: { id: req.body.id }, data: { status: 'PAID' } });
    await stripe.charges.create({ amount: req.body.amount });
  } catch (err) {
    // Swallowed error, non-idempotent duplicate charge risk!
    res.status(500).json({ error: err.message });
  }
}
```

```typescript
// ✅ Industrial Production Standard
import { z } from "zod";
import { db } from "@/lib/db";
import { stripe } from "@/lib/stripe";

const ChargeSchema = z.object({
  orderId: z.string().uuid(),
  amount: z.number().positive(),
  idempotencyKey: z.string().min(16),
});

export async function chargeOrder(req: Request) {
  const body = ChargeSchema.parse(await req.json());
  
  return await db.$transaction(async (tx) => {
    const existing = await tx.idempotency.findUnique({ where: { key: body.idempotencyKey } });
    if (existing) return existing.responsePayload;
    
    const charge = await stripe.charges.create(
      { amount: body.amount, currency: "usd" },
      { idempotencyKey: body.idempotencyKey }
    );
    
    await tx.order.update({ where: { id: body.orderId }, data: { status: "PAID" } });
    return { success: true, chargeId: charge.id };
  });
}
```