Show coupon audit trail to users

[github-actions]

Problem

Users cannot see the transaction history of a coupon (add/take/use/return/void), causing confusion about coupon state.

Evidence

• Multiple feedback messages and reports (see original feedback Show coupon audit trail to users #34).
• Technical admin reported manually querying the DB to explain state to users.
• Several users have shared accounts, increasing the need to understand who performed actions.

Expected Behavior

Provide a per-coupon audit trail view that shows who performed each action (add/take/use/return/void), with timestamps.

Notes

Aligns with PRODUCT VISION's "Accountability". Medium implementation effort; ensure the UI stays simple (textual history, not complex timelines).

[Szer]

Triage (2026-06-23): keeping open as valid product backlog. Per-coupon audit trail is a real feature — the underlying data already exists in coupon_event (add/take/use/return/void with timestamps), so it's a UI/query effort. Product-agent scope; intentionally retained, no code change in this triage pass.

---

Generated by Claude Code

[Szer]

Implementation plan (design agreed, not yet built)

Saving the design here to act on later.

Decision: relative, pseudonymized history (no real names)

The coupon→person mapping is effectively private today (/list, /my, /added, /stats, take/use/return/void messages never name who owns or holds a coupon), and that implicit anonymity is worth keeping. So the user-facing history uses relative labels, never real names:

• viewer → «ты»
• coupon's adder → «владелец»
• every other distinct member → stable per-coupon pseudonym «участник 1 / участник 2 / …», assigned by order of first appearance.

Distinguishing multiple members is the point: it reconstructs the "bad coupon bounced between several people who took-and-returned it before someone flagged «нерабочий»" story without identifying anyone.

Admins keep real names via the unchanged /debug <id> path. Because the buttons add clutter to already button-heavy /my//added rows, the feature sits behind an admin-toggleable feature flag.

Note: per-coupon "who" can't distinguish two humans on one shared Telegram account — they're a single user_id. So attribution is per-account, not per-person, by construction.

Data (no schema change)

coupon_event(coupon_id, user_id, event_type, created_at) (V1) already logs add/take/use/return/void (+ *_reverted). Reuse it.

• Types.fs — add user_id: int64 to CouponEventHistoryRow (the existing user name field stays for the admin render).
• DbService.fs GetCouponEventHistory — add ce.user_id to the SELECT.

Rendering

Add BotHelpers.formatRelativeHistory (viewerId) (rows):

• owner = user_id of the added row; label rows as «ты» / «владелец» / «участник N» (first-appearance order over other distinct ids).
• event_type → verb: added→«добавлен», taken→«взят», used→«использован», returned→«возвращён», voided→«аннулирован»; *_reverted → «откат: ».
• lines • {date} — {verb} ({label}), headed История купона ID:{id}:.

Entry point — buttons on /my and /added

• CommandHandler.handleMy / handleAdded — append «История ID:{id}» → callback history:{id} to each coupon's button row, only when HistoryButtonsEnabled.
• New HandleHistory user chatId couponId: load rows; scope check (show only if viewer is owner or appears in the coupon's events, else «не найден» — prevents enumerating arbitrary coupons); render via formatRelativeHistory.
• CallbackHandler — add a history: branch mirroring void:.

Admin toggle (feature flag)

Reuse existing bot_setting FEATURE_FLAG infra (V15) + reloadSettings() (Program.fs).

• New migration V17__history_buttons_flag.sql: seed ('HISTORY_BUTTONS_ENABLED', 'true', 'FEATURE_FLAG', 'HISTORY', …) ON CONFLICT DO NOTHING.
• buildBotConf — HistoryButtonsEnabled = getSettingOr "HISTORY_BUTTONS_ENABLED" "true" |> bool.Parse; add field to BotConfiguration.
• DbService.UpsertBotSetting(key, value) (INSERT … ON CONFLICT DO UPDATE).
• New admin command /history_buttons on|off (next to /debug in the command match, admin-gated): upsert flag → trigger settings reload so options refreshes live → reply «Кнопки истории включены/выключены». Inject reloadSettings via DI; the /reload-settings HTTP endpoint stays as fallback.

Tests (tests/CouponHubBot.Tests, new HistoryTests.fs)

• 3-member bounce: owner-viewer sees «владелец» + «участник 1/2/3» in order; taker-viewer sees own action as «ты»; assert no @username/first_name leaks.
• Scope: non-participant invoking history:<id> → «не найден».
• Button visibility gated by HistoryButtonsEnabled (true/false via test config).
• /history_buttons off by admin upserts flag + replies; non-admin ignored.
• Regression: admin /debug still shows real names.

Verification

No local dotnet (SDK 10 + Docker/Testcontainers) → CI. Run dotnet test tests/CouponHubBot.Tests -c Release; watch new HistoryTests + existing VoidFlowTests/CouponTests keyboard-JSON assertions.

---

Design captured via Claude Code; implementation deferred.

---

Generated by Claude Code

[github-actions]

Product review of this feature request (issue #112).

Decision

• Keep issue open with labels feature-request + priority-medium (already present).

Rationale / Evidence

• Aligns with PRODUCT VISION: "Accountability" is a core value.
• Issue body reports the technical admin manually querying the DB to explain coupon state — this is a transparency gap and supports a feature request.

Recommendation for implementation (for Project agent)

• Keep UI minimal: a textual per-coupon audit trail listing actions (add/take/use/return/void), actor, and timestamp.
• Prefer server-side storage / index if not already present; avoid complex timelines or heavy UI.
• Verify privacy: only show events relevant to the private community and avoid exposing internal IDs.

No new issues created by Product agent. Assigning to engineering is out-of-scope for Product; Project agent can pick this up if agreed.

Product triage by Product Agent

[github-actions]

Product decision: ACCEPT (priority-medium)

Reasoning

• Aligns directly with PRODUCT VISION: "Accountability" is a core value.
• The issue body cites multiple user reports and the technical admin manually querying the DB — convergent evidence that this is a real, recurring need.
• Proposed scope is small and low-risk: a textual per-coupon audit trail showing actor, action, and timestamp fits the zero-friction principle.

Suggested Minimal Scope (product)

• Expose a per-coupon audit trail entry list: timestamp — action — user (e.g. "2026-07-20 12:34 — taken — @ivan").
• Surface it in the coupon detail view (one-line toggle or small modal) and add a lightweight admin command fallback such as /coupon_history <id> for power users.
• Do not add visual timelines, filters, or complex UI — keep it textual and reachable in two taps.

Expected Behavior

• Users can view who performed each action (add/take/use/return/void) with timestamps.
• The bot does not attempt to verify external redemptions (out of scope).

Implementation Notes (for engineering)

• Backend: reuse existing event log/audit table if present; otherwise add a minimal append-only audit table storing coupon_id, actor_id, action, metadata, created_at.
• Keep migration atomic and grant service role permissions per DB conventions.

Next Steps Taken

• Product agent marks this as accepted for implementation with priority-medium (already present on the issue).
• No new feature issue was created because this request already exists as Show coupon audit trail to users #112.

Product agent — analysis recorded on 2026-07-21

[Szer]

Re-checked 2026-09-15: still unbuilt. /my and /added show current state only; the full coupon_event history is admin-only via /debug and /whois. The design in the earlier comment (pseudonymized relative labels, feature flag, history button) still stands.

Too complicated for the benefit right now. Lowering to priority-low and keeping open. If the picture is the same in a few months, this will be closed as won't-do.