update

docs/plans/2026-03-14-fusion-api-design.md

@@ -0,0 +1,79 @@
+# Fusion API - Design Document
+
+**Goal:** Build a standalone Odoo 19 module (`fusion_api`) serving as the central hub for API key management, usage tracking, rate limiting, and access control across all Fusion products.
+
+**Architecture:** Dedicated Odoo application with a provider/key vault, auto-detected consumer modules, per-module and per-user access rules with budget caps and rate limits, granular usage logging with daily aggregation, and an OWL dashboard. Other Fusion modules call `self.env['fusion.api.service']` methods which handle key retrieval, access checks, usage logging, and API execution.
+
+**Tech Stack:** Odoo 19, Python 3.12, OWL 2, OpenAI SDK (optional), Anthropic SDK (optional)
+
+---
+
+## Scope
+
+### In Scope
+- Shared service keys: OpenAI, Anthropic, Google Maps, Twilio
+- OAuth services: Google OAuth, Microsoft OAuth
+- Usage tracking: per module, per feature, per user, per AI model
+- Rate limiting: global budgets, per-module budgets, RPM/RPD limits, per-user limits
+- Access control: enable/disable per module, per user blocking
+- Auto-detection of consumer modules on first API call
+- OWL dashboard with usage stats and charts
+
+### Out of Scope
+- Shipping carrier credentials (stay on `delivery.carrier`)
+- Payment provider credentials (stay on `payment.provider`)
+- Migrating existing modules (phased rollout later)
+
+---
+
+## Data Model
+
+### `fusion.api.provider`
+API service providers (OpenAI, Anthropic, Google Maps, etc.). Pre-seeded with known providers.
+
+### `fusion.api.key`
+Credential storage per provider. Supports simple API keys and OAuth (client_id/secret/tokens). Masked in UI, system-group access only. Multiple keys per provider with default selection.
+
+### `fusion.api.consumer`
+Auto-detected Fusion modules. Created automatically when a module first calls the API service. Links to `ir.module.module`. Master kill switch per module.
+
+### `fusion.api.access`
+Access rules linking consumers to providers. Configures: enable/disable, monthly/daily budget caps, RPM/RPD rate limits. Computed fields show current usage and budget percentage.
+
+### `fusion.api.user.limit`
+Optional per-user overrides. Monthly budget, daily request cap, manual block toggle.
+
+### `fusion.api.usage`
+Individual API call log. Full granularity: consumer, provider, user, feature, model, tokens, cost, response time, status.
+
+### `fusion.api.usage.daily`
+Cron-aggregated daily summaries. Same dimensions with summed totals. Used for reporting and charts.
+
+---
+
+## Service Layer
+
+`fusion.api.service` (AbstractModel) provides:
+- `call_openai()` - Make OpenAI chat completion calls
+- `call_anthropic()` - Make Anthropic messages API calls
+- `get_api_key()` - Get raw API key for any provider (for non-chat uses like Google Maps)
+- Auto-registration of consumers on first call
+- Access control checks (budget, rate limit, user limit)
+- Usage logging with cost estimation
+- Key validation
+
+---
+
+## Migration Path
+
+1. Module is standalone - no existing modules need changes to install it
+2. Existing modules will be migrated one-by-one to use `fusion.api.service` instead of their own API key fields
+3. During migration, modules can check `fusion_api` first and fall back to their own keys
+
+---
+
+## Security Groups
+
+- `fusion_api.group_user` - View usage data
+- `fusion_api.group_manager` - Manage providers, consumers, access rules
+- `fusion_api.group_admin` - View/edit API keys, full system access