Este documento establece las pautas para la escritura de código en el proyecto, abarcando nomenclatura, formato, comentarios, registros, base de datos y control de versiones. Se actualizará periódicamente según la evolución del proyecto.

1. Convenciones de Nomenclatura

1.1 Clases

• Usar UpperCamelCase (primera letra mayúscula).
• No emplear guiones bajos ni dígitos (excepto clases de interfaz APP relacionadas con versiones).
• Prohibido usar pinyin o abreviaturas personalizadas (se permiten pinyin comunes como "weixin" o "taobao").
• Preferir palabras completas; evitar abreviaturas ambiguas.
• Sufijos obligatorios: Dao para capa de persistencia, Service para capa de negocio, Controller para capa de control.
• Corregir errores ortográficos y enviar los cambios al repositorio.

Nota: En este proyecto, la capa Service no tiene interfaces.

1.2 Métodos y Variables

• Usar lowerCamelCase (primera letra minúscula).
• Sin guiones bajos, pinyin ni abreviaturas arbitrarias.
• Preferir nombres descriptivos aunque sean largos.
• Los métodos de persistencia deben iniciar con: save, delete, update, get, select.
• Corregir errores ortográficos a tiempo.

Ejemplos:

// Correcto
registerByMobileNumber

// Incorrecto
RegisterByMobileNumber  // primera letra mayúscula
registerbymobilenumber  // sin camelCase
registerByMobNum        // abreviatura ambigua
shouJiHaoZhuCe          // pinyin
registerByFool          // nombre sin significado

• Los métodos sobrecargados deben realizar la misma funcionalidad con diferentes parámetros. No usarlos para propósitos distintos.
• Las constantes deben escribirse en MAYÚSCULAS con guiones bajos entre palabras.

// Correcto
FUIOU_REALNAME_ERROR

// Incorrecto
fuiouRealnameError   // no todo mayúsculas
FUIOUREALNAMEERROR   // sin guión bajo

1.3 Literales

• Los literales float deben terminar con F mayúscula.
• Los literales long deben terminar con L mayúscula.
• No usar sufijos en minúscula.
• Los literales double e int no llevan sufijo.

// Correcto
8.0F, 40L

// Incorrecto
8.0f, 40l  // sufijos minúscula
8.0D, 8.0d, 40I, 40i  // sufijos innecesarios

1.4 Paquetes

• Todo en minúsculas.
• Evitar pinyin, abreviaturas o combinaciones.
• Usar una sola palabra si es posible. Si se necesitan varias, no usar guiones bajos.
• Corregir errores ortográficos.

// Correcto
allinpay

// Incorrecto
xinxipiluo          // pinyin y error ortográfico
msgcl               // abreviatura/ pinyin

2. Formato del Código

2.1 Herencia y Anotaciones

• Las entidades deben usar Lombok: @Data y @EqualsAndHashCode(callSuper = true).
• Herencia: Controller → BaseController, Service → BaseService, Dao → BaseDao.
• Usar @Controller, @Service para marcar las capas.
• En las entidades de base de datos, usar tipos envolventes (Integer, Long, etc.) en lugar de primitivos para manejar valores nulos.

2.2 Métodos

• Un método no debe superar las 80 líneas (máximo 150). Si es necesario, refactorizar o extraer sub-métodos.
• Separar bloques lógicos con una línea en blanco.
• Anotar con @Override cualquier método que sobrescriba.
• En equals(), colocar el literal a la izquierda para evitar NullPointerException.

// Correcto
"1".equals(something)

// Incorrecto
something.equals("1")

• Para comprobar cadenas vacías, usar org.springframework.util.StringUtils.isEmpty().
• Para colecciones vacías, usar org.springframework.util.CollectionUtils.isEmpty().
• Eliminar código comentado; el control de versiones guarda el historial.
• Si un bloque de más de 10 líneas se repite, extraerlo a un método común.
• Modificar métodos existentes en lugar de crear versiones como metodo1, metodo2.

3. Comentarios

3.1 Javadoc

• Las clases nuevas deben incluir Javadoc con fecha de creación, autor y propósito.
• Documentar los atributos de la clase.
• Los métodos (interfaz y clase) deben tener Javadoc que describa función, valor de retorno y parámetros complejos. En interfaces, la documentación debe ser detallada.

3.2 Comentarios de Bloque

• Usar comentarios de bloque (/* ... */) para separar secciones lógicas complejas y explicar su propósito.

3.3 Comentarios en Línea

• Agregar comentarios (//) a sentencias que no sean autoexplicativas o simples declaraciones/ asignaciones.
• La mayoría de las líneas de lógica deben tener un comentario breve.

4. Registros (Logs)

• Prohibido usar System.out.println() excepto para depuración temporal; eliminarlo antes de commit.
• En producción, el nivel de log es info. Usar niveles info, warn, error. No usar debug.
• Nunca usar e.printStackTrace(); emplear logger.error().
• En el controlador, registrar al inicio del método la operación y los parámetros recibidos.
• En bloques complejos, registrar el progreso intermedio.
• Para operaciones sensibles, registrar el flujo completo y guardar registro en base de datos.
• En integraciones con terceros, registrar entrada/salida, éxito/fracaso, código y mensaje de error.
• Otras partes críticas deben tener registros adecuados.

5. Base de Datos

• Nombres de tablas y columnas descriptivos, usando guiones bajos entre palabras.
• Los nombres de las tablas deben ser concisos.
• La correspondencia entre tabla y entidad Java debe ser clara.
• Vistas: prefijo v_. Las tablas no deben comenzar con v_.
• Formato de tabla: módulo_nombre_negocio. Las tablas que no pertenezcan al módulo del sistema no deben usar prefijo sys.
• Columnas: todas minúsculas, separadas por guiones bajos para evitar problemas entre entornos.
• Longitud adecuada, pero descriptiva. Coincidir con el campo de la entidad (camelCase → guión bajo).
• Preferir palabras completas a abreviaturas ambiguas.

// Correcto
Tabla: invest_repay
Columna: current_invest_time

// Incorrecto
Tabla: investrepay
Columna: currentinvesttime  // sin guión bajo
Tabla: calcinvestrepaystepone  // demasiado larga, sin guiones

• Seguir la tercera forma normal: no repetir información que pueda obtenerse de otras tablas.

// Incorrecto
Tabla claim con campos duplicados de otras tablas.
Almacenar nombre, DNI del usuario en lugar de solo su ID.

// Correcto
Relacionar con o_user mediante ID, almacenar solo el ID.

• Agregar comentarios a tablas y columnas nuevas. Para columnas con valores fijos, explicar su significado.
• Las columnas de estado deben usar valores numéricos en lugar de cadenas (menor eficiencia de búsqueda).

// Correcto
status TINYINT 0/1  // 0: normal, 1: eliminado

// Incorrecto
status VARCHAR 'normal'/'eliminado'

6. Conttrol de Versiones

• Al hacer commit, escribir un mensaje detallado explicando los cambios.
• Antes de commit, actualizar el repositorio local para evitar conflictos.
• No subir archivos de configuración del IDE, configuraciones JDBC locales ni de terceros. Solo archivos de configuración nuevos que sean necesarios.

7. Notas Finales

Este estándar se irá refinando con el avance del proyecto. Cada desarrolador debe revisar las actualizaciones periódicamente.