# Sistema Financeiro SOLO — Guia de instalação e atualização Aplicação web em **PHP + Laravel + MariaDB** para o controle financeiro do grupo SOLO (multi-CNPJ): lançamentos (entradas/saídas), projetos por centro de custo, balancete realizado, cadastros (fornecedores, clientes, categorias, equipamentos), empresas, usuários com papéis, anexos e auditoria. ------------------------------------------------------------ ## 1. INSTALAÇÃO INICIAL (feita uma única vez pelo Carlos) ------------------------------------------------------------ Requisitos no servidor: PHP 8.2+ (testado até 8.3/8.5), Composer, MariaDB (ou MySQL 8). **1.1.** Criar o projeto Laravel base e entrar na pasta: ``` composer create-project laravel/laravel financeiro-solo cd financeiro-solo ``` **1.2.** Copiar os arquivos DESTE pacote por cima do projeto, mantendo a estrutura: ``` app/ → app/ (substitui o Controller.php base) database/migrations → database/migrations/ database/seeders/DatabaseSeeder.php → database/seeders/ (substitui) resources/views/ → resources/views/ routes/web.php → routes/web.php (substitui) public/css/, public/img/ → public/ ``` **1.3.** Configurar o ambiente: ``` cp .env.example .env php artisan key:generate ``` No `.env`, apontar o banco (criar o banco vazio antes, ex.: `CREATE DATABASE financeiro_solo;`): ``` DB_CONNECTION=mariadb DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=financeiro_solo DB_USERNAME=... DB_PASSWORD=... APP_ENV=production APP_DEBUG=false APP_TIMEZONE=America/Fortaleza APP_URL=https://SEU-DOMINIO ``` > Observação importante sobre fuso: o sistema usa America/Fortaleza no código onde a data > é crítica. Ainda assim, mantenha APP_TIMEZONE=America/Fortaleza no .env. **1.4.** Criar as tabelas e o usuário inicial (o seed roda SÓ AGORA, na instalação): ``` php artisan migrate --force php artisan db:seed --force ``` **1.5.** Permissões de pasta (a aplicação grava anexos e fotos aqui): ``` chmod -R 775 storage bootstrap/cache ``` Garanta que o usuário do PHP/servidor web consegue escrever em `storage/`. **1.6.** Servir: apontar o document root do Nginx/Apache para a pasta **`public/`**. ------------------------------------------------------------ ## 2. PRIMEIRO ACESSO ------------------------------------------------------------ Usuários criados pelo seed (TROQUE as senhas no primeiro acesso — o sistema já obriga): - **thiago** / senha `mudar123` — Administrador - **igor** / senha `mudar123` — Administrador O sistema nasce vazio (sem projetos/lançamentos). A gestão cria empresas, projetos, usuários e começa a lançar a partir do dia 1. ------------------------------------------------------------ ## 3. COMO FUNCIONA A ATUALIZAÇÃO (leia com atenção) ------------------------------------------------------------ O ponto mais importante: **atualizar NÃO apaga os dados.** - **Código e dados são separados.** O código são os arquivos (telas, regras). Os dados ficam no banco (MariaDB) e os documentos anexados ficam em `storage/app/`. Uma atualização mexe nos ARQUIVOS DE CÓDIGO; o banco e os anexos ficam intactos. - Quando uma atualização precisa mexer no banco, ela vem em forma de **migration**, que só **ACRESCENTA** estrutura (um campo novo, uma tabela nova) — nunca apaga o que existe. O Laravel registra quais migrations já rodaram e executa apenas as **novas**. ------------------------------------------------------------ ## 4. PROCESSO DE ATUALIZAÇÃO NO SERVIDOR (passo a passo do Carlos) ------------------------------------------------------------ Sempre que chegar um pacote de atualização: **4.1.** FAZER BACKUP DO BANCO (obrigatório, é a rede de segurança): ``` mysqldump -u USUARIO -p financeiro_solo > backup_AAAA-MM-DD.sql ``` E, de tempos em tempos, copiar também a pasta `storage/app/` (anexos e fotos). **4.2.** Copiar os arquivos do pacote por cima da aplicação (mesma estrutura da instalação). **4.3.** Se o pacote tiver migration nova, aplicar (só adiciona, não apaga): ``` php artisan migrate --force ``` **4.4.** Limpar os caches para as telas novas aparecerem: ``` php artisan view:clear php artisan config:clear php artisan route:clear ``` Pronto — sistema atualizado, **dados preservados**. ------------------------------------------------------------ ## 5. REGRAS DE OURO (para NUNCA perder dados) ------------------------------------------------------------ 1. **SEMPRE fazer backup do banco antes de atualizar.** 2. Usar **somente `php artisan migrate`** (que acrescenta). **NUNCA** rodar: `migrate:fresh`, `migrate:refresh`, `migrate:reset` ou `db:wipe` — esses comandos APAGAM as tabelas/dados. 3. **NUNCA rodar `php artisan db:seed` de novo** depois da instalação — o seed é só para criar os usuários iniciais. Rodar de novo pode redefinir os admins. 4. **Não apagar a pasta `storage/app/`** — é onde ficam os documentos anexados e as fotos. ------------------------------------------------------------ ## 6. NOTAS TÉCNICAS ------------------------------------------------------------ - **Autenticação** própria por sessão contra a tabela `usuarios` (senha em hash bcrypt). Não usa a tabela `users` padrão do Laravel (pode ignorá-la). - **Sessão em arquivo** por padrão (SESSION_DRIVER=file). Se preferir no banco, use `database` (a tabela `sessions` já vem nas migrations padrão do Laravel). - **Anexos e fotos**: guardados em `storage/app/` (privado) e servidos por rota autenticada. Inclua essa pasta no backup. - **Soft delete** nas tabelas sensíveis (excluídos ficam recuperáveis; por isso a numeração dos lançamentos nunca é reutilizada). - **PDFs (AP)**: gerados pela impressão do navegador (não exige biblioteca extra). ------------------------------------------------------------ ## 7. FLUXO DAS MELHORIAS (como será no dia a dia) ------------------------------------------------------------ 1. O Thiago usa o sistema normalmente, com dados reais. 2. Surge um ajuste/novidade → é desenvolvido → chega um pacote de atualização. 3. O Carlos aplica no servidor seguindo a Seção 4 (backup → copiar arquivos → migrate → limpar cache). Os dados continuam intactos. Dúvidas técnicas sobre a aplicação: este arquivo cobre instalação e atualização.