Padrão Geral do Código Fonte - Histórico de revisão

Rodrigogml: /* Organização do Projeto */

2025-04-22T21:52:03Z

Organização do Projeto

← Edição anterior		Edição das 21h52min de 22 de abril de 2025
Linha 1:		Linha 1:
	= Organização do Projeto =		= Organização do Projeto =
	Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, ~~quando~~ do primeiro jogo sendo desenvolvido para ela, o Mystery Realms.		Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, quanto do primeiro jogo sendo desenvolvido para ela, o Mystery Realms.

	== Estrutura de Projeto ==		== Estrutura de Projeto ==
Linha 14:		Linha 14:
	:* '''.vos''' - Pacote base para alocação dos VOs do jogo.		:* '''.vos''' - Pacote base para alocação dos VOs do jogo.

	== ~~Versão Java~~ ==		== Estrutura Maven ==
	* ~~Java 1~~.8		* Diretórios:
			:* '''src''' - arquivos fonte do jogo e da engine.
			:* '''srcTest''' - arquivos fonte de testes unitários.
			:* '''etc''' - estrutura para documentos, scripts e outros materiais do projeto.

	== Codificação UTF-8 ==		== Configurações de Build ==
	* ~~`maven-compiler-plugin` configurado com~~:		* Codificação de arquivos: '''UTF-8'''
	~~<pre>~~		* Versão Java: '''Java 1.8'''
	~~<encoding>UTF-8</encoding>~~		* Gerenciador de build: '''Maven'''
	~~</pre>~~		* Geração de pacotes JAR com estrutura modular por projetos.

	== ~~Estrutura Maven~~ ==		= Tecnologias Utilizadas =
	* ~~Diretórios:~~
	:* '''~~src~~''' ~~- arquivo~~ de ~~diretório fonte, base do package final~~. ~~Aqui devem ser inclusos arquivos que precisam estar na distribuição final, como imagens, bundles, etc~~..		== Engine (Back-end) ==
	:* '''~~srcTest~~''' ~~- arquivo de diretório~~ com ~~os fontes~~ de ~~testes do sistema, que não serão empacotados com a distribuição final.~~		* '''Java 8+''' – linguagem principal da engine PlayTale
	:* '''~~etc~~''' - estrutura ~~com subdiretórios para armazenamento de arquivos relacionados ao projeto mas que não se encaixam nos antesiores, como documentos, scripts, etc.. Cada um organizado em seu próprio subdiretório~~.		* '''GSON''' – manipulação de JSON
			* '''Servidor HTTP Java (com.sun.net.httpserver)''' – servidor leve embutido para API
			* '''RFW Framework''' – framework proprietário com:
			:* Estrutura de VOs
			:* Validações e Exceptions
			:* Serialização e Persistência
			:* Logger e Pré-processamento
			* '''Serialização por arquivos locais''' – persistência dos objetos do jogo em disco, usando estrutura organizada por diretórios.

			== Interface (Front-end) ==
			* '''Vue.js 3''' – framework reativo para criação da interface
			* '''Quasar Framework''' – framework baseado em Vue que permite:
			:* Criação de UI Web responsiva
			:* Exportação para Android/iOS (via Cordova ou Capacitor)
			:* Componentes customizáveis para visual de jogo (barras de vida, botões personalizados etc.)
			* '''JavaScript ES6+''' – lógica de chamada de APIs
			* '''Fetch API''' – comunicação com servidor via JSON

			== Ferramentas de Desenvolvimento ==
			* '''Visual Studio Code (VS Code)''' – IDE principal de desenvolvimento
			:* Plugins: Volar (Vue 3), Debugger for Chrome, Quasar Extension Pack
			* '''Vue Devtools''' – extensão de navegador para debug em tempo real
			* '''Quasar CLI''' – ferramenta para desenvolvimento, empacotamento e publicação da interface

	= Padrões de Código Desenvolvimento =		= Padrões de Código Desenvolvimento =

Rodrigogml: /* Base dos Pacotes */

2025-04-22T21:50:52Z

Base dos Pacotes

← Edição anterior		Edição das 21h50min de 22 de abril de 2025
Linha 9:		Linha 9:
	== Base dos Pacotes ==		== Base dos Pacotes ==
	* '''br.eng.rodrigogml.playtale''' - Pacote base da Engine		* '''br.eng.rodrigogml.playtale''' - Pacote base da Engine
	~~:* '''.crud''' - Pacote com as classes de lógica do sistema (todo core business, não apenas de Criação, Leitura, Atualização e Deleção).~~
	:* '''.vos''' - Pacote base para alocação dos VOs da Engine.		:* '''.vos''' - Pacote base para alocação dos VOs da Engine.

Rodrigogml: /* Base dos Pacotes */

2025-04-22T15:47:46Z

Base dos Pacotes

← Edição anterior		Edição das 15h47min de 22 de abril de 2025
Linha 9:		Linha 9:
	== Base dos Pacotes ==		== Base dos Pacotes ==
	* '''br.eng.rodrigogml.playtale''' - Pacote base da Engine		* '''br.eng.rodrigogml.playtale''' - Pacote base da Engine
			:* '''.crud''' - Pacote com as classes de lógica do sistema (todo core business, não apenas de Criação, Leitura, Atualização e Deleção).
	:* '''.vos''' - Pacote base para alocação dos VOs da Engine.		:* '''.vos''' - Pacote base para alocação dos VOs da Engine.

Rodrigogml: /* Padrões de Código Desenvolvimento */

2025-04-22T15:46:25Z

Padrões de Código Desenvolvimento

← Edição anterior		Edição das 15h46min de 22 de abril de 2025
Linha 34:		Linha 34:

	== JavaDoc ==		== JavaDoc ==
	~~Todas as~~ classes, métodos ~~e atributos devem ter o javadoc no padrão~~ com explicação mais detalhada possível sobre sua finalidade, funcionamento e limitações.		* Sempre gere javadoc em português nos atributos, classes e métodos utilizando as informações presentes na documentação wiki com explicação mais detalhada possível sobre sua finalidade, funcionamento e limitações. Pode inclusive colocar referências para as páginas wiki com mais informações.
			:* No javadoc a referência para os links deve ser a url completa e não o modelo de link wiki. Exemplo: no wiki a página [[Ficha_do_Jogador]] deve ser escrita com a tag <a href> com o link 'https://mysteryrealms.rodrigogml.eng.br/index.php?title=Ficha_do_Jogador', e target para abertura em nova janela.

	* '''JavaDoc de Classe'''		* '''JavaDoc de Classe'''
Linha 42:		Linha 43:
	== Regras de Escrita de Código ==		== Regras de Escrita de Código ==
	* Sempre escrever código em inglês.		* Sempre escrever código em inglês.
	* Sempre gere javadoc em português nos atributos e métodos que forem criados utilizando as informações presentes na documentação wiki. Pode inclusive colocar referências para as páginas wiki com mais informações.
	:* No javadoc a referência para os links deve ser a url completa e não o modelo de link wiki. Exemplo: no wiki a página [[Ficha_do_Jogador]] deve ser escrita com a tag <a href> com o link https://mysteryrealms.rodrigogml.eng.br/index.php?title=Ficha_do_Jogador, e target para abertura em nova janela.
	* Não gere os métodos getter e setter nos Beans/VOs.		* Não gere os métodos getter e setter nos Beans/VOs.
	* Utilizar sempre BigDecimal para números decimais, nunca utilizar float.		* Utilizar sempre BigDecimal para números decimais, nunca utilizar float.

Rodrigogml: /* Padrões de Código Desenvolvimento */

2025-04-22T15:43:51Z

Padrões de Código Desenvolvimento

← Edição anterior		Edição das 15h43min de 22 de abril de 2025
Linha 32:		Linha 32:

	= Padrões de Código Desenvolvimento =		= Padrões de Código Desenvolvimento =

			== JavaDoc ==
			Todas as classes, métodos e atributos devem ter o javadoc no padrão com explicação mais detalhada possível sobre sua finalidade, funcionamento e limitações.

			* '''JavaDoc de Classe'''
			:* Nos javadoc de classe devem ser inclusas a tag '@author' com o nome Rodrigo Leitão, e a tag '@since' com a data atual no formato 'YYYY-MM-DD' (Ex: 2025-04-22)


	== Regras de Escrita de Código ==		== Regras de Escrita de Código ==

Rodrigogml em 12h53min de 22 de abril de 2025

2025-04-22T12:53:16Z

Rodrigogml: Criou página com '= Organização do Projeto = Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, quando do primeiro jogo sendo desenvolvido para ela, o Mystery Realms. == Estrutura de Projeto == * O sistema é dividido em dois projetos Maven separados: :* '''PlayTale:''' biblioteca independente da engine, reusável em outros jogos. :* '''MysteryRealms:''' jogo que utiliza a engine PlayTale. == Base dos Pacotes == * '''br.eng.rodrig...'

2025-04-22T12:52:44Z

Criou página com '= Organização do Projeto = Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, quando do primeiro jogo sendo desenvolvido para ela, o Mystery Realms. == Estrutura de Projeto == * O sistema é dividido em dois projetos Maven separados: :* '''PlayTale:''' biblioteca independente da engine, reusável em outros jogos. :* '''MysteryRealms:''' jogo que utiliza a engine PlayTale. == Base dos Pacotes == * '''br.eng.rodrig...'

Página nova

= Organização do Projeto =
Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, quando do primeiro jogo sendo desenvolvido para ela, o Mystery Realms.

== Estrutura de Projeto ==
* O sistema é dividido em dois projetos Maven separados:
:* '''PlayTale:''' biblioteca independente da engine, reusável em outros jogos.
:* '''MysteryRealms:''' jogo que utiliza a engine PlayTale.

== Base dos Pacotes ==
* '''br.eng.rodrigogml.playtale''' - Pacote base da Engine
:* '''.vos''' - Pacote base para alocação dos VOs da Engine.

* '''br.eng.rodrigogml.mysteryrealms''' - Pacote base do jogo Mystery Realms
:* '''.vos''' - Pacote base para alocação dos VOs do jogo.

== Versão Java ==
* Java 1.8

== Codificação UTF-8 ==
* `maven-compiler-plugin` configurado com:
<pre>
<encoding>UTF-8</encoding>
</pre>

== Estrutura Maven ==
* Diretórios:
* '''src''' - arquivo de diretório fonte, base do package final. Aqui devem ser inclusos arquivos que precisam estar na distribuição final, como imagens, bundles, etc..
* '''srcTest''' - arquivo de diretório com os fontes de testes do sistema, que não serão empacotados com a distribuição final.
* '''etc''' - estrutura com subdiretórios para armazenamento de arquivos relacionados ao projeto mas que não se encaixam nos antesiores, como documentos, scripts, etc.. Cada um organizado em seu próprio subdiretório.

= Padrões de Código Desenvolvimento =

== Regras de Escrita de Código ==
* Sempre escrever código em inglês.
* Sempre gere javadoc em português nos atributos e métodos que forem criados utilizando as informações presentes na documentação wiki. Pode inclusive colocar referências para as páginas wiki com mais informações.
:* No javadoc a referência para os links deve ser a url completa e não o modelo de link wiki. Exemplo: no wiki a página [[Ficha_do_Jogador]] deve ser escrita com a tag <a href> com o link https://mysteryrealms.rodrigogml.eng.br/index.php?title=Ficha_do_Jogador, e target para abertura em nova janela.
* Não gere os métodos getter e setter nos Beans/VOs.
* Utilizar sempre BigDecimal para números decimais, nunca utilizar float.
* Sempre utilizar LocalDate, LocalDateTime e LocalTime para os atributos de tempo/data.
* Atributos que tem uma quantidade limitada de valores aceitos (enumerações como tipos de armas, raridades, etc.) procure criar estrutura de 'enum' estática e pública dentro da própria classe, quando não reaproveita enum de outra classe.

== Nomeação e Estrutura de Classes ==
* Todos objetos de dados devem usar o sufixo '''VO''' (ex: `PlayerVO`).
* VOs devem estender obrigatoriamente a classe base: '''RFWVO'''.

== Exceções ==
* Toda exceção deve ser uma subclasse de '''RFWException'''.
* '''RFWException''' é abstrata — use subclasses específicas.
* Subclasses válidas:
* '''RFWCriticalException''' – erros críticos ou inesperados.
* '''RFWWarningException''' – falhas de ambiente, não de lógica.
* '''RFWSecurityException''' – violação de segurança ou acesso.
* '''RFWValidationException''' – validações de entrada ou estado.
* '''RFWValidationGroupException''' – múltiplas validações agrupadas.
* A única exceção fora dessa hierarquia permitida é '''RFWRunTimeException''', para usos forçados por APIs externas (ex: interfaces que não permitem `throws`).

== Construtores de Exceções ==
* Usar sempre que possível:
<pre>
new RFWValidationException("CAMPOS_INVALIDOS", new String[]{"nome"}, originalException);
</pre>
* Sempre passar o código de erro seguindo padrão: `[A-Z0-9_]+`.
* Parâmetros para i18n devem ser informados via `String[]`.
* Sempre passar a `Throwable` original quando disponível.

← Edição anterior		Edição das 12h53min de 22 de abril de 2025
Linha 25:		Linha 25:
	== Estrutura Maven ==		== Estrutura Maven ==
	* Diretórios:		* Diretórios:
	* '''src''' - arquivo de diretório fonte, base do package final. Aqui devem ser inclusos arquivos que precisam estar na distribuição final, como imagens, bundles, etc..		:* '''src''' - arquivo de diretório fonte, base do package final. Aqui devem ser inclusos arquivos que precisam estar na distribuição final, como imagens, bundles, etc..
	* '''srcTest''' - arquivo de diretório com os fontes de testes do sistema, que não serão empacotados com a distribuição final.		:* '''srcTest''' - arquivo de diretório com os fontes de testes do sistema, que não serão empacotados com a distribuição final.
	* '''etc''' - estrutura com subdiretórios para armazenamento de arquivos relacionados ao projeto mas que não se encaixam nos antesiores, como documentos, scripts, etc.. Cada um organizado em seu próprio subdiretório.		:* '''etc''' - estrutura com subdiretórios para armazenamento de arquivos relacionados ao projeto mas que não se encaixam nos antesiores, como documentos, scripts, etc.. Cada um organizado em seu próprio subdiretório.


Linha 52:		Linha 52:
	* '''RFWException''' é abstrata — use subclasses específicas.		* '''RFWException''' é abstrata — use subclasses específicas.
	* Subclasses válidas:		* Subclasses válidas:
	* '''RFWCriticalException''' – erros críticos ou inesperados.		:* '''RFWCriticalException''' – erros críticos ou inesperados.
	* '''RFWWarningException''' – falhas de ambiente, não de lógica.		:* '''RFWWarningException''' – falhas de ambiente, não de lógica.
	* '''RFWSecurityException''' – violação de segurança ou acesso.		:* '''RFWSecurityException''' – violação de segurança ou acesso.
	* '''RFWValidationException''' – validações de entrada ou estado.		:* '''RFWValidationException''' – validações de entrada ou estado.
	* '''RFWValidationGroupException''' – múltiplas validações agrupadas.		:* '''RFWValidationGroupException''' – múltiplas validações agrupadas.
	* A única exceção fora dessa hierarquia permitida é '''RFWRunTimeException''', para usos forçados por APIs externas (ex: interfaces que não permitem `throws`).		* A única exceção fora dessa hierarquia permitida é '''RFWRunTimeException''', para usos forçados por APIs externas (ex: interfaces que não permitem `throws`).