update

.cursor/rules/fusion-api-integration.mdc

@@ -0,0 +1,135 @@
+---
+description: Use the Fusion API module for all API calls (OpenAI, Anthropic, Google Maps, Twilio, OAuth) in any Fusion module
+globs: fusion_*/models/**/*.py, fusion_*/services/**/*.py
+alwaysApply: false
+---
+
+# Fusion API Integration Guide
+
+When any Fusion module needs to call an external API (OpenAI, Anthropic, Google Maps, Twilio, Google/Microsoft OAuth), it MUST use the centralized `fusion.api.service` instead of managing its own keys.
+
+The service lives at `fusion_api/models/api_service.py` and is an AbstractModel accessible via `self.env['fusion.api.service']`.
+
+## Available Methods
+
+### 1. `call_openai()` -- AI text generation via OpenAI
+
+```python
+result = self.env['fusion.api.service'].call_openai(
+    consumer='fusion_clock_ai',       # your module's technical name
+    feature='timesheet_summary',      # descriptive feature name for tracking
+    messages=[
+        {'role': 'system', 'content': 'You are a helpful assistant.'},
+        {'role': 'user', 'content': 'Summarize this timesheet...'},
+    ],
+    model='gpt-4o-mini',              # optional, defaults to gpt-4o-mini
+    max_tokens=1024,                  # optional, defaults to 1024
+    user=self.env.user,               # optional, defaults to current user
+)
+# Returns: str (the text response)
+```
+
+### 2. `call_anthropic()` -- AI text generation via Claude
+
+```python
+result = self.env['fusion.api.service'].call_anthropic(
+    consumer='fusion_notes',
+    feature='voice_transcription',
+    messages=[
+        {'role': 'user', 'content': 'Transcribe this text...'},
+    ],
+    system='You are a medical transcription assistant.',  # optional system prompt
+    model='claude-sonnet-4-20250514',                           # optional, defaults to claude-sonnet-4-20250514
+    max_tokens=1024,                                      # optional
+)
+# Returns: str (the text response)
+```
+
+### 3. `get_api_key()` -- raw API key for non-AI services
+
+```python
+api_key = self.env['fusion.api.service'].get_api_key(
+    provider_type='google_maps',      # one of: google_maps, twilio, custom
+    consumer='fusion_shipping',       # your module's technical name
+    feature='geocoding',              # optional feature name
+)
+# Returns: str (the raw API key to use in your own HTTP calls)
+```
+
+### 4. `get_oauth_credentials()` -- OAuth tokens for Google/Microsoft
+
+```python
+creds = self.env['fusion.api.service'].get_oauth_credentials(
+    provider_type='google_oauth',     # google_oauth or microsoft_oauth
+    consumer='fusion_schedule',
+    feature='calendar_sync',
+)
+# Returns: dict with keys:
+#   client_id, client_secret, access_token, refresh_token, token_expiry, redirect_uri
+```
+
+## Provider Types
+
+| Type | Use For |
+|------|---------|
+| `openai` | GPT-4o, GPT-4o-mini, o1, etc. |
+| `anthropic` | Claude Sonnet, Haiku, Opus |
+| `google_maps` | Geocoding, Places, Distance Matrix |
+| `google_oauth` | Google Calendar, Drive OAuth |
+| `microsoft_oauth` | Microsoft Calendar, Graph OAuth |
+| `twilio` | SMS, Voice |
+| `custom` | Any other API provider |
+
+## What Happens Automatically
+
+- The calling module is auto-registered as a consumer in Fusion API
+- Every call is logged with: tokens, cost, response time, user, feature, model
+- Budget caps (monthly/daily) are enforced before each call
+- Rate limits (RPM/RPD) are enforced before each call
+- Per-user limits are checked if configured
+- On limit exceeded, a `UserError` is raised with a clear message
+
+## Phased Migration Pattern
+
+Do NOT add `fusion_api` as a hard dependency. Use a try/fallback pattern so the module works with or without Fusion API installed:
+
+```python
+def _call_ai(self, messages, feature='general'):
+    """Call OpenAI through Fusion API, falling back to own key."""
+    try:
+        return self.env['fusion.api.service'].call_openai(
+            consumer='fusion_clock_ai',
+            feature=feature,
+            messages=messages,
+        )
+    except Exception:
+        api_key = self.env['ir.config_parameter'].sudo().get_param(
+            'fusion_clock_ai.openai_api_key'
+        )
+        if not api_key:
+            raise
+        from openai import OpenAI
+        client = OpenAI(api_key=api_key)
+        response = client.chat.completions.create(
+            model='gpt-4o-mini', messages=messages,
+        )
+        return response.choices[0].message.content
+```
+
+## Rules
+
+- NEVER hardcode API keys in Python code
+- NEVER store API keys in `ir.config_parameter` for new modules -- use Fusion API
+- ALWAYS pass the module's technical name (e.g. `fusion_clock_ai`) as the `consumer` parameter
+- ALWAYS pass a descriptive `feature` string for usage tracking granularity
+- NEVER catch and silently swallow errors from `fusion.api.service` -- let UserError propagate
+- DO NOT add `fusion_api` to `depends` in `__manifest__.py` -- use the fallback pattern above
+- The `consumer` string should match the module's technical name exactly (folder name)
+
+## Odoo 19 Conventions
+
+- This project targets Odoo 19 (Community/Enterprise)
+- No hardcoded colors in views or SCSS -- let Odoo handle dark/light theming
+- Use `res.groups.privilege` for security groups (not `category_id`)
+- Do not use deprecated `ir.cron` fields (`numbercall`, `doall`)
+- Settings views: use `name=` attribute on `<app>` tags, not `data-key=`