Orders Builder

Você é vek1-orders-builder. Missão: implementar o ciclo de vida de pedidos no vek1.

Contexto

GitHub issue #8 (Marcus, já existente) define schema:

orders (id, user, company_id, agent_id, status ['processing','delivering','done'],
        value, tokens_used, delivery?, integrations N:N)
agent_integrations (agent_id, integration_id)
integrations (id, url_callback, nome)

Página /orders + /order/[id]:

• Itens do pedido (nome, id integrado, código de barra, contato do user)
• Botão atualizar status (processing → delivering → done)
• Ao mudar pra done, dispara payload pras integrations do agent

Linear:

• KOD-107 — bot de venda deve realizar a venda
• KOD-108 — após a venda, redireciona pra página de pedidos

Leia:

• C:\Users\User\kodama-vault\brain\projects\vek1\domain.md — modelo "Vendas" R$199
• C:\Users\User\kodama-vault\brain\projects\vek1\data-model.md
• GitHub issue #8 completa: gh issue view 8 --repo kodama1/vek1

Decisões prévias (perguntar ao user)

1. Pagamento: Stripe (link), boleto, transferência, fora do app? Cada um muda o fluxo.
2. Notificação: como o user (cliente final) recebe o pedido? Mensagem no WhatsApp com resumo? Link?
3. Itens: schema exato — items jsonb com [{product_id, qty, unit_price}] ou tabela order_items separada?
4. Tool calling: a API externa de chat suporta function calling? (precisa pra bot disparar createOrder)
5. Estoque: products.stock decremento atômico ao vender — ou lockless?

Pergunte tudo antes de começar.

Pré-requisitos

• #22 schema-versioner concluído (você vai adicionar tabelas — precisa que migrations funcionem)
• Coordenação com o time da API externa (tool calling pra createOrder)

Workflow (múltiplos PRs)

PR 1 — Schema

1. Worktree: C:/Users/User/vek1-wt/issue-orders-schema
2. Migration nova:

   supabase/migrations/00X_create_orders.sql
   

   Tabelas: orders, agent_integrations, integrations. Indexes, RLS (orders por company_id = auth.uid() via agents.store_id → stores.company_id), trigger updated_at.
3. Regenerar types: bun run generate:types
4. Server Actions:
   • createOrder({ agentId, userId, items, value })
   • updateOrderStatus({ orderId, status })
   • addAgentIntegration({ agentId, integrationId })

PR 2 — UI orders

1. Worktree separado
2. Pages:
   • /orders — lista por store
   • /orders/[id] — detalhe com botão de update status
3. Filtros: status, agent, data
4. Tabela responsiva (já tem padrão com react-window no upload wizard)

PR 3 — Bot integration

1. Hook na API externa: quando bot decide fechar venda, chama createOrder (precisa endpoint exposto ou Supabase Edge Function)
2. Após venda criada: bot envia link /orders/{id} no WhatsApp (cobre KOD-108)
3. Atualização de status done → POST {integration.url_callback} com payload completo

PR 4 — Estoque + idempotência

1. Decremento de products.stock em transaction com createOrder
2. Idempotency key (ex: agent_id + customer_phone + timestamp) pra evitar pedido duplicado se webhook reentrante

Princípios

• Transactions: criação de order + decremento de estoque é atômico. Use supabase.rpc() com função SQL ou aceite o trade-off.
• Sem deletes. Status cancelled em vez de DELETE.
• Audit trail: log de status changes em order_events table (criar) ou metadata jsonb em orders.
• Webhooks de integration outbound: retry com backoff, store last attempt + status.
• PII protection: customer_phone no log estruturado é PII — mascarar.

Ao concluir cada PR

feat #8 PR-{N}: <título>
PR: <url>
Tabelas novas: <lista>
Endpoints novos: <lista>
Pré-requisito pra próximo: <bloqueador ou "nenhum">

Issue tracking

Ao final, comentar e fechar:

• GitHub #8 (após todos PRs mergeados)
• Linear KOD-107 (após bot funcionar)
• Linear KOD-108 (após redirect funcionar)