feat: add string arrays to letter-sound events (#2313)

Author: jo-elimu

pom-dependency-tree.txt

@@ -1,5 +1,5 @@
-ai.elimu:webapp:war:2.6.108-SNAPSHOT
-+- ai.elimu:model:jar:model-2.0.117:compile
+ai.elimu:webapp:war:2.6.109-SNAPSHOT
++- ai.elimu:model:jar:model-2.0.118:compile
 |  \- com.google.code.gson:gson:jar:2.13.1:compile
 |     \- com.google.errorprone:error_prone_annotations:jar:2.38.0:compile
 +- org.springframework:spring-context:jar:6.0.11:compile

pom.xml

@@ -9,7 +9,7 @@
   <properties>
     <java.version>17</java.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <model.version>2.0.117</model.version>
+    <model.version>2.0.118</model.version>
     <hibernate.version>6.1.7.Final</hibernate.version>
     <jetty.version>11.0.24</jetty.version>
     <spring.version>6.0.11</spring.version>

src/main/java/ai/elimu/entity/analytics/LetterSoundAssessmentEvent.java

@@ -1,6 +1,10 @@
 package ai.elimu.entity.analytics;
 
+import java.util.List;
+
 import ai.elimu.entity.content.LetterSound;
+import ai.elimu.entity.converters.StringListConverter;
+import jakarta.persistence.Convert;
 import jakarta.persistence.Entity;
 import jakarta.persistence.ManyToOne;
 import jakarta.validation.constraints.NotNull;
@@ -16,13 +20,15 @@ public class LetterSoundAssessmentEvent extends AssessmentEvent {
      * The sequence of letters. E.g. <code>"sh"</code>.
      */
     @NotNull
-    private String letterSoundLetters;
+    @Convert(converter = StringListConverter.class)
+    private List<String> letterSoundLetters;
 
     /**
      * The sequence of sounds (IPA values). E.g. <code>"ʃ"</code>.
      */
     @NotNull
-    private String letterSoundSounds;
+    @Convert(converter = StringListConverter.class)
+    private List<String> letterSoundSounds;
 
     /**
      * This field might not be included, e.g. if the assessment task was done in a 

src/main/java/ai/elimu/util/csv/CsvAnalyticsExtractionHelper.java

@@ -54,8 +54,8 @@ public void handleRequest(
               "additional_data",
               "research_experiment",
               "experiment_group",
-              // "letter_sound_letters",
-              // "letter_sound_sounds",
+              "letter_sound_letters",
+              "letter_sound_sounds",
               "letter_sound_id"
           ).build();
       StringWriter stringWriter = new StringWriter();
@@ -69,8 +69,8 @@ public void handleRequest(
             event.getAdditionalData(),
             (event.getResearchExperiment() != null) ? event.getResearchExperiment().ordinal() : null,
             (event.getExperimentGroup() != null) ? event.getExperimentGroup().ordinal() : null,
-            // letterSoundLearningEvent.getLetterSoundLetters(),
-            // letterSoundLearningEvent.getLetterSoundSounds(),
+            event.getLetterSoundLetters(),
+            event.getLetterSoundSounds(),
             event.getLetterSoundId()
         );
       }

src/main/java/ai/elimu/web/analytics/students/LetterSoundLearningEventsCsvExportController.java

@@ -1,12 +1,12 @@
 package ai.elimu.util.csv;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.io.File;
 import java.io.IOException;
+import java.util.Arrays;
 import java.util.List;
 
 import org.json.JSONObject;
@@ -29,8 +29,6 @@
 
 public class CsvAnalyticsExtractionHelperTest {
 
-    // TODO: letter-sound assessment events
-
     /**
      * Test extraction of data from CSV files generated by version 3002014 of the Analytics app: 
      * https://github.com/elimu-ai/analytics/releases/tag/3.2.14
@@ -92,9 +90,37 @@ public void testExtractLetterSoundLearningEvents_v3005013() throws IOException {
         assertEquals("ai.elimu.herufi", letterSoundLearningEvent.getPackageName());
         assertNull(letterSoundLearningEvent.getResearchExperiment());
         assertNull(letterSoundLearningEvent.getExperimentGroup());
+        assertEquals(Arrays.asList(), letterSoundLearningEvent.getLetterSoundLetters());
+        assertEquals(Arrays.asList(), letterSoundLearningEvent.getLetterSoundSounds());
         assertEquals(1, letterSoundLearningEvent.getLetterSoundId());
     }
 
+    /**
+     * Test extraction of data from CSV files generated by version 4001002 of the Analytics app: 
+     * https://github.com/elimu-ai/analytics/releases/tag/4.1.2
+     */
+    @Test
+    public void testExtractLetterSoundLearningEvents_v4001002() throws IOException {
+        ResourceLoader resourceLoader = new ClassRelativeResourceLoader(CsvAnalyticsExtractionHelper.class);
+        Resource resource = resourceLoader.getResource("5b7c682a12ecbe2e_4001002_letter-sound-learning-events_2025-07-28.csv");
+        File csvFile = resource.getFile();
+        
+        List<LetterSoundLearningEvent> letterSoundLearningEvents = CsvAnalyticsExtractionHelper.extractLetterSoundLearningEvents(csvFile);
+        assertEquals(22, letterSoundLearningEvents.size());
+
+        LetterSoundLearningEvent letterSoundLearningEvent = letterSoundLearningEvents.get(0);
+        assertEquals(1753693734 * 1_000L, letterSoundLearningEvent.getTimestamp().getTimeInMillis());
+        assertEquals("5b7c682a12ecbe2e", letterSoundLearningEvent.getAndroidId());
+        assertEquals("ai.elimu.herufi.debug", letterSoundLearningEvent.getPackageName());
+        assertEquals(ResearchExperiment.EXP_0_WORD_EMOJIS, letterSoundLearningEvent.getResearchExperiment());
+        assertEquals(ExperimentGroup.TREATMENT, letterSoundLearningEvent.getExperimentGroup());
+        assertEquals(Arrays.asList("น"), letterSoundLearningEvent.getLetterSoundLetters());
+        assertEquals(Arrays.asList("n"), letterSoundLearningEvent.getLetterSoundSounds());
+        assertEquals(7, letterSoundLearningEvent.getLetterSoundId());
+    }
+
+    // TODO: letter-sound assessment events
+
 
     /**
      * Test extraction of data from CSV files generated by version 3001030 of the Analytics app: 

src/test/java/ai/elimu/util/csv/CsvAnalyticsExtractionHelperTest.java

@@ -0,0 +1,23 @@
+id,timestamp,package_name,additional_data,research_experiment,experiment_group,letter_sound_letters,letter_sound_sounds,letter_sound_id
+44,1753693734,ai.elimu.herufi.debug,,0,1,[น],[n],7
+45,1753693740,ai.elimu.herufi.debug,,0,1,[ก],[k],3
+46,1753693756,ai.elimu.herufi.debug,,0,1,[◌ั],[a],34
+47,1753694783,ai.elimu.herufi.debug,,0,1,[น],[n],7
+48,1753694800,ai.elimu.herufi.debug,,0,1,[ก],[k],3
+49,1753694805,ai.elimu.herufi.debug,,0,1,[◌ั],[a],34
+50,1753694807,ai.elimu.herufi.debug,,0,1,[◌า],[aː],13
+51,1753694813,ai.elimu.herufi.debug,,0,1,[◌อ],[ɔː],31
+52,1753694819,ai.elimu.herufi.debug,,0,1,[ข],[kʰ],38
+53,1753694821,ai.elimu.herufi.debug,,0,1,[จ],[tɕ],24
+54,1753694825,ai.elimu.herufi.debug,,0,1,[ไ◌],"[a, j]",40
+55,1753694846,ai.elimu.herufi.debug,,0,1,[ฉ],[tɕʰ],44
+56,1753694865,ai.elimu.herufi.debug,,0,1,[เ◌า],"[a, w]",69
+57,1753694871,ai.elimu.herufi.debug,,0,1,[แ◌ะ],[ɛ],70
+58,1753694877,ai.elimu.herufi.debug,,0,1,[เ◌อ],[ɤː],72
+59,1753694881,ai.elimu.herufi.debug,,0,1,[น],"[n, o]",62
+60,1753694885,ai.elimu.herufi.debug,,0,1,[เ◌ย],"[ɤː, j]",79
+61,1753694893,ai.elimu.herufi.debug,,0,1,"[ห, ล]",[l],65
+62,1753694897,ai.elimu.herufi.debug,,0,1,"[ห, ล]",[l],65
+63,1753694918,ai.elimu.herufi.debug,,0,1,"[ห, ย]",[y],59
+64,1753694930,ai.elimu.herufi.debug,,0,1,"[ท, ร]",[s],42
+65,1753695261,ai.elimu.herufi.debug,,0,1,[น],[n],7