Merge pull request #43 from rede5/codex/atualizar-documentacao-tecnica-e-regras-de-integridade
Add documentation anchors for contracts and architecture
This commit is contained in:
Tiago Yamamoto
GitHub
commit
c8ae9da6e2
3 changed files with 133 additions and 0 deletions
23
.cursorrules
Normal file
23
.cursorrules
Normal file
|
|
@ -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 ✅
|
||||||
69
ARCHITECTURE.md
Normal file
69
ARCHITECTURE.md
Normal file
|
|
@ -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`.
|
||||||
|
|
||||||
41
frontend/CONVENTIONS.md
Normal file
41
frontend/CONVENTIONS.md
Normal file
|
|
@ -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<T>(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`.
|
||||||
|
|
||||||
Loading…
Reference in a new issue