report-ai-bookkeeping

Report AI Bookkeeping

Turn a month's confirmed transactions into a verifiable, shareable, offline-viewable HTML monthly bill.

When to trigger

• "Produce the July 2026 bill"
• "Give me this month's spending analysis"
• "Generate a chart-rich HTML monthly bill"
• "Where am I spending a lot, and what money-saving advice is there?"
• "Export this month's bill"

Shared entry point

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" \
  report 2026-07 \
  --output-dir "/absolute/path/to/reports"

The command generates both:

• 2026-07-ai-bookkeeping.html
• 2026-07-ai-bookkeeping.json

Generation process

1. Confirm the month and configured time zone. When the user says "this month", convert it to YYYY-MM。
2. Run the report command, reading only that month's transactions.
3. Check data quality: number of pending-confirmation entries, number of voided entries, missing categories, missing accounts, foreign currency exchange rates.
4. Verify the core figures:
   • Real income.
   • Personal spending.
   • Balance and balance rate.
   • Net cash flow.
   • Transfers, refunds, reimbursements received, and pending reimbursements.
5. Verify the chart data: daily trend, categories, merchants, project ledgers, fixed vs. flexible, original currency.
6. Advice may only come from this month's facts. By default, generate a 20% scenario estimate from the largest flexible spending category, and clearly state that this is a hypothetical value.
7. Confirm the HTML contains embedded JSON and has no external script, font, or image URLs.
8. Report back the locations of the two files, the 3 core figures, and the 1 to 3 most noteworthy facts.

Report scope

• Only count transactions with status confirmed, corrected, or closed.
• Refunds offset the original category and personal spending, and do not count as real income.
• Reimbursements received replenish cash and do not count as real income.
• Transfers do not count as income or spending.
• For reimbursable advances, only the final personally borne portion counts as spending.
• Foreign currency is converted at each transaction's confirmed exchange rate, while the original currency totals are also retained.

Advice rules

Advice consists of four parts: facts, actionable steps, monthly and annual scenario impact, and applicable limitations.

Qualified example:

本月弹性餐饮净支出 300.00 元。若先试着减少 20%，每月约留出 60.00 元，一年约 720.00 元。这个数字是情景测算，实际结果取决于下月选择。

When income is zero, data is scarce, or flexible spending is empty, soften the advice and prompt the user to fill in the data first.

Boundaries and exceptions

• The month format must be YYYY-MM。
• Pending-confirmation transactions do not enter the core figures and must be shown in the data quality section.
• When the accounts are clearly incomplete, do not give conclusions like "you can definitely save this much".
• When a refund or reimbursement lacks a link, first go back to the entry Skill to correct it.
• The HTML and JSON must come from the same aggregation; the checksum is used to detect content mismatches.
• The report is suitable for reviewing personal cash flow and does not replace tax, audit, or investment advice.
• The current official output is the monthly bill; the annual bill follows the same transaction model and is left for a future version.

Completion check

• Both files exist and can be opened.
• The HTML is usable offline.
• The core figures match the JSON.
• The suggested amount will change with the source transactions.
• In the reply, clearly state the month, currency, basis, and data quality reminder.