feat(active): add the active beers page, run metadata and tap numbers

Adds the pages that were missing: an "Active Beers" view of what is in the
fermenter right now, and the per-run metadata (canonical name, tap number,
original gravity, brew notes) that could not be derived from the readings.

Why the metadata is needed
--------------------------
The `beer_data` collection stores a beer name on *each reading*, and that
name drifts within a run - run 4 was entered as "Necatron-Christmas Beer",
then "Nocturna the Christmas beer", then "Nocturna Christmas beer". There was
nowhere to record a tap number, a confirmed original gravity, or a note about
the brew.

The new `beer_runs` collection holds one document per run with exactly those
details. It starts empty; `scripts/backfill_run_metadata.py` populates it
from the existing readings. The script is idempotent, only ever inserts into
`beer_runs`, never touches `beer_data`, and never overwrites a name you have
already set by hand.

The active beers page
---------------------
A card per brew that is still in the fermenter, showing the tap number, the
current gravity, the projected alcohol, how many days it has been brewing, a
sparkline of the gravity so far, and the latest comment on a reading.

A run with only one reading and no recorded original gravity has no reliable
estimate, so the alcohol figure shows a dash rather than a misleading number
- record the OG or take a second reading and it appears. The same applies to
the existing reads, where the legacy app's assumed OG of 1012 produced
*negative* alcohol for a perfectly normal OG.

Also adds the history page: alcohol by brew, brews per month, every run in a
table, a comparison of the standard ABV formula against the legacy one, and
a list of readings that fall outside the plausible hydrometer range.

Changes to the existing pages
-----------------------------
- The brew-process page and the run detail page now show the canonical run
  name and the latest comment, and the run detail page lets you edit the
  metadata inline.
- Gravity is displayed as a decimal reading (1.039) with the point scale
  beneath it (39 points), which is the way a brewer reads it. Labelling the
  stored `1039` as "1039 points" would have been wrong.
- A run's display name now prefers the name on its *final* reading - the one
  written when the brew was finished, so the name the operator settled on -
  falling back to the most-used name.
- `upsert_run_metadata` now clears a field when it is passed as `None`, so a
  name or tap number can be deleted. `upsert_run_metadata_partial` is the
  non-clearing variant, used by the backfill.

Bugs found and fixed along the way
----------------------------------
- The chart script was included both in the base template and again by each
  page, so every chart was drawn twice. A test now asserts it is loaded
  exactly once per page.
- The chart library was never referenced by the base template, so all charts
  were silently dead. That was fixed in the previous PR.

Tests
-----
91 (up from 74). New coverage: the active page contents, the tap number, the
projected alcohol, the "needs 2nd reading" case, metadata saving and
clearing, the stored name overriding the drifting reading name, the next free
tap number, the partial-update semantics, the history page, the outlier
list, and the point-scale formatting.

Data safety
-----------
`beer_data` is untouched by this change. The backfill script only inserts into
`beer_runs` and skips any run whose name has already been set by hand.
This commit is contained in:
2026-11-09 12:35:50 +10:00
parent 081014b8dc
commit 1fa9f1dcbe
20 changed files with 1535 additions and 146 deletions
+131
View File
@@ -0,0 +1,131 @@
{% extends 'base.html' %}
{% block title %}Active Beers — Brew Log{% endblock %}
{% block content %}
<div class="page__head">
<div>
<h1 class="page__title">Active Beers</h1>
<p class="page__sub">Everything currently in the fermenter, with its tap and projected strength.</p>
</div>
<div class="btn-row">
<a class="btn btn--ghost btn--sm" href="{{ url_for('brews.index') }}">Record a reading</a>
<a class="btn btn--ghost btn--sm" href="{{ url_for('analysis.history') }}">History</a>
</div>
</div>
<div class="grid grid--3" style="margin-bottom:1.25rem">
<div class="stat">
<div class="stat__label">Active brews</div>
<div class="stat__value">{{ totals.count }}</div>
<div class="stat__meta">in the fermenter now</div>
</div>
<div class="stat">
<div class="stat__label">Average age</div>
<div class="stat__value">{{ totals.avg_days }}</div>
<div class="stat__meta">day{{ '' if totals.avg_days == '1' else 's' }} since first reading</div>
</div>
<div class="stat">
<div class="stat__label">Longest running</div>
<div class="stat__value">{{ totals.longest_days if totals.longest_days is not none else '—' }}</div>
<div class="stat__meta">day{{ '' if totals.longest_days == 1 else 's' }} in the fermenter</div>
</div>
</div>
{% if cards %}
<div class="grid grid--cards">
{% for run in cards %}
<article class="brew-card">
<div class="brew-card__head">
<div>
<h2 class="brew-card__name">
<a href="{{ url_for('brews.run_detail', run_id=run.beer_run_id) }}">{{ run.canonical_name }}</a>
</h2>
<div class="brew-card__meta">
Run {{ run.beer_run_id }}
{% if run.first_date %} &middot; since {{ run.first_date }}{% endif %}
{% if run.reading_count == 1 %} &middot; 1 reading{% else %} &middot; {{ run.reading_count }} readings{% endif %}
</div>
</div>
{% if run.tap_number is not none %}
<span class="chip chip--tap">Tap {{ run.tap_number }}</span>
{% else %}
<span class="chip chip--active">Active</span>
{% endif %}
</div>
<div class="brew-card__stats">
<div class="brew-card__stat">
<div class="stat__label">Gravity</div>
<div class="stat__value">
{% if run.min_sg is not none %}{{ run.min_sg_decimal }}{% else %}—{% endif %}
</div>
{% if run.min_sg is not none %}
<div class="stat__meta">{{ run.min_sg_point_scale }} points</div>
{% endif %}
</div>
<div class="brew-card__stat">
<div class="stat__label">Est. ABV</div>
<div class="stat__value">
{% if run.projected_abv is not none %}{{ '%.2f' % run.projected_abv }}%{% else %}—{% endif %}
</div>
<div class="stat__meta">
{% if run.projected_abv is not none %}projected{% else %}needs 2nd reading{% endif %}
</div>
</div>
<div class="brew-card__stat">
<div class="stat__label">Days</div>
<div class="stat__value">
{% if run.days_in_fermenter is not none %}{{ run.days_in_fermenter }}{% else %}—{% endif %}
</div>
<div class="stat__meta">day{{ '' if run.days_in_fermenter == 1 else 's' }} brewing</div>
</div>
</div>
{% if run.readings | length > 1 %}
<div class="brew-card__spark">
<canvas class="sparkline"
data-labels='{{ run.readings | map(attribute="date") | list | tojson }}'
data-values='{{ run.readings | map(attribute="sg") | list | tojson }}'></canvas>
</div>
{% else %}
<div class="brew-card__spark brew-card__spark--empty faint tiny">
One reading so far — the trend appears after the next one.
</div>
{% endif %}
{% if run.last_comment %}
<div class="small muted">
<strong class="faint tiny">Latest:</strong> {{ run.last_comment }}
</div>
{% endif %}
<div class="btn-row">
<a class="btn btn--ghost btn--sm"
href="{{ url_for('brews.run_detail', run_id=run.beer_run_id) }}">Open run</a>
<a class="btn btn--sm" href="{{ url_for('brews.index') }}">Add reading</a>
</div>
</article>
{% endfor %}
{# A tile that fills the last slot and gives the page its missing
affordance: there is currently no way to start a brew from here. #}
<a class="brew-card brew-card--new" href="{{ url_for('brews.index') }}">
<span class="brew-card__new-mark" aria-hidden="true">+</span>
<span class="brew-card__new-text">
<strong>Start a new beer</strong>
<span class="faint tiny">Record its first reading</span>
</span>
</a>
</div>
{% else %}
<div class="card">
<div class="empty">
<img class="empty__icon" src="{{ url_for('static', filename='img/logo.svg') }}" alt="" width="40" height="40">
<p><strong>Nothing in the fermenter.</strong></p>
<p class="small">Start a run by recording its first reading on the
<a href="{{ url_for('brews.index') }}">brew process page</a>.</p>
</div>
</div>
{% endif %}
{% endblock %}
+7 -1
View File
@@ -19,11 +19,15 @@
<nav class="nav" aria-label="Main">
<a class="nav__link {% if current_path == '/brews' %}is-active{% endif %}"
href="{{ url_for('brews.index') }}">Brew Process</a>
<a class="nav__link {% if current_path == '/active' %}is-active{% endif %}"
href="{{ url_for('analysis.active') }}">Active Beers</a>
<a class="nav__link {% if current_path == '/history' %}is-active{% endif %}"
href="{{ url_for('analysis.history') }}">History</a>
</nav>
<form method="post" action="{{ url_for('auth.logout') }}" class="topbar__logout">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<span class="topbar__user">{{ session.get('username', '') }}</span>
<span class="topbar__user" title="Signed in as {{ session.get('username', '') }}">{{ session.get('username', '') }}</span>
<button class="btn btn--ghost btn--sm" type="submit">Sign out</button>
</form>
</div>
@@ -44,7 +48,9 @@
{% block content %}{% endblock %}
</main>
<script src="{{ url_for('static', filename='js/chart.umd.js') }}"></script>
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
<script src="{{ url_for('static', filename='js/charts.js') }}"></script>
{% block scripts %}{% endblock %}
</body>
</html>
+3 -3
View File
@@ -93,15 +93,15 @@
<td>{{ run.canonical_name }}</td>
<td class="num">
{% if run.min_sg is not none %}
<span class="mono strong">{{ run.min_sg }}</span>
<div class="faint tiny">{{ run.min_sg_decimal }}</div>
<span class="mono strong">{{ run.min_sg_decimal }}</span>
<div class="faint tiny">{{ run.min_sg_point_scale }} pts</div>
{% else %}—{% endif %}
</td>
<td class="num">
{% if run.projected_abv is not none %}
{{ '%.2f' % run.projected_abv }}%
{% else %}
<span class="faint" title="Record the original gravity for this run to get an estimate">—</span>
<span class="faint" title="Record another reading, or set the original gravity, to get an estimate">—</span>
{% endif %}
</td>
<td class="comment">
+207
View File
@@ -0,0 +1,207 @@
{% extends 'base.html' %}
{% block title %}History — Brew Log{% endblock %}
{% block content %}
<div class="page__head">
<div>
<h1 class="page__title">History</h1>
<p class="page__sub">How every brew has gone, and what it turned out like.</p>
</div>
<div class="btn-row">
<a class="btn btn--ghost btn--sm" href="{{ url_for('analysis.active') }}">Active beers</a>
<a class="btn btn--ghost btn--sm" href="{{ url_for('brews.index') }}">Brew process</a>
</div>
</div>
<div class="grid grid--4" style="margin-bottom:1.25rem">
<div class="stat">
<div class="stat__label">Total brews</div>
<div class="stat__value">{{ stats.total_runs }}</div>
<div class="stat__meta">{{ stats.completed }} finished &middot; {{ stats.active }} active</div>
</div>
<div class="stat">
<div class="stat__label">Average ABV</div>
<div class="stat__value">{{ '%.2f' % stats.avg_abv }}%</div>
<div class="stat__meta">across finished brews</div>
</div>
<div class="stat">
<div class="stat__label">Strongest</div>
<div class="stat__value">
{% if stats.best %}{{ '%.2f' % stats.best.abv }}%{% else %}—{% endif %}
</div>
<div class="stat__meta">
{% if stats.best %}{{ stats.best.name }}{% else %}—{% endif %}
</div>
</div>
<div class="stat">
<div class="stat__label">Lightest</div>
<div class="stat__value">
{% if stats.worst %}{{ '%.2f' % stats.worst.abv }}%{% else %}—{% endif %}
</div>
<div class="stat__meta">
{% if stats.worst %}{{ stats.worst.name }}{% else %}—{% endif %}
</div>
</div>
</div>
<div class="grid grid--2" style="margin-bottom:1.25rem">
<section class="card">
<div class="card__head">
<h2 class="card__title">Alcohol by brew</h2>
<span class="card__hint">Standard formula (OG − FG) × 131.25</span>
</div>
<div class="card__body">
<canvas id="abv-chart" height="120"></canvas>
</div>
</section>
<section class="card">
<div class="card__head">
<h2 class="card__title">Brews over time</h2>
<span class="card__hint">Runs started per month</span>
</div>
<div class="card__body">
<canvas id="months-chart" height="120"></canvas>
</div>
</section>
</div>
{% if outliers %}
<section class="card" style="margin-bottom:1.25rem">
<div class="card__head">
<h2 class="card__title">Readings worth a second look</h2>
<span class="card__hint">{{ outliers | length }} outside the usual hydrometer range</span>
</div>
<div class="card__body card__body--flush">
<div class="table-wrap">
<table class="data">
<thead>
<tr>
<th>Run</th>
<th>Name</th>
<th>Date</th>
<th class="num">Reading</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
{% for row in outliers %}
<tr>
<td class="mono">{{ row.beer_run_id }}</td>
<td>{{ row.name }}</td>
<td class="mono nowrap">{{ row.date or '—' }}</td>
<td class="num"><span class="chip chip--warn">{{ row.sg }}</span></td>
<td class="comment">{{ row.comment or '—' }}</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
</div>
</section>
{% endif %}
<section class="card" style="margin-bottom:1.25rem">
<div class="card__head">
<h2 class="card__title">Every brew</h2>
<span class="card__hint">{{ summaries | length }} runs</span>
</div>
<div class="card__body card__body--flush">
<div class="table-wrap">
<table class="data">
<thead>
<tr>
<th>Run</th>
<th>Name</th>
<th>Status</th>
<th class="num">OG</th>
<th class="num">FG</th>
<th class="num">Drop</th>
<th class="num">ABV</th>
<th class="num">Legacy</th>
<th>Finished</th>
<th>Comment</th>
<th></th>
</tr>
</thead>
<tbody>
{% for run in summaries %}
<tr>
<td class="mono">{{ run.beer_run_id }}</td>
<td>{{ run.canonical_name }}</td>
<td>
{% if run.active %}
<span class="chip chip--active">Active</span>
{% else %}
<span class="chip chip--done">Finished</span>
{% endif %}
</td>
<td class="num">{{ run.og_points or '—' }}</td>
<td class="num">{{ run.fg_points or '—' }}</td>
<td class="num">{{ run.drop_points if run.drop_points is not none else '—' }}</td>
<td class="num">
{% if run.abv is not none %}<strong>{{ '%.2f' % run.abv }}%</strong>
{% elif run.projected_abv is not none %}{{ '%.2f' % run.projected_abv }}%*
{% else %}—{% endif %}
</td>
<td class="num muted">{{ run.legacy_abv if run.legacy_abv is not none else '—' }}</td>
<td class="mono nowrap">{{ run.final_date or '—' }}</td>
<td class="comment">
{% if run.comments %}{{ run.comments[-1] }}{% else %}<span class="faint">—</span>{% endif %}
</td>
<td class="right">
<a class="btn btn--ghost btn--sm"
href="{{ url_for('brews.run_detail', run_id=run.beer_run_id) }}">Open</a>
</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
</div>
</section>
<section class="card">
<div class="card__head">
<h2 class="card__title">Standard vs legacy alcohol figures</h2>
<span class="card__hint">The old app used (max − min) ÷ 7.36 + 0.5, which is not a recognised formula</span>
</div>
<div class="card__body card__body--flush">
<div class="table-wrap">
<table class="data">
<thead>
<tr>
<th>Run</th>
<th>Name</th>
<th class="num">Standard ABV</th>
<th class="num">Legacy ABV</th>
<th class="num">Overstated by</th>
<th>Finished</th>
</tr>
</thead>
<tbody>
{% for row in abv_rows %}
<tr>
<td class="mono">{{ row.beer_run_id }}</td>
<td>{{ row.name }}</td>
<td class="num">{{ '%.2f' % row.abv }}%</td>
<td class="num muted">{{ '%.2f' % row.legacy_abv }}%</td>
<td class="num">
{% if row.delta > 0 %}
<span class="chip chip--warn">+{{ '%.2f' % row.delta }}</span>
{% else %}
<span class="faint">{{ '%.2f' % row.delta }}</span>
{% endif %}
</td>
<td class="mono nowrap">{{ row.final_date or '—' }}</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
</div>
</section>
{% endblock %}
+58 -8
View File
@@ -22,14 +22,57 @@
<a class="btn btn--ghost btn--sm" href="{{ url_for('brews.index') }}">&larr; Back</a>
</div>
<div class="grid grid--4" style="margin-bottom:1.25rem">
<div class="grid grid--sidebar" style="margin-bottom:1.25rem">
<!-- ------------------------------------------------- run metadata -->
<section class="card">
<div class="card__head">
<h2 class="card__title">Run details</h2>
</div>
<div class="card__body">
<form method="post" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="field">
<label class="field__label" for="name">Beer / cider name</label>
<input type="text" id="name" name="name" maxlength="120"
value="{{ meta_form.name.data or '' }}">
<div class="field__hint">Overrides the drifting name on each reading.</div>
</div>
<div class="field-row">
<div class="field">
<label class="field__label" for="tap_number">Tap number</label>
<input type="number" id="tap_number" name="tap_number"
min="1" max="99" step="1"
value="{{ meta_form.tap_number.data if meta_form.tap_number.data is not none else '' }}">
</div>
<div class="field">
<label class="field__label" for="og_points">Original gravity</label>
<input type="number" id="og_points" name="og_points"
min="900" max="1300" step="1"
value="{{ meta_form.og_points.data if meta_form.og_points.data is not none else '' }}">
<div class="field__hint">Points, e.g. 1045.</div>
</div>
</div>
<div class="field">
<label class="field__label" for="notes">Brew notes</label>
<textarea id="notes" name="notes" maxlength="4000">{{ meta_form.notes.data or '' }}</textarea>
</div>
<button class="btn btn--block" type="submit">Save run details</button>
</form>
</div>
</section>
<div class="grid grid--4">
<div class="stat">
<div class="stat__label">Original gravity</div>
<div class="stat__value">
{% if summary.og_points is not none %}{{ summary.og_points }}{% else %}—{% endif %}
{% if summary.og_points is not none %}{{ summary.og_decimal_str }}{% else %}—{% endif %}
</div>
{% if summary.og_decimal %}
<div class="stat__meta">{{ summary.og_decimal_str }}</div>
{% if summary.og_points is not none %}
<div class="stat__meta">{{ summary.og_point_scale }} points</div>
{% endif %}
</div>
<div class="stat">
@@ -37,10 +80,10 @@
{% if summary.active %}Current gravity{% else %}Final gravity{% endif %}
</div>
<div class="stat__value">
{% if summary.fg_points is not none %}{{ summary.fg_points }}{% else %}—{% endif %}
{% if summary.fg_points is not none %}{{ summary.fg_decimal_str }}{% else %}—{% endif %}
</div>
{% if summary.fg_decimal %}
<div class="stat__meta">{{ summary.fg_decimal_str }}</div>
{% if summary.fg_points is not none %}
<div class="stat__meta">{{ summary.fg_point_scale }} points</div>
{% endif %}
</div>
<div class="stat">
@@ -53,7 +96,13 @@
{% else %}—{% endif %}
</div>
<div class="stat__meta">
{% if summary.abv is not none %}measured{% else %}projected{% endif %}
{% if summary.abv is not none %}
measured
{% elif summary.projected_abv is not none %}
projected
{% else %}
needs 2nd reading
{% endif %}
</div>
</div>
<div class="stat">
@@ -63,6 +112,7 @@
</div>
<div class="stat__meta">{{ summary.reading_count }} reading{{ '' if summary.reading_count == 1 else 's' }}</div>
</div>
</div>
</div>
<section class="card">