mirror of
https://github.com/we-promise/sure.git
synced 2026-09-05 14:51:15 +00:00
Brandon
fe0d27471d
* feat(bills): the bills pages, calendar feed and in-page AI helpers Second of three chunks carved out of #3083, stacked on the schema and domain core. This is everything a user sees and clicks. The whole surface sits behind the preview flag, so it is unreachable until someone opts in. Pages, all under one nav entry: - the pay run, a month calendar, the full bills table, and the paycheck planner - a detail drawer per bill, with payment history, price changes and cost analytics - create and edit flows for bills, subscriptions, installment plans and income The overview marks pay periods inside the month, so a weekly paycheck no longer reads as one undifferentiated month of bills. Markers appear only when income actually subdivides the month, which means monthly and undeclared income render exactly as before and there is no new setting to configure. Navigation and design system: - one preview-gated nav item shared by the desktop rail and the mobile bar - DS::Sparkline for payment-history charts, replacing raw SVG in views - status badges render through DS::Pill rather than hand-rolled spans - the suggestions panel is a disclosure that remembers being collapsed, per device, the way privacy mode and the sidebar width already do - every surface reflows to phone widths without horizontal scroll Calendar feed: a signed ICS feed per family, served sessionless by token, with a reset that revokes previously shared URLs. In-page AI helpers: smart fill on the bill form and a smart configuration proposal on an existing bill, each reading a bounded slice of charge history. Provider-side prompt assembly sits behind the existing LlmConcept interface, with an implementation for each of the two providers. These belong here rather than with the assistant tools because they are buttons on these pages and lean on the provider suggester, not on the tool registry. Suite 7,776 runs green apart from the pre-existing passkey-session flake, which passes standalone. Rubocop clean, eager loading verified. The hosting guide for the feature ships here rather than with the schema, since its instructions walk pages this PR introduces. * Render the suggested strip through DS::Disclosure The hand-rolled details pair predates the component. The card_inset variant is the same shape, so the strip now inherits the design system chrome, and the persisted-disclosure controller rides along unchanged. * Route the remaining hand-rolled chips through the design system The subscription-state chips, rule-match chips and match-reason chips become DS::Pill, with the state chips extracted to one shared partial so the drawer and the summary tab stop carrying copy-pasted markup. The AI prompt chips become DS::Button and the bills-index filter becomes DS::SearchInput, both of which this PR already uses elsewhere for the same shapes. * Fix erb_lint whitespace offenses in bills views * Address the post-ready review round * Require a writable destination account and gate the feed on preview * Reject an unresolvable declared account out loud
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# Bills and Recurring Transactions
|
|
|
|
This document explains how Sure detects recurring bills, when the detection
|
|
pipeline runs, and the maintenance tasks available to self-hosters.
|
|
|
|
## How detection works
|
|
|
|
Sure clusters your transaction history into recurring patterns (same
|
|
merchant or name, consistent amount within tolerance, consistent day). A
|
|
pattern needs at least three consistent occurrences to become a series.
|
|
New detections land with status `suggested` and wait in a review strip on
|
|
the Bills page (and under Settings -> Recurring transactions) until you
|
|
confirm or dismiss them. Dismissing leaves a tombstone, so a dismissed
|
|
pattern is never suggested again.
|
|
|
|
## When the pipeline runs
|
|
|
|
The full pipeline (detect patterns, materialize upcoming occurrences,
|
|
repair provider-replaced entries, match payments, detect price changes)
|
|
runs automatically:
|
|
|
|
- after every completed bank sync or import (debounced by 30 seconds)
|
|
- nightly at 05:30 UTC (occurrence materialization only, for families
|
|
that never sync)
|
|
|
|
And on demand:
|
|
|
|
- the **Find recurring transactions** button on an empty Bills page
|
|
- the **Identify Patterns** button under Settings -> Recurring transactions
|
|
|
|
All triggers share one per-family lock, so concurrent runs never stack.
|
|
|
|
## First run on existing data
|
|
|
|
The user-triggered detection actions (the **Find recurring transactions**
|
|
button on an empty Bills page and the **Identify Patterns** button under
|
|
Settings -> Recurring transactions) backfill the last six months of
|
|
history: past occurrences are generated and closed as paid where a real
|
|
transaction anchors them. Past occurrences no transaction covers are
|
|
deleted rather than shown as missed, so the backfill reconstructs what
|
|
happened without fabricating debt. The backfill is idempotent, so
|
|
re-running detection never duplicates history. Background syncs never
|
|
backfill; on an instance upgraded from a build without the Bills
|
|
subsystem, run either detection action once to reconstruct history.
|
|
|
|
Confirming an individual suggestion likewise backfills that bill's own
|
|
history, so a just-confirmed bill shows its lived past instead of
|
|
starting blank.
|
|
|
|
## Maintenance tasks
|
|
|
|
Both tasks are safe to re-run; they only close history a real entry
|
|
anchors and never touch existing payment records.
|
|
|
|
```bash
|
|
# Rebuild N months of occurrence history for every family (default 6)
|
|
bin/rails "recurring:backfill_history[12]"
|
|
|
|
# One-shot classification of auto-detected series still on defaults
|
|
# (assigns bill/subscription/installment kind and a category)
|
|
bin/rails recurring:classify_existing
|
|
```
|
|
|
|
## Disabling the feature
|
|
|
|
Settings -> Recurring transactions has a per-family toggle. Disabling
|
|
hides the Bills page and stops all detection and materialization for
|
|
that family.
|