# Look & Charme — Backend + MCP

Backend administrativo da loja Look & Charme: banco de dados, API REST e
servidor MCP que expõe a loja como um conjunto de ferramentas que qualquer
agente de IA compatível (Claude, ChatGPT, Codex, Gemini, OpenCode) pode operar.

## 1. Instalação

```bash
npm install
cp .env.example .env
npm run seed     # cria o banco store.db, ilhas de Cabo Verde, categorias e o admin padrão
npm run api      # sobe a API REST em http://localhost:4000
```

Login padrão criado pelo seed (troque a senha em produção, veja `.env`):
`admin@lookcharme.cv` / `MudeEstaSenha123!`

## 2. Rodando o servidor MCP

```bash
npm run mcp          # stdio — para uso local (Claude Desktop, Claude Code, OpenCode)
npm run mcp:http      # HTTP — para agentes remotos (ChatGPT, Codex hospedado)
```

### Conectar ao Claude Desktop / Claude Code
Copie `claude_desktop_config.example.json` para a configuração do seu
cliente Claude, ajustando os caminhos absolutos.

### Conectar ao OpenCode
O arquivo `opencode.json` na raiz do projeto já registra o servidor MCP.
Basta rodar `opencode` dentro da pasta do projeto — ele detecta o arquivo
automaticamente.

### Conectar a agentes remotos (ChatGPT, Codex hospedado, Gemini)
Rode `npm run mcp:http`, defina `MCP_HTTP_TOKEN` no `.env` e aponte o agente
para `https://seu-servidor/mcp` com o header
`Authorization: Bearer <MCP_HTTP_TOKEN>`.

## 3. Fluxo de trabalho com múltiplos agentes de código (OpenCode + Claude)

Este repositório assume que **mais de um agente de IA vai escrever código**
(não apenas operar a loja via MCP, mas editar o próprio backend). Para isso
funcionar com segurança:

1. **Nunca commitar direto na `main`.** Todo agente trabalha em uma branch:
   - `opencode/<tarefa>` — para tarefas feitas pelo OpenCode
   - `agent/<tarefa>` — para outros agentes automáticos
   - `feature/<tarefa>` — para você
2. **CI roda automaticamente** em cada PR (`.github/workflows/ci.yml`):
   checa sintaxe de todos os arquivos, roda o seed num banco temporário e
   confirma que a API sobe (`/api/health`).
3. **PRs de branches `opencode/*` ou `agent/*` ficam bloqueados** até
   receberem o label `reviewed-by-claude` — isso força uma revisão humana
   ou minha (Claude) antes do merge. Você pode colar o link do PR ou o diff
   aqui no chat, ou usar o Claude Code apontado para o mesmo repositório.
4. Use `.github/PULL_REQUEST_TEMPLATE.md` como checklist — ele já lembra de
   checar segredos vazados, migrações de banco e testes locais.

**Exemplo prático de uso do OpenCode:**

```bash
git checkout -b opencode/adicionar-filtro-de-cor
opencode "adicione um filtro por cor no endpoint GET /api/produtos"
# revise o diff gerado
git push origin opencode/adicionar-filtro-de-cor
# abra o PR — o CI roda, e o PR fica travado até o label reviewed-by-claude
```

Depois, me mande o link do PR (ou cole o diff) aqui para eu revisar antes
do merge.

## 4. Estrutura

```
src/
  schema.sql      # schema do banco (SQLite — trocar por Postgres é direto)
  db.js           # conexão + seed inicial
  store.js        # TODA a regra de negócio (única fonte da verdade)
  api.js          # API REST (usa store.js)
  mcp-server.js   # servidor MCP (usa store.js) — stdio e HTTP
openapi.yaml      # especificação OpenAPI da API REST
opencode.json     # registra o MCP server no OpenCode
claude_desktop_config.example.json
.github/workflows/ci.yml
.github/PULL_REQUEST_TEMPLATE.md
```

`api.js` e `mcp-server.js` nunca duplicam lógica — ambos chamam as mesmas
funções de `store.js`. Isso garante que a loja se comporta de forma idêntica
não importa se a ação veio do painel admin, da API ou de um agente de IA.

## 5. Próximos passos sugeridos

- Trocar SQLite por Postgres (Supabase é uma boa opção com Storage + Auth prontos)
- Upload de imagens (Cloudflare R2 ou Supabase Storage)
- Login de cliente com Google OAuth
- Pagamentos: Vinti4/SISP (Cabo Verde) + Stripe (internacional)
- Frontend da loja (Next.js) e painel admin (React)
- Testes automatizados mais completos (Vitest + supertest)
- Deploy via Docker