feat(mood): structured tag taxonomy + note capture and timeline

Add the Category -> Tag taxonomy the mood surface was missing and the
free-text note the web form could never write, then surface both on the
Insights mood page.

Schema (migration 0101): a global MoodTagCategory -> MoodTag catalog
plus a MoodEntryTagLink join, seeded with a default five-category set
(i18n-keyed labels, Lucide icons). Purely additive — the legacy flat
MoodEntry.tags JSON column, the GLP-1 quick-tags, and the Telegram /
MoodLog sync are untouched; an entry can carry both axes.

Capture: the mood-logging form and the edit sheet gain a Textarea for
the note (model + API already accepted it) and an icon-chip picker over
the taxonomy catalog (GET /api/mood/tags). Create / update resolve the
picked keys to links; unknown keys drop silently against the catalog.

Insights: a structured-tag breakdown (icon + per-tag avg-mood lift) and
a notes timeline join the existing distribution / weekday / flat-tag
sections. The aggregate extension also fixes the flat-tag axis, which
read the raw JSON string and so never populated.

i18n across all six locales. Tests cover the taxonomy aggregation, the
note round-trip, the structured-tag schema, and the notes timeline.
This commit is contained in:
Marc-André Bombeck committed 2026-06-01 20:25:42 +02:00
1 parent b99a015266
commit cf649f72ce
25 files changed
+1688 -18

No files matched your search

@@ -6,11 +6,14 @@ import {
computeInTargetPct,
computeMoodAggregates,
computeMoodMetricCorrelation,
computeNotesTimeline,
computeStructuredTagSummary,
computeTagSummary,
computeWeekdayAverages,
selectHeatmapWindow,
type CrossMetricMeasurement,
type MoodAggregateEntry,
type StructuredTagRef,
} from "../mood-aggregates";
const dayMs = 24 * 60 * 60 * 1000;
@@ -78,6 +81,79 @@ describe("computeTagSummary", () => {
});
});
describe("computeStructuredTagSummary", () => {
function entryWithStructured(
offset: number,
score: number,
structuredTags: StructuredTagRef[],
): MoodAggregateEntry {
return { ...entry(offset, score, null), structuredTags };
}
it("ranks structured tags by frequency, keeps singletons, and groups by category", () => {
const entries: MoodAggregateEntry[] = [
entryWithStructured(1, 5, [
{ key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
{ key: "worked_out", categoryKey: "health", labelKey: "mood.tag.workedOut", icon: "Dumbbell" },
]),
entryWithStructured(2, 3, [
{ key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
]),
entryWithStructured(3, 1, [
{ key: "stressed", categoryKey: "feelings", labelKey: "mood.tag.stressed", icon: "Brain" },
]),
];
const rows = computeStructuredTagSummary(entries, NOW);
const happy = rows.find((r) => r.key === "happy");
expect(happy).toEqual({
key: "happy",
categoryKey: "feelings",
labelKey: "mood.tag.happy",
icon: "Smile",
count: 2,
avgScore: 4,
});
// singletons are kept for the structured breakdown (curated catalog,
// not noisy free text).
expect(rows.find((r) => r.key === "stressed")?.count).toBe(1);
expect(rows.find((r) => r.key === "worked_out")?.categoryKey).toBe("health");
// ranked by frequency desc.
expect(rows[0].key).toBe("happy");
});
it("excludes entries older than the window and ignores entries without structured tags", () => {
const entries: MoodAggregateEntry[] = [
entryWithStructured(1, 5, [
{ key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
]),
entryWithStructured(200, 5, [
{ key: "sad", categoryKey: "feelings", labelKey: "mood.tag.sad", icon: "Frown" },
]),
entry(2, 4, ["flat-only"]), // no structuredTags → ignored here
];
const rows = computeStructuredTagSummary(entries, NOW, 90);
expect(rows.map((r) => r.key)).toEqual(["happy"]);
});
});
describe("computeNotesTimeline", () => {
it("returns noted entries newest-first, skips empty notes, and caps at the limit", () => {
const entries: MoodAggregateEntry[] = [
{ ...entry(5, 2, ["x"]), note: "oldest", mood: "SCHLECHT" },
{ ...entry(3, 4, null), note: " ", mood: "GUT" }, // blank → skipped
{ ...entry(2, 5, null), note: "middle", mood: "SUPER_GUT" },
{ ...entry(1, 3, null), note: "newest", mood: "OKAY" },
];
const timeline = computeNotesTimeline(entries, 2);
expect(timeline.map((n) => n.note)).toEqual(["newest", "middle"]);
expect(timeline[0]).toMatchObject({ score: 3, mood: "OKAY", note: "newest" });
});
it("returns an empty array when no entry carries a note", () => {
expect(computeNotesTimeline([entry(1, 4, ["x"])])).toEqual([]);
});
});
describe("computeInTargetPct", () => {
it("returns the share of the newest 30 daily buckets in the green band", () => {
const daily = [
+197 -2
View File
@@ -28,6 +28,24 @@ import { round, summarizeSeries } from "@/lib/insights/status-shared";
const MS_PER_DAY = 24 * 60 * 60 * 1000;
/**
* Parse the flat `MoodEntry.tags` JSON string into a string array. The
* column stores a JSON-encoded array (or null); the read path must
* decode it before `computeTagSummary`'s `Array.isArray` check, otherwise
* the flat-tag axis silently collapses to empty (the raw string is never
* an array). Defensive against malformed JSON — returns `[]` on a parse
* failure rather than throwing.
*/
function parseTags(tags: string | null): string[] {
if (!tags) return [];
try {
const parsed = JSON.parse(tags);
return Array.isArray(parsed) ? (parsed as string[]) : [];
} catch {
return [];
}
}
/**
* Minimal daily-bucket shape the aggregates read. `DailyBucket` (from
* `bucket-series`) carries an extra `n` field; the helpers only ever
@@ -36,6 +54,23 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
*/
type DailyPoint = Pick<DailyBucket, "dayOffset" | "value">;
/**
* A structured tag attached to a mood entry, resolved from the catalog
* (`mood_tags` + its parent `mood_tag_categories`) via the
* `mood_entry_tag_links` join. Carried alongside the legacy flat `tags`
* string so the breakdown can surface both axes.
*/
export interface StructuredTagRef {
/** Stable tag key (e.g. `happy`). */
key: string;
/** Parent category key (e.g. `feelings`). */
categoryKey: string;
/** i18n message key for the tag label. */
labelKey: string;
/** Lucide icon name, or null. */
icon: string | null;
}
/** Raw mood row shape the aggregates operate on. */
export interface MoodAggregateEntry {
/** TZ-anchored day key (YYYY-MM-DD). */
@@ -46,6 +81,59 @@ export interface MoodAggregateEntry {
tags: unknown;
/** Exact log timestamp — carries time-of-day. */
moodLoggedAt: Date;
/**
* v1.8.5 — structured tags from the taxonomy join. Additive next to
* the flat `tags`: an entry can carry both. Optional so the legacy
* aggregate tests (flat tags only) keep their narrow fixtures.
*/
structuredTags?: StructuredTagRef[];
/** v1.8.5 — free-text note (C1). */
note?: string | null;
/** Mood enum (for the notes timeline label / colour). */
mood?: string;
}
// --- Notes timeline (v1.8.5 C1 — qualitative reflection feed) ---
export interface NoteTimelineEntry {
/** TZ-anchored day key. */
date: string;
/** ISO timestamp of the log. */
loggedAt: string;
score: number;
mood: string | null;
note: string;
/** Flat free-text tags on the entry. */
tags: string[];
/** Structured-tag labels (i18n keys) on the entry. */
structuredTagLabelKeys: string[];
}
/**
* Recent entries that carry a free-text note, newest first. Bounded to
* `limit` so the cached aggregate payload stays small. Entries without a
* note are skipped — the timeline is the qualitative-reflection feed.
*/
export function computeNotesTimeline(
entries: MoodAggregateEntry[],
limit = 20,
): NoteTimelineEntry[] {
return entries
.filter((entry) => typeof entry.note === "string" && entry.note.trim())
.slice()
.reverse() // entries arrive oldest-first; show newest first
.slice(0, limit)
.map((entry) => ({
date: entry.date,
loggedAt: entry.moodLoggedAt.toISOString(),
score: entry.score,
mood: entry.mood ?? null,
note: entry.note!.trim(),
tags: Array.isArray(entry.tags) ? (entry.tags as string[]) : [],
structuredTagLabelKeys: (entry.structuredTags ?? []).map(
(tag) => tag.labelKey,
),
}));
}
/** Cross-metric row shape (WEIGHT / BLOOD_PRESSURE_SYS / PULSE / …). */
@@ -147,6 +235,71 @@ export function computeTagSummary(
}));
}
// --- Structured-tag frequency + per-tag avg score (v1.8.5 taxonomy) ---
export interface StructuredTagRow {
key: string;
categoryKey: string;
labelKey: string;
icon: string | null;
count: number;
avgScore: number;
}
/**
* Frequency + per-tag average mood for the structured taxonomy tags,
* over the same recency window as the flat-tag summary.
*
* Unlike `computeTagSummary` (flat free text), singletons are KEPT — a
* structured tag comes from a curated catalog the user deliberately
* picked, so a single occurrence is signal, not noise. Ranked by
* frequency desc, then label key for a stable order. The category key
* rides along so the UI can group the bars by category with icons.
*/
export function computeStructuredTagSummary(
entries: MoodAggregateEntry[],
now: Date,
windowDays = 90,
): StructuredTagRow[] {
const cutoff = now.getTime() - windowDays * MS_PER_DAY;
const byKey = new Map<
string,
{
categoryKey: string;
labelKey: string;
icon: string | null;
count: number;
scoreSum: number;
}
>();
for (const entry of entries) {
if (entry.moodLoggedAt.getTime() < cutoff) continue;
if (!entry.structuredTags) continue;
for (const tag of entry.structuredTags) {
const current = byKey.get(tag.key) ?? {
categoryKey: tag.categoryKey,
labelKey: tag.labelKey,
icon: tag.icon,
count: 0,
scoreSum: 0,
};
current.count += 1;
current.scoreSum += entry.score;
byKey.set(tag.key, current);
}
}
return Array.from(byKey.entries())
.map(([key, stats]) => ({
key,
categoryKey: stats.categoryKey,
labelKey: stats.labelKey,
icon: stats.icon,
count: stats.count,
avgScore: round(stats.scoreSum / stats.count, 2),
}))
.sort((a, b) => b.count - a.count || a.labelKey.localeCompare(b.labelKey));
}
// --- In-target % over the last 30 daily points (lifted from mood-status) ---
/**
@@ -346,6 +499,10 @@ export interface MoodAggregates {
distribution: DistributionRow[];
weekday: WeekdayRow[];
tags: TagSummaryRow[];
/** v1.8.5 — structured-tag breakdown from the taxonomy join. */
structuredTags: StructuredTagRow[];
/** v1.8.5 — recent notes timeline (qualitative-reflection feed). */
notesTimeline: NoteTimelineEntry[];
correlations: {
sleep: MoodMetricCorrelation;
steps: MoodMetricCorrelation;
@@ -424,6 +581,8 @@ export function computeMoodAggregates(args: {
distribution: computeDistribution(moodDaily),
weekday: computeWeekdayAverages(moodDaily, now),
tags: computeTagSummary(entries, now),
structuredTags: computeStructuredTagSummary(entries, now),
notesTimeline: computeNotesTimeline(entries),
correlations: {
sleep: computeMoodMetricCorrelation(
moodDaily,
@@ -473,9 +632,45 @@ export async function fetchMoodAggregates(
where: { userId, deletedAt: null, moodLoggedAt: { gte: windowCutoff } },
orderBy: { moodLoggedAt: "desc" },
take: 2000,
select: { date: true, score: true, tags: true, moodLoggedAt: true },
select: {
date: true,
score: true,
tags: true,
moodLoggedAt: true,
mood: true,
note: true,
// v1.8.5 — pull the structured-tag links + their catalog rows so
// the breakdown can fold structured tags next to the flat ones.
tagLinks: {
select: {
moodTag: {
select: {
key: true,
labelKey: true,
icon: true,
category: { select: { key: true } },
},
},
},
},
},
})
.then((rows) => rows.reverse());
.then((rows) =>
rows.reverse().map((row) => ({
date: row.date,
score: row.score,
tags: parseTags(row.tags),
moodLoggedAt: row.moodLoggedAt,
mood: row.mood,
note: row.note,
structuredTags: row.tagLinks.map((link) => ({
key: link.moodTag.key,
categoryKey: link.moodTag.category.key,
labelKey: link.moodTag.labelKey,
icon: link.moodTag.icon,
})),
})),
);
const measurements = await prisma.measurement
.findMany({
+73
View File
@@ -0,0 +1,73 @@
import { prisma } from "@/lib/db";
/**
* v1.8.5 — structured-tag link helpers.
*
* Resolve a list of catalog tag keys (`mood_tags.key`) to their ids and
* write the `mood_entry_tag_links` join for a mood entry. The catalog is
* the source of truth: unknown keys are dropped silently so a stale
* client can never mint a link to a tag the deployment doesn't carry.
*/
/**
* Resolve catalog tag keys to ids, dropping unknown / inactive keys.
* Returns the ids in catalog order (deduped).
*/
export async function resolveTagKeysToIds(keys: string[]): Promise<string[]> {
const unique = Array.from(new Set(keys));
if (unique.length === 0) return [];
const rows = await prisma.moodTag.findMany({
where: { key: { in: unique }, isActive: true },
select: { id: true },
});
return rows.map((row) => row.id);
}
/**
* Create the structured-tag links for a freshly-created entry. No-op on
* an empty / all-unknown key set.
*/
export async function createTagLinks(
moodEntryId: string,
keys: string[],
): Promise<void> {
const tagIds = await resolveTagKeysToIds(keys);
if (tagIds.length === 0) return;
await prisma.moodEntryTagLink.createMany({
data: tagIds.map((moodTagId) => ({ moodEntryId, moodTagId })),
skipDuplicates: true,
});
}
/**
* Replace the full structured-tag link set for an entry. `keys` is the
* desired set; the helper deletes links no longer present and inserts
* the new ones, leaving unchanged links in place. Passing an empty array
* clears every link.
*/
export async function replaceTagLinks(
moodEntryId: string,
keys: string[],
): Promise<void> {
const desiredIds = new Set(await resolveTagKeysToIds(keys));
const existing = await prisma.moodEntryTagLink.findMany({
where: { moodEntryId },
select: { moodTagId: true },
});
const existingIds = new Set(existing.map((row) => row.moodTagId));
const toDelete = [...existingIds].filter((id) => !desiredIds.has(id));
const toCreate = [...desiredIds].filter((id) => !existingIds.has(id));
if (toDelete.length > 0) {
await prisma.moodEntryTagLink.deleteMany({
where: { moodEntryId, moodTagId: { in: toDelete } },
});
}
if (toCreate.length > 0) {
await prisma.moodEntryTagLink.createMany({
data: toCreate.map((moodTagId) => ({ moodEntryId, moodTagId })),
skipDuplicates: true,
});
}
}
+113
View File
@@ -0,0 +1,113 @@
/**
* v1.8.5 — default mood-tag taxonomy.
*
* The canonical Category → Tag catalog seeded into `mood_tag_categories`
* + `mood_tags` by migration `0101_v185_mood_tag_taxonomy`. Modelled on
* the standalone mood diary's structured taxonomy but keyed on i18n
* message keys (resolved against all six locales) rather than hard-coded
* labels, so the catalog renders localised everywhere.
*
* The ids are deterministic string literals so the migration seed is
* idempotent (re-running upserts by `key`) and so the catalog rows are
* stable across deployments. Keys are stable machine identifiers; the
* `labelKey` is the i18n key the capture UI + breakdown resolve.
*
* This is purely additive next to the legacy flat `MoodEntry.tags` JSON
* column — the structured taxonomy is a second capture surface, not a
* replacement.
*/
export interface MoodTagSeed {
/** Stable machine key, unique across the catalog. */
key: string;
/** i18n message key `mood.tag.<key>`. */
labelKey: string;
/** Lucide icon name. */
icon: string;
}
export interface MoodTagCategorySeed {
key: string;
/** i18n message key `mood.tagCategory.<key>`. */
labelKey: string;
/** Lucide icon name for the category header. */
icon: string;
tags: MoodTagSeed[];
}
/**
* The seeded taxonomy. Order within the arrays is the `sortOrder` used
* for the catalog rows (category index, tag index within its category).
*/
export const MOOD_TAG_TAXONOMY: MoodTagCategorySeed[] = [
{
key: "feelings",
labelKey: "mood.tagCategory.feelings",
icon: "Heart",
tags: [
{ key: "happy", labelKey: "mood.tag.happy", icon: "Smile" },
{ key: "excited", labelKey: "mood.tag.excited", icon: "Zap" },
{ key: "grateful", labelKey: "mood.tag.grateful", icon: "HandHeart" },
{ key: "relaxed", labelKey: "mood.tag.relaxed", icon: "CloudSun" },
{ key: "content", labelKey: "mood.tag.content", icon: "ThumbsUp" },
{ key: "tired", labelKey: "mood.tag.tired", icon: "Moon" },
{ key: "unsure", labelKey: "mood.tag.unsure", icon: "HelpCircle" },
{ key: "bored", labelKey: "mood.tag.bored", icon: "Meh" },
{ key: "tense", labelKey: "mood.tag.tense", icon: "AlertTriangle" },
{ key: "angry", labelKey: "mood.tag.angry", icon: "Flame" },
{ key: "stressed", labelKey: "mood.tag.stressed", icon: "Brain" },
{ key: "sad", labelKey: "mood.tag.sad", icon: "Frown" },
],
},
{
key: "sleep",
labelKey: "mood.tagCategory.sleep",
icon: "BedDouble",
tags: [
{ key: "slept_well", labelKey: "mood.tag.sleptWell", icon: "Moon" },
{ key: "slept_ok", labelKey: "mood.tag.sleptOk", icon: "CloudMoon" },
{ key: "slept_poorly", labelKey: "mood.tag.sleptPoorly", icon: "MoonStar" },
{ key: "early_night", labelKey: "mood.tag.earlyNight", icon: "Clock" },
],
},
{
key: "health",
labelKey: "mood.tagCategory.health",
icon: "HeartPulse",
tags: [
{ key: "worked_out", labelKey: "mood.tag.workedOut", icon: "Dumbbell" },
{ key: "ate_well", labelKey: "mood.tag.ateWell", icon: "Apple" },
{ key: "hydrated", labelKey: "mood.tag.hydrated", icon: "GlassWater" },
{ key: "walked", labelKey: "mood.tag.walked", icon: "Footprints" },
{ key: "alcohol", labelKey: "mood.tag.alcohol", icon: "Wine" },
],
},
{
key: "social",
labelKey: "mood.tagCategory.social",
icon: "Users",
tags: [
{ key: "family", labelKey: "mood.tag.family", icon: "Home" },
{ key: "friends", labelKey: "mood.tag.friends", icon: "Users" },
{ key: "party", labelKey: "mood.tag.party", icon: "PartyPopper" },
{ key: "alone", labelKey: "mood.tag.alone", icon: "User" },
],
},
{
key: "work",
labelKey: "mood.tagCategory.work",
icon: "Briefcase",
tags: [
{ key: "productive", labelKey: "mood.tag.productive", icon: "CheckCircle" },
{ key: "overtime", labelKey: "mood.tag.overtime", icon: "Clock" },
{ key: "day_off", labelKey: "mood.tag.dayOff", icon: "LogOut" },
{ key: "travel", labelKey: "mood.tag.travel", icon: "Plane" },
{ key: "sick_day", labelKey: "mood.tag.sickDay", icon: "Thermometer" },
],
},
];
/** Flat list of every seeded tag key (for validation / lookups). */
export const MOOD_TAG_KEYS: string[] = MOOD_TAG_TAXONOMY.flatMap((c) =>
c.tags.map((tagSeed) => tagSeed.key),
);
+8
View File
@@ -60,6 +60,14 @@ export const queryKeys = {
* `moodDependentKeys` fan-out below.
*/
moodInsights: () => ["mood-insights"] as const,
/**
* v1.8.5 — structured mood-tag taxonomy catalog (global reference
* data, identical for every user). Read by the mood-logging form's
* tag-category capture surface. Not invalidated on a mood write — the
* catalog only changes on a migration / admin edit, so a long
* `staleTime` is fine.
*/
moodTagCatalog: () => ["mood-tag-catalog"] as const,
/**
* v1.7.0 W6 — unified dashboard first-paint snapshot. One client cell
+46 -1
View File
@@ -1,5 +1,50 @@
import { describe, expect, it } from "vitest";
import { moodLogCredentialsSchema } from "../moodlog";
import {
moodLogCredentialsSchema,
createMoodEntrySchema,
updateMoodEntrySchema,
} from "../moodlog";
describe("createMoodEntrySchema — note + structured tagKeys (v1.8.5)", () => {
const base = { mood: "GUT", moodLoggedAt: "2026-06-01T12:00:00.000Z" };
it("round-trips the note field", () => {
const r = createMoodEntrySchema.safeParse({ ...base, note: "felt great" });
expect(r.success).toBe(true);
if (r.success) expect(r.data.note).toBe("felt great");
});
it("accepts structured tagKeys alongside flat tags", () => {
const r = createMoodEntrySchema.safeParse({
...base,
tags: ["nausea"],
tagKeys: ["happy", "worked_out"],
});
expect(r.success).toBe(true);
if (r.success) {
expect(r.data.tagKeys).toEqual(["happy", "worked_out"]);
expect(r.data.tags).toEqual(["nausea"]);
}
});
it("rejects an over-long note and an over-large tagKeys set", () => {
expect(
createMoodEntrySchema.safeParse({ ...base, note: "x".repeat(501) }).success,
).toBe(false);
expect(
createMoodEntrySchema.safeParse({
...base,
tagKeys: Array.from({ length: 31 }, (_, i) => `t${i}`),
}).success,
).toBe(false);
});
it("allows update to clear tagKeys with null", () => {
const r = updateMoodEntrySchema.safeParse({ tagKeys: null });
expect(r.success).toBe(true);
if (r.success) expect(r.data.tagKeys).toBeNull();
});
});
describe("moodLogCredentialsSchema SSRF guard", () => {
it("accepts a public moodLog URL", () => {
+13
View File
@@ -78,9 +78,19 @@ export function getScoreForMood(mood: string): number {
return MOOD_SCORE_MAP[mood] ?? 3;
}
// v1.8.5 — structured-tag keys picked from the catalog (`mood_tags.key`).
// Additive alongside the flat free-text `tags`: an entry can carry both.
// Bounded so a single create can't fan out an unbounded link set.
const structuredTagKeys = z.array(z.string().max(60)).max(30);
export const createMoodEntrySchema = z.object({
mood: moodLevelEnum,
tags: z.array(z.string().max(50)).max(20).optional(),
// v1.8.5 — structured-tag keys from the taxonomy. Server resolves each
// key to a `MoodTag` row and writes the `MoodEntryTagLink` join;
// unknown keys are dropped silently (the catalog is the source of
// truth, a stale client can't mint a tag).
tagKeys: structuredTagKeys.optional(),
// v1.4.30 H-5 — first-class free-text note. Replaces the
// `tags: ["note:<text>"]` workaround. Capped at 500 chars so the
// Coach evidence shelf renders cleanly without truncating chips.
@@ -92,6 +102,9 @@ export const createMoodEntrySchema = z.object({
export const updateMoodEntrySchema = z.object({
mood: moodLevelEnum.optional(),
tags: z.array(z.string().max(50)).max(20).nullable().optional(),
// v1.8.5 — full replacement of the structured-tag set when present.
// `null` clears every link; omit to leave links untouched.
tagKeys: structuredTagKeys.nullable().optional(),
note: z.string().max(500).nullable().optional(),
moodLoggedAt: z.iso
.datetime({ offset: true })