mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-19 00:12:18 +00:00
feat(onboarding): store what a record needs, and map it to modules
The setup questionnaire the design spec asks for needs somewhere to put its answers. `OnboardingRecord` is that place: one row per RECORD rather than per person, so a guardian running a managed profile's setup writes the child's row and not their own, and the three JSON columns hold the answers, the nine ordered steps with their status, and the one task the flow ends on. Nothing here is encrypted, and the schema comment says why: the columns hold closed enum vocabularies, not free text, which is the same class of value as the module map and the goal slugs sitting in plaintext beside them. The needs to modules map lives next to the module keys rather than in the flow, because a module renamed or retired has to break the map at compile time rather than leave a chip that quietly changes nothing. The derivation is total — every directly-owned key gets an explicit value — and the merge beside it is one-directional: what the answers name is switched on, what they do not name is switched off only where the record does not already carry a deliberate on. The two delegated keys are absent by construction: `cycle` is reported separately because its real column is on the cycle profile, and the Coach is not offered by this flow at all. Readers are fail-soft. They sit on the payload that rides every app boot, and a value written by a release that named an area this one retired must not take the shell down with it. Nothing is retired: the four-step wizard, its goal slugs and the one-time tile seed keep working and keep their meaning until the new surface replaces them. The two states are disjoint — the slugs decide tile order, these answers decide which modules are on, and neither reads the other.
This commit is contained in:
1 parent
036720bcfb
commit
cc98c56172
10 files changed
+1514
No files matched your search
@@ -0,0 +1,215 @@
|
||||
/**
|
||||
* v1.39 (C1) — the needs → modules mapping, and the merge that protects a
|
||||
* decision somebody already made.
|
||||
*
|
||||
* The mapping is the one piece of the flow with a consequence that outlives
|
||||
* the screens: a module switched off here disappears from the navigation until
|
||||
* somebody finds it again in Settings. So the properties below are stated as
|
||||
* properties over the whole registry rather than as a table of examples — a
|
||||
* module key added to `MODULE_KEYS` next year is covered by them on the day it
|
||||
* lands, and an area that stops naming anything fails here rather than
|
||||
* shipping as a chip with no effect.
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
deriveOnboardingModuleDefaults,
|
||||
isModuleKey,
|
||||
mergeDerivedModulePreferences,
|
||||
MODULE_REGISTRY,
|
||||
ONBOARDING_ALWAYS_ON_MODULES,
|
||||
ONBOARDING_AREA_KEYS,
|
||||
ONBOARDING_AREA_MODULES,
|
||||
OWNED_MODULE_KEYS,
|
||||
type OnboardingModuleNeeds,
|
||||
} from "../registry";
|
||||
|
||||
function needs(
|
||||
overrides: Partial<OnboardingModuleNeeds> = {},
|
||||
): OnboardingModuleNeeds {
|
||||
return {
|
||||
recordTarget: "me",
|
||||
areas: [],
|
||||
medication: "no",
|
||||
visit: "no",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("the area → module map", () => {
|
||||
it("gives every area at least one module", () => {
|
||||
expect(ONBOARDING_AREA_KEYS.length).toBe(9);
|
||||
for (const area of ONBOARDING_AREA_KEYS) {
|
||||
expect(
|
||||
ONBOARDING_AREA_MODULES[area]?.length ?? 0,
|
||||
`area \`${area}\` names no module, so ticking it changes nothing`,
|
||||
).toBeGreaterThan(0);
|
||||
}
|
||||
});
|
||||
|
||||
it("names only real module keys", () => {
|
||||
for (const area of ONBOARDING_AREA_KEYS) {
|
||||
for (const key of ONBOARDING_AREA_MODULES[area]) {
|
||||
expect(isModuleKey(key), `\`${key}\` is not a module key`).toBe(true);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("never names the Coach, which the flow deliberately does not offer", () => {
|
||||
const named = ONBOARDING_AREA_KEYS.flatMap(
|
||||
(area) => ONBOARDING_AREA_MODULES[area],
|
||||
);
|
||||
expect(named).not.toContain("coach");
|
||||
});
|
||||
});
|
||||
|
||||
describe("deriveOnboardingModuleDefaults", () => {
|
||||
it("answers for every directly-owned module and for none of the delegated ones", () => {
|
||||
const derived = deriveOnboardingModuleDefaults(needs());
|
||||
expect(Object.keys(derived.preferences).sort()).toEqual(
|
||||
[...OWNED_MODULE_KEYS].sort(),
|
||||
);
|
||||
expect(derived.preferences).not.toHaveProperty("cycle");
|
||||
expect(derived.preferences).not.toHaveProperty("coach");
|
||||
for (const key of OWNED_MODULE_KEYS) {
|
||||
expect(MODULE_REGISTRY[key].delegatesTo).toBeUndefined();
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps the always-on modules on however the questions are answered", () => {
|
||||
const answers: OnboardingModuleNeeds[] = [
|
||||
needs(),
|
||||
needs({ areas: [...ONBOARDING_AREA_KEYS], medication: "yes" }),
|
||||
needs({ recordTarget: "someone-else", visit: "within-a-month" }),
|
||||
needs({ recordTarget: "both", medication: "sometimes", visit: "later" }),
|
||||
];
|
||||
for (const answer of answers) {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(answer);
|
||||
for (const key of ONBOARDING_ALWAYS_ON_MODULES) {
|
||||
expect(
|
||||
preferences[key as keyof typeof preferences],
|
||||
`always-on module \`${key}\` was derived off`,
|
||||
).toBe(true);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("switches on exactly what the chosen areas name", () => {
|
||||
const { preferences, cycleTracking } = deriveOnboardingModuleDefaults(
|
||||
needs({ areas: ["glucose", "sleep", "mood"] }),
|
||||
);
|
||||
expect(preferences.glucose).toBe(true);
|
||||
expect(preferences.sleep).toBe(true);
|
||||
expect(preferences.recovery).toBe(true);
|
||||
expect(preferences.mood).toBe(true);
|
||||
expect(preferences.mentalHealth).toBe(true);
|
||||
expect(preferences.labs).toBe(false);
|
||||
expect(preferences.workouts).toBe(false);
|
||||
expect(preferences.illness).toBe(false);
|
||||
expect(cycleTracking).toBe(false);
|
||||
});
|
||||
|
||||
it("reports the cycle area separately, because the module blob does not own it", () => {
|
||||
expect(deriveOnboardingModuleDefaults(needs({ areas: ["cycle"] }))).toEqual(
|
||||
expect.objectContaining({ cycleTracking: true }),
|
||||
);
|
||||
expect(deriveOnboardingModuleDefaults(needs()).cycleTracking).toBe(false);
|
||||
});
|
||||
|
||||
it("follows the medication answer", () => {
|
||||
for (const answer of ["yes", "sometimes"] as const) {
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ medication: answer }))
|
||||
.preferences.medications,
|
||||
).toBe(true);
|
||||
}
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ medication: "no" })).preferences
|
||||
.medications,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("switches the doctor report on for any visit that is actually coming", () => {
|
||||
for (const visit of ["within-a-month", "later"] as const) {
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ visit })).preferences
|
||||
.doctorReport,
|
||||
).toBe(true);
|
||||
}
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ visit: "no" })).preferences
|
||||
.doctorReport,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("switches the immunization log on for a record somebody else runs", () => {
|
||||
for (const recordTarget of ["someone-else", "both"] as const) {
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ recordTarget })).preferences
|
||||
.vaccinations,
|
||||
).toBe(true);
|
||||
}
|
||||
expect(
|
||||
deriveOnboardingModuleDefaults(needs({ recordTarget: "me" })).preferences
|
||||
.vaccinations,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("leaves the opt-in surfaces off unless something asks for them", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(
|
||||
needs({ areas: [...ONBOARDING_AREA_KEYS] }),
|
||||
);
|
||||
expect(preferences.mcp).toBe(false);
|
||||
expect(preferences.nutrients).toBe(false);
|
||||
expect(preferences.environment).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("mergeDerivedModulePreferences", () => {
|
||||
it("never turns off a module the person switched on by hand", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(needs());
|
||||
expect(preferences.mcp).toBe(false);
|
||||
expect(preferences.labs).toBe(false);
|
||||
|
||||
const merged = mergeDerivedModulePreferences(
|
||||
{ mcp: true, labs: true },
|
||||
preferences,
|
||||
);
|
||||
expect(merged.mcp).toBe(true);
|
||||
expect(merged.labs).toBe(true);
|
||||
});
|
||||
|
||||
it("does turn off a module the record only had by default", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(needs());
|
||||
const merged = mergeDerivedModulePreferences({}, preferences);
|
||||
expect(merged.labs).toBe(false);
|
||||
expect(merged.workouts).toBe(false);
|
||||
});
|
||||
|
||||
it("switches on what the answers named even where the record had it off", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(
|
||||
needs({ areas: ["labs"] }),
|
||||
);
|
||||
const merged = mergeDerivedModulePreferences({ labs: false }, preferences);
|
||||
expect(merged.labs).toBe(true);
|
||||
});
|
||||
|
||||
it("drops a stored key that is not a module", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(needs());
|
||||
const merged = mergeDerivedModulePreferences(
|
||||
{ weight: false, nonsense: true },
|
||||
preferences,
|
||||
);
|
||||
expect(merged).not.toHaveProperty("weight");
|
||||
expect(merged).not.toHaveProperty("nonsense");
|
||||
});
|
||||
|
||||
it("leaves the two delegated keys alone in both directions", () => {
|
||||
const { preferences } = deriveOnboardingModuleDefaults(
|
||||
needs({ areas: ["cycle"] }),
|
||||
);
|
||||
const merged = mergeDerivedModulePreferences({}, preferences);
|
||||
expect(merged).not.toHaveProperty("cycle");
|
||||
expect(merged).not.toHaveProperty("coach");
|
||||
});
|
||||
});
|
||||
@@ -423,3 +423,189 @@ export function moduleDelegatesTo(
|
||||
export function isOptInModule(key: ModuleKey): boolean {
|
||||
return MODULE_REGISTRY[key].optIn === true;
|
||||
}
|
||||
|
||||
/* ─── Needs-based onboarding: the areas a person names → the modules ───────── */
|
||||
|
||||
/**
|
||||
* v1.39 (C1) — the nine areas the needs questionnaire offers (design spec
|
||||
* §"The questions", Q2), as stable slugs.
|
||||
*
|
||||
* They live here rather than in the flow because the answer only means
|
||||
* something as a set of modules, and the mapping below is what gives it that
|
||||
* meaning. Putting the map next to `MODULE_KEYS` is what keeps a module key
|
||||
* renamed or retired from leaving a dangling area behind: the record type
|
||||
* makes it a compile error rather than a silently empty selection.
|
||||
*
|
||||
* All nine stay visible, cycle included — it is one chip, and hiding it behind
|
||||
* recorded sex would make the flow guess at something the person is being
|
||||
* asked about anyway.
|
||||
*/
|
||||
export const ONBOARDING_AREA_KEYS = [
|
||||
"blood-pressure",
|
||||
"weight-body",
|
||||
"glucose",
|
||||
"sleep",
|
||||
"mood",
|
||||
"cycle",
|
||||
"activity",
|
||||
"labs",
|
||||
"illness",
|
||||
] as const;
|
||||
|
||||
export type OnboardingAreaKey = (typeof ONBOARDING_AREA_KEYS)[number];
|
||||
|
||||
/**
|
||||
* The area → module map. Every area names at least one module; blood pressure
|
||||
* and weight name only `insights`, because the readings themselves are CORE
|
||||
* (weight / blood pressure / pulse have no key and can never be switched off)
|
||||
* and the narrative layer is the only thing an answer can decide there.
|
||||
*
|
||||
* `cycle` is in the map and is NOT written through `modulePreferencesJson`:
|
||||
* that key delegates to `CycleProfile.cycleTrackingEnabled`, so the derivation
|
||||
* reports it separately (see {@link DerivedModuleDefaults.cycleTracking}) and
|
||||
* the caller writes the real column. `coach` appears nowhere: the flow never
|
||||
* talks to an AI provider, and turning the Coach on is a Settings decision
|
||||
* with a cost attached to it.
|
||||
*/
|
||||
export const ONBOARDING_AREA_MODULES: Readonly<
|
||||
Record<OnboardingAreaKey, readonly ModuleKey[]>
|
||||
> = Object.freeze({
|
||||
"blood-pressure": ["insights"],
|
||||
"weight-body": ["insights"],
|
||||
glucose: ["glucose", "insights"],
|
||||
sleep: ["sleep", "recovery"],
|
||||
// "Mood and mental wellbeing" is one chip over two modules: the daily mood
|
||||
// entry and the WHO-5 / PHQ-9 / GAD-7 check-in live on the same surface as
|
||||
// far as the person answering is concerned.
|
||||
mood: ["mood", "mentalHealth"],
|
||||
cycle: ["cycle"],
|
||||
activity: ["workouts"],
|
||||
labs: ["labs"],
|
||||
illness: ["illness"],
|
||||
});
|
||||
|
||||
/**
|
||||
* Modules that stay on whatever the answers say (design spec §"Needs → modules
|
||||
* → first result"): the measurement engine is CORE and has no key, and these
|
||||
* three are the surfaces a record is unusable without — the narrative layer,
|
||||
* the badges, and the document vault.
|
||||
*/
|
||||
export const ONBOARDING_ALWAYS_ON_MODULES: readonly ModuleKey[] = [
|
||||
"insights",
|
||||
"achievements",
|
||||
"inboundDocuments",
|
||||
];
|
||||
|
||||
/**
|
||||
* The answers the module derivation actually reads. The flow stores more than
|
||||
* this (the sources, the units); nothing else changes which modules are on.
|
||||
*
|
||||
* The literal unions are written here rather than imported so this file keeps
|
||||
* depending on nothing. `src/lib/onboarding/needs.ts` declares the same
|
||||
* vocabulary with `satisfies`, and the derivation call site is typed against
|
||||
* this interface — a value that drifts apart fails to compile there.
|
||||
*/
|
||||
export interface OnboardingModuleNeeds {
|
||||
recordTarget: "me" | "someone-else" | "both";
|
||||
areas: readonly OnboardingAreaKey[];
|
||||
medication: "yes" | "no" | "sometimes";
|
||||
visit: "within-a-month" | "later" | "no";
|
||||
}
|
||||
|
||||
/** A toggleable module whose state `modulePreferencesJson` really owns. */
|
||||
export type OwnedModuleKey = Exclude<ModuleKey, ModuleDelegation>;
|
||||
|
||||
/** Toggleable modules minus the two delegated keys, in registry order. */
|
||||
export const OWNED_MODULE_KEYS: readonly OwnedModuleKey[] = MODULE_KEYS.filter(
|
||||
(key): key is OwnedModuleKey =>
|
||||
MODULE_REGISTRY[key].delegatesTo === undefined,
|
||||
);
|
||||
|
||||
export interface DerivedModuleDefaults {
|
||||
/**
|
||||
* An explicit value for every directly-owned module: `true` for what the
|
||||
* answers named, `false` for the rest. Explicit `false` rather than absence
|
||||
* is the "ordering versus removal" decision from the design spec — the
|
||||
* stored map is a disabled allowlist, so absence would mean ON.
|
||||
*/
|
||||
preferences: Record<OwnedModuleKey, boolean>;
|
||||
/**
|
||||
* Whether the answers asked for cycle tracking. Only ever `true` here: the
|
||||
* gate derives an unanswered cycle from recorded sex, and an area the person
|
||||
* did not tick is not a statement that they want it switched off. The caller
|
||||
* writes `CycleProfile.cycleTrackingEnabled` when this is true and leaves
|
||||
* the column alone when it is not.
|
||||
*/
|
||||
cycleTracking: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Turn the needs answers into the module map the record starts from.
|
||||
*
|
||||
* Pure and total: every directly-owned key gets a value, so the caller never
|
||||
* has to reason about which keys the answers happened to mention. It says
|
||||
* nothing about what the record already holds — merging is
|
||||
* {@link mergeDerivedModulePreferences}, deliberately a second step, because
|
||||
* "what the answers imply" and "what this person already decided by hand" are
|
||||
* different questions and only one of them may be overwritten.
|
||||
*/
|
||||
export function deriveOnboardingModuleDefaults(
|
||||
needs: OnboardingModuleNeeds,
|
||||
): DerivedModuleDefaults {
|
||||
const on = new Set<ModuleKey>(ONBOARDING_ALWAYS_ON_MODULES);
|
||||
|
||||
for (const area of needs.areas) {
|
||||
for (const key of ONBOARDING_AREA_MODULES[area] ?? []) on.add(key);
|
||||
}
|
||||
if (needs.medication === "yes" || needs.medication === "sometimes") {
|
||||
on.add("medications");
|
||||
}
|
||||
// A visit that is coming at all is what the doctor report is for; "no" is
|
||||
// the only answer that leaves the export surface off.
|
||||
if (needs.visit === "within-a-month" || needs.visit === "later") {
|
||||
on.add("doctorReport");
|
||||
}
|
||||
// A record somebody else runs is usually a child's or a parent's, and the
|
||||
// immunization log is the part of it that matters most there.
|
||||
if (needs.recordTarget === "someone-else" || needs.recordTarget === "both") {
|
||||
on.add("vaccinations");
|
||||
}
|
||||
|
||||
const preferences = {} as Record<OwnedModuleKey, boolean>;
|
||||
for (const key of OWNED_MODULE_KEYS) preferences[key] = on.has(key);
|
||||
|
||||
return { preferences, cycleTracking: on.has("cycle") };
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge a derived map into the one the record already holds, without ever
|
||||
* retracting a decision the person made by hand.
|
||||
*
|
||||
* The rule is one-directional: a derived `true` always lands, a derived
|
||||
* `false` lands only where the stored map does not already carry an explicit
|
||||
* `true`. Someone who switched the MCP endpoint on, then ran the flow again
|
||||
* and did not tick anything that implies it, keeps it on — the questionnaire
|
||||
* orders a record, it does not undo it.
|
||||
*
|
||||
* Keys the stored map carries that are not module keys are dropped; the caller
|
||||
* is expected to have normalised it (`normalisePrefs`), and this is the second
|
||||
* belt on the same trousers rather than a place to be clever.
|
||||
*/
|
||||
export function mergeDerivedModulePreferences(
|
||||
existing: Readonly<Record<string, boolean>>,
|
||||
derived: Readonly<Record<OwnedModuleKey, boolean>>,
|
||||
): Record<string, boolean> {
|
||||
const merged: Record<string, boolean> = {};
|
||||
for (const [key, value] of Object.entries(existing)) {
|
||||
if (isModuleKey(key)) merged[key] = value;
|
||||
}
|
||||
for (const [key, value] of Object.entries(derived)) {
|
||||
if (value) {
|
||||
merged[key] = true;
|
||||
continue;
|
||||
}
|
||||
if (merged[key] === true) continue; // switched on by hand — never retracted
|
||||
merged[key] = false;
|
||||
}
|
||||
return merged;
|
||||
}
|
||||
Reference in new issue
Block a user