diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..59650d2 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,23 @@ +# GoHorse Jobs – Regras de Contexto para IA + +## 1) Regras de Ouro (Obrigatórias) +- **TypeScript estrito**: não use `any`. Prefira tipos explícitos, `unknown` e validação. +- **IDs são UUID v7**: todos os `id`, `userId`, `companyId`, `jobId`, etc. devem ser UUID v7 (string). +- **Sincronia de contrato**: qualquer alteração em modelos Go exige **verificação e atualização** dos tipos do frontend antes de escrever o código do backend. +- **Shadcn/UI**: não invente componentes; use apenas os existentes em `frontend/src/components/ui`. + +## 2) Âncoras de Contrato (Fonte da Verdade) +- **Backend**: `backend/internal/models` (JSON tags definem o contrato HTTP). +- **Frontend**: `frontend/src/lib/types.ts` (tipos usados na UI). +- **Entidades de domínio**: `backend/internal/core/domain/entity` (regras e semântica do domínio). + +## 3) Protocolo de Execução (sempre que receber uma tarefa) +1. **Check de Impacto**: liste quais arquivos do backend e frontend serão afetados. +2. **Validação de Contrato**: compare o JSON real do backend com os tipos do frontend. +3. **Plano de Execução**: apresente o plano em lista; só depois de aprovado, gere o código completo. + +## 4) Checklist rápido antes de finalizar +- Tipos TS sem `any` ✅ +- IDs como UUID v7 ✅ +- Contratos API alinhados ✅ +- Componentes UI existentes ✅ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..5a7618f --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,69 @@ +# GoHorse Jobs – Visão de Arquitetura + +## Backend (Clean Architecture) + +### Fluxo de dados +1. **Router (HTTP)** recebe as requisições e direciona para handlers. (`backend/internal/router/router.go`). +2. **Handlers** fazem validações básicas e delegam para **Use Cases** (core) ou serviços legados. (`backend/internal/api/handlers`, `backend/internal/handlers`). +3. **Use Cases** (core) orquestram regras de negócio e dependem de **repositórios/infrastructure**. (`backend/internal/core/usecases`, `backend/internal/infrastructure`). +4. **Repos/Services** persistem dados e retornam **Models** que são serializados em JSON. (`backend/internal/models`). + +### Domínio (entidades reais) +As entidades do domínio vivem em `backend/internal/core/domain/entity` e definem a semântica do negócio. Exemplos principais: +- **User** com roles, status e perfil completo. (`backend/internal/core/domain/entity/user.go`). +- **Company (Tenant)** com status e dados de contato. (`backend/internal/core/domain/entity/company.go`). +- **Location** (Country/State/City). (`backend/internal/core/domain/entity/location.go`). +- **Roles/Permissions** para RBAC. (`backend/internal/core/domain/entity/permission.go`). + +### Contratos HTTP (Models) +Os contratos expostos via JSON são definidos em `backend/internal/models`. +Principais modelos: +- **Job** com salário, workMode, employmentType, requisitos/benefícios e status. (`backend/internal/models/job.go`). +- **Company** com branding, endereço, status e metadados. (`backend/internal/models/company.go`). +- **User** e **UserResponse** (público). (`backend/internal/models/user.go`). +- **Application** e **ApplicationWithDetails** (job + applicant). (`backend/internal/models/application.go`). +- **Location** (Region/City). (`backend/internal/models/location.go`). +- **Notification**, **Ticket**, **LoginAudit**, **FavoriteJob**, **Tag**. (`backend/internal/models/notification.go`, `backend/internal/models/ticket.go`, `backend/internal/models/login_audit.go`, `backend/internal/models/favorite_job.go`, `backend/internal/models/tag.go`). + +### Rotas principais (v1) +O roteamento está centralizado em `backend/internal/router/router.go` com exemplos: +- **Auth**: `/api/v1/auth/login`, `/api/v1/auth/register`, `/api/v1/auth/logout`. +- **Users**: `/api/v1/users`, `/api/v1/users/{id}`, `/api/v1/users/me`. +- **Companies**: `/api/v1/companies` e ações de admin para status. +- **Jobs**: `/api/v1/jobs` e `/api/v1/jobs/{id}`. + +## Frontend (Next.js App Router) + +### Estrutura +- **App Router**: páginas e layouts em `frontend/src/app`. +- **Componentes**: `frontend/src/components` e UI padronizada em `frontend/src/components/ui`. +- **Contexts**: `frontend/src/contexts` (AuthContext, ConfigContext, ThemeContext, notification-context). +- **Lib**: `frontend/src/lib` para `api.ts`, `types.ts`, `i18n.tsx` e helpers. + +### Tipos e contratos +- O frontend consome os contratos definidos em `frontend/src/lib/types.ts`. +- **Regra de ouro**: comparar `frontend/src/lib/types.ts` com `backend/internal/models` sempre que um campo mudar. + +### i18n +- Strings de UI usadas pelo `useTranslation` ficam em `frontend/src/i18n/*.json` e são carregadas por `frontend/src/lib/i18n.tsx`. +- Há um catálogo adicional em `frontend/messages/*.json` com traduções gerais do produto (ex.: `pt-BR.json`). + +## Variáveis de ambiente críticas (.env.example) + +### Backend +- **Banco**: `DATABASE_URL`. +- **Auth**: `JWT_SECRET`, `JWT_EXPIRATION`, `PASSWORD_PEPPER`, `COOKIE_SECRET`, `COOKIE_DOMAIN`. +- **Servidor**: `BACKEND_PORT`, `BACKEND_HOST`, `ENV`, `CORS_ORIGINS`. +- **Storage/S3**: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT`, `S3_BUCKET`. +- **Cloudflare**: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ZONE_ID`. +- **Stripe**: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY`. +- **Email**: `RESEND_API_KEY`, `EMAIL_FROM`, `APP_URL`. +- **Mensageria**: `AMQP_URL`. + +### Frontend +- **API**: `NEXT_PUBLIC_API_URL`. +- **Backoffice**: `NEXT_PUBLIC_BACKOFFICE_URL`. +- **Seeder API**: `NEXT_PUBLIC_SEEDER_API_URL`. +- **Scraper API**: `NEXT_PUBLIC_SCRAPER_API_URL`. +- **Analytics**: `NEXT_PUBLIC_VERCEL_ANALYTICS`. + diff --git a/frontend/CONVENTIONS.md b/frontend/CONVENTIONS.md new file mode 100644 index 0000000..625ca10 --- /dev/null +++ b/frontend/CONVENTIONS.md @@ -0,0 +1,41 @@ +# Frontend – Convenções Anti-Erro + +## 1) Chamadas de API (padrão obrigatório) + +**Use `src/lib/api.ts` como única porta de entrada para HTTP.** + +Padrão atual: +- Use `apiRequest(endpoint, options)` para qualquer fetch. +- Token vem do `localStorage` (`auth_token` ou `token`) e é enviado no header `Authorization: Bearer`. +- `Content-Type` é JSON sempre que houver `body`. +- `credentials: "include"` está ativado (cookies compartilhados). +- Erros retornam `Error` com `message` do backend, quando disponível. + +> **Não** chame `fetch` direto em páginas/componentes. +> **Sempre** centralize novas rotas em `src/lib/api.ts` (ex.: `usersApi`, `jobsApi`, etc.). + +Referência: `frontend/src/lib/api.ts`. + +## 2) Traduções (i18n sem quebra de build) + +### UI do frontend (Next.js) +- As strings usadas por `useTranslation` estão em **`frontend/src/i18n`** (`en.json`, `es.json`, `pt-BR.json`). +- **Regra**: qualquer nova chave deve existir em **todos** os arquivos de idioma para evitar fallback inconsistente. + +### Catálogo geral +- Existe um catálogo amplo em `frontend/messages` (ex.: `pt-BR.json`, `en-US.json`, `es-ES.json`, `ja-JP.json`). +- Se você adicionar uma nova chave nesse catálogo, replique nas outras línguas **no mesmo caminho de objeto**. + +Referências: `frontend/src/lib/i18n.tsx`, `frontend/src/i18n/*.json`, `frontend/messages/*.json`. + +## 3) Componentes de formulário (padrão JobFormBuilder) + +Todos os formulários com perguntas dinâmicas devem seguir o padrão de `JobFormBuilder`: +- Tipo `Question` com `id`, `type`, `label`, `required` e `options` (quando aplicável). +- `type` permitido: `text`, `long_text`, `yes_no`, `multiple_choice`, `select`. +- `options` existe apenas para `multiple_choice` e `select`. +- Respeite o limite `maxQuestions` (default 7). +- UI deve usar componentes de `components/ui` e manter o campo fixo de currículo (CV) como referência visual. + +Referência: `frontend/src/components/job-form-builder.tsx`. +