FinanceBuddy/README.md

# FinanceBuddy -- money on your Kanboard cards

Attach a money value to each board card, see it on the card, and total it per column, so a
Kanboard project can double as a simple, visual finance board -- bills, installments, income
vs expenses.

FinanceBuddy is **opt-in per board**: installing it changes nothing until a project manager
enables it for a specific board under Settings -> Integrations. Boards that are not enabled
look exactly as before.

## The idea: a bill-lifecycle board

Kanboard imposes no structure, so FinanceBuddy fits one rather than dictating it. A layout that
works well:

- **Columns = a bill's status:** `Templates -> Due this month -> Paid`. Cards flow left to right
  as they are paid.
- **Tags = category:** housing, utilities, comms, food...
- **Due date = the bill's due date;** color/priority = urgency.
- Each card carries a **money value** and, optionally, an **installment** count.

Recurring monthly bills can live as template cards spawned each month by the companion RecoReco
plugin; FinanceBuddy only owns the money.

## What it does

Once a board is enabled:

### Set the money on a card

The task edit/create form gains a **Finance** section in the middle column:

- **Amount** in the board's currency (default R$).
- **Debit** or **Credit** (money out vs money in).
- **Installment** current / total (for example `2` of `10`). Leave the total blank for an
  open-ended recurring bill.

### See it on the card

A badge appears just under the card title -- both on the board and at the top of the opened
card, so the money is visible whether you glance at the board or read the card (no need to open
the edit form):

- **red** with a `-` for a debit, **green** with a `+` for a credit (both the color and the sign
  carry the meaning, and the badge's own background stays readable on any card color);
- followed by `pN/M` when a total is set (for example `p2/10`), hidden for open-ended bills.

### Total per column

Each column header shows a **`Total:`** of its cards -- credits positive, debits negative (the
net): red when negative (what you owe), green when positive, gray at zero. It is shown for every
column, including `Total: R$0,00`.

You can hide the total on a per-column basis: open the column's dropdown menu (the caret next to
the column title) and pick **"Hide column total"**; the same menu then offers **"Show column
total"** to bring it back. This is a per-board manager action, remembered per column.

### Installments and recurrence

FinanceBuddy carries the money across copies. Kanboard's built-in recurrence and RecoReco's
calendar recurrence advance the installment on the next occurrence (`p2/10 -> p3/10`); a manual
duplicate copies it as-is. When a RecoReco-followed plan finishes, the parked template is left one
past the last installment (`p3/3 -> p4/3`) as a "plan complete" marker that RecoReco reads to stop
recurring; the copies themselves still read `p1/3 .. p3/3`. Open-ended plans (blank total) keep
counting.

## Money format

Amounts show with a comma decimal and no thousand separator (for example `R$1234,56`). Input
accepts either a dot or a comma as the decimal separator, so `1234.56` and `1234,56` are the same
value.

The currency symbol shown before every amount is **per board**: set it under
Settings -> Integrations next to the enable checkbox (up to 4 characters, e.g. `US$`, `EUR`, `GBP`).
Leave it empty for the default `R$`.

## How it stores data

No database migration. The per-board enable flag is stored in project metadata; each card's
money is stored in task metadata. The finance fields live in the normal task form but are saved
separately (they are not task columns), so ordinary task saving is untouched. Uninstalling the
plugin leaves that metadata harmlessly in place and changes nothing else.

## Requirements

- Kanboard >= 1.2.0

## Installation

Copy this folder into your Kanboard installation as `plugins/FinanceBuddy/`. The directory name
must be exactly `FinanceBuddy` (Kanboard derives the plugin namespace from the folder name). No
build step and no database migration. Then, on each board you want to track, go to
Settings -> Integrations and tick "Enable FinanceBuddy on this board".

## License

AGPL-3.0. See LICENSE.

## More Kanboard plugins by Dr. Beco

All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco):

- **[RecoReco](https://code.beco.cc/beco/RecoReco)** -- calendar-scheduled recurring cards (yearly,
  monthly, weekly, daily), driven by the card due date.
- **[QualKard](https://code.beco.cc/beco/QualKard)** -- flashcard spaced repetition: grade a card by
  dragging it to a column, and it comes back when due (needs RecoReco).
- **[WorkspaceOrg](https://code.beco.cc/beco/WorkspaceOrg)** -- group your projects into personal
  per-user workspaces, shown on a "My workspaces" dashboard page with a badge on each project.
- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small
  quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due
  dates, extra search keywords and shared board filters, and more.
- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board
  column to another in a single action.
- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed
  board columns so the horizontal scrollbar stays within reach.
- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties:
  drag-to-scroll, a wider column gap, and smoother card dragging.