From 39840a20d7fd1ce117e450e72aaa19dc4d8f944b Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Sun, 15 Nov 2026 13:01:57 -0800 Subject: [PATCH] docs: goal tiers contract Co-Authored-By: Claude Sonnet 5.5 --- docs/ARCHITECTURE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1970ec8..11a2f48 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -81,3 +81,14 @@ Amounts must be >= Settings::effectiveMin(). action_id (for `reward`: applies when that reward triggered; a reward definition wins over an amount definition), title (admin label), visual_id + visual_type (`image` | `video` | '' none), sound_id (audio attachment, 0 none), volume 0-100, duration_ms (how long an image/GIF stays; videos play to the end, capped), message (template with {name} {amount} {reward}; '' = default text), enabled, sort, created_at. + +## Goal tiers (milestones) — contract (Installer DB_VERSION 4) +A goal may have ordered TIERS; each is a cumulative target with an item/unlock (e.g. $100 "Giveaway", $250 "New microphone", $500 "24-hour stream"). +- `sg_goal_tiers`: id, goal_id, target_minor (cumulative raised total needed), title VARCHAR(120) (the item/unlock), description VARCHAR(255), reached_at DATETIME NULL, + reached_donation_id BIGINT UNSIGNED NULL, created_at; UNIQUE(goal_id, target_minor). Tier order = target_minor ascending. +- A goal WITH tiers keeps `sg_goals.target_minor` equal to its HIGHEST tier target (maintained automatically when tiers change; the goal form shows the target as derived/read-only). So "end at target" closes the goal when the FINAL tier is reached, and everything that reads goal target keeps working. +- Raised total for tiers uses the same basis as the goal (`GoalRepository::raised_minor`, base vs total per counts_fees). +- Reaching a tier: after a donation is completed (same finalize path as rules/actions, BEFORE the close-at-target check, never throwing, idempotent): for every tier of the goal with reached_at IS NULL and target_minor <= raised, set reached_at=NOW and reached_donation_id=that donation with `UPDATE ... WHERE id=? AND reached_at IS NULL` (a big donation can unlock several tiers at once; all get its id). +- "Current tier" = the first tier (by target) with reached_at IS NULL. Goal bar progress for a tiered goal = (raised - floor) / (target - floor) clamped 0..1, where floor = previous tier's target (0 for the first); the cumulative raised and the current tier target are still displayed. +- Reached tiers: title/description editable, target locked; a new tier's target must be above the goal's current raised total and unique. +- Overlay `goal` payload for a tiered goal adds `tiers: {count, index (1-based current), current:{title,description,target_minor,target_display,floor_minor}|null, all_reached}`; untiered goals are unchanged. Alert payloads gain `tiers: [{title}]` = tiers whose reached_donation_id is that donation, shown as a "TIER UNLOCKED: title" pill.