docs: atualiza README do dashboard com todas features

- Documenta 10 páginas completas
- Explica design system VSCode-like
- Lista 9 itens de navegação
- Schemas das 4 collections (cloud_accounts, projects, tickets, transactions)
- Scripts de build e deploy
- Troubleshooting e próximos passos
- 306KB bundle size documentado
This commit is contained in:
Tiago Yamamoto 2025-12-11 20:52:10 -03:00
parent e3b994bff2
commit 49be65b28e

View file

@ -1,263 +1,318 @@
# Dashboard - Core Platform # Dashboard - DevOps Orchestration Platform
> Painel administrativo DevOps desenvolvido com **React + TypeScript + Vite** integrado ao **Appwrite Cloud** para autenticação, database e realtime. Dashboard completo para gerenciamento de infraestrutura, projetos, finanças e tasks com design VSCode-like premium.
## 🎯 Visão Geral ## 🎨 Design System
Dashboard para gerenciamento de: Layout **VSCode-like** com:
- **Servidores**: Monitoramento de status, IP e região - **Cores**: slate-900/950 background, cyan-300/400 accents
- **Repositórios GitHub**: Acompanhamento de commits e status - **Cards**: rounded-xl com border-slate-800 e shadow-inner
- **Audit Logs**: Logs de eventos em tempo real - **Typography**: uppercase tracking-wide para labels
- **Contas Cloudflare**: Gerenciamento de integrações - **Avatar**: Gradientes cyan → blue
- **Animações**: Transitions suaves 150ms
## 🛠 Stack Tecnológica ## 📱 Páginas
- **Framework**: [React 18](https://react.dev) ### 🏠 Overview (`/`)
- **Build Tool**: [Vite 5](https://vitejs.dev) - Dashboard principal com métricas
- **Linguagem**: TypeScript 5 - Total de repos, workers ativos, último deploy
- **Roteamento**: React Router DOM 7 - Status de integrações (Appwrite, GitHub, Realtime)
- **Estilização**: Tailwind CSS 3
- **Backend**: Appwrite Cloud SDK
- **Ícones**: Lucide React
- **Linting**: ESLint 8
## 📦 Instalação ### 👤 Perfil (`/profile`)
- Avatar com iniciais do usuário
- Informações da conta (email, ID, data de criação)
- Estatísticas (projetos, tickets, uptime)
- Placeholder para edição e segurança
```bash ### 📊 Projetos (`/projects`)
# Na raiz do projeto - Grid de cards de projetos
cd dashboard - Filtros: Todos, Active, Paused, Archived
- Busca por nome
- Status badges coloridos
- Link para repositório GitHub
# Instalar dependências ### 📋 Kanban (`/kanban`)
npm install - 3 colunas: Backlog 📋 | Em Progresso 🏃 | Concluído ✅
- Cards de tickets com título, descrição
- Labels de prioridade: Low/Medium/High
- Assignee e drag & drop (futuro)
### 🔑 Admin de Contas (`/accounts`)
- Gerenciar credenciais multi-plataforma:
- Cloudflare (laranja)
- GitHub (branco)
- cPanel (azul)
- DirectAdmin (roxo)
- Appwrite (rosa)
- Mascaramento de API Keys com toggle show/hide
- Testes de conexão
- Stats por provider
### 💰 Financeiro (`/finance`)
- Módulo ERP básico
- Cards de resumo: Receitas | Despesas | Saldo
- Lista de transações com categorias
- Gráfico de tendência mensal
- Breakdown por categoria
### ⚡ Hello World (`/hello`)
- Teste de Appwrite Function básica
- Input customizado
- Logs de execução
### 🐙 GitHub Repos (`/github`)
- Sincronizar repositórios do GitHub
- Usar credencial do cloud_accounts
- Listar repos do usuário
### ☁️ Cloudflare Zones (`/cloudflare`)
- Status de Zones e Workers
- Integração com Cloudflare API
- Usar credencial do cloud_accounts
### ⚙️ Settings (`/settings`)
- Configurações gerais
- Preferências (futuro)
## 🧩 Componentes
### `UserDropdown`
- Dropdown de perfil no header (canto direito)
- Avatar com iniciais e gradiente
- Menu: Meu Perfil, Configurações, Sair
- Click outside para fechar
### `TerminalLogs`
- Terminal em tempo real no rodapé
- Monitora collection `audit_logs` via Realtime
- Logs com timestamp
## 🗂️ Estrutura
```
dashboard/src/
├── components/
│ ├── TerminalLogs.tsx # Terminal realtime
│ └── UserDropdown.tsx # Dropdown de perfil
├── contexts/
│ └── Auth.tsx # Contexto auth Appwrite
├── layouts/
│ └── DashboardLayout.tsx # Layout principal com sidebar
├── lib/
│ └── appwrite.ts # Config Appwrite SDK
├── pages/
│ ├── AccountsAdmin.tsx # Admin multi-plataforma
│ ├── Cloudflare.tsx # Zones Cloudflare
│ ├── ERPFinance.tsx # Módulo financeiro
│ ├── Github.tsx # Repos GitHub
│ ├── Hello.tsx # Hello World function
│ ├── Home.tsx # Overview dashboard
│ ├── Kanban.tsx # Board de tickets
│ ├── Login.tsx # Página de login
│ ├── Profile.tsx # Perfil do usuário
│ ├── Projects.tsx # Grid de projetos
│ └── Settings.tsx # Configurações
├── App.tsx # Routes
└── main.tsx # Entry point
``` ```
## ⚙️ Configuração ## 🔧 Stack Tecnológica
### Variáveis de Ambiente - **Framework**: React 18 + TypeScript
- **Build**: Vite 5
- **Routing**: React Router DOM v7
- **Backend**: Appwrite Cloud (BaaS)
- **Styling**: Tailwind CSS 3
- **Icons**: Lucide React
- **Linting**: ESLint + TypeScript ESLint
O dashboard lê variáveis do arquivo `.env` na **raíz do monorepo** (não nesta pasta). ## 🚀 Scripts
Variáveis necessárias (todas com prefixo `VITE_`): ```bash
# Desenvolvimento
npm run dev # Vite dev server em http://localhost:5173
# Build
npm run build # TypeScript + Vite build
# Lint
npm run lint # ESLint com regras TypeScript
# Preview
npm run preview # Preview do build de produção
```
## 🔑 Variáveis de Ambiente
Crie `.env` com:
```env ```env
# Appwrite Endpoint (cliente)
VITE_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 VITE_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
# Project ID (cliente)
VITE_APPWRITE_PROJECT_ID=seu_project_id VITE_APPWRITE_PROJECT_ID=seu_project_id
# Database ID (cliente)
VITE_APPWRITE_DATABASE_ID=seu_database_id VITE_APPWRITE_DATABASE_ID=seu_database_id
# Collections IDs (cliente)
VITE_APPWRITE_COLLECTION_SERVERS_ID=servers VITE_APPWRITE_COLLECTION_SERVERS_ID=servers
VITE_APPWRITE_COLLECTION_GITHUB_REPOS_ID=github_repos VITE_APPWRITE_COLLECTION_GITHUB_REPOS_ID=github_repos
VITE_APPWRITE_COLLECTION_AUDIT_LOGS_ID=audit_logs VITE_APPWRITE_COLLECTION_AUDIT_LOGS_ID=audit_logs
VITE_APPWRITE_COLLECTION_CLOUDFLARE_ACCOUNTS_ID=cloud_accounts VITE_APPWRITE_COLLECTION_CLOUDFLARE_ACCOUNTS_ID=cloud_accounts
``` ```
**⚠️ Importante**: O Vite só expõe variáveis com prefixo `VITE_` para o browser. **Todas as variáveis `VITE_*` são expostas no cliente**, portanto não coloque segredos!
### Configuração do Appwrite ## 📊 Appwrite Collections
Veja o [README principal](../README.md#setup-appwrite-cloud) para instruções completas de setup do Appwrite Cloud.
## 🏃 Scripts
| Comando | Descrição |
|---------|-----------|
| `npm run dev` | Inicia dev server (porta 5173) |
| `npm run build` | Gera build de produção em `dist/` |
| `npm run preview` | Testa build localmente |
| `npm run lint` | Executa ESLint |
### Executar em Desenvolvimento
```bash
npm run dev
```
Acesse: http://localhost:5173
**Login**: Use credenciais criadas no Appwrite Auth (ex: `admin@test.com`)
## 📁 Estrutura de Pastas
```
dashboard/
├── public/ # Arquivos estáticos
│ └── vite.svg
├── src/
│ ├── components/ # Componentes reutilizáveis
│ │ ├── Header.tsx
│ │ ├── Overview.tsx
│ │ ├── ServerList.tsx
│ │ ├── GitHubRepos.tsx
│ │ ├── Terminal.tsx
│ │ └── ...
│ ├── pages/ # Páginas/rotas
│ │ ├── Login.tsx
│ │ ├── Dashboard.tsx
│ │ └── ...
│ ├── lib/ # Utilitários e SDK
│ │ └── appwrite.ts # Inicialização SDK Appwrite
│ ├── App.tsx # Componente raiz + rotas
│ ├── main.tsx # Entry point
│ └── index.css # Tailwind + estilos globais
├── index.html # Template HTML
├── vite.config.ts # Configuração Vite
├── tailwind.config.js # Configuração Tailwind
├── tsconfig.json # Configuração TypeScript
└── package.json # Dependências e scripts
```
## 🔑 Funcionalidades
### Autenticação
- Login com Email/Password via Appwrite Auth
- Session management com `account.createEmailPasswordSession`
- Logout com `account.deleteSession('current')`
- Proteção de rotas com verificação de sessão
### Database Queries
Consulta coleções Appwrite usando o SDK:
### `cloud_accounts`
Credenciais de APIs multi-plataforma:
```typescript ```typescript
import { databases } from './lib/appwrite'; {
name: string // Ex: "Cloudflare Produção"
// Listar servidores provider: enum // cloudflare | github | cpanel | directadmin | appwrite
const servers = await databases.listDocuments( apiKey: string // API Key ou token
import.meta.env.VITE_APPWRITE_DATABASE_ID, endpoint?: string // URL do endpoint (opcional)
import.meta.env.VITE_APPWRITE_COLLECTION_SERVERS_ID active: boolean // Se está ativo
);
```
### Realtime Subscriptions
Terminal assina eventos da coleção `audit_logs`:
```typescript
import { client } from './lib/appwrite';
client.subscribe(
`databases.${databaseId}.collections.${auditLogsId}.documents`,
(response) => {
console.log('Novo log:', response.payload);
} }
);
``` ```
## 🎨 Componentes Principais ### `projects` (futuro)
```typescript
| Componente | Descrição | {
|------------|-----------| name: string
| `Header` | Barra superior com navegação e logout | description: string
| `Overview` | Widgets com métricas de servidores, repos e logs | status: enum // active | paused | archived
| `ServerList` | Tabela de servidores com status online/offline | repository_url?: url
| `GitHubRepos` | Lista de repositórios GitHub integrados | created_at: datetime
| `Terminal` | Console com logs em tempo real (Realtime) | owner_id: string
}
## 🧪 Testes
### Linting
```bash
npm run lint
``` ```
Configuração ESLint em `.eslintrc.cjs`: ### `tickets` (futuro)
- Parser: `@typescript-eslint/parser` ```typescript
- Plugins: React Hooks, React Refresh {
- Regras: React 18.2+ (sem import React necessário) title: string
description: string
### Build de Produção status: enum // backlog | in_progress | done
priority: enum // low | medium | high
```bash assignee?: string
npm run build project_id?: string
created_at: datetime
}
``` ```
Saída: ### `transactions` (futuro - ERP)
- `dist/index.html` ```typescript
- `dist/assets/index-[hash].js` {
- `dist/assets/index-[hash].css` description: string
amount: number
type: enum // income | expense
category: string
date: datetime
}
```
Otimizações: ## 🎯 Navegação
- Tree-shaking
- Minificação 9 itens na sidebar:
- Code splitting
- Hashing de assets 1. **Overview** 🏠 - Dashboard principal
2. **Projetos** 📂 - Gestão de projetos
3. **Kanban** 📋 - Board de tickets
4. **Contas** 🔑 - Admin multi-plataforma
5. **Financeiro** 💰 - ERP módulo
6. **Hello World** ✨ - Test function
7. **GitHub Repos** 🐙 - Integração GitHub
8. **Cloudflare Zones** ☁️ - Integração Cloudflare
9. **Settings** ⚙️ - Configurações
## 🔒 Autenticação
- Login via email/senha com Appwrite Auth
- Redirect automático para dashboard após login
- Protected routes com `PrivateRoute` HOC
- Logout via UserDropdown no header
## 📦 Build Stats
```
Bundle size: 306KB gzipped
Modules: 1727 transformed
Build time: ~8s
```
## 🚀 Deploy ## 🚀 Deploy
### Vercel (Recomendado) ### Vercel
```bash ```bash
npm run build npm run build
# Ou conecte o repo no painel Vercel # Upload pasta dist/
``` ```
**Configuração Vercel**:
- Build Command: `npm run build`
- Output Directory: `dist`
- Environment Variables: Adicione todas as `VITE_*`
### Netlify ### Netlify
```bash
npm run build
# Arraste a pasta dist/ no painel Netlify
```
**netlify.toml** (opcional):
```toml ```toml
[build] [build]
command = "npm run build" command = "npm run build"
publish = "dist" publish = "dist"
``` ```
### Cloudflare Pages ### Docker
```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 5173
CMD ["npm", "run", "preview"]
```
## 🎨 Customização
### Cores
Editar `tailwind.config.js` e trocar `slate`/`cyan` por outras cores mantendo o padrão.
### Ícones
Substituir ícones do Lucide por outros mantendo o `size={16}` ou `size={20}` para consistência.
### Layout
Ajustar sidebar width em `DashboardLayout.tsx` linha 30: `w-64``w-72` para maior.
## 📝 Próximos Passos
- [ ] Implementar CRUD completo de Projetos
- [ ] Drag & drop no Kanban
- [ ] Formulário de criação de Contas
- [ ] Charts reais no Financeiro (recharts/visx)
- [ ] Edição de perfil
- [ ] Notificações toast (sonner)
- [ ] Dark/Light mode toggle
- [ ] Testes com Vitest + Testing Library
## 🐛 Troubleshooting
### Erro ao buildar
```bash ```bash
rm -rf node_modules dist
npm install
npm run build npm run build
# Upload via Wrangler ou painel
``` ```
**⚠️ Importante**: Configure as variáveis de ambiente `VITE_*` no painel do provider! ### Variáveis não carregam
Verifique se tem prefixo `VITE_` e reinicie dev server.
## 🔧 Troubleshooting ### Realtime não funciona
Certifique-se que `audit_logs` collection existe e tem Read permission para usuário autenticado.
### "import.meta.env.VITE_APPWRITE_PROJECT_ID is undefined"
**Causa**: Arquivo `.env` não está na raiz do monorepo ou variável não tem prefixo `VITE_`
**Solução**:
```bash
# Verifique se o .env existe na raiz (não em dashboard/)
cat ../.env
# Certifique-se que as variáveis começam com VITE_
grep VITE_ ../.env
```
### Erro de CORS no Appwrite
**Solução**:
1. Appwrite Console → Settings → Platforms
2. Add Platform → **Web**
3. Hostname: `localhost` (dev) e seu domínio (produção)
### TypeScript errors no build
```bash
# Verificar erros
npx tsc --noEmit
# Atualizar tipos se necessário
npm install --save-dev @types/react@latest @types/react-dom@latest
```
## 📚 Recursos
- [Appwrite React SDK](https://appwrite.io/docs/sdks#client)
- [Vite Guide](https://vitejs.dev/guide/)
- [React Documentation](https://react.dev)
- [Tailwind CSS](https://tailwindcss.com/docs)
--- ---
Para configuração completa e setup do Appwrite, veja o [README principal](../README.md). **Dashboard criado com 💎 mantendo padrão VSCode-like top!**