Phase 6b/7b: per-child decoded periods, separate brief blocks, idempotent calendar (AUD-119)

- Parse each child's own "Today" day widget for the timetable (FR-16); drop the school-wide week calendar's lesson grid and clean the leaked routine rows. - Add the editable codes map (FR-17): subjects, rooms, teachers and period labels, seeded, an unknown code falls back to the raw code; `school codes` CLI. - Brief: Finn's block first, then Harry's, four sections always present (FR-9); periods decoded into plain English; the undated tail is one counted line (FR-18). - Calendar: write periods + work due + work overdue + major events, per child, on every pass. Identity is the stable per-item key, so a re-run never re-inserts (FR-8). morning-brief.sh now runs scan -> calendar push -> notify. - Day-widget labels are 12-hour: 1-6 read as PM, fixing afternoon periods. Proven live on .13: image 0.6.2-phase6b7b; both children's briefs decoded and separate; 35 events in calendar.school; runs 2 and 3 of the scan added nothing. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-10-16 10:25:55 +11:00
parent 4950755b3d
commit 047af0f31d
40 changed files with 2049 additions and 160 deletions
--- a/internal/parse/calendar.go
+++ b/internal/parse/calendar.go
@@ -6,6 +6,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"gitea.lab.audasmedia.com.au/sam/compass_teams_nhs/internal/period"
 )

 // calendarPxPerHour is the Compass week-grid scale: the day gutter is 1200px
@@ -21,13 +23,12 @@ var (
 	calendarTop = regexp.MustCompile(`top:\s*([0-9.]+)px`)
 	// clockPrefix matches the leading "8:55: " of an event label.
 	clockPrefix = regexp.MustCompile(`^(\d{1,2}):(\d{2}):\s*(.*)$`)
-	// periodLabel matches the period part of a lesson label: "5", "C" or
-	// "RLE GROUP D".
-	periodLabel = regexp.MustCompile(`^(\d{1,2}|[A-Z]|RLE GROUP [A-Z])$`)
 )

-// parseCalendar parses the week calendar into event items. It fails loudly when
-// the page has no calendar grid (FR-12).
+// parseCalendar parses the week calendar page. The week calendar is
+// school-wide and its lesson grid belongs to the eldest child, so routine
+// lessons are dropped here: each child's own periods come from that child's
+// day widget (FR-16). Only real school events are kept.
 func parseCalendar(child string, page Page, loc *time.Location) ([]Item, error) {
 	items, found, err := extractCalendar(child, page, loc)
 	if err != nil {
@@ -36,7 +37,13 @@ func parseCalendar(child string, page Page, loc *time.Location) ([]Item, error)
 	if !found {
 		return nil, fmt.Errorf("parse: %s: no calendar grid found in %s (layout changed or fetch failed)", child, page.Slug)
 	}
-	return items, nil
+	out := items[:0]
+	for _, it := range items {
+		if eventIsSchoolEvent(it.Title) {
+			out = append(out, it)
+		}
+	}
+	return out, nil
 }

 // extractCalendar returns the calendar events in one page. found reports whether
@@ -140,8 +147,8 @@ func eventItem(child string, ev *node, page Page, loc *time.Location) (Item, boo
 // label is "5 - 11HLEGB5 - D8 - LHT"; a school event is
 // "End of Year Senior Music Concert - HALL (...) - KSH, CFR, ...".
 func splitEvent(label, title string) (subject, teacher, body string) {
-	parts := splitDash(title)
-	if len(parts) >= 2 && periodLabel.MatchString(parts[0]) {
+	parts := period.SplitDash(title)
+	if len(parts) >= 2 && period.IsPeriodLabel(parts[0]) {
 		for _, p := range parts[1:] {
 			if subject == "" && classCode.MatchString(p) {
 				subject = p
@@ -159,11 +166,4 @@ func splitEvent(label, title string) (subject, teacher, body string) {
 }

 // splitDash splits on " - " and trims each part.
-func splitDash(s string) []string {
-	raw := strings.Split(s, " - ")
-	out := make([]string, 0, len(raw))
-	for _, p := range raw {
-		out = append(out, strings.TrimSpace(p))
-	}
-	return out
-}
+func splitDash(s string) []string { return period.SplitDash(s) }
--- a/internal/parse/daywidget.go
+++ b/internal/parse/daywidget.go
@@ -0,0 +1,114 @@
+package parse
+
+import (
+	"fmt"
+	"strings"
+	"time"
+)
+
+// This file parses the per-child day widget that Compass renders on a child's
+// own pages ("/Records/User.aspx?userId=..." and the Learning Tasks page). The
+// widget is labelled "Today" and its events are that child's own periods:
+//
+//	8:55: 1 - 7SCF - H14LAB - KNI
+//
+// The week calendar is school-wide (it carries the eldest child's lesson grid),
+// so it must never be the source of a child's timetable (AGENTS.md §4 FR-16).
+// This is the per-child source.
+
+// dayWidgetBaseHour is unused: the widget's grid start moves with the day's
+// first event (a page whose first event is 7:45 starts at 07:00, one whose
+// first event is 8:55 starts at 06:00), so the printed clock is the reliable
+// source and the grid offset is not.
+
+// parseDayWidget returns the periods in one child's day widget. found reports
+// whether the page carried a day widget at all.
+func parseDayWidget(child string, page Page, loc *time.Location, ref time.Time) (items []Item, found bool, err error) {
+	root := parseHTML(page.HTML)
+	events := findAll(root, func(n *node) bool {
+		return n.Tag == "div" && n.hasClassPart("day-bd-evt-") && n.hasClassPart("calendardaywidget-")
+	})
+	if len(events) == 0 {
+		return nil, false, nil
+	}
+
+	day := ref.In(loc)
+	if day.IsZero() {
+		day = time.Now().In(loc)
+	}
+	date := time.Date(day.Year(), day.Month(), day.Day(), 0, 0, 0, 0, loc)
+
+	for _, ev := range events {
+		labelSpan := find(ev, func(n *node) bool { return n.hasClass("ext-evt-bd") })
+		if labelSpan == nil {
+			continue
+		}
+		label := collapse(labelSpan.Text())
+		if label == "" {
+			continue
+		}
+		cm := clockPrefix.FindStringSubmatch(label)
+		if cm == nil {
+			return nil, true, fmt.Errorf("parse: %s: day-widget event %q has no start time", page.Slug, label)
+		}
+		at, err := dayWidgetTime(cm, date)
+		if err != nil {
+			return nil, true, fmt.Errorf("parse: %s: day-widget event %q: %w", page.Slug, label, err)
+		}
+		title := strings.TrimSpace(cm[3])
+		if title == "" {
+			title = label
+		}
+
+		subject, teacher, body := splitEvent(label, title)
+		url := page.URL
+		if url == "" {
+			url = compassHost + "/Organise/Calendar/"
+		}
+
+		items = append(items, Item{
+			Child:       child,
+			Source:      SourceCompass,
+			Type:        TypeEvent,
+			Subject:     subject,
+			Teacher:     teacher,
+			Title:       title,
+			Body:        body,
+			DueAt:       &at,
+			URL:         url,
+			SourcePage:  page.Slug,
+			ExternalRef: dedupeKey("day-period", at.Format(time.RFC3339), title),
+			Importance:  importanceNormal,
+		})
+	}
+	return items, true, nil
+}
+
+// dayWidgetTime reads an event's start from the printed clock. Compass prints a
+// 12-hour clock with no AM/PM marker ("1:26" is the afternoon period), so the
+// school-day convention applies: 1-6 are PM, 7-11 are AM, 12 is noon.
+func dayWidgetTime(clock []string, date time.Time) (time.Time, error) {
+	hour, minute := atoiSafe(clock[1]), atoiSafe(clock[2])
+	if hour < 0 || hour > 23 || minute < 0 || minute > 59 {
+		return time.Time{}, fmt.Errorf("bad time %02d:%02d", hour, minute)
+	}
+	if hour >= 1 && hour <= 6 { // 1:26 means 1:26 PM in the Compass day grid
+		hour += 12
+	}
+	return date.Add(time.Duration(hour)*time.Hour + time.Duration(minute)*time.Minute), nil
+}
+
+// atoiSafe parses a small decimal number, returning -1 when it is not one.
+func atoiSafe(s string) int {
+	n := 0
+	if s == "" {
+		return -1
+	}
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			return -1
+		}
+		n = n*10 + int(r-'0')
+	}
+	return n
+}
--- a/internal/parse/importance.go
+++ b/internal/parse/importance.go
@@ -7,6 +7,8 @@ import (
 	"sort"
 	"strings"
 	"time"
+
+	"gitea.lab.audasmedia.com.au/sam/compass_teams_nhs/internal/period"
 )

 // Importance labels stored in items.importance (FR-4).
@@ -69,11 +71,11 @@ func deterministicImportance(it Item, week time.Time) string {
 // "End of Year Senior Music Concert - HALL (...) - KSH, CFR". The first part of
 // a lesson is a period label ("5", "C" or "RLE GROUP D").
 func eventIsSchoolEvent(title string) bool {
-	parts := splitDash(title)
+	parts := period.SplitDash(title)
 	if len(parts) == 0 || strings.TrimSpace(parts[0]) == "" {
 		return false
 	}
-	return !periodLabel.MatchString(parts[0])
+	return !period.IsPeriodLabel(parts[0])
 }

 // ClassifyModel asks a model to classify importance for every item (FR-4). It
--- a/internal/parse/parse.go
+++ b/internal/parse/parse.go
@@ -45,13 +45,16 @@ type Item struct {

 // Page is one stored raw page: its slug, the URL it was fetched from, and the
 // bytes. HTML pages carry HTML; the JSON service page carries JSON and the
-// child's Compass userId (from the fetcher's meta file).
+// child's Compass userId (from the fetcher's meta file). FetchedAt is when the
+// fetcher stored the page, so a "Today" widget can be dated correctly even when
+// an old run is re-parsed.
 type Page struct {
-	Slug   string
-	URL    string
-	HTML   []byte
-	JSON   []byte
-	UserID string
+	Slug      string
+	URL       string
+	HTML      []byte
+	JSON      []byte
+	UserID    string
+	FetchedAt time.Time
 }

 // Parse turns the stored pages for one child into structured items. It fails,
@@ -96,30 +99,39 @@ func Parse(child string, pages []Page, loc *time.Location) ([]Item, error) {
 			items = append(items, got.items...)
 			recognised++
 		case PageLearningTasks:
-			if hasAuthoritativeTasks {
-				recognised++
-				continue
+			if !hasAuthoritativeTasks {
+				got, err := parseLearningTasks(child, p, loc)
+				if err != nil {
+					return nil, err
+				}
+				items = append(items, got...)
 			}
-			got, err := parseLearningTasks(child, p, loc)
+			// The child's own day widget is the per-child timetable (FR-16).
+			day, _, err := parseDayWidget(child, p, loc, p.FetchedAt)
 			if err != nil {
 				return nil, err
 			}
-			items = append(items, got...)
+			items = append(items, day...)
 			recognised++
 		case PageChildProfile:
 			// The React profile page has no server-rendered grid; when it does
 			// carry the legacy grid, use it. The JSON list supersedes it.
-			if hasAuthoritativeTasks {
-				recognised++
-				continue
+			if !hasAuthoritativeTasks {
+				got, found, err := extractLearningTasks(child, p, loc)
+				if err != nil {
+					return nil, err
+				}
+				if found {
+					items = append(items, got...)
+				}
 			}
-			got, found, err := extractLearningTasks(child, p, loc)
+			// The profile page carries the child's own "Today" widget: the
+			// authoritative per-child periods (FR-16).
+			day, _, err := parseDayWidget(child, p, loc, p.FetchedAt)
 			if err != nil {
 				return nil, err
 			}
-			if found {
-				items = append(items, got...)
-			}
+			items = append(items, day...)
 			recognised++
 		case PageHome:
 			got, err := parseNews(child, p, loc)
--- a/internal/parse/parse_test.go
+++ b/internal/parse/parse_test.go
@@ -175,23 +175,20 @@ func TestParseCalendar(t *testing.T) {
 	if err != nil {
 		t.Fatalf("parseCalendar: %v", err)
 	}
-	if len(items) != 2 {
-		t.Fatalf("got %d items, want 2", len(items))
+	// The week calendar is school-wide, so its lesson grid is dropped: a
+	// child's own periods come from that child's day widget (FR-16). Only the
+	// real school event survives.
+	if len(items) != 1 {
+		t.Fatalf("got %d items, want 1 (the routine lesson is not a per-child period)", len(items))
 	}
 	if items[0].Type != TypeEvent {
 		t.Errorf("type = %q", items[0].Type)
 	}
 	if got := items[0].DueAt.Format("2006-01-02 15:04"); got != "2026-10-15 18:00" {
-		t.Errorf("event 1 time = %s", got)
+		t.Errorf("event time = %s", got)
 	}
 	if items[0].Title != "End of Year Concert - HALL - KSH" {
-		t.Errorf("event 1 title = %q", items[0].Title)
-	}
-	if items[1].Subject != "11HLEGB5" || items[1].Teacher != "LHT" {
-		t.Errorf("event 2 subject/teacher = %q/%q", items[1].Subject, items[1].Teacher)
-	}
-	if got := items[1].DueAt.Format("15:04"); got != "14:06" {
-		t.Errorf("event 2 time = %q", got)
+		t.Errorf("event title = %q", items[0].Title)
 	}
 }

@@ -430,3 +427,87 @@ func TestParseReconcilesOverdueWithHome(t *testing.T) {
 		t.Fatal("Parse accepted a home page with no record of the child (FR-12)")
 	}
 }
+
+// dayWidgetFixture is the per-child "Today" widget Compass renders on a child's
+// own profile page. The child is Finn (Year 7).
+const dayWidgetFixture = `<html><body>
+<div class="x-panel compass-day-calendar x-cal-panel" id="calendardaywidget-1055">
+  <div class="x-toolbar">Today</div>
+  <div class="calendardaywidget-1055-day-bd-evt-a x-cal-default calendar-event-93806 custom-event ext-cal-evt activity-type-1 ext-event-no-roll" style="left:0%;width:100%;top:95.8px;height:48.1px;">
+    <span class="ext-evt-bd" lang="en-GB">8:55: 1 - 7SCF - H14LAB - KNI</span>
+  </div>
+  <div class="calendardaywidget-1055-day-bd-evt-b x-cal-default calendar-event-93737 custom-event ext-cal-evt activity-type-1 ext-event-no-roll" style="left:50%;width:50%;top:145px;height:44px;">
+    <span class="ext-evt-bd" lang="en-GB">9:54: 2 - 7DESF - B1 - PSI</span>
+  </div>
+  <div class="calendardaywidget-1055-day-bd-evt-c x-cal-default calendar-event-93755 custom-event ext-cal-evt activity-type-1 ext-event-no-roll" style="left:0%;width:100%;top:321.6666666666667px;height:48px;">
+    <span class="ext-evt-bd" lang="en-GB">1:26: 4 - 7PEF - GYM4 - LTA</span>
+  </div>
+</div>
+</body></html>`
+
+// TestParseDayWidgetIsPerChild proves FR-16: a child's periods come from that
+// child's own day widget, and the school-wide week calendar's lesson grid is
+// never stored against the child.
+func TestParseDayWidgetIsPerChild(t *testing.T) {
+	loc := melbourne(t)
+	fetched := time.Date(2026, 10, 16, 7, 0, 0, 0, loc)
+	pages := []Page{
+		{Slug: PageChildProfile, URL: "https://nhs-vic.compass.education/Records/User.aspx?userId=4242", HTML: []byte(dayWidgetFixture), FetchedAt: fetched},
+		{Slug: PageCalendar, URL: "https://nhs-vic.compass.education/Organise/Calendar/", HTML: []byte(calendarFixture), FetchedAt: fetched},
+	}
+	items, err := Parse("Finn", pages, loc)
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+
+	leaked := 0
+	periods := 0
+	for _, it := range items {
+		if it.Subject == "11HLEGB5" {
+			leaked++
+		}
+		if it.SourcePage == PageChildProfile && it.Type == TypeEvent {
+			periods++
+			if it.DueAt == nil || it.DueAt.In(loc).Format("2006-01-02") != "2026-10-16" {
+				t.Errorf("period %q dated %v, want 2026-10-16", it.Title, it.DueAt)
+			}
+			if it.SourcePage != PageChildProfile {
+				t.Errorf("period %q source page = %q, want %q", it.Title, it.SourcePage, PageChildProfile)
+			}
+		}
+	}
+	if leaked != 0 {
+		t.Errorf("Finn's items carry %d Year 11 lesson(s) from the school-wide calendar", leaked)
+	}
+	if periods != 3 {
+		t.Errorf("Finn has %d periods, want 3", periods)
+	}
+}
+
+// TestDayWidgetParsesRoomAndTeacher proves the label is split into its parts so
+// the brief can decode them.
+func TestDayWidgetParsesRoomAndTeacher(t *testing.T) {
+	loc := melbourne(t)
+	fetched := time.Date(2026, 10, 16, 7, 0, 0, 0, loc)
+	items, found, err := parseDayWidget("Finn", Page{Slug: PageChildProfile, HTML: []byte(dayWidgetFixture), FetchedAt: fetched}, loc, fetched)
+	if err != nil || !found {
+		t.Fatalf("parseDayWidget: found=%v err=%v", found, err)
+	}
+	if len(items) != 3 {
+		t.Fatalf("got %d periods, want 3", len(items))
+	}
+	if items[0].Subject != "7SCF" {
+		t.Errorf("subject = %q", items[0].Subject)
+	}
+	if items[0].Title != "1 - 7SCF - H14LAB - KNI" {
+		t.Errorf("title = %q", items[0].Title)
+	}
+	if got := items[0].DueAt.In(loc).Format("15:04"); got != "08:55" {
+		t.Errorf("start = %q, want 08:55", got)
+	}
+	// The printed clock is 12-hour: the 1:26 period is 1:26 PM (the grid
+	// offset is the authority).
+	if got := items[2].DueAt.In(loc).Format("15:04"); got != "13:26" {
+		t.Errorf("afternoon start = %q, want 13:26", got)
+	}
+}