Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .agents/skills/backend-domain/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@ Procedimento operacional. O racional completo está em `docs/PATTERNS/BACKEND-AR
Sem `try/catch` no handler.
- **Path em camelCase, substantivo no plural, sem verbo.** Ação é o método HTTP. Filtro, busca,
ordenação e paginação na query string.
- Toda rota de lista aceita `search` na query (busca no servidor), além de paginação e ordenação.
- Toda rota de lista aceita `search` na query (busca no servidor), além de paginação e ordenação. O
`search` é `searchSchema([...chaves])` de `server/schemas/common.ts`, e o service passa o termo por
`parseSearch` (`server/lib/search.ts`) com as chaves da lista: texto livre, `campo:valor` e o
período `de:`/`ate:`. Comparação com `matchesTerm`/`normalizeTerm` (sem acento e sem caixa).
- Sucesso sem envelope: recurso direto, ou `{ data, meta }` para lista (`listSchema` de
`server/schemas/common.ts`).

Expand Down
7 changes: 5 additions & 2 deletions .agents/skills/new-screen/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ Procedimento operacional. O racional está em `docs/PATTERNS/FRONTEND-ARCH.md` e
3. **Queries** em `_hooks/<dominio>.queries.ts` com `queryOptions`. O `clientLoader` faz
`void queryClient.prefetchQuery(...)` e a tela usa `useQuery` com a mesma função.
4. **Mutations** com `useMutation`, invalidando as chaves afetadas no `onSuccess` e `toast.success`.
5. **Tela:** `PageHeader` no topo. Lista com `DataTable`, sempre com busca (`search`, obrigatório) e
5. **Tela:** `PageHeader` no topo. Lista com `DataTable`, sempre com busca (`search`, obrigatório, com
o estado do `useListSearch` e as `keys` de `campo:valor` iguais às do service; `periodLabel` liga o
período) e
os filtros em `filters` como um `FilterButton` (`keys` com as chaves da URL que são filtro, cada
filtro num `FilterField`); estado na URL (`useListParams`), com o valor padrão fora dela. Detalhe em
`EntityDrawer` com o id na URL. Criação em `FormDialog`. Confirmação com `useConfirm()`.
Expand All @@ -39,4 +41,5 @@ Procedimento operacional. O racional está em `docs/PATTERNS/FRONTEND-ARCH.md` e
## Antes de concluir

`bun run lint`, `bun run typecheck`, `bun run test:e2e`, e a tela conferida nos dois temas e em
viewport de celular.
viewport de celular (390px, sem rolagem horizontal; o `DataTable` vira cards e coluna secundária leva
`hideOnMobile`). Ver "Celular" em `docs/DESIGN-SYSTEM.md`.
9 changes: 9 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,12 @@ SESSION_SECRET=

# Obrigatória. Senha de admin@local.test e user@local.test, recriados a cada start.
SEED_PASSWORD=

# @modulo:notificacoes
# Par VAPID do Web Push, próprio de cada deploy: bunx web-push generate-vapid-keys. Obrigatório em
# produção; em dev, sem ele, um par novo é gerado a cada start e as inscrições se refazem.
VAPID_PUBLIC_KEY=
VAPID_PRIVATE_KEY=
# mailto: ou a URL https:// do sistema.
VAPID_SUBJECT=mailto:notificacoes@localhost
# @modulo:fim
62 changes: 59 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ perfil e dashboard como domínio de referência: ao criar algo novo, copie o for
- `docs/PATTERNS/API-DESIGN.md`: desenho da API e a matriz de rotas.
- `docs/PATTERNS/FRONTEND-ARCH.md`: colocation, dados, sessão, formulários.
- `docs/DESIGN-SYSTEM.md`: tokens, tipografia, componentes.
- `docs/MODULOS.md`: core e módulos opcionais (`notificacoes`, `chat`), o `modulos.json` e os
marcadores `@modulo:<nome>` nos arquivos do core. Mexeu num ponto de ligação de módulo: marque o
trecho e gere um projeto sem o módulo para rodar os gates.
- Skills em `.agents/skills/` (`.claude/skills` aponta para lá): `backend-domain` para endpoint ou
recurso novo, `new-screen` para tela nova, `react-router` para dúvida do framework.

Expand All @@ -32,6 +35,7 @@ bun run format:check # prettier --check (roda no CI)
bun run test # vitest em watch
bun run test:run # vitest uma vez (roda no CI)
bun run test:e2e # playwright contra o build de produção, porta 4173 (roda no CI)
bun run modulos # cria projeto com os módulos escolhidos e atualiza por módulo (docs/MODULOS.md)
```

Gates antes de dar uma tarefa por concluída: `lint`, `lint:api`, `format:check`, `typecheck`,
Expand Down Expand Up @@ -67,17 +71,69 @@ Gates antes de dar uma tarefa por concluída: `lint`, `lint:api`, `format:check`
- Sem banco nesta etapa: `server/lib/memoryStore.ts` guarda os dados em memória, e o start recria os
usuários do seed (`SEED_PASSWORD`). Só `server/services/` importa o store. Quando o banco entrar, a
troca fica nos services.
- Sessão: cookie `session` HttpOnly com `{ sub, ver, exp }` assinado por HMAC (`SESSION_SECRET`). O
- Sessão: cookie `session` HttpOnly com `{ sub, sid, ver, exp }` assinado por HMAC (`SESSION_SECRET`). O
`requireAuth` (`server/middleware/auth.ts`) relê o usuário a cada request, então role e status valem
na hora. Rotas de admin usam `requireAuth()` seguido de `requireRole("admin")`.
- `ver` é o `sessionVersion` do usuário. Reset de senha e troca da própria senha incrementam, o que
derruba as sessões abertas; na troca própria, o handler reemite o cookie para quem trocou.
- `ver` é o `sessionVersion` do usuário. Reset de senha, troca da própria senha e desativação
incrementam, o que derruba as sessões abertas; na troca própria, o handler reemite o cookie da mesma
sessão para quem trocou. `sid` identifica o login: o que fica preso a ele (a inscrição de Web Push) é
apagado no logout. Cookie sem `sid`, emitido antes dele existir, continua valendo, com o id da sessão
tirado do hash do token.
- Usuário nunca é apagado, só desativado (`active: false`): o audit precisa do autor.
- Toda mudança que um admin precise rastrear grava `recordAudit()` no service.
- Usuário com `mustChangePassword` só acessa `GET /me` e `PUT /me/password`; o resto responde `403`
`PASSWORD_CHANGE_REQUIRED`.
- Erros de contrato de uma rota são declarados com `...problemResponses(401, 422)`.

### Notificações

- Outro módulo avisa alguém com `notifyUser(userId, { title, body, url, senderName, important })`
(`server/services/notifications/notifications.service.ts`). O exemplo do template está no
`updateUser`: cargo mudado e conta reativada por um admin. `senderName` é o que a notificação mostra
com a prévia desligada; `important` avisa mesmo com os avisos silenciados.
- O aviso fica no store (tela `/notifications`, contador na sidebar e `(N)` na aba) e chega por dois
caminhos: as abas abertas pelo stream SSE de `GET /events`, e os navegadores sem o app
aberto por Web Push (`public/sw.js`). O par VAPID vem do `.env` (`VAPID_PUBLIC_KEY`,
`VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`), obrigatório em produção; em dev, sem ele, um par é gerado a
cada start e os navegadores se inscrevem de novo ao abrir o app.
- Cada usuário arquiva avisos (saem da lista e do contador) e silencia os avisos por 8 horas, 1 semana
ou sempre (`PUT /noticeMute`): silenciados chegam na lista, sem notificação nem som, e o contador
fica cinza. O menu de cada aviso abre pela seta ou pelo clique direito.
- Avisos em sequência e grupo agitado: depois de avisar, 15 s sem notificação nem som daquele tipo
(`SQUELCH_MS`, igual na página e no push). Conversa de duas pessoas avisa toda mensagem.
- Texto e preferências da notificação ficam em `shared/` (`notificationText.ts`,
`notificationPreferences.ts`), importados pela página (`~shared/...`) e pelo servidor. `shared/` não
importa `app/` nem `server/` (regra do ESLint). As regras: "Fulano: texto" em grupo, "Mencionou você:",
"Respondeu a você:", "Fulano reagiu ❤️ a: …" e, sem prévia, "N novas mensagens", "Mensagem de
Fulano" ou "Notificação de Fulano".
- As abas abertas ficam na memória do processo (`stream.service.ts`). Com mais de um processo, o
evento precisa de um canal entre eles (Redis, LISTEN/NOTIFY) antes de escalar.
- No front, `NotificationConnection` (montado pelo layout) cuida do stream, da notificação do sistema
(só com a janela sem foco), do som, da inscrição de push, do cache do chat e do `(N)`, que soma os
avisos não silenciados e as conversas não lidas. As configurações ficam no `localStorage` de cada
usuário, separadas para mensagens, grupos e avisos, e vão junto com a inscrição de push.
- `SINGLE_TAB` (`app/config/app.ts`) deixa uma aba do app por navegador, com "Usar aqui" na segunda.

### Conversas

- Chat entre os usuários do app, de duas pessoas ou em grupo (`server/services/chat/chat.service.ts`,
rotas `/conversations` e `/contacts`, tela `app/routes/chat/`). Conversa de duas pessoas é uma só:
pedir de novo devolve a que existe.
- Não lidas, "marcar como não lida" (só a bolinha), silenciar e arquivar são de cada pessoa
(`MemberStateRecord`) e valem só para ela. Responder lê a conversa só para quem respondeu. Arquivada
só volta ao desarquivar.
- Silenciada ou arquivada só avisa a mensagem dirigida à pessoa: menção a ela, `@todos` ou resposta a
uma mensagem dela. Reação de outra pessoa a uma mensagem sua avisa e vira a prévia, mas não fura
silêncio nem arquivo. O `(N)` conta conversas com mensagem não lida, fora as arquivadas e as
silenciadas sem menção.
- A conversa aberta (`ConversationView`) só é lida com a janela em foco há 2,5 s e a rolagem no fim, e
só até a última mensagem que estava na tela (`readUntil`, que nunca volta atrás); aberta sem foco,
espera o primeiro clique ou tecla. Abre na faixa "N mensagens não lidas", buscando páginas
antigas se preciso, e a faixa fica até sair ou mandar mensagem. Só a própria mensagem rola até o fim.
Esc cancela a citação e depois fecha a conversa.
- As mensagens ficam no cache do TanStack Query por conversa (`app/lib/chat/chat.queries.ts`); o
stream acrescenta as novas, e voltar à conversa mantém as páginas antigas já carregadas.

### Frontend: sessão e dados

- `app/lib/api.ts` é a única camada de fetch. Ela lança `ApiError` com o Problem Details, e
Expand Down
32 changes: 25 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Requisitos: Node.js 22.22 ou superior e bun 1.4.2 (fixado em `packageManager`).

```bash
bun install
cp .env.example .env # preencha SESSION_SECRET (openssl rand -base64 48) e SEED_PASSWORD
cp .env.example .env # SESSION_SECRET (openssl rand -base64 48), SEED_PASSWORD e o par VAPID
bun run dev # front em http://localhost:3000, API em :3001
```

Expand Down Expand Up @@ -82,6 +82,7 @@ server/ # backend
├── services/ # regra de negócio e todo acesso a dados
├── middleware/ # sessão e role
└── lib/ # store em memória, Problem Details, router
shared/ # usado pelos dois lados: texto e preferências das notificações
e2e/ # testes do caminho do usuário
docs/ # patterns e design system
```
Expand All @@ -105,25 +106,42 @@ A arquitetura em uma frase de cada lado: no servidor, **só `services/` acessa d
- [docs/PATTERNS/API-DESIGN.md](docs/PATTERNS/API-DESIGN.md): regras da API e matriz de rotas
- [docs/PATTERNS/FRONTEND-ARCH.md](docs/PATTERNS/FRONTEND-ARCH.md): colocation, dados, sessão, formulários
- [docs/DESIGN-SYSTEM.md](docs/DESIGN-SYSTEM.md): tokens, tipografia, componentes
- [docs/MODULOS.md](docs/MODULOS.md): criar projeto com os módulos escolhidos e atualizar por módulo
- `CLAUDE.md` (e o symlink `AGENTS.md`): guia para agentes de código
- `.agents/skills/`: `backend-domain`, `new-screen` e a skill oficial `react-router`

## Deploy

`Dockerfile` multi-stage: build com bun e Node, runtime `node:24-alpine` como usuário `node`, com
`HEALTHCHECK` em `/api/health`. O `docker-compose.yml` é o do Dokploy: sem `ports:` publicadas, o
domínio é cadastrado na aba Domains. Variáveis obrigatórias: `SESSION_SECRET` e `SEED_PASSWORD`.
domínio é cadastrado na aba Domains. Variáveis obrigatórias: `SESSION_SECRET`, `SEED_PASSWORD`, `VAPID_PUBLIC_KEY` e `VAPID_PRIVATE_KEY` (`bunx web-push generate-vapid-keys`).

Versão e CHANGELOG saem do release-please, a partir das mensagens de commit em Conventional Commits.

## Criar um projeto a partir do template

1. "Use this template" no GitHub, ou copie o repositório.
2. Troque o nome em `package.json`, `app/config/app.ts` e no título do contrato em `server/app.ts`.
3. Gere um `SESSION_SECRET` novo por ambiente.
1. Do Default, escolha os módulos e gere o projeto:
`bun run modulos novo ../MeuProjeto --com chat --nome meu-projeto`. Sem `--com`, vem só o core.
Notificações e chat são opcionais (guia em [docs/MODULOS.md](docs/MODULOS.md)).
2. Troque o nome em `app/config/app.ts` e no título do contrato em `server/app.ts`.
3. O `.env` de dev já sai pronto (admin@local.test, senha 12345678). Em staging e produção, gere um
`SESSION_SECRET` novo por ambiente.
4. Crie o secret `RELEASE_PLEASE_TOKEN` no repositório, para o PR de release rodar o CI.
5. Apague ou adapte o que o projeto não usa. O domínio de usuários e a sessão ficam: o resto depende
deles.
5. Para trazer correções do Default depois: `bun run modulos atualizar ../MeuProjeto [módulo]`, que
mostra o que muda antes de gravar.

## Notificações e conversas

Qualquer módulo avisa um usuário com `notifyUser(userId, { title, body, url })`. O aviso aparece na
tela Notificações e no contador da sidebar, põe `(N)` no título e no ícone da aba, e vira notificação
do sistema: pela página aberta (só com a janela sem foco) ou por Web Push com o app fechado. O par
VAPID do push vem do `.env` (`bunx web-push generate-vapid-keys`), obrigatório em produção. Avisos podem ser arquivados e silenciados por 8
horas, 1 semana ou sempre.

A tela Conversas é um chat entre os usuários, de duas pessoas ou em grupo, com não lidas, menção,
resposta citada e reações. Cada pessoa marca como não lida, silencia e arquiva as próprias conversas,
e configura no menu do perfil, separado para mensagens, grupos e avisos, se quer notificação, som e
prévia. Detalhes em `CLAUDE.md`, seções Notificações e Conversas.

## Próxima etapa

Expand Down
65 changes: 37 additions & 28 deletions app/app.css
Original file line number Diff line number Diff line change
Expand Up @@ -73,54 +73,63 @@
}

.dark {
--background: #090b0e;
/* Grafite em vez de quase preto. Três camadas de superfície, cada uma mais clara: página, sidebar e
card, e por cima menu e modal. No escuro a sombra quase não aparece, então a separação vem do tom. */
--background: #13171e;
--foreground: #f3f5f8;
--card: #0f1217;
--card: #1c222c;
--card-foreground: #f3f5f8;
--popover: #0f1217;
--popover: #242b37;
--popover-foreground: #f3f5f8;

--primary: #0066ff;
--primary-foreground: #ffffff;
--primary-glow: rgba(0, 102, 255, 0.12);
/* #0066ff fica abaixo de 4:1 sobre o card escuro. Este azul passa de 4,5:1 como texto em todas as
superfícies, e por ser claro o texto do botão preenchido é escuro (6,4:1), não branco. */
--primary: #4d94ff;
--primary-foreground: #0b0e13;
--primary-glow: rgba(77, 148, 255, 0.16);

--secondary: rgba(255, 255, 255, 0.06);
--secondary: rgba(255, 255, 255, 0.08);
--secondary-foreground: #f3f5f8;
--muted: rgba(255, 255, 255, 0.03);
--muted-foreground: #8e99a7;
--accent: rgba(255, 255, 255, 0.06);
--muted: rgba(255, 255, 255, 0.045);
--muted-foreground: #a7b1be;
--accent: rgba(255, 255, 255, 0.08);
--accent-foreground: #f3f5f8;

--destructive: #ff4a5a;
--border: rgba(255, 255, 255, 0.2);
--destructive: #ff5f6d;
--border: rgba(255, 255, 255, 0.1);
--input: rgba(255, 255, 255, 0.2);
--ring: rgba(0, 102, 255, 0.4);
--ring: rgba(77, 148, 255, 0.5);

--sidebar: #090b0e;
--sidebar: #171c24;
--sidebar-foreground: #f3f5f8;
--sidebar-primary: #0066ff;
--sidebar-primary-foreground: #ffffff;
--sidebar-accent: rgba(255, 255, 255, 0.06);
--sidebar-primary: #4d94ff;
--sidebar-primary-foreground: #0b0e13;
--sidebar-accent: rgba(255, 255, 255, 0.08);
--sidebar-accent-foreground: #f3f5f8;
--sidebar-border: rgba(255, 255, 255, 0.2);
--sidebar-ring: rgba(0, 102, 255, 0.4);
--sidebar-border: rgba(255, 255, 255, 0.1);
--sidebar-ring: rgba(77, 148, 255, 0.5);

--dim: #556070;
--success: #0066ff;
--dim: #8590a0; /* 4:1 sobre o card e o menu, para ícone e dica continuarem visíveis */
--success: #4d94ff;
--warning: #ffb700;
--skeleton: #1b2532;
--badge-primary-fg: #4d94ff;
--badge-primary-bg: rgba(0, 102, 255, 0.12);
--skeleton: #2a323e;
--badge-primary-fg: #7ab0ff;
--badge-primary-bg: rgba(77, 148, 255, 0.16);
--badge-destructive-fg: #ff4a5a;
--badge-destructive-bg: rgba(255, 74, 90, 0.12);
--badge-warning-fg: #ffb700;
--badge-warning-bg: rgba(255, 183, 0, 0.12);

--elevation-card: 0 4px 12px rgba(0, 0, 0, 0.1);
--elevation-card-elevated: 0 10px 40px rgba(0, 0, 0, 0.1), 0 20px 50px rgba(0, 0, 0, 0.45);
--elevation-modal: 0 10px 40px rgba(0, 0, 0, 0.1), 0 20px 50px rgba(0, 0, 0, 0.45);
/* Fio claro no topo marca a borda de cima da superfície, e a sombra escura a de baixo. */
--elevation-card: inset 0 1px 0 rgba(255, 255, 255, 0.04), 0 4px 12px rgba(0, 0, 0, 0.35);
--elevation-card-elevated:
inset 0 1px 0 rgba(255, 255, 255, 0.05), 0 10px 40px rgba(0, 0, 0, 0.4),
0 20px 50px rgba(0, 0, 0, 0.5);
--elevation-modal:
inset 0 1px 0 rgba(255, 255, 255, 0.06), 0 10px 40px rgba(0, 0, 0, 0.5),
0 24px 60px rgba(0, 0, 0, 0.6);
--elevation-primary-glow: 0 0 16px var(--primary-glow);
--scrollbar-thumb: rgba(255, 255, 255, 0.1);
--scrollbar-thumb: rgba(255, 255, 255, 0.18);
}

@theme inline {
Expand Down
2 changes: 1 addition & 1 deletion app/components/layout/AuthCard.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { APP_NAME } from "~/config/app";
// Moldura das telas fora do app (login, troca obrigatória de senha).
export function AuthCard({ subtitle, children }: { subtitle: string; children: React.ReactNode }) {
return (
<div className="h-screen w-full overflow-y-auto bg-background selection:bg-primary/30">
<div className="h-dvh w-full overflow-y-auto bg-background selection:bg-primary/30">
<div className="relative flex min-h-full w-full items-center justify-center overflow-hidden p-6">
<div className="pointer-events-none absolute top-[-10%] left-[-10%] h-[40%] w-[40%] rounded-full bg-primary/5 blur-[120px]" />

Expand Down
Loading
Loading