diff --git a/BACKEND.md b/BACKEND.md index fca9dbc..9c7512c 100644 --- a/BACKEND.md +++ b/BACKEND.md @@ -11,6 +11,8 @@ Este documento descreve as principais funcionalidades, rotas, módulos e variáv - Banco de dados gerenciado com Drizzle (Postgres). - Autenticação via OAuth (Google/GitHub/LinkedIn) e credenciais (email/senha) com `iron-session`. - Cache/índices em memória (Redis) e integração com sistema Valkey para pesquisa rápida. +- Rotas administrativas para usuários, permissões, scrapers, auditoria e observabilidade. +- Métricas Prometheus em `/metrics`. - Documentação OpenAPI/Swagger disponível em `/docs` (quando habilitado). ## Como executar (rápido) @@ -40,12 +42,13 @@ npm test npm run test:watch ``` -Scripts relevantes em `package.json`: +Scripts relevantes em `backend/package.json`: - `start`, `dev`, `api` — iniciar servidor - `scraper`, `scraper:watch` — executar scraper (index.ts / Go) - `test`, `test:coverage`, `test:watch` — testes com Vitest - `db:generate`, `db:migrate`, `db:push` — comandos Drizzle +- `security:backfill-user-pii` — backfill de campos de PII criptografados ## Arquitetura e módulos principais @@ -59,7 +62,9 @@ Módulos principais: - `src/modules/auth` — OAuth providers, `AuthController`, `AuthService`, `credentials` (registro/login/logout). - `src/modules/users` — perfis e preferências do usuário (`UsersController`, `UsersService`). - `src/modules/savedJobs` — CRUD de vagas salvas (`SavedJobsController`, `SavedJobsService`). -- `src/modules/*` — outros módulos relacionados a credenciais, buscas e integrações. +- `src/modules/notifications` — notificações do usuário autenticado. +- `src/modules/jobs` — regras de matching/score de vagas. +- `src/modules/admin` — usuários admin, permissões, scrapers, auditoria, dashboard e observabilidade. Adaptadores externos: @@ -85,6 +90,8 @@ Cache & Indexes: - `requireAuth` — valida autenticação nas rotas que exigem usuário. - `securityHeaders` — cabeçalhos de segurança. - `cors` — configuração de CORS (opções em `src/middleware/cors.ts`). +- `requestId` — correlação de requisições. +- `metrics` — coleta de métricas Prometheus. - `errorHandler` — tratamento centralizado de erros. ## Endpoints principais @@ -93,6 +100,7 @@ Base: `/` - Sistema - `GET /health` — verifica disponibilidade (retorna `{ ok: true }`). + - `GET /metrics` — métricas Prometheus. - `GET /docs` — UI do Swagger (quando habilitado). - Auth / OAuth @@ -119,6 +127,12 @@ Base: `/` - `GET /keywords` — lista keywords persistidas no banco. - `POST /keywords` — enfileira uma keyword para processamento pelo serviço Go (retorna 202). +- Notificações + - `GET /notifications` — lista notificações do usuário autenticado. + - `PATCH /notifications/:id/read` — marca uma notificação como lida. + - `PATCH /notifications/read-all` — marca todas como lidas. + - `DELETE /notifications` — limpa notificações conforme filtros aceitos. + - Vagas salvas (Saved Jobs) - `GET /saved-jobs` — lista vagas salvas do usuário. - `GET /saved-jobs/:id` — obtém vaga salva por id. @@ -126,9 +140,21 @@ Base: `/` - `PATCH /saved-jobs/:id` — atualiza vaga salva. - `DELETE /saved-jobs/:id` — remove vaga salva. +- Admin + - `GET /admin/users` — lista usuários. + - `GET /admin/users/:id` — obtém usuário por id. + - `PATCH /admin/users/:id/block` — bloqueia usuário. + - `PATCH /admin/users/:id/unblock` — desbloqueia usuário. + - `POST /admin/users/:id/reset` — reseta credenciais/senha conforme regra do serviço. + - `POST /admin/scrapers/run` — dispara execução dos scrapers. + - `GET /admin/observability/metrics` — visão de métricas administrativas. + - `GET /admin/observability/dashboards` — lista dashboards de observabilidade. + - `GET /admin/audit` — consulta logs de auditoria. + - `GET /admin/permissions/rules` — lista regras de permissão. + Observações de segurança nas rotas: -- Rotas sob `/users`, `/jobs`, `/keywords` e `/saved-jobs` usam `withSession` + `requireAuth` (quando aplicável). +- Rotas sob `/users`, `/jobs`, `/keywords`, `/notifications`, `/saved-jobs` e `/admin` usam `withSession` + `requireAuth` (quando aplicável). - `auth` usa `withSession` para armazenar OAuth state e criar sessão. ## Variáveis de ambiente importantes @@ -148,6 +174,9 @@ Definidas/consumidas em `src/config.ts` e outros módulos: - `VALKEY_URL` — endpoint do Valkey (se usado). - `GO_SCRAPER_URL` — URL do serviço Go que realiza scraping. - `SESSION_SECRET` — senha para `iron-session` (obrigatória em produção). +- `ENCRYPTION_MASTER_KEY`, `ENCRYPTION_KEY_ID`, `SEARCH_KEY` — criptografia e campos pesquisáveis de PII. +- `CORS_ALLOWED_ORIGINS` — origens permitidas, incluindo `http://localhost:5173` e `http://localhost:5174` em desenvolvimento local com admin. +- `PROMETHEUS_URL` — integração com Prometheus para rotas de observabilidade. - `PORT` — porta do servidor (padrão 3001). ## Segurança e criptografia @@ -155,6 +184,7 @@ Definidas/consumidas em `src/config.ts` e outros módulos: - Senhas armazenadas usando Argon2 (`argon2`), com opções configuradas no serviço de credenciais. - Cookies de sessão `httpOnly` e `secure` quando NODE_ENV=production. - Índices únicos e constraints no DB (ex: email/username/keyword uniques) definidos nas tabelas Drizzle. +- Campos sensíveis de perfil usam criptografia e hashes pesquisáveis onde aplicável. ## Integração com serviço Go @@ -179,8 +209,11 @@ Definidas/consumidas em `src/config.ts` e outros módulos: ## Docker / Infra -- `Dockerfile` presente no diretório `backend`. -- `docker-compose.yml` no projeto raiz orquestra serviços (possivelmente `scraper-go`, `postgres`, `redis`). +- `backend/Dockerfile` existe para o backend. +- O fluxo Docker principal usa `docker/node.Dockerfile` com targets para backend, frontend e admin. +- `docker-compose.yml` no projeto raiz orquestra `scraper-go`, `backend`, `frontend` e `front_admin`. +- `docker-compose.infra.yml` sobe Postgres e Valkey. +- `docker-compose.migrate.yml` executa migrations e backfill antes do backend. ## Pontos de atenção / Próximos passos sugeridos @@ -200,7 +233,7 @@ Seguem exemplos práticos para os endpoints mais usados. Ajuste `HOST` para seu Request: -POST /api/auth/register +POST /auth/register ```json { @@ -229,7 +262,7 @@ Response (201): Request: -POST /api/auth/login +POST /auth/login ```json { @@ -251,7 +284,7 @@ Response (200): Request: -GET /api/jobs/search?keywords=react,node&page=1&limit=10 +GET /jobs/search?keywords=react,node&page=1&limit=10 Response (200): @@ -272,7 +305,7 @@ Response (200): Request: -POST /api/keywords +POST /keywords ```json { @@ -293,7 +326,7 @@ Response (202): Request: -POST /api/saved-jobs +POST /saved-jobs ```json { @@ -325,7 +358,7 @@ Response (201): Request: -GET /api/users/profile +GET /users/profile Response (200): diff --git a/README.md b/README.md index 23faa26..606683a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ![Monorepo](https://img.shields.io/badge/architecture-monorepo-0A66C2) ![License ISC](https://img.shields.io/badge/license-ISC-lightgrey) -Plataforma de captura, agregação e consulta de vagas com arquitetura monorepo, composta por frontend web, backend Node.js e aplicação desktop com Electron. +Plataforma de captura, agregação e consulta de vagas com arquitetura monorepo, composta por frontend web, API Node.js, scraper Go, painel administrativo e aplicação desktop com Electron. O produto evoluiu para um modelo orientado a serviços (API + scraper Go + cache/índices), com autenticação, preferências de usuário e integração com banco de dados. @@ -32,17 +32,18 @@ O produto evoluiu para um modelo orientado a serviços (API + scraper Go + cache - [Testes e qualidade](#testes-e-qualidade) - [Fluxo de desenvolvimento e branching](#fluxo-de-desenvolvimento-e-branching) - [Git Hooks e qualidade local](#git-hooks-e-qualidade-local) -- [Inconsistências atuais mapeadas](#inconsistências-atuais-mapeadas) - [Roadmap técnico sugerido](#roadmap-técnico-sugerido) - [Contribuição](#contribuição) ## Visão geral -Este repositório centraliza três frentes: +Este repositório centraliza as frentes principais do produto: -- Frontend React para visualização e operação da plataforma. -- Backend Node.js/Express (TypeScript) com autenticação, preferências e rotas de domínio. -- Scraper em Go para coleta de vagas em múltiplas fontes. +- `frontend`: aplicação web para usuários finais, com landing page, autenticação e dashboard de vagas. A nova estrutura de painel do frontend fica em `frontend/src/domains/new_dashboard`. +- `backend`: API Node.js/Express com autenticação, perfis, preferências, vagas salvas, notificações, rotas admin e observabilidade. +- `scraper-go`: serviço Go de scraping multi-fonte, cache, deduplicação e indexação em Valkey. +- `front_admin`: painel administrativo para operação, usuários, permissões, scrapers, auditoria e observabilidade. +- `electron`: shell desktop que empacota a experiência principal. Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão de vagas com foco em qualidade de dados, escalabilidade e operação contínua. @@ -53,8 +54,9 @@ Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão d ├─ frontend/ # Dashboard web (React + Vite) ├─ backend/ # API Node.js (Express + TS + Drizzle) ├─ scraper-go/ # Serviço Go de scraping multi-fonte +├─ front_admin/ # Painel administrativo (React + Vite) ├─ electron/ # Shell desktop -├─ docker-compose.yml # App stack (frontend + backend + scraper-go) +├─ docker-compose.yml # App stack (frontend + front_admin + backend + scraper-go) ├─ docker-compose.infra.yml # Infra stack (Postgres + Valkey) ├─ docker-compose.migrate.yml # Migration job do backend └─ .github/workflows/ci.yml # CI @@ -63,10 +65,11 @@ Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão d ## Stack real do projeto - Frontend: React 19, TypeScript, Vite 8, Tailwind CSS, Vitest. +- Front admin: React 19, TypeScript, Vite 8, Tailwind CSS 4, Vitest. - Backend: Node.js 22+, Express 5, TypeScript, Drizzle ORM, Zod, Iron Session, Redis/Valkey. - Scraping: Go (serviço dedicado em scraper-go). - Desktop: Electron + Electron Builder. -- Qualidade: Vitest (frontend/backend), cobertura v8, ESLint (frontend), GitHub Actions CI. +- Qualidade: Vitest (frontend/backend/front_admin), cobertura v8, ESLint (frontend/front_admin), GitHub Actions CI. - Dados: Postgres (persistência) + Valkey/Redis (cache e índice). ## Quickstart local @@ -79,12 +82,12 @@ Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão d ### Caminho recomendado: stack completa com Docker -Use este fluxo para subir Postgres, Valkey, scraper Go, backend e frontend com a mesma rede Docker. +Use este fluxo para subir Postgres, Valkey, scraper Go, backend, frontend e front_admin com a mesma rede Docker. 1. Instale as dependências locais: ```bash -npm ci +npm install ``` 2. Crie o `.env` da raiz a partir do exemplo versionado: @@ -107,7 +110,7 @@ docker network create vagas-net Se a rede já existir, o Docker vai avisar e você pode seguir para o próximo passo. -4. Suba Postgres, Valkey, scraper, backend e frontend: +4. Suba Postgres, Valkey, scraper, backend, frontend e front_admin: ```bash docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml up --build -d @@ -116,6 +119,7 @@ docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compo 5. Acesse os serviços: - Frontend: http://localhost:5173 +- Front admin: http://localhost:5174 - Backend health: http://localhost:3001/health - Scraper health: http://localhost:8081/health - Vagas salvas no scraper: http://localhost:8081/admin/jobs/count @@ -129,6 +133,7 @@ Arquivos esperados: - `.env`: usado pela infra/scraper e por comandos auxiliares. - `backend/.env`: usado pelo backend local. - `frontend/.env`: usado pelo Vite local. +- `front_admin` usa `VITE_API_URL`, mas ainda não possui `.env.example` próprio. Criação dos arquivos locais: @@ -150,11 +155,20 @@ Comandos: npm run dev ``` +Esse comando sobe apenas o necessário para a maioria das contribuições: frontend e backend. + +Para trabalhar também no painel administrativo: + +```bash +npm run dev:admin +``` + Execução separada: ```bash npm run dev:frontend npm run dev:backend +npm run dev:front_admin ``` ### Execução de testes @@ -163,21 +177,30 @@ npm run dev:backend npm run test:coverage ``` +### Instalação limpa e CI + +Para onboarding e desenvolvimento local, prefira `npm install`. + +Use `npm ci` em automações como GitHub Actions, Docker/deploy ou quando quiser reinstalar tudo exatamente a partir do `package-lock.json`. Ele remove `node_modules`, não altera o lockfile e falha se `package.json` e `package-lock.json` estiverem fora de sincronia. + ## Comandos verificados -Os comandos abaixo existem hoje no repositório e foram conferidos nos package.json de raiz, frontend e backend. +Os comandos abaixo existem hoje no repositório e foram conferidos nos `package.json` da raiz, backend, frontend e front_admin. ### Raiz - npm run dev +- npm run dev:admin - npm run dev:frontend - npm run dev:backend +- npm run dev:front_admin - npm run scraper - npm run scraper:watch - npm run test - npm run test:coverage - npm run build - npm run build:frontend +- npm run build:front_admin - npm run validate - npm run electron - npm run electron:dev @@ -209,6 +232,15 @@ Os comandos abaixo existem hoje no repositório e foram conferidos nos package.j - npm run test:coverage - npm run test:watch +### Front admin + +- npm run dev +- npm run build +- npm run lint +- npm run test +- npm run test:coverage +- npm run preview + ## API backend (estado atual) Base: / @@ -251,6 +283,19 @@ Saved jobs: - PATCH /saved-jobs/:id - DELETE /saved-jobs/:id +Admin: + +- GET /admin/users +- GET /admin/users/:id +- PATCH /admin/users/:id/block +- PATCH /admin/users/:id/unblock +- POST /admin/users/:id/reset +- POST /admin/scrapers/run +- GET /admin/observability/metrics +- GET /admin/observability/dashboards +- GET /admin/audit +- GET /admin/permissions/rules + Swagger: - GET /docs @@ -260,7 +305,7 @@ Swagger: Este projeto separa infraestrutura e aplicação em dois arquivos Compose: - `docker-compose.infra.yml`: Postgres + Valkey. -- `docker-compose.yml`: scraper Go + backend + frontend. +- `docker-compose.yml`: scraper Go + backend + frontend + front_admin. - `docker-compose.migrate.yml`: job de migrations do backend. Subir infraestrutura, migrations e aplicação: @@ -289,6 +334,7 @@ Ver logs: docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml logs -f migrate docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml logs -f backend docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml logs -f frontend +docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml logs -f front_admin docker compose -f docker-compose.infra.yml -f docker-compose.yml -f docker-compose.migrate.yml logs -f scraper-go ``` @@ -312,6 +358,7 @@ Por isso o `docker-compose.yml` e o `docker-compose.migrate.yml` sobrescrevem va Serviços padrão: - Frontend: http://localhost:5173 +- Front admin: http://localhost:5174 - Backend: http://localhost:3001 - Scraper Go: http://localhost:8081 @@ -356,12 +403,14 @@ Arquivos locais ignorados pelo Git: - .env - backend/.env - frontend/.env +- front_admin/.env, se criado localmente Uso recomendado: - Docker Compose: copie `.env.example` para `.env`. O Compose usa esse arquivo para infra, scraper, backend e build do frontend. - Backend local via Node: use `backend/.env`. - Frontend local via Vite: use `frontend/.env`. +- Front admin local via Vite: crie `front_admin/.env` com `VITE_API_URL=http://localhost:3001` quando precisar sobrescrever o padrão. Variáveis centrais de operação: @@ -380,6 +429,10 @@ Variáveis centrais de operação: - PAGE_TIMEOUT_MS - MAX_PAGES_PER_KEYWORD - CACHE_TTL_MS +- VITE_API_BASE_URL +- VITE_API_URL +- VITE_API_PROXY_TARGET +- VITE_APP_ENV Segurança operacional: @@ -395,6 +448,7 @@ Estrutura: - backend/tests/integration - frontend/tests/unit - frontend/tests/integration +- front_admin/tests Threshold mínimo: @@ -409,6 +463,7 @@ Comandos: npm run test:coverage npm --workspace frontend run test:coverage npm --workspace backend run test:coverage +npm --workspace front_admin run test:coverage ``` Observação importante: o backend já está configurado para coletar cobertura apenas em src/**/*.ts, evitando contagem de artefatos gerados. @@ -425,6 +480,8 @@ Executa em push para master/develop e em pull_request: - Lint frontend - Build frontend +Observação: o painel admin já possui testes e build próprios, mas ainda deve ser incluído no fluxo de validação/CI quando se tornar parte obrigatória do release. + ## Fluxo de desenvolvimento e branching Padrão oficial: @@ -451,7 +508,7 @@ Hooks configurados: - commit-msg: valida mensagem de commit com commitlint (Conventional Commits). - pre-push: executa validação do monorepo (test backend + lint/build frontend). -Bootstrap recomendado para novos ambientes: +Bootstrap local com instalação e hooks: ```bash npm run setup:dev @@ -515,4 +572,6 @@ Se você vai trabalhar em backend, scraper ou testes, use também: - [BACKEND.md](BACKEND.md) - [SCRAPER.md](SCRAPER.md) +- [frontend/README.md](frontend/README.md) +- [front_admin/README.md](front_admin/README.md) - [TESTING.md](TESTING.md) diff --git a/SCRAPER.md b/SCRAPER.md index 356aeb9..26d9a29 100644 --- a/SCRAPER.md +++ b/SCRAPER.md @@ -90,7 +90,7 @@ Arquivo: `scraper-go/openapi.yaml` (no repositório) --- -O scraper é um serviço que consulta múltiplas fontes de vagas (LinkedIn, Adzuna, Greenhouse, TheMuse, Lever, Jooble, etc.), agrega os resultados, remove duplicatas e persiste/retorna as vagas via cache (Redis / Valkey). Ele foi projetado para ser usado internamente pelo backend Node.js, que delega buscas ao serviço Go. +O scraper é um serviço HTTP em Go que consulta múltiplas fontes de vagas (LinkedIn, Adzuna, Greenhouse, TheMuse, Lever, Jooble, etc.), agrega os resultados, remove duplicatas e persiste/retorna as vagas via cache e índice Redis/Valkey. Ele foi projetado para ser usado internamente pelo backend Node.js, que delega buscas ao serviço Go. Componentes principais: @@ -102,6 +102,8 @@ Componentes principais: - `internal/dedup` — regras para deduplicação/merge de vagas. - `internal/keywords` — carregamento e persistência de keywords (configuração). - `internal/inflight` — deduplicador de requisições concorrentes (singleflight). +- `internal/cronjob` — scheduler de scraping em background e execução manual. +- `internal/metrics` — métricas Prometheus por fonte/execução. ## Como executar @@ -124,17 +126,21 @@ go run ./cmd/server Docker: há um `Dockerfile` em `scraper-go/`. No Docker Compose, configure `VALKEY_URL=redis://valkey:6379/0` no `.env` da raiz para que o scraper acesse o Valkey pelo nome do serviço na rede Docker. +No Compose da raiz, o serviço escuta em http://localhost:8081. + ## Endpoints HTTP O serviço expõe endpoints HTTP (implementação em `cmd/server` e arquivos associados). Principais rotas: - POST `/scrape` — body JSON com `ScrapeRequest` para disparar uma busca em todas as fontes configuradas. Retorna `ScrapeResponse` com `jobs`, `total`, `cachedAt` e `fromCache`. - GET `/health` — verifica se o scraper está online e qual cache está em uso. +- GET `/metrics` — métricas Prometheus. - GET `/api/keywords` — retorna as keywords atualmente carregadas. - POST `/api/keywords` — atualiza/persiste as keywords (aceita `keywords: string[]`). +- POST `/admin/scrape` — dispara uma execução manual em background; retorna 409 se já houver execução em andamento. - GET `/admin/scrape/status` — informa se existe uma execução em andamento. - GET `/admin/jobs/count` — retorna a quantidade de vagas persistidas no Valkey. -- GET `/admin/jobs` — lista as vagas persistidas no Valkey. +- GET `/admin/jobs` — lista uma amostra das vagas persistidas no Valkey; aceita `limit`. Exemplo de `ScrapeRequest` (JSON): @@ -178,7 +184,7 @@ Exemplo de `ScrapeResponse` (JSON): } ``` -> Observação: os nomes dos endpoints e o prefixo podem variar conforme a implementação local; verifique `cmd/server` para confirmar a porta e rotas ativadas. +> Observação: os endpoints acima refletem a implementação atual em `scraper-go/cmd/server`. ## Pipeline de scraping @@ -243,7 +249,7 @@ Boas práticas nos adaptadores: - Projetado para rodar frequentemente; use caching e indexação para reduzir chamadas repetidas. - Monitorar erros 429 e ajustar `WaitBetweenSearchesMs` / semáforos por adaptador. -- Verifique logs estruturados (slog JSON) para métricas de sucesso/falhas por adaptador. +- Verifique logs estruturados (slog JSON) e `/metrics` para métricas de sucesso/falhas por adaptador. --- diff --git a/front_admin/README.md b/front_admin/README.md index c300135..c3f4169 100644 --- a/front_admin/README.md +++ b/front_admin/README.md @@ -1,75 +1,107 @@ -# React + TypeScript + Vite +# Front Admin -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +Painel administrativo do , separado da experiência principal para reduzir atrito no onboarding de contribuidores. -Currently, two official plugins are available: +Use este workspace quando a tarefa envolver operação da plataforma, gestão de usuários, permissões, scrapers, auditoria, observabilidade ou configurações administrativas. -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +## Stack -## React Compiler +- React 19 +- TypeScript +- Vite 8 +- Tailwind CSS 4 +- Lucide React +- Zod +- Vitest + Testing Library -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). +## Como executar -## Expanding the ESLint configuration +Na raiz do monorepo, instale as dependências: -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +```bash +npm install +``` + +Para subir frontend, backend e painel administrativo juntos: + +```bash +npm run dev:admin +``` + +Para executar apenas o painel: + +```bash +npm run dev --workspace=front_admin +``` + +Quando executado junto com o frontend principal, use a porta http://localhost:5174 para o admin. + +## Variáveis de ambiente + +O workspace ainda não possui `front_admin/.env.example` versionado. + +Para desenvolvimento local, crie `front_admin/.env` quando precisar configurar explicitamente a API: + +```bash +VITE_API_URL=http://localhost:3001 +``` + +O backend precisa permitir a origem do admin em `CORS_ALLOWED_ORIGINS`, por exemplo: + +```bash +CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174 +``` + +## Organização + +- `src/app`: providers, rotas, layout principal, páginas de erro e proteção de rotas. +- `src/app/layouts/MainLayout`: sidebar, header, busca, filtros de tempo, menu de usuário e notificações. +- `src/modules/auth`: login administrativo e estado de autenticação. +- `src/modules/dashboard`: visão geral de métricas, serviços e scrapers. +- `src/modules/users`: listagem, edição, bloqueio e ações administrativas de usuários. +- `src/modules/permissions`: regras e matriz de permissões. +- `src/modules/scrapers`: status, execução e console de eventos dos scrapers. +- `src/modules/observability`: painéis, métricas e uso de infraestrutura. +- `src/modules/audit`: logs de auditoria. +- `src/modules/settings`: configurações administrativas. +- `src/lib/api`: clientes HTTP e contratos das rotas admin. +- `src/lib/theme`: tokens, cores e tema. +- `src/components`: providers, UI compartilhada, tema, notificações e estados comuns. + +## Rotas principais + +- `/login`: autenticação do painel. +- `/`: dashboard administrativo. +- `/users`: gestão de usuários. +- `/permissions`: permissões. +- `/scrapers`: operação de scrapers. +- `/observability`: saúde da plataforma. +- `/audit`: auditoria. +- `/settings`: configurações. + +## Comandos + +```bash +npm run dev --workspace=front_admin +npm run build --workspace=front_admin +npm run lint --workspace=front_admin +npm run test --workspace=front_admin +npm run test:coverage --workspace=front_admin +npm run preview --workspace=front_admin +``` -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... +## Testes - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, +Os testes ficam em `front_admin/tests` e cobrem rotas, layout, módulos administrativos, schemas, API clients, hooks e componentes compartilhados. - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +Para rodar somente os testes do admin: +```bash +npm run test --workspace=front_admin ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: - -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x' -import reactDom from 'eslint-plugin-react-dom' - -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +Para cobertura: +```bash +npm run test:coverage --workspace=front_admin ``` diff --git a/frontend/ARCHITECTURE.md b/frontend/ARCHITECTURE.md index 173f4ed..56ef6dd 100644 --- a/frontend/ARCHITECTURE.md +++ b/frontend/ARCHITECTURE.md @@ -1,22 +1,23 @@ -# Frontend Architecture +# Arquitetura do Frontend -The frontend is organized around domain boundaries instead of technical file types. +O frontend é organizado por domínios de negócio, não por tipos técnicos de arquivo. -## Layers +## Camadas -- `src/app`: application composition, providers, routing, and app-level pages. -- `src/domains//domain`: business types and pure rules without React or HTTP. -- `src/domains//application`: React hooks and use-cases that orchestrate domain rules. -- `src/domains//infrastructure`: API gateways and transport-specific code. -- `src/domains//presentation`: pages and components owned by that domain. -- `src/shared`: reusable UI primitives, assets, hooks, and technical utilities. +- `src/app`: composição da aplicação, providers, rotas e páginas de nível global. +- `src/domains//domain`: tipos de negócio e regras puras, sem React ou HTTP. +- `src/domains//application`: hooks React e casos de uso que orquestram regras de domínio. +- `src/domains//infrastructure`: gateways de API e código específico de transporte. +- `src/domains//presentation`: páginas e componentes pertencentes ao domínio. +- `src/shared`: primitivas de UI, assets, hooks e utilitários técnicos reutilizáveis. -## Domains +## Domínios -- `auth`: session state, credentials/OAuth API access, login/register/callback screens. -- `jobs`: job entities, filtering/deduplication/pagination rules, scraper/job API access, dashboard UI. -- `marketing`: public landing page sections. +- `auth`: estado de sessão, acesso à API de credenciais/OAuth e telas de login, registro e callback. +- `jobs`: entidades de vagas, filtros, deduplicação, paginação, acesso à API de vagas/scraper e UI de vagas. +- `marketing`: seções da landing page pública. +- `new_dashboard`: nova estrutura de painel do frontend. Contribuidores que procuram a experiência atual de dashboard devem começar por aqui. -## Import policy +## Política de imports -Code should import from `@/app`, `@/domains`, or `@/shared`. Legacy technical folders such as `src/components`, `src/pages`, `src/hooks`, `src/services`, `src/context`, `src/lib`, and `src/types` were removed to keep a single domain-oriented structure. +O código deve importar a partir de `@/app`, `@/domains` ou `@/shared`. Pastas técnicas antigas como `src/components`, `src/pages`, `src/hooks`, `src/services`, `src/context`, `src/lib` e `src/types` foram removidas para manter uma estrutura única orientada por domínio. diff --git a/frontend/README.md b/frontend/README.md index a36934d..89f4cfc 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,16 +1,90 @@ -# React + Vite +# Frontend -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +Aplicação web principal do , voltada para usuários finais. -Currently, two official plugins are available: +Ela concentra a landing page pública, autenticação, callback OAuth e dashboard de vagas com filtros, detalhes, vagas salvas, perfil e preferências. -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +## Stack -## React Compiler +- React 19 +- TypeScript +- Vite 8 +- React Router +- Tailwind CSS +- Vitest + Testing Library -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). +## Como executar -## Expanding the ESLint configuration +Na raiz do monorepo, instale as dependências: -If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project. +```bash +npm install +``` + +Para subir frontend e backend juntos: + +```bash +npm run dev +``` + +Para executar apenas este workspace: + +```bash +npm run dev --workspace=frontend +``` + +Por padrão o Vite usa http://localhost:5173. + +## Variáveis de ambiente + +Crie o arquivo local a partir do exemplo: + +```bash +cp frontend/.env.example frontend/.env +``` + +Variáveis usadas: + +- `VITE_API_BASE_URL`: URL base da API, normalmente `http://localhost:3001`. +- `VITE_API_PROXY_TARGET`: alvo do proxy Vite quando chamadas relativas forem usadas. + +## Organização + +O frontend segue uma estrutura orientada por domínio: + +- `src/app`: composição da aplicação, providers, rotas e layouts autenticados. +- `src/domains/auth`: login, registro, callback OAuth e estado de sessão. +- `src/domains/jobs`: busca, filtros, paginação e interface de vagas. +- `src/domains/marketing`: landing page pública. +- `src/domains/new_dashboard`: nova estrutura de painel do frontend. É aqui que contribuidores devem procurar a experiência nova de dashboard, com abas de home, vagas, mentoring, perfil e ajuda. +- `src/shared`: componentes de UI, assets, hooks e utilitários reutilizáveis. + +Veja também [ARCHITECTURE.md](ARCHITECTURE.md). + +## Comandos + +```bash +npm run dev --workspace=frontend +npm run build --workspace=frontend +npm run lint --workspace=frontend +npm run test --workspace=frontend +npm run test:coverage --workspace=frontend +npm run test:watch --workspace=frontend +npm run preview --workspace=frontend +``` + +## Testes + +Os testes ficam em `frontend/tests` e cobrem componentes, páginas, hooks, contexto de autenticação, serviços e regras de domínio. + +Para rodar somente os testes do frontend: + +```bash +npm run test --workspace=frontend +``` + +Para cobertura: + +```bash +npm run test:coverage --workspace=frontend +``` diff --git a/package.json b/package.json index 041a852..84482cd 100644 --- a/package.json +++ b/package.json @@ -12,8 +12,9 @@ ], "scripts": { "prepare": "husky", - "setup:dev": "npm ci && npm run prepare", - "dev": "concurrently \"npm run dev --workspace=frontend\" \"npm run dev --workspace=backend\" \"npm run dev --workspace=front_admin\"", + "setup:dev": "npm install && npm run prepare", + "dev": "concurrently \"npm run dev --workspace=frontend\" \"npm run dev --workspace=backend\"", + "dev:admin": "concurrently \"npm run dev --workspace=frontend\" \"npm run dev --workspace=backend\" \"npm run dev --workspace=front_admin\"", "dev:frontend": "npm run dev --workspace=frontend", "dev:backend": "npm run dev --workspace=backend", "dev:front_admin": "npm run dev --workspace=front_admin",