feat: letter-sound assessment event

pom-dependency-tree.txt

@@ -1,4 +1,4 @@
-ai.elimu:webapp:war:2.6.15-SNAPSHOT
+ai.elimu:webapp:war:2.6.16-SNAPSHOT
 +- ai.elimu:model:jar:model-2.0.97:compile
 |  \- com.google.code.gson:gson:jar:2.13.0:compile
 |     \- com.google.errorprone:error_prone_annotations:jar:2.37.0:compile

src/main/java/ai/elimu/dao/LetterSoundAssessmentEventDao.java

@@ -0,0 +1,12 @@
+package ai.elimu.dao;
+
+import java.util.List;
+
+import org.springframework.dao.DataAccessException;
+
+import ai.elimu.entity.analytics.LetterSoundAssessmentEvent;
+
+public interface LetterSoundAssessmentEventDao extends GenericDao<LetterSoundAssessmentEvent> {
+
+    List<LetterSoundAssessmentEvent> readAll(String androidId) throws DataAccessException;
+}

src/main/java/ai/elimu/dao/jpa/LetterSoundAssessmentEventDaoJpa.java

@@ -0,0 +1,22 @@
+package ai.elimu.dao.jpa;
+
+import java.util.List;
+
+import org.springframework.dao.DataAccessException;
+
+import ai.elimu.dao.LetterSoundAssessmentEventDao;
+import ai.elimu.entity.analytics.LetterSoundAssessmentEvent;
+
+public class LetterSoundAssessmentEventDaoJpa extends GenericDaoJpa<LetterSoundAssessmentEvent> implements LetterSoundAssessmentEventDao {
+
+    @Override
+    public List<LetterSoundAssessmentEvent> readAll(String androidId) throws DataAccessException {
+        return em.createQuery(
+            "SELECT event " + 
+            "FROM LetterSoundAssessmentEvent event " +
+            "WHERE event.androidId = :androidId " + 
+            "ORDER BY event.timestamp")
+            .setParameter("androidId", androidId)
+            .getResultList();
+    }
+}

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

@@ -0,0 +1,57 @@
+package ai.elimu.entity.analytics;
+
+import ai.elimu.entity.BaseEntity;
+import ai.elimu.entity.application.Application;
+import jakarta.persistence.Column;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MappedSuperclass;
+import jakarta.persistence.Temporal;
+import jakarta.persistence.TemporalType;
+import jakarta.validation.constraints.NotNull;
+import java.util.Calendar;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@MappedSuperclass
+public abstract class AssessmentEvent extends BaseEntity {
+
+  @NotNull
+  @Temporal(TemporalType.TIMESTAMP)
+  private Calendar timestamp;
+
+  /**
+   * A 64-bit number (expressed as a hexadecimal string), unique to each combination of 
+   * app-signing key, user, and device.
+   * 
+   * See https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID
+   */
+  @NotNull
+  private String androidId;
+
+  /**
+   * The package name of the {@link #application} where the assessment event occurred.
+   * E.g. <code>ai.elimu.soundcards</code>.
+   */
+  @NotNull
+  private String packageName;
+
+  /**
+   * This field will only be populated if a corresponding {@link Application} can be 
+   * found in the database for the {@link #packageName}.
+   */
+  @ManyToOne
+  private Application application;
+
+  /**
+   * Any additional data should be stored in the format of a JSON object.
+   * 
+   * Example:
+   * <pre>
+   * {'word_ids_presented': [1,2,3], 'word_id_selected': 2}
+   * </pre>
+   */
+  @Column(length = 1024)
+  private String additionalData;
+}

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

@@ -25,6 +25,9 @@ public abstract class LearningEvent extends BaseEntity {
   private Calendar timestamp;
 
   /**
+   * A 64-bit number (expressed as a hexadecimal string), unique to each combination of 
+   * app-signing key, user, and device.
+   * 
    * See https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID
    */
   @NotNull

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

@@ -0,0 +1,39 @@
+package ai.elimu.entity.analytics;
+
+import jakarta.persistence.Entity;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity
+public class LetterSoundAssessmentEvent extends AssessmentEvent {
+
+    /**
+     * The sequence of letters. E.g. <code>"sh"</code>.
+     */
+    private String letterSoundLetters;
+
+    /**
+     * The sequence of sounds (IPA values). E.g. <code>"ʃ"</code>.
+     */
+    private String letterSoundSounds;
+
+    /**
+     * This field might not be included, e.g. if the assessment task was done in a 
+     * 3rd-party app that did not load the content from the elimu.ai Content Provider. 
+     * In this case, the {@link #letterSoundId} will be {@code null}.
+     */
+    private Long letterSoundId;
+
+    /**
+     * A value in the range [0.0, 1.0].
+     */
+    private Float masteryScore;
+
+    /**
+     * The number of milliseconds passed between the student opening the assessment task 
+     * and submitting a response. E.g. <code>15000</code>.
+     */
+    private Long timeSpentMs;
+}

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

@@ -0,0 +1,93 @@
+package ai.elimu.web.analytics.students;
+
+import ai.elimu.dao.LetterSoundAssessmentEventDao;
+import ai.elimu.dao.StudentDao;
+import ai.elimu.entity.analytics.LetterSoundAssessmentEvent;
+import ai.elimu.entity.analytics.students.Student;
+import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.StringWriter;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.csv.CSVFormat;
+import org.apache.commons.csv.CSVPrinter;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+@Controller
+@RequestMapping("/analytics/students/{studentId}/letter-sound-assessment-events.csv")
+@RequiredArgsConstructor
+@Slf4j
+public class LetterSoundAssessmentEventCsvExportController {
+
+  private final StudentDao studentDao;
+
+  private final LetterSoundAssessmentEventDao letterSoundAssessmentEventDao;
+
+  @GetMapping
+  public void handleRequest(
+      @PathVariable Long studentId,
+      HttpServletResponse response,
+      OutputStream outputStream
+  ) throws IOException {
+    log.info("handleRequest");
+
+    Student student = studentDao.read(studentId);
+    log.info("student.getAndroidId(): " + student.getAndroidId());
+
+    List<LetterSoundAssessmentEvent> letterSoundAssessmentEvents = letterSoundAssessmentEventDao.readAll(student.getAndroidId());
+    log.info("letterSoundAssessmentEvents.size(): " + letterSoundAssessmentEvents.size());
+
+    CSVFormat csvFormat = CSVFormat.DEFAULT.builder()
+        .setHeader(
+            "id",
+            "timestamp",
+            "package_name",
+            "letter_sound_letters",
+            "letter_sound_sounds",
+            "letter_sound_id",
+            "mastery_score",
+            "time_spent_ms",
+            "additional_data"
+        )
+        .build();
+
+    StringWriter stringWriter = new StringWriter();
+    CSVPrinter csvPrinter = new CSVPrinter(stringWriter, csvFormat);
+
+    for (LetterSoundAssessmentEvent letterSoundAssessmentEvent : letterSoundAssessmentEvents) {
+      log.info("letterSoundAssessmentEvent.getId(): " + letterSoundAssessmentEvent.getId());
+
+      csvPrinter.printRecord(
+          letterSoundAssessmentEvent.getId(),
+          letterSoundAssessmentEvent.getTimestamp().getTimeInMillis(),
+          letterSoundAssessmentEvent.getPackageName(),
+          letterSoundAssessmentEvent.getLetterSoundLetters(),
+          letterSoundAssessmentEvent.getLetterSoundSounds(),
+          letterSoundAssessmentEvent.getLetterSoundId(),
+          letterSoundAssessmentEvent.getMasteryScore(),
+          letterSoundAssessmentEvent.getTimeSpentMs(),
+          letterSoundAssessmentEvent.getAdditionalData()
+      );
+    }
+    csvPrinter.flush();
+    csvPrinter.close();
+
+    String csvFileContent = stringWriter.toString();
+
+    response.setContentType("text/csv");
+    byte[] bytes = csvFileContent.getBytes();
+    response.setContentLength(bytes.length);
+    try {
+      outputStream.write(bytes);
+      outputStream.flush();
+      outputStream.close();
+    } catch (IOException ex) {
+      log.error(ex.getMessage());
+    }
+  }
+}

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

@@ -1,13 +1,19 @@
 package ai.elimu.web.analytics.students;
 
+import ai.elimu.dao.LetterSoundAssessmentEventDao;
+import ai.elimu.dao.LetterSoundLearningEventDao;
 import ai.elimu.dao.StoryBookLearningEventDao;
 import ai.elimu.dao.StudentDao;
 import ai.elimu.dao.VideoLearningEventDao;
 import ai.elimu.dao.WordLearningEventDao;
+import ai.elimu.entity.analytics.LetterSoundAssessmentEvent;
+import ai.elimu.entity.analytics.LetterSoundLearningEvent;
 import ai.elimu.entity.analytics.StoryBookLearningEvent;
 import ai.elimu.entity.analytics.VideoLearningEvent;
 import ai.elimu.entity.analytics.WordLearningEvent;
 import ai.elimu.entity.analytics.students.Student;
+import ai.elimu.model.v2.enums.content.LiteracySkill;
+import ai.elimu.model.v2.enums.content.NumeracySkill;
 import ai.elimu.util.AnalyticsHelper;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -33,6 +39,9 @@ public class StudentController {
 
   private final StudentDao studentDao;
 
+  private final LetterSoundAssessmentEventDao letterSoundAssessmentEventDao;
+  private final LetterSoundLearningEventDao letterSoundLearningEventDao;
+
   private final WordLearningEventDao wordLearningEventDao;
 
   private final StoryBookLearningEventDao storyBookLearningEventDao;
@@ -46,6 +55,17 @@ public String handleRequest(@PathVariable Long studentId, Model model) {
     Student student = studentDao.read(studentId);
     log.info("student.getAndroidId(): " + student.getAndroidId());
 
+
+    model.addAttribute("literacySkills", LiteracySkill.values());
+    model.addAttribute("numeracySkills", NumeracySkill.values());
+
+
+    List<LetterSoundAssessmentEvent> letterSoundAssessmentEvents = letterSoundAssessmentEventDao.readAll();
+    model.addAttribute("letterSoundAssessmentEvents", letterSoundAssessmentEvents);
+
+    List<LetterSoundLearningEvent> letterSoundLearningEvents = letterSoundLearningEventDao.readAll();
+    model.addAttribute("letterSoundLearningEvents", letterSoundLearningEvents);
+
 
     // Prepare chart data - WordLearningEvents
     List<WordLearningEvent> wordLearningEvents = wordLearningEventDao.readAll();

src/main/resources/META-INF/jpa-schema-export.sql

@@ -43,6 +43,8 @@
 
     drop table if exists LetterSound_Sound;
 
+    drop table if exists LetterSoundAssessmentEvent;
+
     drop table if exists LetterSoundContributionEvent;
 
     drop table if exists LetterSoundLearningEvent;
@@ -304,6 +306,21 @@
         primary key (LetterSound_id, sounds_ORDER)
     ) type=MyISAM;
 
+    create table LetterSoundAssessmentEvent (
+       id bigint not null auto_increment,
+        additionalData text,
+        androidId varchar(255),
+        packageName varchar(255),
+        timestamp datetime,
+        letterSoundId bigint,
+        letterSoundLetters varchar(255),
+        letterSoundSounds varchar(255),
+        masteryScore float(23),
+        timeSpentMs bigint,
+        application_id bigint,
+        primary key (id)
+    ) type=MyISAM;
+
     create table LetterSoundContributionEvent (
        id bigint not null auto_increment,
         comment text,
@@ -755,6 +772,11 @@
        foreign key (LetterSound_id) 
        references LetterSound (id);
 
+    alter table LetterSoundAssessmentEvent 
+       add constraint FKehf1rjbixnmdjol91didaj4b5 
+       foreign key (application_id) 
+       references Application (id);
+
     alter table LetterSoundContributionEvent 
        add constraint FK5uk320agfa13pvh52v6n6ncbs 
        foreign key (contributor_id)