NEC-387: Grafana: Feedback dashboard ranked by paid votes #358

Merged
nectenda-agent merged 8 commits from worktree-nec-387-grafana-feedback-dashboard-ranked-by-pai into main 2026-11-11 23:18:49 +00:00
Collaborator

Task: NEC-387 — https://projectron.nerchure.com/tasks/409

Adds a Feedback dashboard to Grafana that ranks the board's ideas by who is paying, with a Rank by menu (paid votes, annual only, all votes). The board gains a read-only GET /api/kpi behind KPI_TOKEN (BOARD-016); identity's /api/kpi carries each person's class from boardClass() (BOARD-017), so 'upgraded since voting' agrees with billing by construction. The collector reads the board hourly after the core run commits. The views are tested in PGlite (Postgres 18) by running each panel's own SQL with each Rank by value, and the dashboard was checked in a real Grafana 13. After merge: KPI_TOKEN goes in board.env on the identity host, and clconsole's kpi directory is re-synced and the collector rebuilt (spec, 'After merge').

Spec: docs/changes/NEC-387-feedback-dashboard/spec.md

Changelog

NONE

Task: NEC-387 — https://projectron.nerchure.com/tasks/409 Adds a Feedback dashboard to Grafana that ranks the board's ideas by who is paying, with a Rank by menu (paid votes, annual only, all votes). The board gains a read-only GET /api/kpi behind KPI_TOKEN (BOARD-016); identity's /api/kpi carries each person's class from boardClass() (BOARD-017), so 'upgraded since voting' agrees with billing by construction. The collector reads the board hourly after the core run commits. The views are tested in PGlite (Postgres 18) by running each panel's own SQL with each Rank by value, and the dashboard was checked in a real Grafana 13. After merge: KPI_TOKEN goes in board.env on the identity host, and clconsole's kpi directory is re-synced and the collector rebuilt (spec, 'After merge'). Spec: `docs/changes/NEC-387-feedback-dashboard/spec.md` ## Changelog NONE
The Feedback dashboard: the board's own KPI feed, each person's plan class
from identity's, and a Rank by variable over views tested in PGlite.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
GET /api/kpi answers the KPI collector on clconsole with every idea anyone
can see, and the votes on them with the class each recorded: what the
Feedback dashboard ranks by. It is the one answer outside the Team view that
carries a class and who voted, so it opens only to KPI_TOKEN, the same
shared secret identity and the shards hold, and is checked before the
board-token check: no board token opens it, the team's included. Off until
the token is set; a token under 32 characters refuses boot.

Deleted, merged and hidden ideas stay out, and so do public names, comments
and bodies. The privacy walk for BOARD-007 now tries the route as every
viewer and the team.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
The Feedback dashboard compares the class a vote recorded with the voter's
class now. It takes the second from boardClass(), the function that signs
the class into the board token, rather than from a copy of its rule in SQL,
so the two cannot drift. The address boardClass() needs to find seats is
read inside kpiSnapshot and goes no further.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
The Feedback dashboard's views are tested in deploy/ against
fixtures/board-kpi.json, with no board running. A fixture that drifted
from what the board sends would keep those tests green while the dashboard
went blank, so the board's tests ask a real board and compare keys at every
depth, as the website's snapshot fixture already is. The shape helpers move
into the test harness so both contract tests share them.

The fixture's numbers are chosen so each Rank by option orders the ideas
differently and every tie-break is reached.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
The collector reads the feedback board's /api/kpi hourly with the outside
sources, after the core run has committed, so a board that is down is a row
in source_runs and never costs the sign-in events only the core run can
catch. Ideas and votes are replaced on each read, in one transaction: a
failed write leaves the last good copy. Each person's plan class now comes
from identity's feed into snap_identity_users.board_class.

The new dashboard, generated beside the KPI one, has a Rank by variable
(paid, annual, all) that orders both Top ideas and the ideas table. Counts
are by the class each vote recorded; the class now is used only for
"upgraded since voting". Every definition is a v_feedback_* view.

The views are tested in PGlite, Postgres 18 in WASM, the same major as
clconsole: schema.sql applied as the collector applies it, rows written
through the collector's own writes, and each panel's SQL taken from the
generated JSON with ${rank} substituted. The source writes move from
collector.mjs into lib.mjs so the test can drive them. The KPI dashboard's
JSON is byte-identical after the builder learnt to build two.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
BOARD-007 now allows the KPI feed's own token beside an admin. BOARD-016
says who that feed answers and what it may carry, and BOARD-017 that
identity's class for the dashboard is boardClass()'s own answer. The
security model says the usage dashboard reads public ideas and votes with
their plan, through a feed no board token opens and that names nobody.
SETUP and the clconsole README name board.env's KPI_TOKEN and the second
dashboard. The spec follows where the tests landed.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
Run against real Postgres 18 and Grafana 13 with the test fixture, every
Rank by option drew Top ideas top to bottom in the table's order. But a
zero segment printed a stray "0", the weekly chart stacked annual, free,
monthly, since Grafana names long-format series in name order whatever the
rows' order, the Idea column was cut short, and two titles were truncated.
Zeros now go out as NULL, the weekly chart is one column per class, the
Idea column has a width, and the tiles are laid out to fit.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
Fix what the review of NEC-387 found
All checks were successful
Release note / release-note (pull_request) Successful in 15s
CI / build (pull_request) Successful in 4m31s
CI / e2e (pull_request) Successful in 17m19s
CI / promote (pull_request) Has been skipped
Deploy site / deploy (push) Successful in 1m7s
CI / build (push) Successful in 5m23s
CI / e2e (push) Successful in 17m34s
CI / promote (push) Successful in 44s
eb8663db02
boardClass() runs inside identity's /api/kpi, which the collector's
15-minute run reads, so one person's class throwing would have failed that
run and lost the sign-in events only it catches. That person is now sent
with no class, logged by id, and everyone else as before; BOARD-017 says
so. A test makes it throw with a directory entry that will not parse.

Two acceptance lines had no test that could fail: --check refusing either
dashboard (it now edits each in a copy and expects the refusal), and the
outside sources writing only after the core transaction commits (it now
reads that order from collector.mjs). And a 404 from the board names
BOARD_URL as well as KPI_TOKEN, since a 404 cannot say whose it is.

Task: NEC-387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztYjhgsq6n7uzBz68QG
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Nectenda/nectenda!358
No description provided.