dsh-family-budget

dsh-family-budget · 家庭财务整理助手

A monthly household budget page for the DSH Web UI: a sidebar entry opens one table per month with income, fixed expenses, variable expenses, savings, an emergency fund, debt and a review block. It adds up what you enter, shows the gaps to your own savings / debt / down-payment target, and keeps every month on disk.

It is bookkeeping, not advice. No market data, no products, no forecasts, no investment suggestions — the page says so itself.

The monthly table

Block	What you enter	What the page computes
收入 Income	工资、奖金、其他进项	收入合计，占各比例的基数
固定支出 Fixed	房贷／房租、水电燃气、通讯、保险、教育	固定支出合计，占收入比例
可变支出 Variable	每项的预算与实际	预算合计、实际合计、逐项差额、超支项
储蓄 Savings	计划储蓄、已累计储蓄	本月可存（结余）、距计划差额、一键记入累计
应急金 Emergency fund	现有应急金、目标月数（3/6/12）	目标金额 = 固定支出 × 月数，覆盖率与缺口
债务 Debt	每笔余额、月供、本月已还	余额合计、月供合计、已还合计
复盘 Review	做得好的／超支原因／下月调整	自动核对：储蓄率、超支项、固定支出占比、应急金覆盖

The goal bar switches between 储蓄 / 还债 / 买房 and tracks one target with an accumulated amount you control.

Install

Add it from Settings → Plugins → Add with the repository spec:

github:skyline66/dsh-family-budget

Or take the prebuilt dsh-family-budget.tgz from the releases page. Either way, reload the window afterwards and open the 家庭财务 / Family budget entry in the sidebar.

The package is not on npm, so a bare dsh-family-budget name will not resolve.

Data

• Everything is kept in one document under <dsh home>/family-budget/budget.json.
• The Host half validates every write: unknown keys are dropped, amounts are clamped to non-negative numbers rounded to cents, month keys must be YYYY-MM, review prose is capped, and an unreadable file is moved aside instead of being overwritten.
• Nothing leaves the machine. The page talks only to its own plugin route.
• Export CSV for a spreadsheet, export/import JSON for a backup. The import is confirmed in the page before it replaces the document.

Displayed amounts use a ¥ prefix as a formatting convention only; the plugin does not convert currencies.

Development

npm test        # arithmetic + module wiring (no browser needed)
npm run test:api -- http://127.0.0.1:57253   # live Host round-trip against a running Harness

test/calc.test.mjs evaluates the exact arithmetic block from client.js, so the shipped maths is what gets tested. test/wiring.test.mjs loads client.js through the module loader, applies the plugin to a stub context and checks both slot registrations plus zh/en dictionary parity. test/api.test.mjs POSTs a hostile document at the live route, checks the cleaned result, and restores the previous document.

Layout

index.js            Host half: /family-budget/api/{doc,health}, validation, atomic write
client.js           Client half: sidebar entry + budget page (plain JS, React from the host)
locale/{en,zh}.json plugin title and description for the plugin list
cordis.patch.yml    the bundle row and its storage root
test/               arithmetic, wiring and live-API tests

License

MIT