diff --git a/fusion_accounting_followup/CLAUDE.md b/fusion_accounting_followup/CLAUDE.md new file mode 100644 index 00000000..f9ce5ce3 --- /dev/null +++ b/fusion_accounting_followup/CLAUDE.md @@ -0,0 +1,142 @@ +# 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. diff --git a/fusion_accounting_followup/README.md b/fusion_accounting_followup/README.md new file mode 100644 index 00000000..02347676 --- /dev/null +++ b/fusion_accounting_followup/README.md @@ -0,0 +1,66 @@ +# fusion_accounting_followup + +AI-augmented customer follow-ups (dunning) for Odoo 19 Community — a +Fusion-native replacement for Enterprise's `account_followup` module. + +## What it does + +- Multi-level dunning sequences (gentle reminder, firm warning, legal + notice) with delay-day cadence per level +- 6-bucket aging analysis (current, 1-30, 31-60, 61-90, 91-120, 120+) + per customer +- Per-partner follow-up state machine (`current`, `action_due`, + `paused`, `blocked`, `with_credit_team`) +- Daily cron that scans overdue customers and queues / sends follow-ups +- Weekly cron that refreshes the AI risk score on every overdue customer +- Mail templates per level, with per-partner context interpolation +- Batch wizard for bulk-send across all overdue customers, an + arbitrary selection, or a level-filtered subset +- Per-partner follow-up history with state, level, and amount audit +- AI augmentation: + - **Payment-risk scoring** — 0-100 score plus structured drivers + (paid-late ratio, longest-overdue band, recent dispute, etc.) + - **Tone selection** — gentle / firm / legal based on level + risk + - **Follow-up text generation** — LLM-driven subject + body keyed + on tone, with a templated keyword fallback so the feature still + works offline +- Coexists with Enterprise `account_followup` (Enterprise wins by + default; the Fusion menu only appears when Enterprise is uninstalled) +- Migration-aware: bootstrap step backfills `fusion.followup.level` + records from existing `account_followup.followup.line` rows so the AI + has memory from day 1 + +## Quick start + +```bash +# Install (sub-module) +odoo --addons-path=... -i fusion_accounting_followup + +# Or install the whole suite via the meta-module +odoo --addons-path=... -i fusion_accounting + +# Open the dashboard (when Enterprise's account_followup is NOT installed) +# Apps -> Customer Follow-ups -> Overdue Customers + +# When Enterprise IS installed: use Enterprise's UI; the engine + AI tools +# are still available via the AI chat. +``` + +## Configuration + +- Local LLM (LM Studio, Ollama): + - `fusion_accounting.openai_base_url` = + `http://host.docker.internal:1234/v1` + - `fusion_accounting.openai_model` = your local model name + - `fusion_accounting.openai_api_key` = `lm-studio` (anything non-empty) + - `fusion_accounting.provider.followup_text` = `openai` + +## Public API (engine) + +`fusion.followup.engine` is the single write surface. See `CLAUDE.md` +for the full 7-method signature list. + +## See also + +- `CLAUDE.md` — agent context +- `UPGRADE_NOTES.md` — Odoo version anchoring diff --git a/fusion_accounting_followup/UPGRADE_NOTES.md b/fusion_accounting_followup/UPGRADE_NOTES.md new file mode 100644 index 00000000..a3193f49 --- /dev/null +++ b/fusion_accounting_followup/UPGRADE_NOTES.md @@ -0,0 +1,56 @@ +# fusion_accounting_followup — Upgrade Notes + +## Odoo Version Anchor + +This module targets **Odoo 19.0** (community-base). + +Reference snapshot of Enterprise code mirrored from: +- `account_followup` (Odoo 19.0.x) +- Source: `/Users/gurpreet/Github/RePackaged-Odoo/accounting/account_followup/` + +## Cross-Version Diff Strategy + +When a new Odoo version ships: + +1. Run `check_odoo_diff.sh` (in repo root) against the new Enterprise + version +2. Note any breaking changes in `account_followup.followup.line`, + `res.partner` follow-up fields, or mail-template invocation API +3. For mirrored OWL components, diff Enterprise's new versions against + ours and port material changes (signature renames, new behaviour we + want to inherit) +4. Re-run the full test suite + tour tests against the new Odoo version +5. Update this file with the new version anchor and any deviations + +## V19 Migration Notes (already 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"` removed; manifest concatenation order + (`_variables.scss` first) provides the variables to the rest of the + asset bundle +- OWL `t-on-click` arrow handlers always close over an explicit `this.` + +## Phase 4 → Phase 4.5 Migration + +If we ship Phase 4.5 (full `paid_late_count` traversal, sub-annual +follow-up cadences, multi-currency aggregation in `risk_scorer`, +admin-only pause sudo wrapper), changes will go in incremental commits. +No DB migration needed (Phase 4 schema is forward-compatible — new +columns will be nullable / default-valued). + +## Coexistence with Enterprise `account_followup` + +The migration step in `fusion.migration.wizard` backfills +`fusion.followup.level` records from existing +`account_followup.followup.line` rows. It is idempotent (skips rows +already linked via the `legacy_followup_line_id` column). + +When `account_followup` is installed the Customer Follow-ups menu hides +via `fusion_accounting_core.group_fusion_show_when_enterprise_absent`. +The engine and AI tools remain available for chat-driven workflows.