Aplicativo Flutter para gestão simples de vendas, gastos e resultados de um ateliê artesanal.

O VCOS centraliza a rotina financeira de um ateliê em uma experiência mobile limpa, acessível e preparada para funcionar offline. A proposta é permitir que a artesã registre vendas, acompanhe gastos, visualize indicadores e mantenha os dados essenciais do negócio mesmo antes da integração definitiva com uma API.

• Início: resumo financeiro do ateliê com saldo, total de vendas, total de gastos e status de sincronização.
• Vendas: cadastro, edição e exclusão lógica de vendas, com cliente, valor, data e sugestões de preenchimento.
• Gastos: cadastro, edição, exclusão lógica e visualização detalhada de despesas, incluindo suporte a fotos.
• Relatórios: visão consolidada de entradas, saídas, saldo e proporção dos gastos sobre as vendas.
• Configurações: dados do ateliê, responsável, telefone, sincronização automática e preferência de alto contraste.
• Offline-first: persistência local com sqflite e fila de sincronização para integração futura.

• Flutter / Dart para aplicação multiplataforma.
• FastAPI / Python para API backend.
• Provider para gerenciamento de estado.
• sqflite para armazenamento local.
• intl para formatação.
• image_picker para anexos de imagens.
• pdf, printing e share_plus para evolução de exportação e compartilhamento.
• flutter_test e integration_test para testes automatizados.

lib/
  app/
    vcos_app.dart
  core/
    data/
    models/
    state/
    sync/
    theme/
    widgets/
  features/
    expenses/
    home/
    reports/
    sales/
    settings/
    shared/
    shell/
test/
integration_test/
web/
android/
backend/
  app/
    api/
    core/
    main.py
  Dockerfile
  requirements.txt
docker-compose.yml

Os ícones abaixo fazem parte do pacote web do aplicativo e representam a identidade visual usada no projeto.

Ícone principal	Ícone PWA	Ícone maskable

Para screenshots de telas, salve as imagens em docs/images/ e referencie-as neste README usando caminhos relativos, por exemplo: docs/images/home.png.

• Flutter 3.44.1 ou versão compatível com o SDK definido em pubspec.yaml.
• Dart 3.x.
• Android SDK configurado para execução em emulador ou dispositivo físico.

O projeto também possui .fvmrc, então é possível usar FVM caso ele esteja instalado no ambiente.

Instale as dependências:

flutter pub get

Execute o app:

flutter run

Execute os testes:

flutter test

Analise o código:

flutter analyze

Execute a API com Docker a partir da raiz:

docker compose up -d --build

Teste o health check:

curl http://localhost:8000/api/v1/health

A documentação interativa fica em:

http://localhost:8000/docs

Para configuração local ou produção, copie o exemplo de variáveis:

copy backend\.env.example backend\.env

Na VPS, o fluxo recomendado é clonar o repositório, ajustar backend/.env e subir com docker compose up -d --build. Depois coloque Caddy ou Nginx na frente para domínio e HTTPS.

Crie uma branch a partir da branch principal antes de iniciar qualquer alteração:

git checkout main
git pull
git checkout -b feature/nome-da-funcionalidade

Mantenha commits pequenos, objetivos e relacionados a uma única mudança. Antes de abrir um pull request, rode:

powershell -NoProfile -ExecutionPolicy Bypass -File .github/scripts/dart_format_check.ps1
flutter analyze
flutter test

O projeto possui um workflow em .github/workflows/ci-cd.yml para garantir qualidade e padronização antes de fazer merge ou publicar uma versão.

• Valida nomes de branches.
• Valida mensagens de commit.
• Executa .github/scripts/dart_format_check.ps1.
• Executa flutter analyze.
• Executa flutter test --coverage.
• Publica o arquivo coverage/lcov.info como artefato.
• Gera APK release automaticamente quando uma tag vX.Y.Z é publicada.

As regras completas estão em CONTRIBUTING.md.

Use os prefixos abaixo para organizar branches e commits. O nome deve ser curto, em minúsculo e separado por hífen.

feature/login
feature/dashboard
feature/usuarios

fix/correcao-api
fix/correcao-validacao

hotfix/crash-android

refactor/camada-dados
refactor/repositorios

docs/readme-inicial

Exemplos de commits aceitos pelo CI:

git commit -m "feature/dashboard: adiciona cards de resumo"
git commit -m "fix(custos): ajusta validacao de valores"
git commit -m "Improve reports accessibility"

As tags devem marcar pontos estáveis do projeto e seguir versionamento semântico:

v0.1.0
v0.2.0
v1.0.0

Padrão recomendado:

• MAJOR: mudanças incompatíveis ou grandes reestruturações.
• MINOR: novas funcionalidades sem quebrar compatibilidade.
• PATCH: correções, ajustes pequenos e melhorias internas.

Criação de tag:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

Listagem de tags:

git tag

Cada release deve ser criada a partir de uma tag publicada. Use a área Releases do GitHub para documentar o que mudou e anexar artefatos quando existirem builds distribuíveis.

Modelo recomendado de release:

## v0.1.0

### Novidades

- Cadastro local de vendas
- Cadastro local de gastos
- Dashboard financeiro inicial

### Correções

- Ajustes de validação nos formulários

### Observações

- Sincronização com API ainda pendente

Boas práticas:

• Crie releases apenas para versões testadas.
• Relacione a release a uma tag vX.Y.Z.
• Inclua notas claras para usuários e desenvolvedores.
• Anexe APKs, relatórios ou outros artefatos quando aplicável.

Antes de fazer merge, valide:

• powershell -NoProfile -ExecutionPolicy Bypass -File .github/scripts/dart_format_check.ps1
• flutter analyze
• flutter test
• Navegação principal do app
• Cadastro e edição de vendas
• Cadastro e edição de gastos
• Persistência local e mensagens de sincronização pendente

Este projeto está licenciado sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.