foxclaw 0.1.0 → 0.1.2

package/python/tests/test_finance.py

@@ -0,0 +1,153 @@
+"""
+B 阶段测试 — 财务 Agent 内核(资金行为操作系统)
+验证:CSV 导入 → 推理(预算/异常/订阅/烧钱) → Policy 守门人裁决
+不真实动钱:执行层只产出审批请求。
+"""
+import sys, tempfile
+from datetime import datetime, timedelta
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.finance import FinanceRuntime, Transaction
+from foxclaw.finance.reasoning import FinanceReasoning
+
+CSV = str(Path(__file__).parent.parent / "examples" / "sample_transactions.csv")
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 60)
+    print("B 阶段 · 财务 Agent 内核(资金行为操作系统)")
+    print("=" * 60)
+
+    # policy 落临时目录:原先写 ./b_finance_policy.yaml 再 os.remove —— 一旦中途抛异常
+    # 就会在仓库根留下垃圾文件。改临时目录后无需清理,也不会污染工作区。
+    fr = FinanceRuntime(policy_path=str(Path(tempfile.mkdtemp()) / "b_finance_policy.yaml"))
+    n = fr.import_csv(CSV)
+    fr.set_budget("food", 400)
+    fr.set_budget("subscription", 100)
+    fr.set_balance("debit", 11800)
+    fr.set_balance("credit_card_1", -700)
+    print(f"\n导入 {n} 笔交易")
+    check(n == 13, f"CSV 导入 13 笔交易(实为 {n})")
+
+    r = fr.analyze(period="2026-06", current_balance=11100)
+
+    print("\n【预算推理】")
+    for b in r["budget_status"]:
+        flag = "⚠ 超支" if b["is_over"] else "OK"
+        print(f"  {b['category']:<14} {b['spent']:.0f}/{b['monthly_limit']:.0f} "
+              f"({b['usage_ratio']*100:.0f}%) {flag}")
+    over = {b["category"]: b["is_over"] for b in r["budget_status"]}
+    check(over.get("food") is True and over.get("subscription") is True,
+          f"两大超支分类被正确标记(food={over.get('food')}, subscription={over.get('subscription')})")
+
+    print("\n【超支预测】")
+    for f in r["overspend_forecast"]:
+        print(f"  {f['category']:<14} 月底预计 {f['projected_month_end']:.0f} / "
+              f"限额 {f['monthly_limit']:.0f} · 将超支={f['will_overspend']}")
+    check(len(r["overspend_forecast"]) >= 2
+          and all(f["will_overspend"] for f in r["overspend_forecast"]),
+          f"超支预测命中({len(r['overspend_forecast'])} 项,全部 will_overspend=True)")
+
+    print("\n【异常消费(MAD 检测)】")
+    for a in r["anomalies"]:
+        print(f"  {a['entity']} {a['amount']} (修正Z={a['z_score']}) — {a['reason']}")
+    check(any(a["entity"] == "高级餐厅" for a in r["anomalies"]),
+          f"MAD 检测出「高级餐厅」离群消费({len(r['anomalies'])} 条异常)")
+
+    print("\n【重复扣款】")
+    for d in r["duplicate_charges"]:
+        print(f"  {d['reason']}")
+    if not r["duplicate_charges"]:
+        print("  无")
+    check(isinstance(r["duplicate_charges"], list), "重复扣款检测返回列表结构")
+
+    print("\n【订阅膨胀】")
+    sc = r["subscription_creep"]
+    print(f"  {sc['subscription_count']} 个订阅,月总 {sc['monthly_total']:.0f},"
+          f"预警={sc['creep_warning']}")
+    check(sc["subscription_count"] == 6 and sc["creep_warning"] is True,
+          f"订阅膨胀预警触发(6 个订阅 / 月总 {sc['monthly_total']:.0f})")
+
+    print("\n【烧钱速度 / 现金流】")
+    br = r["burn_rate"]
+    print(f"  日均支出 {br['daily_burn']} · 日均净流 {br['daily_net']}")
+    cf = r["cashflow_projection"]
+    if cf:
+        print(f"  现金流趋势: {cf['trend']} · 月净流 {cf['monthly_net']}")
+        for t in cf["trajectory"]:
+            print(f"    第 {t['month']} 月预计余额 {t['projected_balance']}")
+        check(len(cf["trajectory"]) == 3, "现金流预测给出 3 个月轨迹")
+
+    # ⚠ burn_rate 是**相对 now 的 30 天窗口**,而 examples/sample_transactions.csv 的交易
+    # 日期固定在 2026-06 —— 随真实时间推移,样例必然滑出窗口,于是上面那段会**静默变成 0
+    # 却毫无报错**(本测试此前不断言,故退化无人发现)。这里做两件事:
+    #   (a) 用"当下日期"的交易构造可控用例,把 burn/cashflow 的算术真正锁住;
+    #   (b) 断言其与 now-30天 窗口严格一致,把这个耦合显式写出来(而非假装它是稳定值)。
+    _cutoff = datetime.now() - timedelta(days=30)
+    in_window = [t for t in fr.transactions if t.dt >= _cutoff]
+    expect_expense = round(sum(abs(t.amount) for t in in_window if t.is_expense), 2)
+    check(br["total_expense"] == expect_expense,
+          f"burn_rate 严格按 now-30天 窗口统计(窗口内 {len(in_window)} 笔;样例日期已过期,故为 {expect_expense})")
+    check(isinstance(br["daily_burn"], (int, float)) and br["daily_burn"] == round(expect_expense / 30, 2),
+          f"日均支出 = 窗口内支出 / 30(daily_burn={br['daily_burn']})")
+
+    fresh = [
+        Transaction(amount=-300, category="food", entity="测试超市", account="debit"),
+        Transaction(amount=-150, category="transport", entity="测试打车", account="debit"),
+        Transaction(amount=2000, category="salary", entity="某公司", account="debit"),
+    ]
+    br2 = FinanceReasoning.burn_rate(fresh, days=30)
+    check(br2["total_expense"] == 450.0 and br2["total_income"] == 2000.0,
+          f"当日交易用例:支出 450 / 收入 2000(实为 {br2['total_expense']}/{br2['total_income']})")
+    check(br2["daily_burn"] == 15.0, f"日均支出 = 450/30 = 15.0(实为 {br2['daily_burn']})")
+    check(br2["daily_net"] == round(1550 / 30, 2),
+          f"日均净流 = (2000-450)/30(实为 {br2['daily_net']})")
+    cf2 = FinanceReasoning.cashflow_projection(fresh, current_balance=1000.0, months=3)
+    check(cf2["trend"] == "上升" and cf2["monthly_net"] > 0, "净流入 → 趋势判定为上升")
+    check(cf2["trajectory"][-1]["projected_balance"] > 1000.0, "预测余额随净流入增长")
+
+    print("\n【守门人裁决(整体状态)】")
+    for v in r["gatekeeper_verdicts"]:
+        print(f"  [{v['action'].upper()}] {v['message']}")
+    acts = {v["action"].lower() for v in r["gatekeeper_verdicts"]}
+    check("veto" in acts and "alert" in acts,
+          f"整体裁决含 VETO(异常消费否决)与 ALERT(订阅超标)(实为 {sorted(acts)})")
+
+    print("\n【守门人裁决(单笔大额交易)】")
+    big = Transaction(amount=-680, category="electronics", entity="Apple Store",
+                      account="credit_card_1")
+    big_acts = {v.action.lower() for v in fr.policy.evaluate_transaction(big, account_balance=300)}
+    for v in fr.policy.evaluate_transaction(big, account_balance=300):
+        print(f"  [{v.action.upper()}] {v.message}")
+    check("require_confirmation" in big_acts,
+          "大额支出(680>500)触发 REQUIRE_CONFIRMATION")
+    check("freeze" in big_acts,
+          "余额不足(300<500)触发 FREEZE 可选支出")
+
+    print("\n【执行层:审批流(不自动动钱)】")
+    req = fr.request_action("cancel_subscription", {"entity": "YouTube", "save": 12.0})
+    print(f"  请求: {req['action']} · 状态: {req['status']}")
+    print(f"  说明: {req['note']}")
+    # 本文件 docstring 的承诺是"不真实动钱":执行层必须只产出**待批**状态。
+    # 若哪天有人把它改成自动执行(EXECUTED/DONE),这里必须红。
+    check("PENDING" in str(req["status"]).upper(),
+          f"执行层只产出待批状态,不自动动钱(status={req['status']})")
+
+    print("\n" + "=" * 60)
+    print("✓ B 阶段验证完成:财务内核(记忆+推理+Policy 守门人)成立")
+    print("=" * 60)
+
+
+def test_finance():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_finance_ledger.py

@@ -0,0 +1,252 @@
+"""自然语言记账 —— 用户随口报备的一句花费,要能自己识别、记账、汇总。
+
+这是财务应用第一线的功能,输入是「今天买了一件衣服花了 105 块」这种大白话。
+测试固定四件事:
+  1. 金额/币种/时间/分类识别对(含中文数字、美元/美金/块/块钱);
+  2. 过去/今天 → 已发生,明天/下个月 → 计划支出,且计划不污染"本月已花";
+  3. 一段话多笔要拆开,时间可继承;
+  4. 记账本汇总(按天/按分类/按币种)与汇率折算正确。
+"""
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.finance import FinanceRuntime
+from foxclaw.finance.nlparse import (cn_to_number, has_expense_signal,
+                                         has_payment_verb, parse)
+from foxclaw.agents.impl.finance import _should_autorecord
+from foxclaw.agents.impl.supervisor import SupervisorAgent
+
+NOW = datetime(2026, 11, 7, 20, 0)
+
+
+def _rt(tmp_path):
+    return FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                          data_path=str(tmp_path / "finance_data.json"))
+
+
+def _one(text, now=NOW):
+    ps = parse(text, now=now)
+    assert len(ps) == 1, f"{text!r} 解析出 {len(ps)} 笔"
+    return ps[0]
+
+
+# ── 1. 用户原话 ────────────────────────────────────────────
+def test_今天买衣服105块():
+    p = _one("今天买了一件衣服花了105块")
+    assert (p.amount, p.currency, p.direction) == (105.0, "CNY", "expense")
+    assert p.when.date() == NOW.date() and not p.planned
+    assert p.category == "clothing"
+    assert p.entity == "衣服"
+
+
+def test_明天买大米45():
+    p = _one("明天买一袋大米花了45")
+    assert p.amount == 45.0 and p.planned
+    assert p.when.date() == datetime(2026, 11, 8).date()
+    assert p.category == "food"
+
+
+def test_后天洗车100():
+    p = _one("后天花了100洗车")
+    assert p.amount == 100.0 and p.planned
+    assert p.category == "transport"
+    assert p.when.date() == datetime(2026, 11, 9).date()
+
+
+# ── 2. 币种 ───────────────────────────────────────────────
+def test_货币单位识别():
+    assert _one("花了105块").currency == "CNY"
+    assert _one("花了105块钱").currency == "CNY"
+    assert _one("花了105元").currency == "CNY"
+    assert _one("花了105人民币").currency == "CNY"
+    assert _one("花了105rmb").currency == "CNY"
+    assert _one("花了105美元").currency == "USD"
+    assert _one("花了105美金").currency == "USD"
+    assert _one("花了$105").currency == "USD"
+    assert _one("花了105港币").currency == "HKD"
+    assert _one("花了105欧元").currency == "EUR"
+
+
+def test_符号与前置币种():
+    assert _one("¥105").currency == "CNY"
+    assert _one("美元105").currency == "USD"
+
+
+def test_量级后缀():
+    assert _one("买了个包1.5k").amount == 1500.0
+    assert _one("买了个手机2万").amount == 20000.0
+
+
+def test_中文数字():
+    assert cn_to_number("一百零五") == 105
+    assert cn_to_number("两千三") == 2300
+    assert cn_to_number("三千五") == 3500
+    assert cn_to_number("十五") == 15
+    assert cn_to_number("十万") == 100000
+    assert _one("买了一百零五块的衣服").amount == 105.0
+    assert _one("两千三买了个手机").amount == 2300.0
+
+
+# ── 3. 时间关键词 ──────────────────────────────────────────
+def test_过去时间词():
+    assert _one("昨天买了个杯子30").when.date() == datetime(2026, 11, 6).date()
+    assert _one("前天买了个杯子30").when.date() == datetime(2026, 11, 5).date()
+    assert _one("大前天买了个杯子30").when.date() == datetime(2026, 11, 4).date()
+    assert _one("3天前买了个杯子30").when.date() == datetime(2026, 11, 4).date()
+
+
+def test_未来时间词():
+    assert _one("大后天买了个杯子30").when.date() == datetime(2026, 11, 10).date()
+    assert _one("3天后买了个杯子30").when.date() == datetime(2026, 11, 10).date()
+    assert _one("下个月5号交房租3000").when.date() == datetime(2026, 12, 5).date()
+    assert _one("下个月5号交房租3000").planned
+
+
+def test_上个月与上月():
+    p = _one("上个月花了2000")
+    assert p.when.strftime("%Y-%m") == "2026-10" and not p.planned
+    assert _one("上月5号买衣服300").when.date() == datetime(2026, 10, 5).date()
+
+
+def test_几月与几号():
+    assert _one("9月买衣服105").when.strftime("%Y-%m") == "2026-09"
+    # 本月已过的 5 号 → 本月;本月还没到的 28 号 → 上个月
+    assert _one("5号买衣服105", now=datetime(2026, 11, 7)).when.strftime("%Y-%m") == "2026-11"
+    assert _one("28号买衣服105", now=datetime(2026, 11, 7)).when.strftime("%Y-%m") == "2026-10"
+
+
+def test_时间词不会被当成金额():
+    p = _one("上个月5号买了双鞋300")
+    assert p.amount == 300.0
+    assert p.when.date() == datetime(2026, 10, 5).date()
+
+
+# ── 4. 多笔与分类 ──────────────────────────────────────────
+def test_一句话多笔拆分():
+    ps = parse("今天买衣服105，还买了大米45", now=NOW)
+    assert [p.amount for p in ps] == [105.0, 45.0]
+    assert {p.category for p in ps} == {"clothing", "food"}
+
+
+def test_时间可继承():
+    ps = parse("今天买衣服105，洗车100", now=NOW)
+    assert len(ps) == 2
+    assert all(p.when.date() == NOW.date() for p in ps)
+
+
+def test_单笔带逗号不拆坏():
+    p = _one("今天，我买了一件衣服，花了105块")
+    assert p.amount == 105.0 and p.category == "clothing"
+
+
+def test_收入方向():
+    p = _one("工资发了12000")
+    assert p.direction == "income" and p.amount == 12000.0
+    assert p.category == "income"
+
+
+# ── 5. 不该记账的句子 ──────────────────────────────────────
+def test_无金额不解析():
+    assert parse("今天几号", now=NOW) == []
+    assert parse("本月预算怎么分配", now=NOW) == []
+    assert parse("今天买了几件衣服", now=NOW) == []
+
+
+def test_花费信号闸门():
+    assert has_expense_signal("今天买了一件衣服花了105块")
+    assert has_expense_signal("洗车100")
+    assert not has_expense_signal("今天几号")
+    assert not has_expense_signal("3个月计划")
+    assert has_payment_verb("我买了105块的衣服")
+    assert not has_payment_verb("衣服预算800")
+
+
+def test_预算句不自动记账():
+    assert not _should_autorecord("衣服预算800")
+    assert not _should_autorecord("给我定个800的餐饮预算")
+    assert _should_autorecord("今天买了一件衣服花了105块")
+    assert _should_autorecord("洗车100")
+
+
+def test_主管把花费报备路由给财务():
+    assert SupervisorAgent._is_expense_report("今天买了一件衣服花了105块")
+    assert SupervisorAgent._is_expense_report("后天花了100洗车")
+    assert not SupervisorAgent._is_expense_report("帮我总结这篇文档")
+    assert not SupervisorAgent._is_expense_report("今天几号")
+
+
+# ── 6. 记账与汇总 ──────────────────────────────────────────
+def test_记账回执与账本(tmp_path):
+    rt = _rt(tmp_path)
+    rec = rt.record_text("今天买了一件衣服花了105块")
+    assert len(rec["recorded"]) == 1
+    assert "已记账 1 笔" in rec["ack"] and "105.00" in rec["ack"]
+
+    led = rt.ledger("2026-11")
+    assert led["count"] == 1 and led["expense"] == 105.0
+    assert led["by_category"][0]["category"] == "clothing"
+    assert led["planned"]["count"] == 0
+
+
+def test_计划支出不进本月已花(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("明天买一袋大米花了45")
+
+    led = rt.ledger()
+    assert led["expense"] == 105.0               # 45 还没发生
+    assert led["planned"]["count"] == 1
+    assert led["planned"]["expense"] == 45.0
+    assert rt.analyze()["transaction_count"] == 1  # 分析也不能把未来算进来
+
+
+def test_多币种折成本位币(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("花了100美元")           # 内置汇率 7.2
+    led = rt.ledger()
+    assert led["expense"] == 720.0
+    usd = [c for c in led["by_currency"] if c["currency"] == "USD"][0]
+    assert usd["original_total"] == -100.0 and usd["base_total"] == -720.0
+    assert rt.transactions[0].amount_original == -100.0
+    assert rt.transactions[0].fx_rate == 7.2
+
+
+def test_汇率可改(tmp_path):
+    rt = _rt(tmp_path)
+    rt.fx.set_rate("USD", 7.0)
+    rt.record_text("花了100美金")
+    assert rt.ledger()["expense"] == 700.0
+    assert _rt(tmp_path).fx.rate("USD") == 7.0      # 汇率也落盘
+
+
+def test_按天与分类汇总(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("今天在星巴克花了32块钱")
+    led = rt.ledger()
+    assert led["count"] == 2
+    day = led["by_day"][0]
+    assert day["count"] == 2 and day["expense"] == -137.0
+    cats = {c["category"]: c["total"] for c in led["by_category"]}
+    assert cats["clothing"] == 105.0 and cats["food"] == 32.0
+
+
+def test_记账后账本可持久化(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("上个月5号买了双鞋300")
+    again = _rt(tmp_path)
+    assert len(again.transactions) == 2
+    assert again.ledger("2026-10")["expense"] == 300.0
+    assert again.ledger("2026-11")["expense"] == 105.0
+
+
+def test_未配置汇率按1比1并提示(tmp_path):
+    rt = _rt(tmp_path)
+    rt.fx.rates.pop("JPY", None)          # 模拟"币种认识但没配汇率"
+    rec = rt.record_text("花了100日元")
+    assert any("汇率" in w for w in rec["recorded"][0]["warnings"])
+    assert rt.ledger()["expense"] == 100.0

package/python/tests/test_finance_persist.py

@@ -0,0 +1,178 @@
+"""财务内核持久化 — 重启不丢账、坏文件不阻断启动、批量导入不逐笔写盘。
+
+背景:交易/预算/余额原先只在内存,后端一重启就清零,财务分析永远是"0 笔交易"。
+这里固定住三件事:
+  1. 写进去的状态能被**新实例**读回来(真正的重启等价);
+  2. 文件损坏 / 单条记录坏 / 落盘失败时,一律降级并把错误暴露出来,不抛、不阻断启动;
+  3. 批量导入只做一次磁盘 IO。
+"""
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.finance import FinanceRuntime, Transaction
+
+CSV = str(Path(__file__).parent.parent / "examples" / "sample_transactions.csv")
+
+
+def _rt(tmp_path, data_name="finance_data.json"):
+    """临时目录里的 runtime:policy 与数据都写在 tmp_path,不污染工作区。"""
+    return FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                          data_path=str(tmp_path / data_name))
+
+
+def test_落盘点默认与policy同目录(tmp_path):
+    rt = FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"))
+    assert rt._data_path == tmp_path / "finance_data.json"
+
+
+def test_交易预算余额重启后可恢复(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-88.5, category="food",
+                                   entity="星巴克", account="debit",
+                                   tags=["recurring"], note="早餐"))
+    rt.add_transaction(Transaction(amount=12000, category="salary",
+                                   entity="公司", account="debit"))
+    rt.set_budget("food", 400)
+    rt.set_balance("debit", 11800)
+
+    assert rt.save() is True
+    assert (tmp_path / "finance_data.json").exists()
+
+    # 新实例 = 进程重启后的状态
+    rt2 = _rt(tmp_path)
+    assert len(rt2.transactions) == 2
+    assert rt2.transactions[0].amount == -88.5
+    assert rt2.transactions[0].entity == "星巴克"
+    assert rt2.transactions[0].note == "早餐"
+    assert rt2.transactions[0].tags == ["recurring"]
+    assert rt2.transactions[1].amount == 12000
+    assert len(rt2.budgets) == 1 and rt2.budgets[0].monthly_limit == 400
+    assert rt2.account_balances == {"debit": 11800}
+    # 实体统计随交易一起恢复(重启后 trace_category / status 不该突然归零)
+    assert rt2.entities["星巴克"].txn_count == 1
+    assert rt2.entities["星巴克"].entity_type == "subscription"
+    assert rt2.entities["公司"].total_amount == 12000
+
+
+def test_写入即落盘下次实例自动加载(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-20, category="transport",
+                                   entity="地铁", account="debit"))
+    rt.set_balance("debit", 100)
+
+    loaded = _rt(tmp_path)
+    assert loaded.load()  # 已显式 load 过,再次 load 幂等
+    assert len(loaded.transactions) == 1
+    assert loaded.status()["persist"]["load_error"] == ""
+
+
+def test_文件格式合法且带版本(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-1, category="misc",
+                                   entity="x", account="debit"))
+    data = json.loads((tmp_path / "finance_data.json").read_text(encoding="utf-8"))
+    assert data["version"] == 1
+    assert data["saved_at"]
+    assert len(data["transactions"]) == 1
+
+
+def test_损坏文件不阻断启动且可自愈(tmp_path):
+    p = tmp_path / "finance_data.json"
+    p.write_text("{ 这不是 json ", encoding="utf-8")
+
+    rt = _rt(tmp_path)              # 构造本身不得抛
+    assert rt.transactions == [] and rt.budgets == []
+    assert rt.load_error                    # 错误必须可见,不能静默吞掉
+
+    rt.add_transaction(Transaction(amount=-5, category="misc",
+                                   entity="y", account="debit"))
+    assert rt.save() is True
+    assert rt.load_error == ""              # 覆盖写成功后重新可读
+    assert len(_rt(tmp_path).transactions) == 1
+
+
+def test_顶层非对象也降级(tmp_path):
+    (tmp_path / "finance_data.json").write_text("[1, 2, 3]", encoding="utf-8")
+    rt = _rt(tmp_path)
+    assert rt.transactions == []
+    assert "JSON 对象" in rt.load_error
+
+
+def test_单条坏记录只跳过自己不废掉整份(tmp_path):
+    (tmp_path / "finance_data.json").write_text(json.dumps({
+        "version": 1,
+        "transactions": [
+            {"amount": -10, "category": "food", "entity": "a", "account": "debit"},
+            {"category": "food"},            # 缺 amount/entity/account → 跳过
+            "not-a-dict",                    # 非对象 → 跳过
+            {"amount": -20, "category": "food", "entity": "b", "account": "debit"},
+        ],
+        "budgets": [{"category": "food", "monthly_limit": 300}],
+        "account_balances": {"debit": "not-a-number", "cash": 50},
+    }, ensure_ascii=False), encoding="utf-8")
+
+    rt = _rt(tmp_path)
+    assert [t.entity for t in rt.transactions] == ["a", "b"]
+    assert len(rt.budgets) == 1
+    assert rt.account_balances == {"cash": 50.0}   # 坏值单独跳过
+
+
+def test_实体段缺失时按交易重建(tmp_path):
+    (tmp_path / "finance_data.json").write_text(json.dumps({
+        "transactions": [
+            {"amount": -30, "category": "subscription", "entity": "Netflix",
+             "account": "card", "tags": ["recurring"]},
+            {"amount": -10, "category": "food", "entity": "Netflix", "account": "card"},
+        ],
+    }, ensure_ascii=False), encoding="utf-8")
+
+    rt = _rt(tmp_path)
+    assert rt.entities["Netflix"].txn_count == 2
+    assert rt.entities["Netflix"].total_amount == -40
+    assert rt.entities["Netflix"].entity_type == "subscription"
+
+
+def test_批量导入只写一次盘(tmp_path, monkeypatch):
+    rt = _rt(tmp_path)
+    calls = []
+    orig = rt.save
+
+    def _counting_save():
+        calls.append(1)
+        return orig()
+
+    monkeypatch.setattr(rt, "save", _counting_save)
+    n = rt.import_csv(CSV)
+    assert n > 0
+    assert len(calls) == 1, f"导入 {n} 笔应只落盘 1 次,实为 {len(calls)} 次"
+    assert len(_rt(tmp_path).transactions) == n
+
+
+def test_落盘失败只回报不抛异常(tmp_path):
+    blocker = tmp_path / "blocker"
+    blocker.write_text("我是个文件,不是目录", encoding="utf-8")
+    # 父目录被一个文件占住 → mkdir/写入必失败
+    rt = FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                        data_path=str(blocker / "finance_data.json"))
+    assert rt.save() is False
+    assert rt.save_error                   # 失败原因必须留痕
+    # 内存里的数据仍在,用户这次会话不至于丢东西
+    rt.add_transaction(Transaction(amount=-1, category="misc",
+                                   entity="z", account="debit"))
+    assert len(rt.transactions) == 1
+    assert rt.status()["persist"]["save_error"]
+
+
+def test_分析使用持久化后的数据(tmp_path):
+    rt = _rt(tmp_path)
+    rt.set_budget("food", 100)
+    rt.add_transaction(Transaction(amount=-150, category="food",
+                                   entity="餐厅", account="debit"))
+
+    report = _rt(tmp_path).analyze(period="2026-11")
+    assert report["transaction_count"] == 1
+    food = [b for b in report["budget_status"] if b["category"] == "food"]
+    assert food and food[0]["is_over"] is True