@polymorphism-tech/morph-spec 1.0.0

package/content/.morph/examples/api-nextjs/README.md

@@ -0,0 +1,241 @@
+# API .NET + Next.js Example
+
+Exemplo de arquitetura full-stack com .NET API backend e Next.js frontend.
+
+## Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| **Frontend** | Next.js 14 (App Router) |
+| **Backend** | .NET 8 Minimal APIs |
+| **Database** | SQL Server / PostgreSQL |
+| **Auth** | Clerk (SSO) |
+| **API Communication** | REST + React Query |
+| **Infra** | Azure Container Apps |
+
+## Arquitetura
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Next.js Frontend                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Pages     │  │ Components  │  │    Hooks            │  │
+│  │  /dashboard │  │ DataTable   │  │ useProducts()       │  │
+│  │  /products  │  │ Forms       │  │ useOrders()         │  │
+│  │  /orders    │  │ Charts      │  │ useAuth()           │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ REST API
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      .NET API                                │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  Endpoints: /api/products, /api/orders, /api/users  │    │
+│  └─────────────────────────────────────────────────────┘    │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  Services    │  │  Validators  │  │  Middlewares     │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Infrastructure                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  EF Core     │  │  Redis       │  │  Blob Storage    │  │
+│  │  Repository  │  │  Cache       │  │  (files)         │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Estrutura de Pastas
+
+```
+project/
+├── src/
+│   ├── api/                          # .NET Backend
+│   │   ├── Api/
+│   │   │   ├── Endpoints/
+│   │   │   │   ├── ProductEndpoints.cs
+│   │   │   │   ├── OrderEndpoints.cs
+│   │   │   │   └── UserEndpoints.cs
+│   │   │   ├── Middleware/
+│   │   │   └── Program.cs
+│   │   ├── Application/
+│   │   │   ├── Services/
+│   │   │   └── Validators/
+│   │   ├── Domain/
+│   │   │   ├── Entities/
+│   │   │   └── Interfaces/
+│   │   └── Infrastructure/
+│   │       ├── Data/
+│   │       └── Repositories/
+│   │
+│   └── web/                          # Next.js Frontend
+│       ├── app/
+│       │   ├── (auth)/
+│       │   │   ├── sign-in/
+│       │   │   └── sign-up/
+│       │   ├── (dashboard)/
+│       │   │   ├── dashboard/
+│       │   │   ├── products/
+│       │   │   └── orders/
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       ├── components/
+│       │   ├── ui/
+│       │   └── shared/
+│       ├── hooks/
+│       │   ├── use-products.ts
+│       │   └── use-orders.ts
+│       ├── lib/
+│       │   ├── api-client.ts
+│       │   └── utils.ts
+│       └── types/
+│
+├── infra/                            # Infrastructure as Code
+│   ├── main.bicep
+│   └── modules/
+│
+└── docker-compose.yml
+```
+
+## Quick Start
+
+### Backend (.NET)
+
+```bash
+cd src/api
+dotnet restore
+dotnet ef database update
+dotnet run
+```
+
+### Frontend (Next.js)
+
+```bash
+cd src/web
+npm install
+npm run dev
+```
+
+### Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+## Features
+
+### Backend
+- Minimal APIs com OpenAPI
+- FluentValidation para validação
+- EF Core com Repository Pattern
+- JWT Bearer Authentication
+- Health Checks
+- Structured Logging
+
+### Frontend
+- App Router (Next.js 14)
+- Server Components + Client Components
+- React Query para data fetching
+- Tailwind CSS + shadcn/ui
+- Form handling com React Hook Form
+- TypeScript estrito
+
+## Autenticação
+
+### Fluxo
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant NextJS
+    participant Clerk
+    participant API
+
+    User->>NextJS: Acessa /sign-in
+    NextJS->>Clerk: Redirect para Clerk
+    User->>Clerk: Login
+    Clerk-->>NextJS: JWT Token
+    NextJS->>API: Request com Bearer Token
+    API->>Clerk: Valida token (JWKS)
+    API-->>NextJS: Response
+    NextJS-->>User: Renderiza página
+```
+
+### Configuração Clerk (Next.js)
+
+```typescript
+// middleware.ts
+import { clerkMiddleware } from "@clerk/nextjs/server";
+
+export default clerkMiddleware();
+
+export const config = {
+  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
+};
+```
+
+### Configuração JWT (API)
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.Authority = builder.Configuration["Clerk:Authority"];
+        options.TokenValidationParameters = new TokenValidationParameters
+        {
+            ValidateAudience = false,
+            NameClaimType = "sub"
+        };
+    });
+```
+
+## API Client (Frontend)
+
+```typescript
+// lib/api-client.ts
+import { auth } from "@clerk/nextjs/server";
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL;
+
+export async function apiClient<T>(
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<T> {
+  const { getToken } = auth();
+  const token = await getToken();
+
+  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`API Error: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+```
+
+## Custos Estimados
+
+| Recurso | Tier | Custo/mês |
+|---------|------|-----------|
+| Container App (API) | Consumption | ~$0-5 |
+| Container App (Web) | Consumption | ~$0-5 |
+| SQL Database | Free 32GB | $0 |
+| Clerk | Free 10k MAU | $0 |
+
+**Total**: < $10/mês para MVPs
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/examples/api-nextjs/contracts.ts

@@ -0,0 +1,307 @@
+// ==============================================================================
+// API .NET + Next.js - Frontend Contracts (TypeScript)
+// Types compartilhados entre API e Frontend
+// ==============================================================================
+
+// ==============================================================================
+// PAGINATION
+// ==============================================================================
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortDesc?: boolean;
+  search?: string;
+}
+
+export interface PagedResult<T> {
+  items: T[];
+  totalItems: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+// ==============================================================================
+// ENTITIES
+// ==============================================================================
+
+export interface Product {
+  id: number;
+  name: string;
+  description?: string;
+  price: number;
+  stock: number;
+  category?: string;
+  imageUrl?: string;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export interface Order {
+  id: number;
+  orderNumber: string;
+  customerId: number;
+  customer?: Customer;
+  status: OrderStatus;
+  items: OrderItem[];
+  subtotal: number;
+  tax: number;
+  total: number;
+  notes?: string;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export interface OrderItem {
+  id: number;
+  productId: number;
+  product?: Product;
+  quantity: number;
+  unitPrice: number;
+  total: number;
+}
+
+export interface Customer {
+  id: number;
+  name: string;
+  email: string;
+  phone?: string;
+  address?: Address;
+  createdAt: string;
+}
+
+export interface Address {
+  street: string;
+  number: string;
+  complement?: string;
+  neighborhood: string;
+  city: string;
+  state: string;
+  zipCode: string;
+  country: string;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  name?: string;
+  imageUrl?: string;
+  role: UserRole;
+  createdAt: string;
+  lastLoginAt?: string;
+}
+
+// ==============================================================================
+// ENUMS
+// ==============================================================================
+
+export type OrderStatus =
+  | "Pending"
+  | "Confirmed"
+  | "Processing"
+  | "Shipped"
+  | "Delivered"
+  | "Cancelled";
+
+export type UserRole = "Admin" | "Manager" | "User" | "Viewer";
+
+export type ProductCategory =
+  | "Electronics"
+  | "Clothing"
+  | "Food"
+  | "Books"
+  | "Other";
+
+// ==============================================================================
+// REQUEST DTOs
+// ==============================================================================
+
+export interface CreateProductRequest {
+  name: string;
+  description?: string;
+  price: number;
+  stock: number;
+  category?: string;
+  imageUrl?: string;
+}
+
+export interface UpdateProductRequest {
+  name?: string;
+  description?: string;
+  price?: number;
+  stock?: number;
+  category?: string;
+  imageUrl?: string;
+  isActive?: boolean;
+}
+
+export interface CreateOrderRequest {
+  customerId: number;
+  items: CreateOrderItemRequest[];
+  notes?: string;
+}
+
+export interface CreateOrderItemRequest {
+  productId: number;
+  quantity: number;
+}
+
+export interface UpdateOrderStatusRequest {
+  status: OrderStatus;
+  notes?: string;
+}
+
+export interface CreateCustomerRequest {
+  name: string;
+  email: string;
+  phone?: string;
+  address?: Address;
+}
+
+// ==============================================================================
+// RESPONSE DTOs
+// ==============================================================================
+
+export interface ApiResponse<T> {
+  data: T;
+  success: boolean;
+  message?: string;
+}
+
+export interface ApiError {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  errors?: Record<string, string[]>;
+}
+
+export interface DashboardStats {
+  totalProducts: number;
+  totalOrders: number;
+  totalCustomers: number;
+  totalRevenue: number;
+  ordersToday: number;
+  revenueToday: number;
+  recentOrders: Order[];
+  topProducts: ProductSales[];
+}
+
+export interface ProductSales {
+  product: Product;
+  totalSold: number;
+  totalRevenue: number;
+}
+
+// ==============================================================================
+// FILTER DTOs
+// ==============================================================================
+
+export interface ProductFilters extends PaginationParams {
+  category?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  inStock?: boolean;
+  isActive?: boolean;
+}
+
+export interface OrderFilters extends PaginationParams {
+  status?: OrderStatus;
+  customerId?: number;
+  startDate?: string;
+  endDate?: string;
+  minTotal?: number;
+  maxTotal?: number;
+}
+
+export interface CustomerFilters extends PaginationParams {
+  city?: string;
+  state?: string;
+}
+
+// ==============================================================================
+// FORM SCHEMAS (Zod)
+// ==============================================================================
+
+// Exemplo de uso com Zod:
+/*
+import { z } from "zod";
+
+export const createProductSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  description: z.string().max(500).optional(),
+  price: z.number().positive("Price must be positive"),
+  stock: z.number().int().nonnegative("Stock cannot be negative"),
+  category: z.string().optional(),
+  imageUrl: z.string().url().optional(),
+});
+
+export type CreateProductFormData = z.infer<typeof createProductSchema>;
+
+export const createOrderSchema = z.object({
+  customerId: z.number().int().positive(),
+  items: z.array(z.object({
+    productId: z.number().int().positive(),
+    quantity: z.number().int().positive("Quantity must be at least 1"),
+  })).min(1, "At least one item is required"),
+  notes: z.string().max(500).optional(),
+});
+
+export type CreateOrderFormData = z.infer<typeof createOrderSchema>;
+*/
+
+// ==============================================================================
+// REACT QUERY KEYS
+// ==============================================================================
+
+export const queryKeys = {
+  products: {
+    all: ["products"] as const,
+    list: (filters: ProductFilters) => ["products", "list", filters] as const,
+    detail: (id: number) => ["products", "detail", id] as const,
+  },
+  orders: {
+    all: ["orders"] as const,
+    list: (filters: OrderFilters) => ["orders", "list", filters] as const,
+    detail: (id: number) => ["orders", "detail", id] as const,
+  },
+  customers: {
+    all: ["customers"] as const,
+    list: (filters: CustomerFilters) =>
+      ["customers", "list", filters] as const,
+    detail: (id: number) => ["customers", "detail", id] as const,
+  },
+  dashboard: ["dashboard"] as const,
+};
+
+// ==============================================================================
+// API ENDPOINTS
+// ==============================================================================
+
+export const apiEndpoints = {
+  products: {
+    list: "/api/products",
+    detail: (id: number) => `/api/products/${id}`,
+    create: "/api/products",
+    update: (id: number) => `/api/products/${id}`,
+    delete: (id: number) => `/api/products/${id}`,
+  },
+  orders: {
+    list: "/api/orders",
+    detail: (id: number) => `/api/orders/${id}`,
+    create: "/api/orders",
+    updateStatus: (id: number) => `/api/orders/${id}/status`,
+    cancel: (id: number) => `/api/orders/${id}/cancel`,
+  },
+  customers: {
+    list: "/api/customers",
+    detail: (id: number) => `/api/customers/${id}`,
+    create: "/api/customers",
+    update: (id: number) => `/api/customers/${id}`,
+  },
+  dashboard: "/api/dashboard",
+};