changes

2026-04-02 23:40:34 -04:00
parent 1c560c6df2
commit 4cd7357aa0
73 changed files with 7076 additions and 0 deletions
--- a/docs/specs/2026-04-03-fusion-accounting-design.md
+++ b/docs/specs/2026-04-03-fusion-accounting-design.md
@@ -0,0 +1,581 @@
+# fusion_accounting -- AI Accounting Co-Pilot for Odoo 19
+
+**Module:** `fusion_accounting`
+**Version:** 1.0
+**Odoo:** 19.0 Enterprise
+**Date:** April 3, 2026
+**Status:** Design Specification
+
+---
+
+## 1. Purpose
+
+An Odoo 19 module that embeds an AI agent (Claude / GPT with tool-calling) into the Accounting menu. The agent can query, analyze, reconcile, audit, and report on every aspect of the accounting system through a conversational interface backed by a dashboard.
+
+The module serves three user types: business owner (strategic oversight), office staff (daily processing), and external accountant (period-end work). It starts with tiered permissions (read-free, low-risk auto-approved, high-risk requires approval) and adapts over time by promoting tool+scenario combinations that achieve high approval rates.
+
+---
+
+## 2. Architecture
+
+### 2.1 Component Overview
+
+```
+fusion_accounting (Odoo Module)
+├── AI Service Layer
+│   ├── Agent orchestrator (prompt + tool dispatch)
+│   ├── Claude adapter (Anthropic API, tool-calling)
+│   ├── GPT adapter (OpenAI API, function-calling)
+│   └── Provider config (switchable via settings)
+│
+├── Tool Layer (73+ Odoo ORM wrappers across 12 domains)
+│   ├── Each tool: name, description, parameters, tier, domain
+│   ├── Registered in fusion.accounting.tool model
+│   └── Callable by AI via orchestrator dispatch
+│
+├── Rules Engine (Fusion Rules)
+│   ├── fusion.accounting.rule model
+│   ├── Created by admin or AI (with approval)
+│   ├── Applied before general AI reasoning
+│   └── Versioned with rollback
+│
+├── Memory Layer
+│   ├── fusion.accounting.match.history (every suggestion + outcome)
+│   ├── fusion.accounting.session (chat sessions)
+│   └── Confidence scoring per tool+scenario
+│
+├── Dashboard
+│   ├── Health cards (bank recon, AR, AP, HST, audit, month-end)
+│   ├── Action center (prioritized needs-attention + recent activity)
+│   └── Chat panel (persistent, context-aware)
+│
+└── Odoo Integration
+    ├── Menu: Accounting > Fusion AI
+    ├── Cron: periodic audit scan on posted entries
+    ├── Hook: post-action_post audit check (optional)
+    └── Security: role-based tool access
+```
+
+### 2.2 Data Flow
+
+User message or dashboard click enters the controller. The controller builds a prompt containing: the user message, active Fusion Rules, recent match history, current Odoo context (page, journal, period), and the tool definitions for the relevant domain(s). This prompt goes to the selected AI provider.
+
+The AI responds with either a text message or one or more tool calls. Tool calls are dispatched to the tool layer, which executes ORM operations against Odoo. Results return to the AI for further reasoning or final response. Tier 3 tool calls are intercepted and presented to the user for approval before execution.
+
+### 2.3 AI Provider Integration
+
+Both Claude (Anthropic) and GPT (OpenAI) are supported via adapters that normalize the tool-calling interface.
+
+- **Claude:** Uses `tools` parameter with `input_schema` per tool. Responses include `tool_use` content blocks.
+- **GPT:** Uses `functions` parameter with JSON Schema per function. Responses include `function_call` in the message.
+- **Adapter pattern:** Each adapter translates between the normalized internal tool format and the provider-specific format. Switching providers requires only changing a config setting.
+
+API keys are stored in `ir.config_parameter` with the `fusion_accounting.` prefix.
+
+---
+
+## 3. Tool Catalog
+
+### 3.1 Tool Tiers
+
+| Tier | Behavior | Examples |
+|---|---|---|
+| **1 -- Free** | Execute immediately, no approval. All read-only operations. | `get_unreconciled_bank_lines`, `calculate_hst_balance`, `get_ar_aging` |
+| **2 -- Auto-approved** | Execute immediately, logged. Low-risk writes that annotate but don't change financial data. | `flag_entry`, `set_audit_status`, `send_followup` (draft) |
+| **3 -- Requires approval** | AI proposes, user approves/rejects. Financial writes. | `match_bank_line_to_payments`, `reconcile_payment_to_invoice`, `create_payroll_journal_entry` |
+
+Tier promotion: when a Tier 3 tool+scenario combination reaches a configurable accuracy threshold (default 95%) over a minimum sample size (default 30 decisions), it is promoted to Tier 2. Promotions can be reverted by the admin.
+
+### 3.2 Domain 1 -- Bank Reconciliation
+
+| Tool | Tier | Odoo Method | Purpose |
+|---|---|---|---|
+| `get_unreconciled_bank_lines` | 1 | `account.bank.statement.line.search_read(is_reconciled=False)` | List unreconciled bank statement lines with filters |
+| `get_unreconciled_receipts` | 1 | `account.move.line.search_read(account_id=1122, reconciled=False)` | List unreconciled Outstanding Receipts entries |
+| `match_bank_line_to_payments` | 3 | `account.bank.statement.line.set_line_bank_statement_line(move_line_ids)` | Match a bank line to one or more payment journal items |
+| `auto_reconcile_bank_lines` | 3 | `account.bank.statement.line._try_auto_reconcile_statement_lines()` | Run Odoo's built-in auto-reconciliation |
+| `apply_reconcile_model` | 3 | `account.reconcile.model._trigger_reconciliation_model(st_line)` | Apply a specific reconciliation model/rule |
+| `unmatch_bank_line` | 3 | `account.bank.statement.line.action_unreconcile_entry()` | Undo a reconciliation |
+| `get_reconcile_suggestions` | 1 | `account.reconcile.model.get_available_reconcile_model_per_statement_line()` | Get Odoo's suggested reconciliation models |
+| `sum_payments_by_date` | 1 | SQL aggregate on `account.move.line` | Sum card payments for a date range (Elavon batch matching) |
+
+### 3.3 Domain 2 -- HST/GST Management
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `calculate_hst_balance` | 1 | Net HST position (collected on 2005 minus ITCs on 2006) for a period |
+| `get_tax_report` | 1 | Generate tax report via `account.report` generic tax handler |
+| `find_missing_tax_invoices` | 1 | Invoices with taxable products but no tax applied |
+| `find_missing_itc_bills` | 1 | Vendor bills without input tax credits |
+| `get_tax_return_status` | 1 | Status of periodic tax returns via `account.return` |
+| `generate_tax_return` | 2 | Refresh tax return data via `account.return._generate_or_refresh_all_returns()` |
+| `validate_tax_return` | 3 | Mark tax return as validated |
+
+### 3.4 Domain 3 -- Accounts Receivable
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_ar_aging` | 1 | AR aging buckets (current, 30, 60, 90+) |
+| `get_overdue_invoices` | 1 | Invoices past due with partner contact info |
+| `get_partner_balance` | 1 | Single partner AR balance and open items |
+| `send_followup` | 2 | Draft follow-up email via `res.partner.execute_followup()` |
+| `get_followup_report` | 1 | HTML follow-up report for a partner |
+| `reconcile_payment_to_invoice` | 3 | Match payment to invoice via `account.move.line.reconcile()` |
+| `get_unmatched_payments` | 1 | Payments not matched to invoices |
+
+### 3.5 Domain 4 -- Accounts Payable
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_ap_aging` | 1 | AP aging buckets |
+| `find_duplicate_bills` | 1 | Same vendor + amount + date within configurable window |
+| `match_bill_to_po` | 1 | Cross-reference bill lines to PO lines |
+| `get_unpaid_bills` | 1 | Vendor bills with outstanding balance |
+| `verify_bill_taxes` | 1 | Check bill tax vs fiscal position expectation |
+| `get_payment_schedule` | 1 | Bills sorted by due date for cash planning |
+
+### 3.6 Domain 5 -- Journal Review and Error Detection
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `find_wrong_direction_balances` | 1 | Accounts where balance direction contradicts account type |
+| `find_duplicate_entries` | 1 | Entries with matching partner + amount + date + journal |
+| `find_wrong_account_entries` | 1 | Product lines on unlikely accounts (e.g., revenue on tax account) |
+| `find_sequence_gaps` | 1 | `account.move` records where `made_sequence_gap = true` |
+| `find_draft_entries` | 1 | Draft entries that should have been posted or deleted |
+| `find_unreconciled_suspense` | 1 | Suspense/clearing accounts with non-zero balance |
+| `verify_reconciliation_integrity` | 1 | Check `account.partial.reconcile` consistency |
+
+### 3.7 Domain 6 -- Month-End / Year-End Close
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_close_checklist` | 1 | Aggregate all domain checks into a period close checklist |
+| `get_unreconciled_counts` | 1 | Per-account count of unreconciled items |
+| `find_entries_in_locked_period` | 1 | Entries after lock dates |
+| `get_accrual_status` | 1 | Balance on accrual accounts (vacation, sick, etc.) |
+| `run_hash_integrity_check` | 1 | `res.company._check_hash_integrity()` |
+| `get_period_summary` | 1 | Trial balance for the closing period |
+
+### 3.8 Domain 7 -- Payroll Verification
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_payroll_entries` | 1 | Journal entries in payroll-related journals |
+| `compare_payroll_to_bank` | 1 | Cross-reference payroll cheques to bank statement lines |
+| `verify_source_deductions` | 1 | CPP + EI + tax calculation verification against CRA tables |
+| `get_cra_remittance_status` | 1 | CRA payable balance vs payments made |
+| `find_unmatched_payroll_cheques` | 1 | Bank cheques without matching payroll entry |
+
+### 3.9 Domain 8 -- Inventory and COGS
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_stock_valuation` | 1 | Stock In Hand (1069) balance and layers |
+| `get_price_differences` | 1 | Entries on account 5010 (PO price vs bill price) |
+| `get_cogs_ratio_by_category` | 1 | COGS vs revenue per product category |
+| `find_unusual_adjustments` | 1 | Large inventory adjustment entries |
+| `get_inventory_turnover` | 1 | Sales vs average inventory |
+
+### 3.10 Domain 9 -- ADP Reconciliation
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_adp_receivable_aging` | 1 | Aging on account 1101 (ADP Receivable) |
+| `match_adp_payment_to_invoice` | 3 | Match ADP deposit to ADP invoices |
+| `verify_adp_split` | 1 | Customer portion + ADP portion = invoice total |
+| `find_adp_without_payment` | 1 | ADP invoices without matching government deposit |
+| `get_adp_summary` | 1 | Period summary of ADP billing vs collection |
+
+### 3.11 Domain 10 -- Financial Reporting
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `get_profit_loss` | 1 | P&L via `account.report` |
+| `get_balance_sheet` | 1 | Balance sheet via `account.report` |
+| `get_trial_balance` | 1 | Trial balance via `account.report` |
+| `get_cash_flow` | 1 | Cash flow via `account.report` |
+| `compare_periods` | 1 | Two period reports side by side |
+| `answer_financial_question` | 1 | Natural language to ORM/SQL query |
+| `export_report` | 2 | `account.report.export_to_pdf()` or `export_to_xlsx()` |
+
+### 3.12 Domain 11 -- Audit and Integrity
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `audit_posted_entry` | 1 | Run all entry-level checks on a single `account.move` |
+| `audit_account_balances` | 1 | Run all account-level checks (wrong direction, stale items) |
+| `audit_tax_compliance` | 1 | All tax checks (missing tax, wrong rate, exempt verification) |
+| `audit_reconciliation_integrity` | 1 | Verify `account.partial.reconcile` / `account.full.reconcile` consistency |
+| `check_hash_chain` | 1 | `res.company._check_hash_integrity()` |
+| `check_sequence_gaps` | 1 | `account.journal._query_has_sequence_holes()` |
+| `flag_entry` | 2 | Create chatter message on `account.move` with flag and recommendation |
+| `get_audit_status` | 1 | `account.audit.account.status` per tax return |
+| `set_audit_status` | 2 | Update review status (todo / reviewed / supervised / anomaly) |
+| `get_audit_trail` | 1 | `mail.message` history for an `account.move` |
+| `run_full_audit` | 1 | All checks across all domains for a period |
+| `get_audit_report` | 1 | Summary of all findings with severity ratings |
+
+### 3.13 Domain 12 -- Payroll Management
+
+| Tool | Tier | Purpose |
+|---|---|---|
+| `parse_payroll_summary` | 1 | Read pasted/uploaded QBO or fusion_payroll data |
+| `create_payroll_journal_entry` | 3 | `account.move.create()` with payroll debit/credit lines |
+| `get_payroll_schedule` | 1 | Employee pay dates, amounts, history |
+| `match_payroll_cheques` | 3 | Match bank cheques to payroll liabilities |
+| `verify_payroll_deductions` | 1 | Check CPP/EI/tax against CRA rate tables |
+| `get_cra_remittance_due` | 1 | Calculate CRA obligation vs payments made |
+| `prepare_cra_payment` | 3 | Create CRA remittance payment entry |
+| `generate_t4` | 2 | Trigger `fusion_payroll` T4 generation |
+| `generate_roe` | 2 | Trigger `fusion_payroll` ROE generation |
+| `get_payroll_cost_report` | 1 | Period summary by employee/department |
+
+Phase 1 (QBO bridge): tools work with pasted/uploaded payroll data.
+Phase 2 (fusion_payroll native): tools call fusion_payroll ORM methods directly.
+
+---
+
+## 4. Fusion Rules Engine
+
+### 4.1 Rule Model
+
+```
+fusion.accounting.rule
+├── name                    Char, required
+├── rule_type               Selection: match / classify / audit / fee / routing / followup
+├── description             Text (natural language, read by AI)
+├── trigger_domain          Text/JSON (Odoo domain filter for matching records)
+├── match_logic             Text (natural language matching instructions for AI)
+├── match_code              Text (optional Python for deterministic matching)
+├── fee_account_id          Many2one → account.account
+├── write_off_account_id    Many2one → account.account
+├── approval_tier           Selection: auto / needs_approval
+├── created_by              Selection: admin / ai
+├── confidence_score        Float (0.0 to 1.0)
+├── total_uses              Integer
+├── total_approved          Integer
+├── total_rejected          Integer
+├── promotion_threshold     Float (default 0.95)
+├── min_sample_size         Integer (default 30)
+├── active                  Boolean
+├── version                 Integer
+├── parent_rule_id          Many2one → self (version chain)
+├── journal_ids             Many2many → account.journal
+├── company_id              Many2one → res.company
+├── notes                   Text
+```
+
+### 4.2 Rule Lifecycle
+
+1. **Creation:** Admin creates via UI form, or AI proposes after detecting a pattern (3+ identical matches). AI-proposed rules start at Tier 3.
+2. **Application:** During reconciliation or auditing, the AI loads active rules and applies them before general reasoning. Rules with `match_code` run deterministically; rules with only `match_logic` are interpreted by the AI.
+3. **Scoring:** Each use updates `total_uses` and `total_approved` / `total_rejected`. Confidence score is recalculated.
+4. **Promotion:** When confidence crosses `promotion_threshold` with at least `min_sample_size` decisions, `approval_tier` changes from `needs_approval` to `auto`.
+5. **Modification:** Admin or AI (with approval) can edit. Changes increment `version` and create a new record linked via `parent_rule_id`. Confidence resets for the modified variant.
+6. **Rollback:** Admin can deactivate current version and reactivate a previous version.
+
+### 4.3 Rule Priority
+
+During processing, rules are evaluated in order:
+1. Admin-created rules (highest priority)
+2. AI-created rules with auto-approval (proven patterns)
+3. AI-created rules needing approval (proposed patterns)
+4. No rule matches: AI reasons from scratch using tools
+
+---
+
+## 5. Match History and Learning
+
+### 5.1 Match History Model
+
+```
+fusion.accounting.match.history
+├── session_id              Many2one → fusion.accounting.session
+├── tool_name               Char (which tool was called)
+├── tool_params             Text/JSON (parameters passed)
+├── tool_result             Text/JSON (result returned)
+├── ai_reasoning            Text (AI's explanation for the match)
+├── ai_confidence           Float (AI's self-assessed confidence)
+├── rule_id                 Many2one → fusion.accounting.rule (if rule-based)
+├── proposed_at             Datetime
+├── decision                Selection: approved / rejected / pending
+├── decided_at              Datetime
+├── decided_by              Many2one → res.users
+├── rejection_reason        Text (user's explanation if rejected)
+├── correct_action          Text/JSON (what should have happened, if corrected)
+├── bank_statement_line_id  Many2one → account.bank.statement.line
+├── move_line_ids           Many2many → account.move.line
+├── amount                  Monetary
+├── partner_id              Many2one → res.partner
+```
+
+### 5.2 How Learning Works
+
+The AI's system prompt includes the most recent N match history records (configurable, default 50) filtered to the current domain/scenario. This gives the AI context about:
+- What patterns have been approved (do more of this)
+- What was rejected and why (avoid this)
+- Partner-specific quirks (e.g., "Shirley Ramsumair: label unreliable")
+- Fee patterns (e.g., "Elavon: ~1.6% fee to 60545")
+- Timing patterns (e.g., "weekend card batches combine Fri+Sat")
+
+The AI does not have persistent memory across sessions beyond what is stored in match history and rules. Every session starts fresh with the system prompt + loaded history + loaded rules.
+
+---
+
+## 6. Dashboard
+
+### 6.1 Location
+
+Accounting menu > Fusion AI (submenu, next to Dashboard).
+
+### 6.2 Layout
+
+**Top row: 6 health cards.** Each shows a key metric with color coding (green/yellow/red). Clicking any card starts a relevant conversation in the chat panel.
+
+| Card | Metric | Source |
+|---|---|---|
+| Bank Reconciliation | Unmatched line count + total amount | `account.bank.statement.line` where `is_reconciled = False` |
+| AR Outstanding | Total receivable + overdue count | `account.move.line` on AR account, `amount_residual > 0` |
+| AP Due | Total payable + due this week | `account.move.line` on AP account, grouped by due date |
+| HST Balance | Net HST (collected minus ITCs) | Balances on accounts 2005 and 2006 |
+| Audit Score | Score 0-100 + active flag count | Weighted composite of all audit checks |
+| Month-End Status | Current period status + open items | Aggregate of close checklist items |
+
+**Middle: two-column action center.**
+
+Left column: "Needs Attention" -- AI-prioritized list of actionable items. Re-ranked daily by the audit cron. Items are clickable to start the relevant conversation.
+
+Right column: "Recent AI Activity" -- log of autonomous actions (Tier 2), pending approvals (Tier 3), and completed conversations. Provides transparency.
+
+**Bottom/Side: Chat panel.** Persistent across navigation within the Accounting module. Shows conversation history for the current session. Supports text input, file upload (for QBO payroll summaries), and structured approval cards for Tier 3 actions.
+
+### 6.3 Approval Cards
+
+When the AI proposes a Tier 3 action, the chat displays a structured card:
+
+```
+┌─────────────────────────────────────────────┐
+│ Match Proposal                    94% conf  │
+│                                             │
+│ Bank: Mar 4 elavon mrch svc      $697.61   │
+│ ↔ 4 card payments (Mar 3)        $709.14   │
+│ Fee to 60545 (Elavon Fee)         $11.53   │
+│                                             │
+│ AI: "Weekend daily batch, 1.6% fee"        │
+│                                             │
+│         [ Approve ]  [ Reject ]             │
+└─────────────────────────────────────────────┘
+```
+
+Batch mode: multiple cards can be displayed at once with "Approve All" / "Reject All" buttons plus individual controls.
+
+---
+
+## 7. Security
+
+### 7.1 Access Groups
+
+| Group | Dashboard | Chat (Read) | Chat (Tier 2) | Chat (Tier 3) | Rules | Config |
+|---|---|---|---|---|---|---|
+| `fusion_accounting.group_user` (Staff) | View | Yes | No | No | View | No |
+| `fusion_accounting.group_manager` (Manager) | View | Yes | Yes | Yes | Create/Edit | No |
+| `fusion_accounting.group_admin` (Admin) | View | Yes | Yes | Yes | Create/Edit | Yes |
+
+### 7.2 Tool-Level Security
+
+Each tool definition includes `required_groups`. The AI adapter filters available tools based on the current user's groups before building the prompt. A staff user's AI session simply does not have access to write tools.
+
+### 7.3 Audit Trail
+
+All AI actions are logged in `fusion.accounting.match.history` with the user who approved, timestamp, and full context. This is in addition to Odoo's standard chatter/mail tracking on modified records.
+
+---
+
+## 8. Module Structure
+
+```
+/mnt/extra-addons/fusion_accounting/
+├── __manifest__.py
+├── __init__.py
+├── models/
+│   ├── __init__.py
+│   ├── accounting_session.py         # Chat session model
+│   ├── accounting_match_history.py   # Match history (approved/rejected)
+│   ├── accounting_rule.py            # Fusion Rules
+│   ├── accounting_tool.py            # Tool registry model
+│   ├── accounting_config.py          # Settings (API keys, thresholds)
+│   └── accounting_dashboard.py       # Dashboard computed fields
+├── services/
+│   ├── __init__.py
+│   ├── agent.py                      # AI orchestrator (prompt assembly, tool dispatch loop)
+│   ├── adapters/
+│   │   ├── __init__.py
+│   │   ├── claude.py                 # Anthropic Claude adapter
+│   │   └── openai.py                 # OpenAI GPT adapter
+│   ├── tools/
+│   │   ├── __init__.py
+│   │   ├── bank_reconciliation.py    # Domain 1 tools
+│   │   ├── hst_management.py         # Domain 2 tools
+│   │   ├── accounts_receivable.py    # Domain 3 tools
+│   │   ├── accounts_payable.py       # Domain 4 tools
+│   │   ├── journal_review.py         # Domain 5 tools
+│   │   ├── month_end.py              # Domain 6 tools
+│   │   ├── payroll.py                # Domain 7 + 12 tools
+│   │   ├── inventory.py              # Domain 8 tools
+│   │   ├── adp.py                    # Domain 9 tools
+│   │   ├── reporting.py              # Domain 10 tools
+│   │   └── audit.py                  # Domain 11 tools
+│   ├── prompts/
+│   │   ├── system_prompt.py          # Base system prompt
+│   │   └── domain_prompts.py         # Per-domain context injections
+│   └── scoring.py                    # Confidence scoring + tier promotion logic
+├── controllers/
+│   ├── __init__.py
+│   └── chat_controller.py            # JSON endpoint for chat messages
+├── wizards/
+│   ├── __init__.py
+│   └── rule_wizard.py                # Quick-create rule from chat suggestion
+├── static/
+│   └── src/
+│       ├── components/
+│       │   ├── dashboard/
+│       │   │   ├── fusion_dashboard.js
+│       │   │   ├── fusion_dashboard.xml
+│       │   │   ├── health_card.js
+│       │   │   └── health_card.xml
+│       │   ├── chat/
+│       │   │   ├── chat_panel.js
+│       │   │   ├── chat_panel.xml
+│       │   │   ├── approval_card.js
+│       │   │   └── approval_card.xml
+│       │   └── rules/
+│       │       └── rule_form.js
+│       └── scss/
+│           ├── dashboard.scss
+│           └── chat.scss
+├── views/
+│   ├── dashboard_views.xml
+│   ├── session_views.xml
+│   ├── rule_views.xml
+│   ├── config_views.xml
+│   ├── match_history_views.xml
+│   └── menus.xml
+├── security/
+│   ├── security.xml                  # Groups
+│   └── ir.model.access.csv          # Model access rules
+├── data/
+│   ├── cron.xml                      # Periodic audit scan cron
+│   ├── tool_definitions.xml          # Seed tool registry
+│   └── default_rules.xml            # Starter Fusion Rules
+└── report/
+    └── audit_report_template.xml     # PDF audit report
+```
+
+---
+
+## 9. Implementation Phases
+
+### Phase 1: Foundation (estimated 2 weeks)
+
+Build the module skeleton, AI service layer, and first 2 domains.
+
+- Module skeleton: manifest, models, security, menu
+- AI service: agent orchestrator, Claude adapter, GPT adapter
+- Tool layer: Domain 1 (bank reconciliation) + Domain 5 (journal review)
+- Controller: chat endpoint (JSON-RPC)
+- Basic chat UI: simple text input/output in an Odoo form view (no OWL widget yet)
+- Match history model + logging
+- Test: reconcile a batch of bank lines via chat
+
+**Milestone:** Can reconcile bank statement lines through conversation.
+
+### Phase 2: Rules + More Domains (estimated 2 weeks)
+
+- Fusion Rules model + CRUD views
+- AI rule proposal flow (detect pattern, suggest rule, user approves)
+- Confidence scoring + tier promotion logic
+- Domains 2 (HST), 3 (AR), 4 (AP)
+- Approval card flow for Tier 3 actions
+
+**Milestone:** Can prepare HST filing, chase overdue invoices, and auto-create matching rules.
+
+### Phase 3: Dashboard + Audit (estimated 2 weeks)
+
+- OWL dashboard with health cards
+- OWL chat panel (persistent side panel)
+- Approval cards with approve/reject buttons
+- Domain 11 (audit) with cron-based periodic scanning
+- Domain 6 (month-end close)
+
+**Milestone:** Dashboard shows accounting health at a glance. Audit cron flags issues automatically.
+
+### Phase 4: Remaining Domains + Polish (estimated 2 weeks)
+
+- Domains 7-10 (payroll verification, inventory, ADP, reporting)
+- Domain 12 (payroll management -- QBO bridge for Phase 1, fusion_payroll-ready)
+- Export/report tools (PDF, XLSX)
+- Batch approval mode
+- Learning/adaptation refinements
+- Documentation
+
+**Milestone:** Full 12-domain AI accounting co-pilot operational.
+
+---
+
+## 10. Dependencies
+
+### Odoo Modules (required)
+
+- `account` (core accounting)
+- `account_accountant` (enterprise bank reconciliation)
+- `account_reports` (enterprise reporting + tax returns + audit status)
+- `account_followup` (AR follow-ups)
+- `mail` (chatter integration for flagging)
+
+### Odoo Modules (optional, enhanced features if installed)
+
+- `account_budget` (budget tools)
+- `account_asset` (asset depreciation tools)
+- `account_batch_payment` (batch payment tools)
+- `fusion_payroll` (native payroll integration for Domain 12 Phase 2)
+- `fusion_poynt` (Poynt terminal data for card payment matching)
+- `stock_account` (inventory valuation tools)
+
+### External
+
+- Anthropic API key (for Claude) OR OpenAI API key (for GPT) -- at least one required
+- Python packages: `anthropic`, `openai` (installed in Odoo container)
+
+---
+
+## 11. Configuration
+
+Settings page at: Accounting > Fusion AI > Configuration
+
+| Setting | Type | Default |
+|---|---|---|
+| AI Provider | Selection (claude / openai) | claude |
+| Anthropic API Key | Char (password field) | -- |
+| OpenAI API Key | Char (password field) | -- |
+| Claude Model | Char | claude-sonnet-4-20250514 |
+| OpenAI Model | Char | gpt-4o |
+| Tier 3 Promotion Threshold | Float | 0.95 |
+| Tier 3 Min Sample Size | Integer | 30 |
+| Audit Cron Frequency | Selection (daily / weekly / monthly) | daily |
+| Match History in Prompt | Integer (recent N records) | 50 |
+| Max Tool Calls Per Turn | Integer | 20 |
+| Enable Post-Action Audit Hook | Boolean | False |
+
+---
+
+## 12. Risks and Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| AI calls wrong tool or wrong parameters | Tiered permissions; Tier 3 requires human approval; tool parameter validation in each tool function |
+| AI hallucinates financial data | All data comes from Odoo ORM queries, not AI generation. AI reasons about data but cannot invent it. |
+| Reconciliation error corrupts books | All reconciliation uses Odoo's native engine (`set_line_bank_statement_line`, `reconcile`). Reversible via `action_unreconcile_entry`. |
+| API costs escalate | Token usage tracked per session. Max tool calls per turn limits runaway loops. Model selection (cheaper models for simple queries). |
+| Learning from bad patterns | Confidence scoring requires minimum sample size. Admin can demote promoted tools. Rule versioning with rollback. |
+| Sensitive data in API calls | Financial data sent to AI provider. Mitigate by using AI provider's data privacy agreements. No customer PII in tool descriptions. Partner names in transaction data are necessary for matching. |