127 lines
7.6 KiB
Markdown
127 lines
7.6 KiB
Markdown
## Sistema de Chamados
|
|
|
|
Aplicação **Next.js 16 (App Router)** com **React 19**, **Convex** e **Better Auth** para gestão de tickets da Rever. A stack ainda inclui **Prisma 6** (SQLite padrão para DEV), **Tailwind** e **Turbopack** em desenvolvimento (o build de produção roda com o webpack padrão do Next). Todo o código-fonte fica na raiz do monorepo seguindo as convenções do App Router.
|
|
|
|
## Requisitos
|
|
|
|
- Bun >= 1.3 (recomendado 1.3.1). Após instalar via script oficial, adicione `export PATH="$HOME/.bun/bin:$PATH"` ao seu shell (ex.: `.bashrc`) para ter `bun` disponível globalmente.
|
|
- Node.js >= 20 (necessário para ferramentas auxiliares como Prisma CLI e Next.js em modo fallback).
|
|
- CLI do Convex (`bunx convex dev` instalará automaticamente no primeiro uso, se ainda não estiver presente).
|
|
|
|
## Configuração rápida
|
|
|
|
1. Instale as dependências:
|
|
```bash
|
|
bun install
|
|
```
|
|
2. Ajuste o arquivo `.env` (ou crie a partir de `.env.example`) e confirme os valores de:
|
|
- `NEXT_PUBLIC_CONVEX_URL` (gerado pelo Convex Dev)
|
|
- `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL` (por padrão `file:./db.dev.sqlite`, que mapeia para `prisma/db.dev.sqlite`)
|
|
3. Aplique as migrações e gere o client Prisma:
|
|
```bash
|
|
bunx prisma migrate deploy
|
|
bun run prisma:generate
|
|
```
|
|
4. Popule usuários padrão do Better Auth:
|
|
```bash
|
|
bun run auth:seed
|
|
```
|
|
> Sempre que trocar de máquina ou quiser “zerar” o ambiente local, basta repetir os passos 3 e 4 com a mesma `DATABASE_URL`.
|
|
|
|
### Resetar rapidamente o ambiente local
|
|
|
|
1. Garanta que `DATABASE_URL` aponte para o arquivo desejado (ex.: `file:./db.dev.sqlite` para desenvolvimento, `file:./db.sqlite` em produção local).
|
|
2. Aplique as migrações no arquivo informado:
|
|
```bash
|
|
DATABASE_URL=file:./db.dev.sqlite bunx prisma migrate deploy
|
|
```
|
|
3. Recrie/garanta as contas padrão de login:
|
|
```bash
|
|
DATABASE_URL=file:./db.dev.sqlite bun run auth:seed
|
|
```
|
|
4. Suba o servidor normalmente com `bun run dev`. Esses três comandos bastam para reconstruir o ambiente sempre que trocar de computador.
|
|
|
|
### Subir serviços locais
|
|
|
|
- (Opcional) Para re-sincronizar manualmente as filas padrão, execute `bun run queues:ensure`.
|
|
- Em um terminal, rode o backend em tempo real do Convex com `bun run convex:dev:bun` (ou `bun run convex:dev` para o runtime Node).
|
|
- Em outro terminal, suba o frontend Next.js (Turpoback) com `bun run dev:bun` (`bun run dev:webpack` serve como fallback).
|
|
- Com o Convex rodando, acesse `http://localhost:3000/dev/seed` uma vez para popular dados de demonstração (tickets, usuários, comentários).
|
|
|
|
> Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente.
|
|
|
|
### Documentação
|
|
- Índice de docs: `docs/README.md`
|
|
- Operações (produção): `docs/OPERATIONS.md` (versão EN) e `docs/OPERACAO-PRODUCAO.md` (PT-BR)
|
|
- Guia de DEV: `docs/DEV.md`
|
|
- Testes automatizados (Vitest/Playwright): `docs/testes-vitest.md`
|
|
- Stack Swarm: `stack.yml` (roteado por Traefik, rede `traefik_public`).
|
|
|
|
### Variáveis de ambiente
|
|
|
|
- Exemplo na raiz: `.env.example` — copie para `.env` e preencha segredos.
|
|
- App Desktop: `apps/desktop/.env.example` — copie para `apps/desktop/.env` e ajuste `VITE_APP_URL`.
|
|
- Nunca faça commit de arquivos `.env` com valores reais (já ignorados em `.gitignore`).
|
|
|
|
### Guia de DEV (Prisma, Auth e Desktop/Tauri)
|
|
|
|
Para fluxos detalhados de desenvolvimento — banco de dados local (SQLite/Prisma), seed do Better Auth, ajustes do Prisma CLI no DEV e build do Desktop (Tauri) — consulte `docs/DEV.md`.
|
|
|
|
## Scripts úteis
|
|
|
|
- `bun run dev:bun` — padrão atual para o Next.js com runtime Bun (`bun run dev:webpack` permanece como fallback).
|
|
- `bun run convex:dev:bun` — runtime Bun para o Convex (`bun run convex:dev` mantém o fluxo antigo usando Node).
|
|
- `bun run build:bun` / `bun run start:bun` — build e serve com Bun; `bun run build` mantém o fallback Node.
|
|
- `bun run dev:webpack` — fallback do Next.js em modo desenvolvimento (webpack).
|
|
- `bun run lint` — ESLint com as regras do projeto.
|
|
- `bun test` — suíte de testes unitários usando o runner do Bun (o teste de screenshot fica automaticamente ignorado se o matcher não existir).
|
|
- `bun run build` — executa `next build --webpack` (webpack padrão do Next).
|
|
- `bun run build:turbopack` — executa `next build --turbopack` para reproduzir/debugar problemas.
|
|
- `bun run auth:seed` — atualiza/cria contas padrão do Better Auth (credenciais em `agents.md`).
|
|
- `bunx prisma migrate deploy` — aplica migrações ao banco SQLite local.
|
|
- `bun run convex:dev` — roda o Convex em modo desenvolvimento com Node, gerando tipos em `convex/_generated`.
|
|
|
|
## Transferir dispositivo entre colaboradores
|
|
|
|
Quando uma dispositivo trocar de responsável:
|
|
|
|
1. Abra `Admin > Dispositivos`, selecione o equipamento e clique em **Resetar agente**.
|
|
2. No equipamento, execute o reset local do agente (`rever-agent reset` ou reinstale o serviço) e reprovisione com o código da empresa.
|
|
3. Após o agente gerar um novo token, associe a dispositivo ao novo colaborador no painel.
|
|
|
|
Sem o reset de agente, o Convex reaproveita o token anterior e o inventário continua vinculado ao usuário antigo.
|
|
|
|
## Estrutura principal
|
|
|
|
- `app/` dentro de `src/` — rotas e layouts do Next.js (App Router).
|
|
- `components/` — componentes reutilizáveis (UI, formulários, layouts).
|
|
- `convex/` — queries, mutations e seeds do Convex.
|
|
- `prisma/` — schema, migrações e banco SQLite (`prisma/db.sqlite`).
|
|
- `scripts/` — utilitários em Node para sincronização e seeds adicionais.
|
|
- `agents.md` — guia operacional e contexto funcional (em PT-BR).
|
|
- `PROXIMOS_PASSOS.md` — backlog de melhorias futuras.
|
|
|
|
## Credenciais de demonstração
|
|
|
|
Após executar `bun run auth:seed`, as credenciais padrão ficam disponíveis conforme descrito em `agents.md` (seção “Credenciais padrão”). Ajuste variáveis `SEED_USER_*` se precisar sobrepor usuários ou senhas durante o seed.
|
|
|
|
## Próximos passos
|
|
|
|
Consulte `PROXIMOS_PASSOS.md` para acompanhar o backlog funcional e o progresso das iniciativas planejadas.
|
|
|
|
### Executar com Bun
|
|
|
|
- `bun install` é o fluxo padrão (o arquivo `bun.lock` deve ser versionado; use `bun install --frozen-lockfile` em CI).
|
|
- `bun run dev:bun`, `bun run convex:dev:bun`, `bun run build:bun` e `bun run start:bun` já estão configurados; internamente executam `bun run --bun <script>` para usar o runtime do Bun sem abrir mão dos scripts existentes. O `cross-env` garante os valores esperados de `NODE_ENV` (`development`/`production`).
|
|
- Se precisar validar o bundler experimental, use `bun run build:turbopack`; para o fluxo estável mantenha `bun run build` (webpack).
|
|
- `bun test` utiliza o test runner do Bun. O teste de snapshot de screenshot é automaticamente ignorado quando o matcher não está disponível; testes de navegador completos continuam via `bun run test:browser` (Vitest + Playwright).
|
|
|
|
<!-- ci: smoke test 3 -->
|
|
|
|
## Diagnóstico de sessão da dispositivo (Desktop)
|
|
|
|
- Quando o portal for aberto via app desktop, use a página `https://seu-app/portal/debug` para validar cookies e contexto:
|
|
- `/api/auth/get-session` deve idealmente mostrar `user.role = "machine"` (em alguns ambientes WebView pode retornar `null`, o que não é bloqueante).
|
|
- `/api/machines/session` deve retornar `200` com `assignedUserId/assignedUserEmail`.
|
|
- O frontend agora preenche `machineContext` mesmo que `get-session` retorne `null`, e deriva o papel efetivo a partir desse contexto.
|
|
- Se `machines/session` retornar `401/403`, revise CORS/credenciais e o fluxo de handshake documentados em `docs/OPERACAO-PRODUCAO.md`.
|