README.md

Especificação do Ladesa

Definição de dados e entidades do Ladesa

🚀 O que você encontra aqui

Definições de Entidades

Tudo sobre as entidades do Ladesa, suas propriedades e como se relacionam.

Dados de Comunicação

Formatos e estruturas dos dados para comunicação entre sistemas.

Artefatos de Integração

Esquemas JSON, pacotes para C# (NuGet) e JavaScript/TypeScript (NPM), todos gerados automaticamente.

👽 O quê este projeto não é

Você não encontra neste repositório as informações de como consumir e integrar aos nossos serviços em si. Para isso, indicamos que você consulte a documentação Conectar — Ladesa Dev Docs.

Dessa forma, esta especificação foca em definir quais são os dados e informações pertinentes aos nossos sistemas de maneira detalhada.

🧭 Por onde começar?

Para começar a trabalhar com a Especificação do Ladesa, siga estes passos:

• Entender os sistemas do Ladesa: Consulte a documentação essencial para desenvolvedores para entender os conceitos fundamentais de nossos projetos.

• Consumir a especificação: Veja como você pode integrar as modelagens das entidades em seus sistemas, consultando a seção 💖 Utilização.

• Obter o Código-fonte: Clone o repositório e familiarize-se com a estrutura do projeto.

• Configurar o Ambiente de Desenvolvimento: Siga as instruções na seção de 🧑‍💻 Desenvolvimento Local para configurar seu ambiente de trabalho.

• Contribuir: Veja como você pode ajudar a melhorar a especificação, consultando a seção 😊 Como Contribuir.

Conteúdo

• 💖 Utilização
  • Integração C# / DotNet
    • Instalar o pacote para dotnet
    • Utilizar o pacote para dotnet
  • Integração TypeScript / JavaScript
    • Instalar o pacote para TypeScript / JavaScript
    • Utilizar o pacote para TypeScript / JavaScript
• 🧑‍💻 Desenvolvimento Local
  • Pré-requisitos
  • Obter o código-fonte
  • Instalar as dependências
  • Estrutura do projeto
  • Gerar os artefatos da especificação
  • Comandos
• 😊 Como Contribuir
  • 1. Reportar Problemas
  • 2. Sugerir Melhorias
  • 3. Fazer um Pull Request
  • 4. Revisar Pull Requests
• 👋 Contato
• 🤝 Licença

💖 Utilização

A Especificação do Ladesa pode ser utilizada por:

• Desenvolvedores: Para criar e manter aplicações que fazem parte do ecossistema Ladesa, garantindo que os aplicativos sigam as mesmas regras de dados e integração.

• Integradores: Para desenvolver integrações entre sistemas existentes e o Ladesa, assegurando interoperabilidade e conformidade com padrões estabelecidos.

• Analistas de Sistemas: Para entender como os dados são modelados e gerenciados dentro do ecossistema Ladesa.

Integração C# / DotNet

Instalar o pacote para dotnet

dotnet add package Ladesa.Dtos

Utilizar o pacote para dotnet

• Utilização do namespace Ladesa.Dtos

using Ladesa.Dtos;

• Conversão de uma string JSON para uma instância de alguma das classes

Arquivo arquivo = Arquivo.FromJson(jsonString);

Integração TypeScript / JavaScript

Instalar o pacote para TypeScript / JavaScript

# npm
npm install @ladesa-ro/especificacao

# pnpm
pnpm add @ladesa-ro/especificacao

# yarn
yarn add @ladesa-ro/especificacao

Utilizar o pacote para TypeScript / JavaScript

import {} from "@ladesa-ro/especificacao";

🧑‍💻 Desenvolvimento Local

Para você realizar o desenvolvimento local, preparamos o guia a seguir.

Pré-requisitos

Para o desenvolvimento local, é necessário preparar o seu ambiente de trabalho para mexer com este projeto.

Preparamos dicas e tutoriais para você acerca de cada pré-requisito, basta clicar nos links para saber mais.

• Acesso à Linha de Comando;
• Git;
• Node.js + Corepack;
• dotnet.

Obter o código-fonte

O primeiro passo para o desenvolvimento local é de obter uma cópia dos arquivos deste repositório. Para isso, digite:

git clone https://github.com/ladesa-ro/especificacao.git
cd especificacao

Instalar as dependências

pnpm install

Estrutura do projeto

O projeto está organizado da seguinte forma:

Visualização em Árvore da estrutura do repositório.

.
├── .changeset/                   # Arquivos de configuração e log de mudanças
│   ├── README.md                 # Instruções sobre changesets
│   ├── *.md                      # Log de mudanças específico
│   └── config.json               # Configuração de changesets
├── .editorconfig                 # Definições de estilo de código
├── .github/                      # Configurações e ações do GitHub
│   ├── actions/                  # Ações personalizadas do GitHub
│   │   ├── prepare-build/        # Preparação para build
│   │   └── prepare-install/      # Preparação para instalação
│   ├── workflows/                # Workflows do GitHub Actions
│   │   ├── continuos-release-publish.yml
│   │   ├── publish-dotnet.yml
│   │   ├── publish-npm.yml
│   │   ├── quality.yml
│   │   └── release.yml
│   └── dependabot.yml            # Configuração do Dependabot para atualizações automáticas
├── .gitignore                    # Arquivos e diretórios ignorados pelo Git
├── .husky/                       # Configuração de hooks do Git (ex: pre-commit)
│   └── pre-commit
├── .vscode/                      # Configurações do Visual Studio Code
│   ├── extensions.json           # Extensões recomendadas
│   └── settings.json             # Configurações de ambiente de desenvolvimento
├── CODEOWNERS                    # Arquivo de proprietários de código
├── LICENSE                       # Arquivo de licença (MIT)
├── README.md                     # Arquivo de documentação principal
├── biome.json                    # Configuração do Biome para o projeto
├── definitions/                  # Diretório principal contendo definições
│   ├── biome.json                # Configuração do Biome para definitions
│   ├── package.json              # Configuração npm do módulo definitions
│   ├── src/                      # Código-fonte das definições
│   │   ├── .utils/               # Utilitários compartilhados
│   │   │   ├── -index.tsp
│   │   │   ├── common.tsp
│   │   │   ├── entity-token.tsp
│   │   │   └── extensions/       # Extensões para decorators
│   │   │       ├── -index.tsp
│   │   │       ├── decorators/
│   │   │       │   ├── -index.tsp
│   │   │       │   ├── entity.js
│   │   │       │   ├── entity.tsp
│   │   │       │   ├── entityPartialOf.js
│   │   │       │   └── entityPartialOf.tsp
│   │   │       └── tokens.js
│   │   ├── autenticacao/          # Definições de autenticação
│   │   │   ├── -index.tsp
│   │   │   └── usuario.tsp
│   │   ├── base/                 # Definições de entidades básicas
│   │   │   ├── -index.tsp
│   │   │   ├── arquivo.tsp
│   │   │   ├── imagem-arquivo.tsp
│   │   │   └── imagem.tsp
│   │   └── main.tsp              # Definições principais do projeto
│   └── tspconfig.json-schema.yaml # Configuração do TypeScript para JSON Schema
├── integrations/                 # Diretório de artefatos de integração
│   ├── dotnet/                   # Definições para integração com .NET (C#)
│   │   ├── Ladesa.Dtos.Test/     # Testes unitários para .NET
│   │   │   ├── GlobalUsings.cs
│   │   │   ├── Ladesa.Dtos.Test.csproj
│   │   │   └── UnitTest1.cs
│   │   ├── Ladesa.Dtos/          # Definições principais para .NET
│   │   │   ├── .gitignore
│   │   │   ├── Ladesa.Dtos.cs
│   │   │   └── Ladesa.Dtos.csproj
│   │   ├── Ladesa.Spec.sln       # Solução do .NET para o projeto
│   │   └── package.json          # Configurações do npm para integração dotnet
│   ├── json-schema/              # Esquemas JSON para integração
│   │   ├── lib/                  # Biblioteca de schemas JSON
│   │   │   ├── Arquivo.json
│   │   │   ├── ArquivoFindOneInputView.json
│   │   │   ├── ArquivoFindOneResultView.json
│   │   │   ├── ArquivoView.json
│   │   │   ├── DatedObject.json
│   │   │   ├── EntityToken.json
│   │   │   ├── Imagem.json
│   │   │   ├── ImagemArquivo.json
│   │   │   ├── ObjectUuid.json
│   │   │   ├── Usuario.json
│   │   │   ├── date_time.json
│   │   │   └── uuid.json
│   │   └── package.json          # Configurações npm para JSON Schema
│   └── npm/                      # Artefatos npm para integração JavaScript/TypeScript
│       ├── especificacao/        # Pacote npm da especificação
│       │   ├── biome.json        # Configuração do Biome para o pacote
│       │   ├── package.json      # Configurações npm para o pacote especificacao
│       │   └── src/              # Código-fonte do pacote especificacao
│       │       └── schemas.ts
├── package.json                  # Configurações gerais do projeto
├── pnpm-lock.yaml                # Lockfile do pnpm
└── pnpm-workspace.yaml           # Configurações do workspace para pnpm

Gerar os artefatos da especificação

pnpm run build

Comandos

Todos os comandos são executados a partir da raiz do projeto, em um terminal:

Comando	Ação
pnpm install	Instala as dependências.
pnpm run -w build	Gera os artefatos da especificação.
pnpm run -w code-static:fix	Correção de lint e formatação.

Outros comandos

Comando	Ação
pnpm run -w lint:check	Checa as regras do lint.
pnpm run -w lint:fix	Corrige erros resolviveis de lint.
pnpm run -w format:check	Checa as formatações dos arquivos.
pnpm run -w format:fix	Corrige as formatações inconsistêntes dos arquivos.
pnpm run -w code-static:check	Checagem de lint e formatação.

😊 Como Contribuir

Este projeto é open source, e contribuições são sempre bem-vindas! Existem diversas formas de você colaborar com a Especificação do Ladesa:

1. Reportar Problemas

Se você encontrou algum problema ou erro na especificação, por favor, abra uma issue no GitHub. Detalhe o máximo possível para que possamos investigar e resolver rapidamente.

2. Sugerir Melhorias

Tem uma ideia para melhorar a especificação? Sinta-se à vontade para sugerir novas funcionalidades, ajustes ou correções abrindo uma issue ou discutindo na Ladesa Community.

3. Fazer um Pull Request

Se você já tem uma solução para um problema ou deseja propor uma melhoria no código, siga os passos abaixo para enviar um pull request:

1. Faça um fork deste repositório.
2. Clone o repositório em sua máquina local.
3. Crie uma branch com o nome da sua funcionalidade ou correção.
4. Faça as alterações necessárias.
5. Envie um pull request detalhando o que foi alterado e por que.

4. Revisar Pull Requests

Se você tiver experiência com o projeto, pode ajudar revisando e sugerindo melhorias nos pull requests abertos por outros colaboradores. A revisão cuidadosa ajuda a garantir que o código mantido esteja sempre em alta qualidade.

Lembre-se de seguir o código de conduta da comunidade em todas as interações.

👋 Contato

Se você tiver dúvidas, sugestões ou precisar de ajuda, entre em contato conosco:

• Email: em breve.
• Comunidade: Participe de discussões e interações na comunidade do Ladesa através do Ladesa Community.
• GitHub Issues: Para relatar bugs ou sugerir melhorias, utilize a seção de Issues do GitHub.

🤝 Licença

MIT © 2024 – presente, Ladesa.

---

⭐ Marque este repositório com estrela se achar útil!