📚 ICTI Share

Plataforma de compartilhamento de materiais acadêmicos com controle de usuários, downloads e permissões.

📋 Índice

Visão Geral
Tech Stack
Funcionalidades
Como Rodar Localmente
Como Rodar Testes
Estrutura de Pastas
Convenções de Código
Critérios de Aceitação
Documentação

🎯 Visão Geral

O ICTI Share é uma plataforma web moderna para compartilhamento de materiais acadêmicos (PDFs, documentos, etc.) desenvolvida com Next.js 16 (App Router), TypeScript e PostgreSQL. A aplicação oferece:

✅ Autenticação completa com NextAuth v5
✅ Sistema de roles (Visitante, Usuário, Admin)
✅ Upload e download de materiais com validação
✅ Workflow de aprovação para materiais (opcional)
✅ Painel administrativo completo
✅ Filtros e busca avançada
✅ Rate limiting e segurança OWASP
✅ Interface moderna com Tailwind CSS e shadcn/ui

🛠️ Tech Stack

Core

Next.js 16 - Framework React com App Router
TypeScript - Tipagem estática
React 18 - Biblioteca UI
Prisma - ORM para PostgreSQL

Autenticação & Segurança

NextAuth v5 - Autenticação
bcryptjs - Hash de senhas
Zod - Validação de schemas

UI/UX

Tailwind CSS - Framework CSS
shadcn/ui - Componentes UI
Framer Motion - Animações
Lucide React - Ícones
date-fns - Manipulação de datas
React Hook Form - Gerenciamento de formulários
@hookform/resolvers - Resolvers para validação (Zod)

Testes

Jest - Testes unitários
Testing Library - Testes de componentes
Playwright - Testes E2E

DevOps

Railway - Deploy e hospedagem
PostgreSQL - Banco de dados

✨ Funcionalidades

🔐 Autenticação

Cadastro de usuários com validação
Login/Logout
Recuperação de senha (preparado)
Sessões JWT seguras
Proteção de rotas por middleware

📄 Materiais

Upload de arquivos (PDF, DOC, etc.)
Validação de tipo e tamanho
Metadados (curso, disciplina, semestre, tipo)
Download com contador
Filtros e busca avançada
Paginação
Workflow de aprovação (PENDING → APPROVED → REJECTED)

👥 Usuários

Perfis personalizáveis
Sistema de roles (VISITANTE, USUARIO, ADMIN)
Histórico de uploads e downloads
Edição de perfil
Alteração de senha com indicador de força

🛡️ Administração

Painel administrativo completo
Aprovação/Rejeição de materiais
Gerenciamento de usuários e roles
Estatísticas (uploads, downloads, top 10)
Listagem de materiais pendentes

🔒 Segurança

Rate limiting (upload, download, auth)
Validação de arquivos (tipo, tamanho, MIME, magic bytes)
Sanitização de inputs
Headers de segurança (CSP, HSTS, etc.)
Proteção CSRF (NextAuth)
Hash de senhas com bcrypt
Validação de força de senha

🔍 SEO

Sitemap dinâmico (/sitemap.xml)
Robots.txt configurável (/robots.txt)
Metadata otimizada (Open Graph, Twitter Cards)
Structured Data (JSON-LD)

🚀 Como Rodar Localmente

Pré-requisitos

Node.js 20.9.0+ e npm 10.0.0+
PostgreSQL 15+ (local ou remoto)
Git

Passo 1: Clonar Repositório

git clone <url-do-repositorio>
cd icti-share

Passo 2: Instalar Dependências

npm install
# ou
pnpm install

Passo 3: Configurar Variáveis de Ambiente

Copie o arquivo de exemplo:
```
cp .env.example .env
```

Configure as variáveis no .env:

# Banco de Dados
DATABASE_URL="postgresql://usuario:senha@localhost:5432/icti_share?schema=public"

# NextAuth
AUTH_SECRET="seu-secret-aqui"  # Gere com: openssl rand -base64 32
AUTH_URL="http://localhost:3000"

# Uploads (opcional)
UPLOAD_DIR="./uploads"
RAILWAY_VOLUME_PATH=""  # Deixe vazio em desenvolvimento

# Ambiente
NODE_ENV="development"

📝 Nota: Para instruções detalhadas, consulte ENV_SETUP.md

Passo 4: Configurar Banco de Dados

# Gerar Prisma Client
npm run prisma:generate

# Executar migrações
npm run prisma:migrate

# (Opcional) Popular com dados de exemplo
npm run prisma:seed

Passo 5: Criar Diretório de Uploads

mkdir -p uploads

Passo 6: Iniciar Servidor de Desenvolvimento

npm run dev

A aplicação estará disponível em http://localhost:3000

Comandos Disponíveis

# Desenvolvimento
npm run dev              # Inicia servidor de desenvolvimento

# Build e Produção
npm run build            # Cria build de produção
npm start                # Inicia servidor de produção

# Banco de Dados
npm run prisma:generate  # Gera Prisma Client
npm run prisma:migrate   # Executa migrações (dev)
npm run prisma:migrate:deploy  # Executa migrações (produção)
npm run prisma:studio    # Abre Prisma Studio
npm run prisma:seed      # Popula banco com dados de exemplo

# Qualidade de Código
npm run lint             # Executa ESLint
npm run format           # Formata código com Prettier

# Testes
npm test                 # Testes unitários
npm run test:watch       # Testes em modo watch
npm run test:coverage    # Testes com cobertura
npm run test:e2e         # Testes E2E
npm run test:e2e:ui      # Testes E2E com UI

Dados de Teste (Seed)

Após executar o seed, você terá:

3 usuários:
- admin@icti.edu.br (senha: senha123) - Role: ADMIN
- joao.silva@icti.edu.br (senha: senha123) - Role: USUARIO
- maria.santos@icti.edu.br (senha: senha123) - Role: USUARIO
10 materiais de exemplo com metadados variados
~500 downloads históricos

Para mais detalhes, consulte SEED.md

🧪 Como Rodar Testes

Testes Unitários (Jest)

# Executar todos os testes
npm test

# Modo watch (re-executa ao salvar)
npm run test:watch

# Com cobertura de código
npm run test:coverage

Testes implementados:

✅ Validação de schemas Zod
✅ Componentes React (MaterialCard, UploadForm)

Testes E2E (Playwright)

# Executar todos os testes E2E
npm run test:e2e

# Com UI interativa
npm run test:e2e:ui

# Com navegador visível
npm run test:e2e:headed

Testes implementados:

✅ Fluxo de autenticação (signup → login → logout)
✅ Fluxo de upload e download
✅ Filtragem de materiais

📝 Nota: Para detalhes completos, consulte TESTING.md

📁 Estrutura de Pastas

icti-share/
├── app/                          # Next.js App Router
│   ├── actions/                  # Server Actions
│   │   ├── admin.ts             # Ações administrativas
│   │   ├── auth.ts              # Autenticação (login, signup, logout)
│   │   ├── materials.ts         # CRUD de materiais
│   │   ├── profile.ts           # Perfil do usuário
│   │   └── upload.ts            # Upload de arquivos
│   ├── admin/                   # Painel administrativo
│   │   └── page.tsx
│   ├── api/                     # API Routes
│   │   └── auth/[...nextauth]/  # NextAuth handler
│   ├── login/                   # Página de login
│   ├── signup/                  # Página de cadastro
│   ├── materiais/               # Listagem de materiais
│   ├── material/               # Detalhes e download
│   │   ├── [id]/               # Página de detalhes
│   │   └── download/[id]/      # Rota de download
│   ├── upload/                  # Página de upload
│   ├── meus-materiais/          # Materiais do usuário
│   ├── perfil/                  # Perfil do usuário
│   ├── layout.tsx               # Layout raiz
│   ├── page.tsx                 # Home page
│   ├── providers.tsx            # Providers (Client Component)
│   ├── robots.ts                # Robots.txt
│   └── sitemap.ts               # Sitemap.xml
│
├── components/                   # Componentes React
│   ├── ui/                      # Componentes shadcn/ui
│   │   ├── avatar.tsx
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── dropdown-menu.tsx
│   │   ├── input.tsx
│   │   ├── password-input.tsx
│   │   └── table.tsx
│   ├── AdminContent.tsx         # Conteúdo do painel admin
│   ├── AdminMaterialActions.tsx  # Ações admin para materiais
│   ├── ChangePasswordForm.tsx   # Formulário de alteração de senha
│   ├── EditProfileForm.tsx      # Formulário de edição de perfil
│   ├── FeaturedMaterialsSection.tsx  # Seção de materiais em destaque
│   ├── FeaturesSection.tsx      # Seção de funcionalidades
│   ├── Filters.tsx              # Filtros de busca
│   ├── Footer.tsx               # Rodapé
│   ├── Header.tsx               # Cabeçalho
│   ├── HeroSection.tsx          # Seção hero da home
│   ├── MaterialActions.tsx      # Ações de materiais (editar/deletar)
│   ├── MaterialCard.tsx          # Card de material
│   ├── MaterialList.tsx          # Lista de materiais
│   ├── Pagination.tsx           # Paginação
│   ├── PasswordStrengthIndicator.tsx  # Indicador de força de senha
│   ├── ProfileContent.tsx       # Conteúdo da página de perfil
│   ├── UploadForm.tsx           # Formulário de upload
│   ├── UserMenu.tsx             # Menu do usuário
│   └── UserRoleEditor.tsx       # Editor de role (admin)
│
├── lib/                          # Bibliotecas e utilitários
│   ├── auth.ts                  # Configuração NextAuth
│   ├── prisma.ts                # Cliente Prisma singleton
│   ├── seo.ts                   # Utilitários de SEO
│   ├── session.ts               # Helper de sessão
│   ├── utils.ts                 # Utilitários gerais
│   ├── security/                # Módulos de segurança
│   │   ├── file-validation.ts   # Validação de arquivos
│   │   ├── headers.ts           # Headers de segurança
│   │   ├── rate-limit.ts        # Rate limiting
│   │   └── sanitize.ts          # Sanitização de inputs
│   └── validations/             # Schemas Zod
│       └── schemas.ts
│
├── prisma/                       # Prisma ORM
│   ├── migrations/              # Migrações do banco
│   ├── schema.prisma            # Schema do banco
│   └── seed.ts                  # Seed do banco
│
├── types/                        # Tipos TypeScript
│   └── next-auth.d.ts           # Tipos NextAuth
│
├── __tests__/                    # Testes unitários
│   ├── components/
│   └── validations/
│
├── e2e/                          # Testes E2E
│   ├── auth-flow.spec.ts
│   ├── filtering.spec.ts
│   ├── upload-download-flow.spec.ts
│   └── helpers/
│
├── scripts/                      # Scripts utilitários
│   ├── backup-db.sh
│   ├── backup-uploads.sh
│   └── restore-db.sh
│
├── middleware.ts                 # Middleware Next.js (proteção de rotas)
├── auth.ts                       # Configuração NextAuth (export)
├── next.config.js                # Configuração Next.js
├── tailwind.config.js            # Configuração Tailwind
├── tsconfig.json                 # Configuração TypeScript
└── package.json                  # Dependências e scripts

📐 Convenções de Código

Server Components vs Client Components

Server Components (Padrão)

Não incluem "use client"
Executam no servidor
Acesso direto ao banco de dados
Sem hooks do React (useState, useEffect, etc.)
Melhor performance

Exemplo:

// app/materiais/page.tsx (Server Component)
import { prisma } from "@/lib/prisma";

export default async function MateriaisPage() {
  const materials = await prisma.material.findMany();
  return <MaterialList materials={materials} />;
}

Client Components

Incluem "use client" no topo
Executam no cliente
Podem usar hooks e interatividade
Necessários para formulários, modais, etc.

Exemplo:

// components/UploadForm.tsx (Client Component)
"use client";

import { useState } from "react";

export function UploadForm() {
  const [isLoading, setIsLoading] = useState(false);
  // ...
}

Server Actions

Sempre começam com "use server"
Localizadas em app/actions/
Protegidas por autenticação quando necessário
Validação com Zod

Exemplo:

// app/actions/upload.ts
"use server";

import { auth } from "@/auth";
import { z } from "zod";

export async function uploadMaterial(formData: FormData) {
  const session = await auth();
  if (!session) {
    return { success: false, error: "Não autenticado" };
  }
  // ...
}

Convenções de Nomenclatura

Componentes: PascalCase (MaterialCard.tsx)
Arquivos de página: page.tsx (Next.js App Router)
Server Actions: camelCase (uploadMaterial)
Tipos/Interfaces: PascalCase (Material, UserRole)
Constantes: UPPER_SNAKE_CASE (MAX_FILE_SIZE)

Estrutura de Arquivos

app/
  [feature]/
    page.tsx          # Página principal
    [id]/
      page.tsx        # Página dinâmica
components/
  [Feature]/
    [Component].tsx   # Componente específico
  ui/
    [component].tsx   # Componente shadcn/ui
lib/
  [module]/
    [file].ts         # Utilitário específico

Validação

Sempre use Zod para validação
Schemas em lib/validations/schemas.ts
Valide no servidor (Server Actions)
Valide no cliente (opcional, para UX)

Segurança

✅ Sempre valide inputs no servidor
✅ Use Server Actions para mutações
✅ Sanitize strings e nomes de arquivos
✅ Valide tipos MIME e tamanhos de arquivo
✅ Implemente rate limiting
✅ Use headers de segurança

✅ Critérios de Aceitação

🏠 Página Inicial (`/`)

Exibe hero section com título e descrição
Mostra botão "Explorar Materiais" sempre visível
Mostra botão "Enviar Material" se autenticado
Mostra botão "Entrar" se não autenticado
Exibe seção de materiais em destaque (top 6)
Cada material mostra: título, autor, downloads, data
Links funcionam corretamente
Layout responsivo (mobile, tablet, desktop)
Animações suaves (Framer Motion)

🔐 Autenticação

Login (`/login`)

Formulário com email e senha
Validação de campos obrigatórios
Mensagens de erro claras
Redireciona após login bem-sucedido
Mantém callbackUrl se fornecido
Link para página de cadastro
Não permite acesso se já autenticado

Cadastro (`/signup`)

Formulário com nome, email, senha, confirmar senha
Validação de email válido
Validação de senha (mínimo 6 caracteres)
Confirmação de senha deve coincidir
Mensagens de erro claras
Login automático após cadastro
Link para página de login
Não permite acesso se já autenticado

Logout

Botão de logout no menu do usuário
Limpa sessão corretamente
Redireciona para home após logout

📄 Materiais

Listagem (`/materiais`)

Exibe todos os materiais aprovados
Filtros funcionais (curso, disciplina, semestre, tipo)
Busca por texto (título e descrição)
Paginação funcional
Ordenação por data (mais recentes primeiro)
Cards responsivos
Links para detalhes funcionam
Exibe informações: título, autor, downloads, data

Detalhes (`/material/[id]`)

Exibe informações completas do material
Mostra: título, descrição, metadados, autor, data
Botão de download funcional
Contador de downloads atualizado
Link para perfil do autor (se disponível)
Botões de ação (editar/deletar) se for o dono
Layout responsivo

Upload (`/upload`)

Meus Materiais (`/meus-materiais`)

Lista apenas materiais do usuário logado
Exibe status do material (PENDING, APPROVED, REJECTED)
Botões de editar e deletar funcionais
Confirmação antes de deletar
Feedback de ações
Ordenação por data (mais recentes primeiro)
Protegido por autenticação

👤 Perfil (`/perfil`)

Exibe informações do usuário
Estatísticas: materiais enviados, downloads realizados
Formulário de edição funcional
Formulário de alteração de senha
Indicador de força de senha
Validação de campos
Atualização em tempo real
Protegido por autenticação

🛡️ Administração (`/admin`)

Acesso

Apenas usuários com role ADMIN podem acessar
Redireciona não-admins para home
Redireciona não-autenticados para login

Estatísticas

Cards com: total de materiais, pendentes, downloads, usuários
Valores corretos e atualizados
Ícones apropriados

Materiais Pendentes

Lista apenas materiais com status PENDING
Exibe: título, autor, data de upload
Botões: Aprovar, Rejeitar, Remover
Ações funcionam corretamente
Feedback de ações
Atualização em tempo real

Top 10 Downloads

Lista top 10 materiais mais baixados
Ordenação por downloadsCount (desc)
Exibe: posição, título, autor, downloads, data
Links funcionam

Gerenciamento de Usuários

Lista todos os usuários
Exibe: nome, email, role, materiais, downloads, data
Editor de role funcional
Não permite remover próprio acesso admin
Feedback de ações
Atualização em tempo real

🔒 Segurança

Rate limiting em upload, download e auth
Validação de arquivos (tipo, tamanho, MIME)
Sanitização de inputs
Headers de segurança aplicados
Proteção CSRF (NextAuth)
Senhas hasheadas (bcrypt)
Sessões JWT seguras
Middleware protege rotas corretamente

🎨 UI/UX

Design consistente (Tailwind + shadcn/ui)
Responsivo (mobile, tablet, desktop)
Acessível (ARIA labels, navegação por teclado)
Animações suaves (Framer Motion)
Feedback visual em ações
Mensagens de erro claras
Loading states apropriados

📱 Responsividade

Mobile (< 768px): layout adaptado
Tablet (768px - 1024px): layout intermediário
Desktop (> 1024px): layout completo
Navegação funcional em todos os tamanhos
Formulários usáveis em mobile

📚 Documentação

Documentos Principais

ENV_SETUP.md - Configuração de variáveis de ambiente
DEPLOY.md - Guia completo de deploy no Railway
AUTH_SETUP.md - Configuração de autenticação
TESTING.md - Guia de testes
SEED.md - População do banco de dados
SECURITY.md - Implementações de segurança

Documentos Técnicos

SECURITY_IMPLEMENTATION.md - Detalhes de segurança
CI_CD.md - Configuração de CI/CD
SETUP_CI.md - Setup de CI
SEO_SETUP.md - Configuração de SEO
CRIAR_TABELAS.md - Criação manual de tabelas
PR_TEMPLATES.md - Templates de Pull Request

Documentos de Troubleshooting

DEBUG_LOGIN.md - Debug de problemas de login
RAILWAY_SETUP.md - Setup no Railway
RAILWAY_DATABASE_URL_FIX.md - Correção de DATABASE_URL
RAILWAY_QUICK_FIX.md - Correções rápidas Railway
VERCEL_AUTH_FIX.md - Correção de autenticação Vercel
VERCEL_LOGIN_FIX.md - Correção de login Vercel
VERCEL_MIGRATIONS.md - Migrações no Vercel

Outros Documentos

SUGESTOES_MELHORIAS.md - Sugestões de melhorias futuras

🤝 Contribuindo

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Padrões de Commit

Use Conventional Commits:

feat: adiciona funcionalidade de busca
fix: corrige bug no upload
docs: atualiza README
style: formata código
refactor: refatora componente
test: adiciona testes
chore: atualiza dependências

📄 Licença

Este projeto está sob a licença especificada no arquivo LICENSE.

👥 Autores

Equipe ICTI - Desenvolvimento inicial

🙏 Agradecimentos

Next.js - Framework React
Prisma - ORM
shadcn/ui - Componentes UI
Tailwind CSS - Framework CSS

Última atualização: 2025-11-26

Name		Name	Last commit message	Last commit date
Latest commit History 142 Commits
.github/workflows		.github/workflows
.husky		.husky
__tests__		__tests__
app		app
components		components
docs		docs
e2e		e2e
lib		lib
prisma		prisma
public		public
scripts		scripts
types		types
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
auth.ts		auth.ts
components.json		components.json
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
middleware.ts		middleware.ts
next.config.js		next.config.js
nixpacks.toml		nixpacks.toml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.js		postcss.config.js
railway.json		railway.json
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

License

LuisT-ls/icti-share

Folders and files

Latest commit

History

Repository files navigation

📚 ICTI Share

📋 Índice

🎯 Visão Geral

🛠️ Tech Stack

Core

Autenticação & Segurança

UI/UX

Testes

DevOps

✨ Funcionalidades

🔐 Autenticação

📄 Materiais

👥 Usuários

🛡️ Administração

🔒 Segurança

🔍 SEO

🚀 Como Rodar Localmente

Pré-requisitos

Passo 1: Clonar Repositório

Passo 2: Instalar Dependências

Passo 3: Configurar Variáveis de Ambiente

Passo 4: Configurar Banco de Dados

Passo 5: Criar Diretório de Uploads

Passo 6: Iniciar Servidor de Desenvolvimento

Comandos Disponíveis

Dados de Teste (Seed)

🧪 Como Rodar Testes

Testes Unitários (Jest)

Testes E2E (Playwright)

📁 Estrutura de Pastas

📐 Convenções de Código

Server Components vs Client Components

Server Components (Padrão)

Client Components

Server Actions

Convenções de Nomenclatura

Estrutura de Arquivos

Validação

Segurança

✅ Critérios de Aceitação

🏠 Página Inicial (/)

🔐 Autenticação

Login (/login)

Cadastro (/signup)

Logout

📄 Materiais

Listagem (/materiais)

Detalhes (/material/[id])

Upload (/upload)

Meus Materiais (/meus-materiais)

👤 Perfil (/perfil)

🛡️ Administração (/admin)

Acesso

Estatísticas

Materiais Pendentes

Top 10 Downloads

Gerenciamento de Usuários

🔒 Segurança

🎨 UI/UX

📱 Responsividade

📚 Documentação

Documentos Principais

Documentos Técnicos

Documentos de Troubleshooting

Outros Documentos

🤝 Contribuindo

Padrões de Commit

📄 Licença

👥 Autores

🙏 Agradecimentos

About

Topics

Resources

License

🏠 Página Inicial (`/`)

Login (`/login`)

Cadastro (`/signup`)

Listagem (`/materiais`)

Detalhes (`/material/[id]`)

Upload (`/upload`)

Meus Materiais (`/meus-materiais`)

👤 Perfil (`/perfil`)

🛡️ Administração (`/admin`)

Packages