Infraestrutura digital comunitária orientada ao território

12. Criar ou atualizar loja

Moradores validados podem criar ou atualizar sua loja no território via POST /api/v1/stores. A loja define informações de contato e visibilidade.

curl -X POST http://localhost:8080/api/v1/stores \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "displayName": "Loja da Ana",
    "description": "Produtos artesanais",
    "contactVisibility": "Public",
    "contact": {
      "phone": "+5511999999999",
      "email": "ana@exemplo.com"
    }
  }'

13. Criar item (produto ou serviço) com imagens

Lojas podem criar items via POST /api/v1/items. Items podem ser produtos ou serviços, com preço fixo, negociável ou gratuito. Items podem incluir até 10 imagens através do campo mediaIds.

curl -X POST http://localhost:8080/api/v1/items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "storeId": "22222222-2222-2222-2222-222222222222",
    "type": "Product",
    "title": "Bolo de chocolate",
    "description": "Bolo caseiro",
    "category": "Alimentos",
    "tags": "bolo,chocolate",
    "pricingType": "Fixed",
    "priceAmount": 25.00,
    "currency": "BRL",
    "unit": "unidade",
    "latitude": -23.55,
    "longitude": -46.63,
    "mediaIds": ["dddddddd-dddd-dddd-dddd-dddddddddddd", "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"]
  }'

14. Buscar items

Use GET /api/v1/items para buscar produtos e serviços por território, categoria, tags ou texto livre (q).

curl "http://localhost:8080/api/v1/items?territoryId=11111111-1111-1111-1111-111111111111&q=bolo&category=Alimentos" \
  -H "Authorization: Bearer <token>"

15. Gerenciar carrinho

Usuários podem adicionar itens ao carrinho via POST /api/v1/cart/items, atualizar quantidade via PATCH /api/v1/cart/items/{id} e fazer checkout via POST /api/v1/cart/checkout.

curl -X POST http://localhost:8080/api/v1/cart/items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "itemId": "33333333-3333-3333-3333-333333333333",
    "quantity": 2,
    "notes": "Entregar após 18h (se possível)"
  }'

16. Criar inquiry

Interessados podem criar inquiries diretamente em items via POST /api/v1/items/{id}/inquiries.

curl -X POST http://localhost:8080/api/v1/items/{id}/inquiries \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Gostaria de mais informações"}'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

📋 Passo 1: Entendendo o Fluxo de Payout

Quando um cliente compra algo na loja de um vendedor e o pagamento é confirmado, o seguinte acontece:

1. Checkout pago → Sistema cria SellerTransaction automaticamente
2. Valor líquido → Subtotal - Fees da plataforma = Valor para o vendedor
3. Período de retenção → Aguarda dias configurados (ex: 7 dias)
4. Valor mínimo → Acumula até atingir valor mínimo configurado (ex: R$ 100,00)
5. Payout automático → Background worker processa quando todas as condições são atendidas
6. Transferência → Dinheiro é transferido para o vendedor via gateway (Stripe, MercadoPago, etc.)

⚙️ Passo 2: Configurar Payout para um Território

Antes de usar o sistema de payout, você precisa configurar como ele funciona para cada território. Essa configuração define período de retenção, valores mínimo/máximo, frequência e se requer aprovação manual.

# Criar ou atualizar configuração de payout
curl -X POST "http://localhost:8080/api/v1/territories/{territoryId}/payout-config" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retentionPeriodDays": 7,
    "minimumPayoutAmountInCents": 10000,
    "maximumPayoutAmountInCents": 5000000,
    "frequency": "Weekly",
    "autoPayoutEnabled": true,
    "requiresApproval": false,
    "currency": "BRL"
  }'

🔍 Passo 3: Consultar Configuração de Payout

Para ver a configuração atual de payout de um território:

# Consultar configuração ativa
curl "http://localhost:8080/api/v1/territories/{territoryId}/payout-config" \
  -H "Authorization: Bearer <token>"

💰 Passo 4: Consultar Saldo do Vendedor

Vendedores podem consultar seu saldo e histórico de transações:

# Consultar meu saldo como vendedor
curl "http://localhost:8080/api/v1/territories/{territoryId}/seller-balance/me" \
  -H "Authorization: Bearer <token>"

# Consultar minhas transações como vendedor
curl "http://localhost:8080/api/v1/territories/{territoryId}/seller-balance/me/transactions" \
  -H "Authorization: Bearer <token>"

📈 Passo 5: Gestão Financeira da Plataforma

Administradores podem consultar o saldo financeiro da plataforma (receitas de fees e despesas de payouts):

# Consultar saldo da plataforma (apenas SystemAdmin ou FinancialManager)
curl "http://localhost:8080/api/v1/territories/{territoryId}/platform-financial/balance" \
  -H "Authorization: Bearer <token>"

# Listar receitas (fees coletadas)
curl "http://localhost:8080/api/v1/territories/{territoryId}/platform-financial/revenue" \
  -H "Authorization: Bearer <token>"

# Listar despesas (payouts processados)
curl "http://localhost:8080/api/v1/territories/{territoryId}/platform-financial/expenses" \
  -H "Authorization: Bearer <token>"

🔧 Passo 6: Configuração em Produção - Checklist

Para colocar o sistema de payout em produção, siga este checklist:

🏗️ Passo 7: Implementar Gateway de Pagamento Real

O sistema vem com um MockPayoutGateway para desenvolvimento. Para produção, você precisa implementar o IPayoutGateway para seu gateway de pagamento preferido (Stripe Connect, MercadoPago, etc.).

public interface IPayoutGateway
{
  Task<OperationResult<PayoutResult>> CreatePayoutAsync(
    long amountInCents,
    string currency,
    string sellerAccountId,
    string description,
    Dictionary<string, string>? metadata,
    CancellationToken cancellationToken);

  Task<OperationResult<PayoutStatusResult>> GetPayoutStatusAsync(
    string payoutId,
    CancellationToken cancellationToken);

  Task<OperationResult> CancelPayoutAsync(
    string payoutId,
    CancellationToken cancellationToken);
}

🔄 Passo 8: Como Funciona o Background Worker

O PayoutProcessingWorker verifica payouts pendentes a cada 5 minutos e processa automaticamente conforme a frequência configurada:

• Daily: Processa payouts todos os dias (quando o worker roda)
• Weekly: Processa payouts toda segunda-feira às 00:00 UTC
• Monthly: Processa payouts no dia 1 de cada mês às 00:00 UTC
• Manual: Não processa automaticamente - apenas quando chamado manualmente via API

O worker está configurado automaticamente quando você roda a API. Não precisa fazer nada extra para ativá-lo.

📊 Passo 9: Monitoramento e Troubleshooting

Para monitorar o sistema de payout em produção:

• Logs do Worker: Procure por PayoutProcessingWorker nos logs para ver processamento
• Transações Financeiras: Consulte GET /api/v1/territories/{territoryId}/platform-financial/revenue para receitas
• Transações de Despesa: Consulte GET /api/v1/territories/{territoryId}/platform-financial/expenses para payouts
• Status de Payouts: Use UpdatePayoutStatusAsync para atualizar status do gateway periodicamente

17. Criar evento com imagem de capa e imagens adicionais

Use POST /api/v1/events para criar eventos. O evento automaticamente gera um post no feed e aparece no mapa. Eventos podem incluir uma imagem de capa (coverMediaId) e até 10 imagens adicionais (additionalMediaIds).

curl -X POST http://localhost:8080/api/v1/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "title": "Feira de artesanato",
    "description": "Feira mensal no centro",
    "startsAtUtc": "2024-12-15T10:00:00Z",
    "endsAtUtc": "2024-12-15T18:00:00Z",
    "latitude": -23.55,
    "longitude": -46.63,
    "locationLabel": "Praça Central",
    "coverMediaId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "additionalMediaIds": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"]
  }'

18. Interesse e confirmação em eventos

Usuários podem marcar interesse via POST /api/v1/events/{eventId}/interest e confirmar participação via POST /api/v1/events/{eventId}/confirm.

# Marcar interesse
curl -X POST http://localhost:8080/api/v1/events/{eventId}/interest \
  -H "Authorization: Bearer <token>" \

# Confirmar participação
curl -X POST http://localhost:8080/api/v1/events/{eventId}/confirm \
  -H "Authorization: Bearer <token>"

19. Listar tarefas pendentes

Use GET /api/v1/work-queue para listar tarefas pendentes. Você pode filtrar por território, tipo de tarefa e status.

curl "http://localhost:8080/api/v1/work-queue?territoryId=11111111-1111-1111-1111-111111111111&status=Pending" \
  -H "Authorization: Bearer <token>"

20. Processar tarefa

Use POST /api/v1/work-queue/{id}/process para processar uma tarefa. Você pode aprovar, rejeitar ou adiar a tarefa.

curl -X POST http://localhost:8080/api/v1/work-queue/{id}/process \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Approve",
    "notes": "Aprovado após verificação"
  }'

⚙️ Configuração Avançada de Limites de Mídia por Território

Cada território pode configurar limites personalizados de tamanho e tipos MIME para mídias (imagens, vídeos e áudios) em diferentes contextos (Posts, Eventos, Marketplace, Chat). Os limites territoriais não podem exceder os limites globais do sistema, garantindo consistência e controle centralizado.

📋 Estrutura da Configuração

A configuração permite ajustar limites separadamente para cada contexto:

• Posts: Limites para mídias em posts do feed
• Eventos: Limites para mídias de capa e adicionais em eventos
• Marketplace: Limites para mídias em itens do marketplace
• Chat: Limites para imagens e áudios em mensagens (vídeos sempre bloqueados)

🔒 Limites Globais vs Territoriais

O sistema possui limites globais configurados em MediaStorageOptions que definem os valores máximos permitidos em toda a plataforma. Os limites territoriais podem ser mais restritivos, mas nunca mais permissivos que os globais:

• Limites globais (padrão): Imagens 10MB, Vídeos 50MB, Áudios 20MB
• Limites territoriais: Podem ser menores que os globais (ex: 5MB para imagens), mas nunca maiores
• Tipos MIME: Podem ser restringidos por território (ex: apenas JPEG para imagens)
• Fallback automático: Se não configurado, usa limites globais

📝 Exemplo: Atualizar Limites de Posts

# Atualizar limites de mídia para Posts (como Curator)
curl -X PUT "http://localhost:8080/api/v1/territories/{territoryId}/media-config" \
  -H "Authorization: Bearer <curator-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": {
      "imagesEnabled": true,
      "videosEnabled": true,
      "audioEnabled": true,
      "maxMediaCount": 10,
      "maxVideoCount": 1,
      "maxAudioCount": 1,
      "maxImageSizeBytes": 5242880,
      "maxVideoSizeBytes": 26214400,
      "maxAudioSizeBytes": 5242880,
      "maxVideoDurationSeconds": 60,
      "maxAudioDurationSeconds": 300,
      "allowedImageMimeTypes": ["image/jpeg", "image/png"],
      "allowedVideoMimeTypes": ["video/mp4"],
      "allowedAudioMimeTypes": ["audio/mpeg", "audio/wav"]
    },
    "events": null,
    "marketplace": null,
    "chat": null
  }'

🔄 Atualização Parcial

Você pode atualizar apenas uma parte da configuração. Os campos não especificados mantêm seus valores atuais:

# Atualizar apenas limites de Chat
curl -X PUT "http://localhost:8080/api/v1/territories/{territoryId}/media-config" \
  -H "Authorization: Bearer <curator-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": null,
    "events": null,
    "marketplace": null,
    "chat": {
      "imagesEnabled": true,
      "audioEnabled": true,
      "maxImageSizeBytes": 2097152,
      "maxAudioSizeBytes": 1048576,
      "maxAudioDurationSeconds": 60
    }
  }'

Endpoint

POST /api/v1/auth/social

Exemplo de Requisição

curl -X POST http://localhost:8080/api/v1/auth/social \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "externalId": "abc-123",
    "displayName": "Ana Souza",
    "cpf": "12345678900",
    "email": "ana@exemplo.com"
  }'

Diagrama de Sequência

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

Endpoints

• Territórios próximos: GET /api/v1/territories/nearby?lat=-23.55&lng=-46.63
• Listar todos: GET /api/v1/territories

Exemplo de Requisição

curl "http://localhost:8080/api/v1/territories/nearby?lat=-23.55&lng=-46.63" \
  -H "Authorization: Bearer <token>"

Diagrama de Sequência

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

Fluxo Completo

1. Criar loja: POST /api/v1/stores
2. Adicionar itens: POST /api/v1/items
3. Adicionar ao carrinho: POST /api/v1/cart/items
4. Checkout: POST /api/v1/cart/checkout
5. Marcar como pago: PATCH /api/v1/cart/checkout/{id}/status (Status: Paid)
6. Payout automático: Sistema processa payout conforme configuração

Diagrama de Sequência

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

Quickstart - Copie e cole (5–10 comandos)

# 1) Rodar API
ASPNETCORE_ENVIRONMENT=Development dotnet run --project backend/Arah.Api --urls http://localhost:8080

# 2) Autenticação social (gera token)
curl -X POST http://localhost:8080/api/v1/auth/social \
  -H "Content-Type: application/json" \
  -d '{"provider":"google","externalId":"abc-123","displayName":"Ana","cpf":"12345678900"}'

# 3) Descobrir território
curl http://localhost:8080/api/v1/territories

# 4) Selecionar território (X-Session-Id)
curl -X POST http://localhost:8080/api/v1/territories/selection \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{"territoryId":"11111111-1111-1111-1111-111111111111"}'

# 1) Rodar API
$env:ASPNETCORE_ENVIRONMENT="Development"
dotnet run --project backend/Arah.Api --urls "http://localhost:8080"

# 2) Autenticação social (gera token)
curl.exe -X POST "http://localhost:8080/api/v1/auth/social" `
  -H "Content-Type: application/json" `
  -d "{\"provider\":\"google\",\"externalId\":\"abc-123\",\"displayName\":\"Ana\",\"cpf\":\"12345678900\"}"

# 3) Descobrir território
curl.exe "http://localhost:8080/api/v1/territories"

# 4) Selecionar território (X-Session-Id)
curl.exe -X POST "http://localhost:8080/api/v1/territories/selection" `
  -H "Content-Type: application/json" `
  -H "X-Session-Id: session-123" `
  -d "{\"territoryId\":\"11111111-1111-1111-1111-111111111111\"}"

1. Autenticação social → JWT

Use POST /api/v1/auth/social com Provider, ExternalId, DisplayName e CPF ou ForeignDocument. A resposta traz o token JWT.

curl -X POST http://localhost:8080/api/v1/auth/social \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "externalId": "abc-123",
    "displayName": "Ana Souza",
    "cpf": "12345678900",
    "email": "ana@exemplo.com"
  }'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

2. Descoberta de território

GET /api/v1/territories lista territórios disponíveis. Para busca, use /search ou /nearby com lat e lng.

curl "http://localhost:8080/api/v1/territories/nearby?lat=-23.55&lng=-46.63&radiusKm=10"

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

3. Seleção de território (sessão)

Defina o território ativo com POST /api/v1/territories/selection usando X-Session-Id. Esse header substitui o territoryId em várias rotas.

curl -X POST http://localhost:8080/api/v1/territories/selection \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{"territoryId": "11111111-1111-1111-1111-111111111111"}'

4. Feed territorial

GET /api/v1/feed retorna posts filtrados pelo território ativo. Visitantes veem apenas posts públicos publicados. Moradores veem conteúdo ampliado.

curl http://localhost:8080/api/v1/feed \
  -H "Authorization: Bearer <token>" \
  -H "X-Session-Id: session-123"

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

5. Criar post + âncoras geográficas + mídias

Para criar post use POST /api/v1/feed. As âncoras geográficas são opcionais e posts são criados por moradores. Posts podem incluir até 10 mídias (imagens, vídeos e/ou áudios) através do campo mediaIds, com no máximo 1 vídeo e 1 áudio por post. Eventos são criados via POST /api/v1/events, com data/hora e geolocalização obrigatória, e aparecem no feed e no mapa.

curl -X POST http://localhost:8080/api/v1/feed \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{
    "title": "Mutirão de limpeza",
    "content": "Encontro sábado 9h.",
    "type": "General",
    "visibility": "Public",
    "mapEntityId": null,
    "geoAnchors": [{"latitude": -23.55, "longitude": -46.63, "type": "POST"}],
    "assetIds": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"],
    "mediaIds": ["bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "cccccccc-cccc-cccc-cccc-cccccccccccc"]
  }'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

5a. Criar evento comunitário

Eventos são criados via POST /api/v1/events com data/hora e geolocalização obrigatória. Eventos aparecem automaticamente no feed e no mapa. Usuários podem marcar interesse ou confirmação.

curl -X POST http://localhost:8080/api/v1/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "title": "Mutirão de limpeza",
    "description": "Encontro sábado 9h",
    "startsAtUtc": "2025-01-25T09:00:00Z",
    "latitude": -23.55,
    "longitude": -46.63,
    "locationLabel": "Praça Central"
  }'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

6. Assets territoriais (com geolocalização obrigatória)

Assets sempre possuem ao menos uma âncora geográfica e são exibidos no mapa via pins do tipo asset. Somente moradores validados ou curadores podem criar/editar/arquivar.

curl -X POST http://localhost:8080/api/v1/assets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111",
    "type": "river",
    "name": "Rio do Vale",
    "description": "Trecho monitorado",
    "geoAnchors": [{"latitude": -23.55, "longitude": -46.63}]
  }'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

7. Alertas ambientais (feed + mapa)

Alertas usam /api/v1/alerts e aparecem no feed e no mapa (pins do tipo alert) quando validados por curadores.

curl -X POST http://localhost:8080/api/v1/alerts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-123" \
  -d '{"title": "Queimada", "description": "Fumaça próxima à nascente"}'

8. Mapa: entidades, pins e validação

Use GET /api/v1/map/entities e /pins para visualizar. Sugestões usam POST /api/v1/map/entities (categorias: estabelecimento, órgão do governo, espaço público, espaço natural). Confirmações usam /confirmations e validações /validation são exclusivas para curadores. Pins aceitam filtros por types, assetId e assetTypes.

curl http://localhost:8080/api/v1/map/pins?types=asset,alert,entity \
  -H "Authorization: Bearer <token>" \
  -H "X-Session-Id: session-123"

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

9. Membership: visitor → resident

O visitante solicita residência via POST /api/v1/memberships/{territoryId}/become-resident (convite direcionado via recipientUserIds ou fila de curadoria). Destinatários (ou curadores) aprovam em POST /api/v1/join-requests/{id}/approve, promovendo para RESIDENT (com ResidencyVerification=NONE). O status atual do vínculo está em GET /api/v1/memberships/{territoryId}/me. Para verificar residência (geo/doc), use /verify-residency/geo ou /verify-residency/document. Quando a policy exige presença, envie X-Geo-Latitude/X-Geo-Longitude.

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

10. Moderação & segurança: reports, triagem e bloqueios

O fluxo típico é: (1) um usuário reporta; (2) a curadoria lista reports do território e prioriza; (3) quando necessário, aplica bloqueio para cortar propagação do conteúdo no feed e no mapa. Reports usam reason (obrigatório) e details (opcional).

# Reportar um post
curl -X POST http://localhost:8080/api/v1/reports/posts/{postId} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Spam","details":"Link suspeito no conteúdo"}'

# Reportar um usuário (opcionalmente por território)
curl -X POST "http://localhost:8080/api/v1/reports/users/{userId}?territoryId=11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Abuso","details":"Comportamento inadequado"}'

# Curadoria lista reports para triagem
curl "http://localhost:8080/api/v1/reports?territoryId=11111111-1111-1111-1111-111111111111&status=Open" \
  -H "Authorization: Bearer <token>"

# Bloquear / desbloquear um usuário
curl -X POST http://localhost:8080/api/v1/blocks/users/{userId} \
  -H "Authorization: Bearer <token>"

curl -X DELETE http://localhost:8080/api/v1/blocks/users/{userId} \
  -H "Authorization: Bearer <token>"

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

9a. Verificação de residência

Moradores podem verificar residência por geolocalização (POST /api/v1/memberships/{territoryId}/verify-residency/geo) ou por comprovante documental (POST /api/v1/memberships/{territoryId}/verify-residency/document). Quando a policy exige presença, envie X-Geo-Latitude/X-Geo-Longitude.

# Verificação por geo
curl -X POST http://localhost:8080/api/v1/memberships/{territoryId}/verify-residency/geo \
  -H "Authorization: Bearer <token>" \
  -H "X-Geo-Latitude: -23.55" \
  -H "X-Geo-Longitude: -46.63" \
  -H "Content-Type: application/json" \
  -d '{"lat": -23.55, "lng": -46.63}'

# Verificação por documento
curl -X POST http://localhost:8080/api/v1/evidences \
  -H "Authorization: Bearer <token>" \
  -F "file=@comprovante.pdf" \
  -F "type=ResidencyDocument"

curl -X POST http://localhost:8080/api/v1/memberships/{territoryId}/verify-residency/document \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"evidenceId": "evidence-id"}'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

11. Notificações in-app

Eventos relevantes geram mensagens em outbox que são processadas em background para criar notificações por usuário. Consulte GET /api/v1/notifications e marque como lidas em POST /api/v1/notifications/{id}/read.

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

11a. Enviar mensagem no chat com imagem

O chat permite enviar imagens junto com mensagens de texto. Cada mensagem pode conter uma imagem (máximo 5MB, apenas imagens). Primeiro faça upload da imagem via POST /api/v1/media/upload e depois inclua o mediaId ao enviar a mensagem.

# 1) Upload da imagem
curl -X POST http://localhost:8080/api/v1/media/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@imagem.jpg"

# 2) Enviar mensagem com imagem
curl -X POST http://localhost:8080/api/v1/chat/conversations/{conversationId}/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Olha essa foto!",
    "mediaId": "gggggggg-gggg-gggg-gggg-gggggggggggg"
  }'

📊 Ver Diagrama de Sequência

⛶ Tela Cheia

Fluxo Completo

1. Autenticar: POST /api/v1/auth/social (obtém JWT)
2. Descobrir território: GET /api/v1/territories/nearby?lat=-23.55&lng=-46.63
3. Selecionar território: POST /api/v1/territories/selection + header X-Session-Id
4. Declarar vínculo: POST /api/v1/memberships/{territoryId}/enter-visitor
5. Verificar membership: GET /api/v1/memberships/{territoryId}/me

Fluxo Completo

1. Upload de mídias: POST /api/v1/media/upload (obtém mediaIds)
2. Criar post: POST /api/v1/feed com mediaIds (até 10 imagens)
3. GeoAnchors automáticos: derivados de mídias quando disponíveis
4. Visualizar no mapa: GET /api/v1/map/pins?types=post
5. Ver no feed: GET /api/v1/feed/paged

Fluxo Completo

1. Criar asset: POST /api/v1/assets (geo obrigatória em geoAnchors)
2. Tipos disponíveis: river, trail, spring, lookout, sanctuary
3. Apenas moradores verificados ou curadores: podem criar/editar/arquivar
4. Visualizar no mapa: GET /api/v1/map/pins?types=asset&assetTypes=river,trail

Fluxo Completo

1. Criar conversa: POST /api/v1/chat/conversations
2. Enviar mensagem: POST /api/v1/chat/conversations/{id}/messages
3. Mensagem com imagem: incluir mediaId no payload
4. Listar conversas: GET /api/v1/chat/conversations
5. Histórico: GET /api/v1/chat/conversations/{id}/messages

Fluxo Completo

1. Criar loja: POST /api/v1/stores
2. Adicionar itens: POST /api/v1/items com mediaIds (até 10 imagens)
3. Carrinho: POST /api/v1/cart/items
4. Checkout: POST /api/v1/cart/checkout
5. Consultar itens: GET /api/v1/items (paginação incluída)

Fluxo Completo

1. Criar evento: POST /api/v1/events (geo obrigatória)
2. Imagens: coverMediaId e additionalMediaIds (até 10)
3. Marcar interesse: POST /api/v1/events/{id}/interest
4. Confirmar presença: POST /api/v1/events/{id}/confirm
5. Aparece no feed e mapa: eventos aparecem em ambos os contextos

1. Checkout pago → Sistema cria SellerTransaction automaticamente
2. Valor líquido → Subtotal - Fees da plataforma = Valor para o vendedor
3. Período de retenção → Aguarda dias configurados (ex: 7 dias)
4. Valor mínimo → Acumula até atingir valor mínimo configurado (ex: R$ 100,00)
5. Payout automático → Background worker processa quando todas as condições são atendidas
6. Transferência → Dinheiro é transferido para o vendedor via gateway (Stripe, MercadoPago, etc.)

Endpoint

POST /api/v1/territories/{territoryId}/payout-config

Exemplo de Requisição

curl -X POST "http://localhost:8080/api/v1/territories/{territoryId}/payout-config" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retentionPeriodDays": 7,
    "minimumPayoutAmountInCents": 10000,
    "maximumPayoutAmountInCents": 5000000,
    "frequency": "Weekly",
    "autoPayoutEnabled": true,
    "requiresApproval": false,
    "currency": "BRL"
  }'

Endpoint

GET /api/v1/territories/{territoryId}/payout-config

Exemplo de Requisição

curl "http://localhost:8080/api/v1/territories/{territoryId}/payout-config" \
  -H "Authorization: Bearer <token>"

Endpoints

# Consultar meu saldo como vendedor
GET /api/v1/territories/{territoryId}/seller-balance/me

# Consultar minhas transações como vendedor
GET /api/v1/territories/{territoryId}/seller-balance/me/transactions

Exemplo de Requisição

curl "http://localhost:8080/api/v1/territories/{territoryId}/seller-balance/me" \
  -H "Authorization: Bearer <token>"

Passo 1: Configuração Inicial do Ambiente

O que você precisa:

• Navegador web com suporte a JavaScript (Chrome, Firefox, Edge, Safari)
• Ferramenta para testar API: Postman, Insomnia, ou curl (linha de comando)
• Acesso à API Arah: URL base da API (ex: http://localhost:8080 ou URL de produção)
• Conta de usuário: CPF ou documento estrangeiro para autenticação

Configuração (5 minutos):

1. Instale ferramenta de teste de API: Baixe Postman (https://www.postman.com/downloads/) ou use curl
2. Configure ambiente: Anote a URL da API e prepare dados de autenticação (CPF, nome, email)
3. Verifique acesso: Teste se consegue acessar a URL base da API no navegador

Passo 2: Autenticação Social (Primeiro Acesso)

O que acontece: Você obtém um token JWT que permite acesso à API.

Endpoint: POST /api/v1/auth/social

curl -X POST http://localhost:8080/api/v1/auth/social \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "externalId": "seu-id-unico",
    "displayName": "Seu Nome",
    "cpf": "12345678900",
    "email": "seu@email.com"
  }'

Resposta esperada:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-01-21T10:00:00Z"
}

Próximo passo: Guarde o token. Você vai usar ele em todas as requisições autenticadas.

Passo 3: Descobrir Territórios Disponíveis

O que acontece: Você lista todos os territórios disponíveis na plataforma para escolher qual analisar.

Endpoint: GET /api/v1/territories

curl http://localhost:8080/api/v1/territories \
  -H "Authorization: Bearer <seu-token>"

Resposta esperada:

{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Sertão do Camburi",
      "description": "Território comunitário...",
      "latitude": -23.55,
      "longitude": -46.63
    }
  ]
}

Análise funcional:

• Observe os dados retornados: Nome, descrição, localização geográfica
• Pergunte-se: Esses dados são suficientes para identificar um território? Falta algo?
• Documente observações: O que você observa que poderia melhorar?

Passo 4: Selecionar Território para Análise

O que acontece: Você define qual território vai analisar, facilitando requisições subsequentes.

Endpoint: POST /api/v1/territories/selection

curl -X POST http://localhost:8080/api/v1/territories/selection \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <seu-token>" \
  -H "X-Session-Id: sessao-analise-001" \
  -d '{
    "territoryId": "11111111-1111-1111-1111-111111111111"
  }'

Análise funcional:

• Observe o fluxo: Você precisa de um X-Session-Id único para cada sessão de análise
• Pergunte-se: Seria melhor não precisar disso? Como isso afeta a experiência?
• Documente necessidades: O que facilitaria seu trabalho como analista?

Passo 5: Explorar Feed do Território

O que acontece: Você vê o conteúdo publicado no feed do território selecionado.

Endpoint: GET /api/v1/feed

curl http://localhost:8080/api/v1/feed \
  -H "Authorization: Bearer <seu-token>" \
  -H "X-Session-Id: sessao-analise-001"

Resposta esperada:

{
  "items": [
    {
      "id": "...",
      "title": "Mutirão de limpeza",
      "content": "Encontro sábado 9h...",
      "type": "General",
      "visibility": "Public",
      "authorName": "Ana Silva",
      "createdAtUtc": "2025-01-20T10:00:00Z"
    }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalCount": 45,
    "totalPages": 3
  }
}

Análise funcional - exercício prático:

1. Observe os tipos de conteúdo: Quais tipos existem? (General, AlertPost, etc.)
2. Analise visibilidade: O que significa Public vs ResidentsOnly?
3. Identifique necessidades: Que filtros seriam úteis? (por tipo, por data, por autor)
4. Documente proposta: Escreva uma proposta de melhoria baseada na observação

Passo 6: Analisar Marketplace do Território

O que acontece: Você explora produtos e serviços disponíveis no marketplace territorial.

Endpoint: GET /api/v1/items

curl "http://localhost:8080/api/v1/items?territoryId=11111111-1111-1111-1111-111111111111&q=bolo&category=Alimentos" \
  -H "Authorization: Bearer <seu-token>"

Análise funcional - exercício prático:

1. Teste diferentes buscas: Por nome (q=bolo), por categoria (category=Alimentos)
2. Observe resultados: As buscas são eficientes? Retornam resultados relevantes?
3. Identifique necessidades: Que filtros faltam? (preço, localização, disponibilidade)
4. Documente observações: O que você observa que poderia melhorar?

Passo 7: Propor Melhoria Funcional (Criar Issue no GitHub)

O que fazer: Após observar e analisar, documente suas observações e propostas.

Template de Issue (GitHub):

## Análise Funcional: [Nome da Funcionalidade Proposta]

### Contexto Territorial
- **Território observado**: [Nome]
- **Necessidade identificada**: [Descrição clara]

### Análise Técnica (via API)
- **Endpoint testado**: `GET /api/v1/...`
- **Comportamento atual**: [O que observou]
- **Limitações identificadas**: [O que falta]

### Proposta Funcional
- **O que faria**: [Descrição clara]
- **Como funcionaria**: [Fluxo de uso]
- **Regras de negócio**: [Quem pode fazer o quê]

### Benefícios
- Para o território: [Benefício territorial]
- Para a comunidade: [Benefício comunitário]

### Evidências Técnicas
[Exemplos de requisições/respostas da API que suportam a proposta]

Passo 1: Verificar Requisitos do Sistema

Requisitos obrigatórios:

Se algum requisito faltar:

• .NET SDK 8.0: Baixe em https://dotnet.microsoft.com/download/dotnet/8.0 (escolha "SDK", não apenas Runtime)
• Git: Windows: https://git-scm.com/download/win | macOS: brew install git | Linux: sudo apt install git

Passo 2: Clonar o Repositório

O que acontece: Você baixa todo o código fonte do projeto para sua máquina local.

# Clone o repositório
git clone https://github.com/sraphaz/araponga.git

# Entre na pasta do projeto
cd araponga

Verificação:

# Verifique que os arquivos foram baixados
ls backend/
# Deve mostrar: Arah.Api, Arah.Application, Arah.Domain, etc.

Estrutura do projeto:

• backend/: Código fonte C# (.NET) organizado em camadas (Clean Architecture)
• docs/: Documentação do projeto (visão, roadmap, API, etc.)
• frontend/: Código frontend (Wiki e DevPortal)
• .cursorrules: Regras e padrões do projeto (Cursor lê automaticamente)

Passo 3: Restaurar Dependências

O que acontece: O .NET baixa todas as bibliotecas (pacotes NuGet) necessárias para o projeto compilar e rodar.

# Restaura pacotes NuGet
dotnet restore

O que você vai ver:

Determining projects to restore...
Restored backend/Arah.Domain/Arah.Domain.csproj
Restored backend/Arah.Application/Arah.Application.csproj
...
Restore succeeded.

Tempo estimado: 2-5 minutos na primeira vez (depende da velocidade da internet).

Passo 4: Compilar o Projeto

O que acontece: O .NET compila todo o código C# para verificar se está tudo correto e pronto para executar.

# Compila o projeto
dotnet build

Resultado esperado:

Build succeeded.
    0 Warning(s)
    0 Error(s)
Time Elapsed 00:01:23

Se houver erros de compilação:

• Verifique se o .NET SDK 8.0 está instalado: dotnet --version
• Verifique se todas as dependências foram restauradas: dotnet restore novamente
• Verifique se há conflitos de versão: procure por mensagens de erro específicas

Passo 5: Executar Testes Automatizados

O que acontece: Todos os testes automatizados são executados para garantir que o código está funcionando corretamente.

# Executa todos os testes
dotnet test

Resultado esperado:

Passed!  - Failed:     0, Passed:   245, Skipped:     0
Total:   245
Duration: 00:02:15

Se alguns testes falharem:

• Não se preocupe imediatamente: Pode ser configuração específica do seu ambiente
• Verifique mensagens de erro: Leia a saída do teste para entender o problema
• Teste em modo verbose: dotnet test --verbosity detailed para mais informações
• Verifique dependências externas: Alguns testes podem precisar de banco de dados ou serviços externos

Passo 6: Executar a API Localmente

O que acontece: Você inicia o servidor da API localmente para testar e desenvolver.

# Configurar ambiente de desenvolvimento
export ASPNETCORE_ENVIRONMENT=Development  # Linux/macOS
# OU
$env:ASPNETCORE_ENVIRONMENT="Development"  # Windows PowerShell

# Executar a API
dotnet run --project backend/Arah.Api --urls http://localhost:8080

O que você vai ver:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:8080
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

Testar a API:

# Em outro terminal, teste se a API está respondendo
curl http://localhost:8080/api/v1/territories

# Ou abra no navegador:
# http://localhost:8080

Para parar a API: Pressione Ctrl+C no terminal onde está rodando.

Passo 7: Abrir o Projeto no Cursor (Recomendado)

O que é o Cursor: Editor de código com IA que entende o contexto do projeto e ajuda você a programar seguindo os padrões.

Instalar Cursor:

• Baixe em https://cursor.sh/
• Instale normalmente (setup automático)

Abrir projeto no Cursor:

1. Abra o Cursor
2. File > Open Folder (ou Ctrl+K Ctrl+O no Windows/Linux, Cmd+K Cmd+O no macOS)
3. Selecione a pasta araponga que você clonou
4. Pronto! O Cursor automaticamente:
   • Lê o arquivo .cursorrules com todas as regras do projeto
   • Configura o ambiente de desenvolvimento
   • Prepara autocompletar e sugestões baseadas no projeto

Passo 8: Entender a Estrutura do Código (Clean Architecture)

Organização em camadas:

backend/
├── Arah.Domain/          # Camada mais interna (não depende de nada)
│   └── Entidades, Value Objects, Interfaces de Repositórios
│
├── Arah.Application/     # Camada de lógica de negócio
│   └── Services, Use Cases, DTOs de Aplicação
│
├── Arah.Infrastructure/  # Camada de infraestrutura
│   └── Implementações de Repositórios, Storage, External Services
│
├── Arah.Api/             # Camada mais externa (HTTP, Controllers)
│   └── Controllers, Middlewares, Configurações de API
│
└── Arah.Tests/           # Testes automatizados
    └── Testes unitários, integração, E2E

Regra fundamental: Dependências apontam para dentro (Domain não depende de nada, Application depende apenas de Domain, etc.).

Exemplo prático - Criação de Posts:

1. Controller (Arah.Api/Controllers/FeedController.cs) recebe requisição HTTP
2. Controller chama Service (Arah.Application/Services/PostCreationService.cs)
3. Service usa Entidades (Arah.Domain/Feed/CommunityPost.cs) para criar post
4. Service usa Repository Interface (IPostRepository) para salvar
5. Repository Implementation (Arah.Infrastructure/Postgres/PostgresPostRepository.cs) salva no banco

Passo 9: Primeira Contribuição - Exemplo Prático

Exercício sugerido: Melhorar mensagem de erro em um endpoint.

Passo a passo:

1. Escolha um endpoint: Ex: GET /api/v1/feed (listar posts do feed)
2. Encontre o Controller: backend/Arah.Api/Controllers/FeedController.cs
3. Encontre o Service: backend/Arah.Application/Services/FeedService.cs
4. Analise o código: Pergunte ao Cursor "Como funciona a listagem de posts?"
5. Identifique melhoria: Ex: Mensagem de erro quando não há posts poderia ser mais clara
6. Implemente a mudança: Use o Cursor para fazer a alteração seguindo padrões
7. Adicione teste: Crie teste que valida a nova mensagem de erro
8. Valide build e testes:

   dotnet build
   dotnet test

9. Crie Pull Request: Siga o template em .github/pull_request_template.md