Règles Parquet et Entités Parquet

Copy of sumaris-pod/.agents/rules/parquet-entities.md (rule written for AI coding agents, when creating or modifying Parquet repositories, Parquet Value Objects (VO), or using Parquet annotations). Do not edit here: run npm run site:sync-rules to update it.

Ce document détaille les règles et conventions pour l'utilisation du repository Parquet et le mapping des entités (VO) via les annotations Parquet.

Architecture Parquet

Le projet utilise un système de lecture/écriture Parquet « maison » basé sur la réflexion et des annotations dédiées.

• Repository : Les repositories Parquet doivent étendre ParquetRepositoryImpl<V, ID, F> ou implémenter IParquetRepository.
• Value Objects (VO) : Les objets de données sont des POJO (souvent annotés Lombok) qui servent de documents pour les fichiers Parquet.

Mapping des colonnes (Annotations)

1. @ParquetColumn

L'annotation principale pour mapper un champ de classe à une colonne Parquet.

• value / name : Le nom exact de la colonne dans le fichier Parquet.
• required : (Défaut: false) Indique si la donnée est obligatoire.
• requiredColumn : (Défaut: true) Si true, le système lèvera une erreur si la colonne est absente du fichier Parquet lors de la désérialisation. Si false, le champ sera simplement ignoré (mis à null) si la colonne manque.

@ParquetColumn(name = "SpecCode", required = true)
private Integer specCode;

@ParquetColumn(value = "CommonName_French", requiredColumn = false)
private String commonNameFrench;

2. @ParquetId

Marque le champ utilisé comme identifiant unique pour l'entité. Un VO Parquet doit posséder un champ annoté @ParquetId.

@ParquetId
@ParquetColumn("Ordnum")
private Integer ordnum;

3. @ParquetIgnore

Indique au système d'ignorer ce champ lors des opérations de lecture/écriture Parquet. Les champs statiques sont ignorés par défaut.

@ParquetIgnore
private String temporaryData;

Conventions et Bonnes Pratiques

• Complétude du mapping : Toutes les colonnes présentes dans le fichier Parquet source devraient idéalement être mappées dans le VO, même si elles ne sont pas utilisées. Utiliser requiredColumn = false pour les colonnes qui pourraient être absentes dans certaines versions de fichiers (ex: fichiers FishBase vs SealifeBase).
• Types de données :
  • Utiliser les types wrappers (Integer, Double, Boolean, Long) pour supporter les valeurs nulles.
  • Les dates sont souvent stockées sous forme de String (ISO) ou Long (timestamp) selon l'origine des données.
• Lombok : Utiliser @Data, @Builder, @NoArgsConstructor, @AllArgsConstructor et @FieldNameConstants.
• Vérification des colonnes : Dans les tests unitaires de repository Parquet, utilise assertNoExtraColumns(VO.class, file) pour s'assurer que toutes les colonnes du fichier Parquet sont bien mappées dans le VO.

Exemple Type de VO Parquet

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@FieldNameConstants
public class MyParquetVO implements IValueObject<Integer> {

    @ParquetId
    @ParquetColumn("ID")
    private Integer id;

    @ParquetColumn("NAME")
    private String name;

    @ParquetColumn(value = "OPTIONAL_DESC", requiredColumn = false)
    private String description;

    @ParquetIgnore
    private String extraInfo;

    @Override
    public Integer getId() {
        return id;
    }

    @Override
    public void setId(Integer id) {
        this.id = id;
    }
}