@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/stacks/blazor-azure/.morph/examples/api-nextjs/contracts.ts

@@ -1,307 +0,0 @@
-// ==============================================================================
-// 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",
-};

package/stacks/blazor-azure/.morph/examples/api-nextjs/spec.md

@@ -1,399 +0,0 @@
-# API .NET + Next.js - Especificação
-
-## 1. Visão Geral
-
-Arquitetura full-stack moderna com API .NET e frontend Next.js, seguindo boas práticas de separação de responsabilidades.
-
-### 1.1 Objetivos
-
-- Backend robusto com .NET Minimal APIs
-- Frontend moderno com Next.js App Router
-- Autenticação unificada via Clerk
-- Type-safety end-to-end
-- Deploy independente de cada camada
-
-### 1.2 Use Cases
-
-- Dashboards administrativos
-- Aplicações CRUD complexas
-- Sistemas que precisam de SEO (Next.js SSR)
-- Aplicações com múltiplos frontends (web, mobile)
-
-## 2. Requisitos Funcionais
-
-### 2.1 Backend (.NET API)
-
-| ID | Requisito |
-|----|-----------|
-| API-001 | Minimal APIs com OpenAPI/Swagger |
-| API-002 | Autenticação JWT via Clerk |
-| API-003 | Validação com FluentValidation |
-| API-004 | Paginação, filtros e ordenação |
-| API-005 | Rate limiting por usuário |
-| API-006 | Health checks (liveness + readiness) |
-| API-007 | Logging estruturado |
-| API-008 | CORS configurável |
-
-### 2.2 Frontend (Next.js)
-
-| ID | Requisito |
-|----|-----------|
-| WEB-001 | App Router com layouts aninhados |
-| WEB-002 | Server Components para dados estáticos |
-| WEB-003 | Client Components para interatividade |
-| WEB-004 | React Query para cache e mutations |
-| WEB-005 | Forms com React Hook Form + Zod |
-| WEB-006 | UI com Tailwind + shadcn/ui |
-| WEB-007 | Dark mode support |
-| WEB-008 | Loading states e error boundaries |
-
-### 2.3 Autenticação
-
-| ID | Requisito |
-|----|-----------|
-| AUTH-001 | SSO via Clerk |
-| AUTH-002 | Proteção de rotas (middleware) |
-| AUTH-003 | Token refresh automático |
-| AUTH-004 | Role-based access control |
-
-## 3. Requisitos Não-Funcionais
-
-### 3.1 Performance
-
-| ID | Requisito |
-|----|-----------|
-| PERF-001 | API response < 100ms (P95) |
-| PERF-002 | LCP < 2.5s (Core Web Vitals) |
-| PERF-003 | FID < 100ms |
-| PERF-004 | CLS < 0.1 |
-
-### 3.2 Segurança
-
-| ID | Requisito |
-|----|-----------|
-| SEC-001 | HTTPS obrigatório |
-| SEC-002 | CORS restrito a domínios conhecidos |
-| SEC-003 | Input validation em todos endpoints |
-| SEC-004 | SQL injection prevention (EF Core) |
-| SEC-005 | XSS prevention (React default) |
-
-## 4. Arquitetura da API
-
-### 4.1 Estrutura de Camadas
-
-```
-Api/
-├── Endpoints/          # Minimal API endpoints
-├── Middleware/         # Custom middlewares
-├── Filters/            # Exception filters
-└── Program.cs          # Entry point
-
-Application/
-├── Services/           # Business logic
-├── Validators/         # FluentValidation
-└── DTOs/               # Data transfer objects
-
-Domain/
-├── Entities/           # Domain models
-├── Interfaces/         # Repository contracts
-└── Enums/              # Domain enums
-
-Infrastructure/
-├── Data/               # DbContext
-├── Repositories/       # EF Core implementations
-└── Services/           # External service clients
-```
-
-### 4.2 Endpoint Pattern
-
-```csharp
-// Endpoints/ProductEndpoints.cs
-public static class ProductEndpoints
-{
-    public static void MapProductEndpoints(this IEndpointRouteBuilder app)
-    {
-        var group = app.MapGroup("/api/products")
-            .WithTags("Products")
-            .RequireAuthorization();
-
-        group.MapGet("/", GetAll);
-        group.MapGet("/{id:int}", GetById);
-        group.MapPost("/", Create);
-        group.MapPut("/{id:int}", Update);
-        group.MapDelete("/{id:int}", Delete);
-    }
-
-    private static async Task<IResult> GetAll(
-        [AsParameters] PaginationQuery query,
-        IProductService service,
-        CancellationToken ct)
-    {
-        var result = await service.GetAllAsync(query, ct);
-        return Results.Ok(result);
-    }
-}
-```
-
-### 4.3 Pagination
-
-```csharp
-public record PaginationQuery(
-    int Page = 1,
-    int PageSize = 20,
-    string? SortBy = null,
-    bool SortDesc = false,
-    string? Search = null
-);
-
-public record PagedResult<T>(
-    IReadOnlyList<T> Items,
-    int TotalItems,
-    int Page,
-    int PageSize,
-    int TotalPages
-);
-```
-
-## 5. Arquitetura do Frontend
-
-### 5.1 Estrutura de Pastas
-
-```
-app/
-├── (auth)/
-│   ├── sign-in/[[...sign-in]]/page.tsx
-│   └── sign-up/[[...sign-up]]/page.tsx
-├── (dashboard)/
-│   ├── layout.tsx              # Dashboard layout
-│   ├── dashboard/page.tsx
-│   ├── products/
-│   │   ├── page.tsx            # List
-│   │   ├── [id]/page.tsx       # Detail
-│   │   └── new/page.tsx        # Create
-│   └── orders/
-├── api/                        # API routes (BFF)
-├── layout.tsx                  # Root layout
-└── page.tsx                    # Landing
-
-components/
-├── ui/                         # shadcn components
-├── forms/                      # Form components
-├── tables/                     # Table components
-└── shared/                     # Shared components
-
-hooks/
-├── use-products.ts
-├── use-orders.ts
-└── use-pagination.ts
-
-lib/
-├── api-client.ts               # Fetch wrapper
-├── query-client.ts             # React Query config
-└── utils.ts                    # Utility functions
-
-types/
-├── api.ts                      # API response types
-└── entities.ts                 # Domain types
-```
-
-### 5.2 Data Fetching Pattern
-
-```typescript
-// hooks/use-products.ts
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { apiClient } from "@/lib/api-client";
-import type { Product, CreateProductRequest } from "@/types/entities";
-
-export function useProducts(params?: PaginationParams) {
-  return useQuery({
-    queryKey: ["products", params],
-    queryFn: () => apiClient<PagedResult<Product>>("/api/products", { params }),
-  });
-}
-
-export function useProduct(id: number) {
-  return useQuery({
-    queryKey: ["products", id],
-    queryFn: () => apiClient<Product>(`/api/products/${id}`),
-    enabled: !!id,
-  });
-}
-
-export function useCreateProduct() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: CreateProductRequest) =>
-      apiClient<Product>("/api/products", {
-        method: "POST",
-        body: JSON.stringify(data),
-      }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["products"] });
-    },
-  });
-}
-```
-
-### 5.3 Form Pattern
-
-```typescript
-// components/forms/product-form.tsx
-"use client";
-
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-import { useCreateProduct } from "@/hooks/use-products";
-
-const schema = z.object({
-  name: z.string().min(1, "Name is required"),
-  price: z.number().positive("Price must be positive"),
-  description: z.string().optional(),
-});
-
-type FormData = z.infer<typeof schema>;
-
-export function ProductForm() {
-  const { mutate, isPending } = useCreateProduct();
-  const form = useForm<FormData>({
-    resolver: zodResolver(schema),
-  });
-
-  const onSubmit = (data: FormData) => {
-    mutate(data);
-  };
-
-  return (
-    <form onSubmit={form.handleSubmit(onSubmit)}>
-      {/* Form fields */}
-    </form>
-  );
-}
-```
-
-## 6. Comunicação API
-
-### 6.1 API Client
-
-```typescript
-// lib/api-client.ts
-import { auth } from "@clerk/nextjs/server";
-
-const API_URL = process.env.NEXT_PUBLIC_API_URL;
-
-interface FetchOptions extends RequestInit {
-  params?: Record<string, string | number | undefined>;
-}
-
-export async function apiClient<T>(
-  endpoint: string,
-  options: FetchOptions = {}
-): Promise<T> {
-  const { params, ...init } = options;
-
-  // Build URL with query params
-  const url = new URL(`${API_URL}${endpoint}`);
-  if (params) {
-    Object.entries(params).forEach(([key, value]) => {
-      if (value !== undefined) {
-        url.searchParams.append(key, String(value));
-      }
-    });
-  }
-
-  // Get auth token
-  const { getToken } = auth();
-  const token = await getToken();
-
-  const response = await fetch(url.toString(), {
-    ...init,
-    headers: {
-      "Content-Type": "application/json",
-      ...(token && { Authorization: `Bearer ${token}` }),
-      ...init.headers,
-    },
-  });
-
-  if (!response.ok) {
-    const error = await response.json().catch(() => ({}));
-    throw new ApiError(response.status, error.title || "Request failed", error);
-  }
-
-  return response.json();
-}
-
-class ApiError extends Error {
-  constructor(
-    public status: number,
-    message: string,
-    public details?: unknown
-  ) {
-    super(message);
-    this.name = "ApiError";
-  }
-}
-```
-
-## 7. Configurações
-
-### 7.1 API (appsettings.json)
-
-```json
-{
-  "ConnectionStrings": {
-    "DefaultConnection": "Server=...;Database=...;"
-  },
-  "Clerk": {
-    "Authority": "https://your-clerk-domain.clerk.accounts.dev",
-    "SecretKey": "sk_..."
-  },
-  "Cors": {
-    "AllowedOrigins": ["http://localhost:3000", "https://your-domain.com"]
-  }
-}
-```
-
-### 7.2 Frontend (.env.local)
-
-```env
-NEXT_PUBLIC_API_URL=http://localhost:5000
-NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
-CLERK_SECRET_KEY=sk_...
-```
-
-## 8. Deploy
-
-### 8.1 Docker
-
-```dockerfile
-# API Dockerfile
-FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
-WORKDIR /app
-EXPOSE 8080
-
-FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
-WORKDIR /src
-COPY ["src/api/Api/Api.csproj", "Api/"]
-RUN dotnet restore "Api/Api.csproj"
-COPY src/api/ .
-RUN dotnet build "Api/Api.csproj" -c Release -o /app/build
-
-FROM build AS publish
-RUN dotnet publish "Api/Api.csproj" -c Release -o /app/publish
-
-FROM base AS final
-WORKDIR /app
-COPY --from=publish /app/publish .
-ENTRYPOINT ["dotnet", "Api.dll"]
-```
-
-### 8.2 Container Apps
-
-Dois Container Apps separados:
-- `app-api`: .NET API
-- `app-web`: Next.js (com output: standalone)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*