@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/docs/examples.md

@@ -1,328 +1,328 @@
-# MORPH-SPEC Examples Guide
-
-Guia dos exemplos incluídos no framework.
-
----
-
-## Visão Geral
-
-| Exemplo | Stack | Complexidade | Tempo Est. |
-|---------|-------|--------------|------------|
-| [micro-saas](#micro-saas) | Blazor + Asaas | Alta | 2-3 dias |
-| [api-nextjs](#api-nextjs) | .NET + Next.js | Média | 1-2 dias |
-| [multi-agent](#multi-agent) | Semantic Kernel | Alta | 2-3 dias |
-
----
-
-## micro-saas
-
-**Localização**: `.morph/examples/micro-saas/`
-
-### Descrição
-
-SaaS completo com multi-tenancy e billing integrado via Asaas.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Frontend | Blazor Server |
-| Backend | .NET 8 Minimal APIs |
-| Database | SQL Server |
-| Auth | Clerk |
-| Billing | Asaas |
-| Infra | Azure Container Apps |
-
-### Features
-
-- **Multi-tenancy**: Isolamento completo por tenant
-- **Subscription Management**: Planos Free, Starter, Pro, Enterprise
-- **Payment Methods**: PIX, Boleto, Cartão de Crédito
-- **Dashboard**: Métricas e gestão
-- **User Management**: Convites, roles (Owner, Admin, Member)
-- **Webhooks**: Processamento de eventos Asaas
-
-### Arquivos
-
-```
-micro-saas/
-├── README.md           # Visão geral e arquitetura
-├── spec.md             # Especificação completa
-├── contracts.cs        # 50+ interfaces e DTOs
-├── tasks.md            # 51 tasks organizadas
-└── decisions.md        # 10 ADRs documentados
-```
-
-### ADRs Principais
-
-| ADR | Decisão |
-|-----|---------|
-| ADR-001 | Blazor Server vs WebAssembly |
-| ADR-002 | Asaas vs Stripe |
-| ADR-003 | Clerk vs Azure AD B2C |
-| ADR-004 | Single DB com Query Filters |
-| ADR-005 | Tenant Resolution Strategy |
-
-### Para Começar
-
-```bash
-# 1. Copie o exemplo para seu projeto
-cp -r .morph/examples/micro-saas/ .morph/features/
-
-# 2. Revise a spec
-cat .morph/features/micro-saas/spec.md
-
-# 3. Ajuste para suas necessidades
-# Edite spec.md com seus requisitos específicos
-
-# 4. Implemente
-/morph-apply micro-saas
-```
-
-### Custos Estimados
-
-| Recurso | Custo/mês |
-|---------|-----------|
-| Container Apps | ~$0 (scale-to-zero) |
-| SQL Database | $0 (Free tier) |
-| Storage | ~$0.50 |
-| Asaas | 2.99% + R$0.49/transação |
-| **Total** | **< $5/mês** |
-
----
-
-## api-nextjs
-
-**Localização**: `.morph/examples/api-nextjs/`
-
-### Descrição
-
-Arquitetura full-stack com API .NET e frontend Next.js.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Frontend | Next.js 14 (App Router) |
-| Backend | .NET 8 Minimal APIs |
-| Database | SQL Server |
-| Auth | Clerk |
-| Data Fetching | React Query |
-| UI | Tailwind + shadcn/ui |
-
-### Features
-
-- **Minimal APIs**: Endpoints organizados e documentados
-- **App Router**: Server Components + Client Components
-- **React Query**: Cache, mutations, optimistic updates
-- **TypeScript**: Types compartilhados (contracts.ts)
-- **Forms**: React Hook Form + Zod validation
-- **Dark Mode**: Theme switching
-
-### Arquivos
-
-```
-api-nextjs/
-├── README.md           # Arquitetura e setup
-├── spec.md             # Especificação detalhada
-├── contracts.ts        # Types TypeScript compartilhados
-└── tasks.md            # 67 tasks organizadas
-```
-
-### Estrutura do Projeto
-
-```
-project/
-├── src/
-│   ├── api/            # .NET Backend
-│   │   ├── Api/
-│   │   ├── Application/
-│   │   ├── Domain/
-│   │   └── Infrastructure/
-│   │
-│   └── web/            # Next.js Frontend
-│       ├── app/
-│       ├── components/
-│       ├── hooks/
-│       ├── lib/
-│       └── types/
-│
-└── infra/              # IaC
-```
-
-### Para Começar
-
-```bash
-# 1. Copie o exemplo
-cp -r .morph/examples/api-nextjs/ .morph/features/
-
-# 2. Revise contracts.ts para seu domínio
-# Este arquivo define os types compartilhados
-
-# 3. Ajuste spec.md
-# Modifique entidades e endpoints para seu caso
-
-# 4. Implemente
-/morph-apply api-nextjs
-```
-
-### Patterns Demonstrados
-
-| Pattern | Descrição |
-|---------|-----------|
-| API Client | Fetch wrapper com auth |
-| Query Keys | Organização de cache keys |
-| Data Hooks | useProducts, useOrders |
-| Form Pattern | React Hook Form + Zod |
-| Server Components | Data fetching no servidor |
-
----
-
-## multi-agent
-
-**Localização**: `.morph/examples/multi-agent/`
-
-### Descrição
-
-Sistema de agentes AI cooperativos com Semantic Kernel.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Framework | Semantic Kernel |
-| LLM | Azure OpenAI |
-| Orchestration | Custom Orchestrator |
-| Storage | In-Memory / Cosmos DB |
-| Infra | Azure Container Apps |
-
-### Agentes
-
-| Agente | Responsabilidade |
-|--------|------------------|
-| **Orchestrator** | Coordena outros agentes |
-| **Research** | Busca e RAG |
-| **Analysis** | Análise e comparações |
-| **Writing** | Geração de texto |
-
-### Features
-
-- **Task Decomposition**: Quebra tarefas complexas
-- **Plugin System**: WebSearch, Documents, Calculator
-- **Conversation Memory**: Contexto por sessão
-- **Semantic Memory**: RAG com embeddings
-- **Streaming**: Server-Sent Events
-
-### Arquivos
-
-```
-multi-agent/
-├── README.md           # Visão geral
-├── spec.md             # Especificação detalhada
-├── contracts.cs        # Interfaces e DTOs
-└── tasks.md            # 53 tasks organizadas
-```
-
-### Fluxo de Execução
-
-```
-User Request
-    │
-    ▼
-┌─────────────┐
-│ Orchestrator│ → Decompõe tarefa
-└─────────────┘
-    │
-    ├──► Research Agent → Busca informações
-    │
-    ├──► Analysis Agent → Analisa dados
-    │
-    └──► Writing Agent → Gera output
-          │
-          ▼
-   Consolidated Response
-```
-
-### Para Começar
-
-```bash
-# 1. Configure Azure OpenAI
-# - Crie deployment gpt-4
-# - Crie deployment text-embedding-ada-002
-
-# 2. Copie o exemplo
-cp -r .morph/examples/multi-agent/ .morph/features/
-
-# 3. Configure appsettings
-# Adicione suas credenciais Azure OpenAI
-
-# 4. Implemente
-/morph-apply multi-agent
-```
-
-### Custos Estimados
-
-| Recurso | Custo |
-|---------|-------|
-| GPT-4 | ~$0.03/1K tokens |
-| Embeddings | ~$0.0001/1K tokens |
-| Container Apps | ~$0-10/mês |
-
-**Nota**: Custos variam com uso. Para dev, use gpt-3.5-turbo.
-
----
-
-## Como Usar os Exemplos
-
-### 1. Estudar a Estrutura
-
-Cada exemplo segue o padrão MORPH-SPEC:
-- `spec.md` - O quê construir
-- `contracts.cs/ts` - Interfaces e tipos
-- `tasks.md` - Como construir
-- `decisions.md` - Por que decisões foram tomadas
-
-### 2. Adaptar para Seu Projeto
-
-1. Copie o exemplo para `.morph/features/`
-2. Edite `spec.md` com seus requisitos
-3. Ajuste `contracts.cs` com suas entidades
-4. Revise `tasks.md` e remova o que não precisa
-
-### 3. Implementar
-
-```bash
-/morph-apply <nome-do-exemplo>
-```
-
-### 4. Customizar Templates
-
-Se precisar de padrões diferentes:
-1. Copie templates de `.morph/templates/`
-2. Modifique conforme necessário
-3. MORPH usará seus templates customizados
-
----
-
-## Comparação de Complexidade
-
-| Aspecto | micro-saas | api-nextjs | multi-agent |
-|---------|------------|------------|-------------|
-| **Entities** | 6 | 4 | 5 |
-| **Tasks** | 51 | 67 | 53 |
-| **Integrations** | 2 (Asaas, Clerk) | 1 (Clerk) | 2 (OpenAI, Bing) |
-| **IaC Resources** | 5 | 6 | 4 |
-| **Custo Infra** | < $5 | < $10 | Variável |
-
----
-
-## Próximos Passos
-
-1. Escolha o exemplo mais próximo do seu caso
-2. Leia a `spec.md` completa
-3. Revise os `contracts.*` para entender o modelo
-4. Use como base ou implemente diretamente
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# MORPH-SPEC Examples Guide
+
+Guia dos exemplos incluídos no framework.
+
+---
+
+## Visão Geral
+
+| Exemplo | Stack | Complexidade | Tempo Est. |
+|---------|-------|--------------|------------|
+| [micro-saas](#micro-saas) | Blazor + Asaas | Alta | 2-3 dias |
+| [api-nextjs](#api-nextjs) | .NET + Next.js | Média | 1-2 dias |
+| [multi-agent](#multi-agent) | Semantic Kernel | Alta | 2-3 dias |
+
+---
+
+## micro-saas
+
+**Localização**: `.morph/examples/micro-saas/`
+
+### Descrição
+
+SaaS completo com multi-tenancy e billing integrado via Asaas.
+
+### Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| Frontend | Blazor Server |
+| Backend | .NET 8 Minimal APIs |
+| Database | SQL Server |
+| Auth | Clerk |
+| Billing | Asaas |
+| Infra | Azure Container Apps |
+
+### Features
+
+- **Multi-tenancy**: Isolamento completo por tenant
+- **Subscription Management**: Planos Free, Starter, Pro, Enterprise
+- **Payment Methods**: PIX, Boleto, Cartão de Crédito
+- **Dashboard**: Métricas e gestão
+- **User Management**: Convites, roles (Owner, Admin, Member)
+- **Webhooks**: Processamento de eventos Asaas
+
+### Arquivos
+
+```
+micro-saas/
+├── README.md           # Visão geral e arquitetura
+├── spec.md             # Especificação completa
+├── contracts.cs        # 50+ interfaces e DTOs
+├── tasks.md            # 51 tasks organizadas
+└── decisions.md        # 10 ADRs documentados
+```
+
+### ADRs Principais
+
+| ADR | Decisão |
+|-----|---------|
+| ADR-001 | Blazor Server vs WebAssembly |
+| ADR-002 | Asaas vs Stripe |
+| ADR-003 | Clerk vs Azure AD B2C |
+| ADR-004 | Single DB com Query Filters |
+| ADR-005 | Tenant Resolution Strategy |
+
+### Para Começar
+
+```bash
+# 1. Copie o exemplo para seu projeto
+cp -r .morph/examples/micro-saas/ .morph/features/
+
+# 2. Revise a spec
+cat .morph/features/micro-saas/spec.md
+
+# 3. Ajuste para suas necessidades
+# Edite spec.md com seus requisitos específicos
+
+# 4. Implemente
+/morph-apply micro-saas
+```
+
+### Custos Estimados
+
+| Recurso | Custo/mês |
+|---------|-----------|
+| Container Apps | ~$0 (scale-to-zero) |
+| SQL Database | $0 (Free tier) |
+| Storage | ~$0.50 |
+| Asaas | 2.99% + R$0.49/transação |
+| **Total** | **< $5/mês** |
+
+---
+
+## api-nextjs
+
+**Localização**: `.morph/examples/api-nextjs/`
+
+### Descrição
+
+Arquitetura full-stack com API .NET e frontend Next.js.
+
+### Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| Frontend | Next.js 14 (App Router) |
+| Backend | .NET 8 Minimal APIs |
+| Database | SQL Server |
+| Auth | Clerk |
+| Data Fetching | React Query |
+| UI | Tailwind + shadcn/ui |
+
+### Features
+
+- **Minimal APIs**: Endpoints organizados e documentados
+- **App Router**: Server Components + Client Components
+- **React Query**: Cache, mutations, optimistic updates
+- **TypeScript**: Types compartilhados (contracts.ts)
+- **Forms**: React Hook Form + Zod validation
+- **Dark Mode**: Theme switching
+
+### Arquivos
+
+```
+api-nextjs/
+├── README.md           # Arquitetura e setup
+├── spec.md             # Especificação detalhada
+├── contracts.ts        # Types TypeScript compartilhados
+└── tasks.md            # 67 tasks organizadas
+```
+
+### Estrutura do Projeto
+
+```
+project/
+├── src/
+│   ├── api/            # .NET Backend
+│   │   ├── Api/
+│   │   ├── Application/
+│   │   ├── Domain/
+│   │   └── Infrastructure/
+│   │
+│   └── web/            # Next.js Frontend
+│       ├── app/
+│       ├── components/
+│       ├── hooks/
+│       ├── lib/
+│       └── types/
+│
+└── infra/              # IaC
+```
+
+### Para Começar
+
+```bash
+# 1. Copie o exemplo
+cp -r .morph/examples/api-nextjs/ .morph/features/
+
+# 2. Revise contracts.ts para seu domínio
+# Este arquivo define os types compartilhados
+
+# 3. Ajuste spec.md
+# Modifique entidades e endpoints para seu caso
+
+# 4. Implemente
+/morph-apply api-nextjs
+```
+
+### Patterns Demonstrados
+
+| Pattern | Descrição |
+|---------|-----------|
+| API Client | Fetch wrapper com auth |
+| Query Keys | Organização de cache keys |
+| Data Hooks | useProducts, useOrders |
+| Form Pattern | React Hook Form + Zod |
+| Server Components | Data fetching no servidor |
+
+---
+
+## multi-agent
+
+**Localização**: `.morph/examples/multi-agent/`
+
+### Descrição
+
+Sistema de agentes AI cooperativos com Semantic Kernel.
+
+### Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| Framework | Semantic Kernel |
+| LLM | Azure OpenAI |
+| Orchestration | Custom Orchestrator |
+| Storage | In-Memory / Cosmos DB |
+| Infra | Azure Container Apps |
+
+### Agentes
+
+| Agente | Responsabilidade |
+|--------|------------------|
+| **Orchestrator** | Coordena outros agentes |
+| **Research** | Busca e RAG |
+| **Analysis** | Análise e comparações |
+| **Writing** | Geração de texto |
+
+### Features
+
+- **Task Decomposition**: Quebra tarefas complexas
+- **Plugin System**: WebSearch, Documents, Calculator
+- **Conversation Memory**: Contexto por sessão
+- **Semantic Memory**: RAG com embeddings
+- **Streaming**: Server-Sent Events
+
+### Arquivos
+
+```
+multi-agent/
+├── README.md           # Visão geral
+├── spec.md             # Especificação detalhada
+├── contracts.cs        # Interfaces e DTOs
+└── tasks.md            # 53 tasks organizadas
+```
+
+### Fluxo de Execução
+
+```
+User Request
+    │
+    ▼
+┌─────────────┐
+│ Orchestrator│ → Decompõe tarefa
+└─────────────┘
+    │
+    ├──► Research Agent → Busca informações
+    │
+    ├──► Analysis Agent → Analisa dados
+    │
+    └──► Writing Agent → Gera output
+          │
+          ▼
+   Consolidated Response
+```
+
+### Para Começar
+
+```bash
+# 1. Configure Azure OpenAI
+# - Crie deployment gpt-4
+# - Crie deployment text-embedding-ada-002
+
+# 2. Copie o exemplo
+cp -r .morph/examples/multi-agent/ .morph/features/
+
+# 3. Configure appsettings
+# Adicione suas credenciais Azure OpenAI
+
+# 4. Implemente
+/morph-apply multi-agent
+```
+
+### Custos Estimados
+
+| Recurso | Custo |
+|---------|-------|
+| GPT-4 | ~$0.03/1K tokens |
+| Embeddings | ~$0.0001/1K tokens |
+| Container Apps | ~$0-10/mês |
+
+**Nota**: Custos variam com uso. Para dev, use gpt-3.5-turbo.
+
+---
+
+## Como Usar os Exemplos
+
+### 1. Estudar a Estrutura
+
+Cada exemplo segue o padrão MORPH-SPEC:
+- `spec.md` - O quê construir
+- `contracts.cs/ts` - Interfaces e tipos
+- `tasks.md` - Como construir
+- `decisions.md` - Por que decisões foram tomadas
+
+### 2. Adaptar para Seu Projeto
+
+1. Copie o exemplo para `.morph/features/`
+2. Edite `spec.md` com seus requisitos
+3. Ajuste `contracts.cs` com suas entidades
+4. Revise `tasks.md` e remova o que não precisa
+
+### 3. Implementar
+
+```bash
+/morph-apply <nome-do-exemplo>
+```
+
+### 4. Customizar Templates
+
+Se precisar de padrões diferentes:
+1. Copie templates de `.morph/templates/`
+2. Modifique conforme necessário
+3. MORPH usará seus templates customizados
+
+---
+
+## Comparação de Complexidade
+
+| Aspecto | micro-saas | api-nextjs | multi-agent |
+|---------|------------|------------|-------------|
+| **Entities** | 6 | 4 | 5 |
+| **Tasks** | 51 | 67 | 53 |
+| **Integrations** | 2 (Asaas, Clerk) | 1 (Clerk) | 2 (OpenAI, Bing) |
+| **IaC Resources** | 5 | 6 | 4 |
+| **Custo Infra** | < $5 | < $10 | Variável |
+
+---
+
+## Próximos Passos
+
+1. Escolha o exemplo mais próximo do seu caso
+2. Leia a `spec.md` completa
+3. Revise os `contracts.*` para entender o modelo
+4. Use como base ou implemente diretamente
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*