Odoo-Modules/fusion_accounting_followup/CLAUDE.md

fusion_accounting_followup — Cursor / Claude Context

Purpose

AI-augmented customer follow-ups (dunning) — a Fusion-native replacement for (and coexisting with) Odoo Enterprise's account_followup module. Ships in Phase 4 of the fusion_accounting roadmap.

Architecture

Hybrid: the engine (fusion.followup.engine, AbstractModel) is the SINGLE write surface for the follow-up lifecycle. Everything else (controllers, OWL components, AI tools, wizards, cron) routes through the engine's 7-method public API:

• get_overdue_for_partner(partner)
• compute_followup_level(partner)
• send_followup_email(partner, level=None, force=False)
• escalate_to_next_level(partner)
• pause_followup(partner, until_date=None)
• reset_followup(partner)
• snapshot_followup_history(partner, limit=50)

Pure-Python services live in services/:

• overdue_aging — 6 buckets (current, 1-30, 31-60, 61-90, 91-120, 120+)
• level_resolver — match aging to a fusion.followup.level
• risk_scorer — 0-100 payment-risk score plus structured drivers
• tone_selector — gentle / firm / legal based on level + risk
• followup_text_generator + followup_text_prompt — LLM-generated follow-up text with a templated fallback that keeps the feature usable offline

Persisted models in models/:

• fusion.followup.level — level definition (delay_days, tone, mail_template_id, requires_manual_review, sequence)
• fusion.followup.run — per-partner audit record (state, level, amount, ai-generated flag, error captured)
• fusion.followup.text.cache — LLM cost-saving cache keyed on (partner, level, tone, prompt fingerprint)
• fusion.followup.engine — AbstractModel (the API)
• fusion.followup.cron — cron handlers (daily scan, weekly risk refresh)
• res.partner (inherits) — adds fusion_followup_status, fusion_followup_paused_until, fusion_followup_last_level_id, fusion_followup_risk_score, fusion_followup_risk_band
• account.move.line (inherits) — adds fusion_followup_level_id and fusion_followup_last_run_date

Wizards (TransientModel) in wizards/:

• fusion.batch.followup.wizard — bulk-send across all overdue customers, a manual selection, or a level-filtered subset; supports auto_resolve_level, override_level_id, and force flags

Controllers: controllers/followup_controller.py exposes 6 JSON-RPC endpoints under /fusion/followup/* (list_overdue, get_partner, compute_level, send, escalate, pause, reset, history, generate_text). All calls route through the engine.

OWL frontend: static/src/

• services/followup_service.js — central reactive state + RPC wrappers
• views/followup_dashboard/* — top-level dashboard view
• components/risk_badge, partner_card, aging_bucket_strip, ai_text_panel, followup_history_table — 5 components
• scss/_variables.scss + followup.scss + dark_mode.scss
• tours/followup_tours.js — 5 OWL tour smoke tests

Default data:

• data/followup_levels_data.xml — 3 default levels (Reminder @ 7d gentle, Warning @ 30d firm, Legal Notice @ 60d legal)
• data/mail_templates_data.xml — 3 mail templates wired to the levels
• data/cron.xml — daily scan + weekly risk refresh

Coexistence

When account_followup is installed the Customer Follow-ups menu hides via fusion_accounting_core.group_fusion_show_when_enterprise_absent. The engine + AI tools always remain available for the chat / API. The migration step in fusion.migration.wizard backfills fusion.followup.level records from existing account_followup.followup.line rows (idempotent — skips rows already linked via the legacy_followup_line_id column).

V19 Conventions Applied

• _sql_constraints → models.Constraint (every persisted model)
• @api.depends('id') → not used (would raise NotImplementedError)
• @route(type='json') → type='jsonrpc' (all 6 endpoints in controllers/followup_controller.py)
• numbercall removed from ir.cron (data/cron.xml)
• res.groups.users → user_ids and ir.ui.menu.groups_id → group_ids (security + menu_views.xml)
• SCSS: @import "variables" is forbidden in V19; rely on manifest asset concatenation order (_variables.scss first)
• OWL t-on-click arrow handlers must use an explicit this. reference

Performance baseline (Task 21)

Operation	P95	Budget
engine.compute_followup_level	0ms	50ms
engine.get_overdue_for_partner	1ms	100ms
engine.send_followup_email (no due)	0ms	200ms
controller.list_overdue (20 ptrs)	100ms	500ms

(Engine ops measured against partners with no overdue lines — these are floor measurements; load-driven scaling is verified in test_performance_benchmarks.py.) All Phase 4 perf metrics are within 1x of budget; no optimization needed at ship.

Test counts (Phase 4 ship)

• 106 logical tests in fusion_accounting_followup
• 0 failures, 0 errors
• Coverage includes: 4 engine + 1 controller benchmark (tagged benchmark), 1 local LLM smoke (tagged local_llm, skips when no LLM), 5 OWL tour tests (tagged tour, skip without websocket-client), Hypothesis property tests on the engine, integration tests on the public API, controller round-trip tests, cron tests, batch wizard tests, coexistence tests, migration round-trip test.

Known concerns / Phase 4.5 backlog

• risk_scorer._compute_risk paid_late_count and avg_days_late are placeholders; full reconciliation traversal deferred for performance.
• Migration tone heuristic could misclassify Enterprise levels with non-standard sequence numbers (numeric sequence outside 1/10/100 buckets).
• pause_followup / reset_followup do not sudo() the partner write — could fail for non-admin users without partner-write rights.
• Email send is best-effort — failure is captured on the fusion.followup.run record but does not raise.
• followup_text_generator always returns a usable dict (templated fallback when LLM absent), so callers can't distinguish "AI said so" from "fallback fired"; the tone_used and absence of key_points are the only signals.
• Sub-second SLA on controller.list_overdue for partner counts > 200 is not yet stress-tested.