Odoo-Modules/CLAUDE.md

Odoo Modules — Claude Code Instructions

Project

27 custom Odoo 19 modules for Fusion Central (Westin Healthcare + NEXA Systems).

Critical Rules — Odoo 19

1. NEVER code from memory — Always read a reference file from Docker first:

   docker exec odoo-dev-app cat /usr/lib/python3/dist-packages/odoo/addons/<module>/static/src/<path>
   

2. Frontend JS: Use Interaction class from @web/public/interaction, registered via registry.category("public.interactions"). NOT IIFE/DOMContentLoaded.
3. Backend OWL: Use standalone rpc() from @web/core/network/rpc. NOT useService("rpc"). static props = [] not {}.
4. HTTP routes: type="jsonrpc" — NOT type="json" (deprecated).
5. res.config.settings: Only boolean/integer/float/char/selection/many2one/datetime. NO Date fields.
6. res.groups: NO users field, NO category_id field.
7. Search views: NO group expand="0" syntax.
8. SCSS imports: @import "./partial" is FORBIDDEN in Odoo 19 custom SCSS. It prints a warning and silently falls back to the old cached bundle. Register every SCSS file (including _partial.scss tokens) as a separate entry in web.assets_backend. Put tokens first; Odoo concatenates bundle files so SCSS variables/mixins from the first file are visible to every later file.

Card Styling — Copy Odoo's Kanban Pattern

Don't rely on var(--bs-border-color) or var(--bs-body-bg) for card surfaces — they drift between themes/addons and often render invisible. Odoo's own kanban (.o_kanban_record) uses explicit hex values:

background-color: white;
border: 1px solid #d8dadd;

For custom OWL dashboards / client actions use the same approach:

• Define a _tokens.scss partial with explicit hex values wrapped in a CSS custom property:

  $fp-card:   var(--fp-card-bg, #ffffff);
  $fp-border: var(--fp-border-color, #d8dadd);
  

• Reference those tokens everywhere (never var(--bs-border-color) directly)
• Three-layer contrast: page (grayest) → container/column (mid) → card (brightest). That's what makes cards pop.
• Reference implementation: fusion_plating_shopfloor/static/src/scss/_fp_shopfloor_tokens.scss.

Dark Mode — Branch on $o-webclient-color-scheme at SCSS Compile Time

Odoo 19 does NOT flip dark mode via a runtime DOM class. It compiles TWO asset bundles:

• web.assets_backend — compiled with $o-webclient-color-scheme: bright
• web.assets_web_dark — compiled with $o-webclient-color-scheme: dark (dark variant primary variables loaded first)

Your SCSS file is compiled into BOTH bundles. To make the dark bundle have different colors, branch at compile time using the SCSS variable Odoo sets:

$o-webclient-color-scheme: bright !default;

$_my-page-hex: #f3f4f6;
$_my-card-hex: #ffffff;

@if $o-webclient-color-scheme == dark {
    $_my-page-hex: #1a1d21 !global;
    $_my-card-hex: #22262d !global;
}

$my-page: var(--my-page-bg, $_my-page-hex);
$my-card: var(--my-card-bg, $_my-card-hex);

Do NOT use .o_dark_mode class selectors, [data-bs-theme="dark"], or @media (prefers-color-scheme: dark) — none of those fire reliably in Odoo 19. The user toggles dark mode via the user profile, which sets a color_scheme cookie and reloads the page; Odoo then serves the dark bundle. Your SCSS @if handles the rest at compile time.

Verify by inspecting the attachments — you should see two files with different URLs for the two bundles:

env['ir.qweb']._get_asset_bundle('web.assets_backend').css()     # light
env['ir.qweb']._get_asset_bundle('web.assets_web_dark').css()    # dark

Asset Bundle Cache Busting

Odoo content-hashes the compiled bundle URL (/web/assets/<hash>/...). When CSS changes but the hash doesn't update, the browser serves the old bundle. Fixes in order of escalation:

1. Bump the module version in __manifest__.py
2. DELETE FROM ir_attachment WHERE url LIKE '/web/assets/%'; then restart odoo
3. Call env['ir.qweb']._get_asset_bundle('web.assets_backend').css() in odoo-shell to force regeneration
4. Hard-refresh browser with cache clear (DevTools → right-click refresh → Empty Cache and Hard Reload); on mobile clear website data

Naming

• New fields: x_fc_* prefix
• Legacy fields: x_studio_*
• Canadian English for all user-facing text
• Currency: $ sign with Monetary fields + currency_id

Cursor-Managed Modules

• fusion_clock is currently being modified in Cursor — always read files fresh before editing, don't assume you know the current state

Workflow

• Local dev: docker exec odoo-dev-app odoo -d fusion-dev -u <module> --stop-after-init
• Local URL: http://localhost:8069
• Test before deploying. Edit existing files — don't create unnecessary new ones.

PDF Preview — Prefer fusion_pdf_preview Over Downloads/New-Tab

When a Python action opens an attachment, route it through fusion_pdf_preview instead of returning ir.actions.act_url with download=true or target=new. The preview dialog gives operators preview + print + download in one place and writes an audit log; non-PDF attachments fall back to the legacy download path automatically.

The drop-in replacement is the new helper on ir.attachment:

return att.action_fusion_preview(title='My Doc')
# vs. the old pattern:
# return {'type': 'ir.actions.act_url',
#         'url':  '/web/content/%s?download=true' % att.id,
#         'target': 'new'}

The helper auto-detects mimetype: PDFs go to the dialog, everything else (ZPL, CSV, XML, images) stays on download. So a callsite that today serves CSV today and a PDF tomorrow doesn't need a code change — same call, different routing.

If you need to invoke the client action directly (rare — only when you don't have a recordset handy), the tag is fusion_pdf_preview.open_attachment and the params are {attachment_id, title, model_name, record_ids, report_name}. See fusion_pdf_preview/static/src/js/open_attachment_action.js.

Existing reports (ir.actions.report of type qweb-pdf) are intercepted automatically by fusion_pdf_preview/static/src/js/pdf_preview.js; the helper above is for the other pattern — attachments opened by custom buttons.

Supabase Knowledge Base

Before starting unfamiliar work, check Supabase for context:

PGPASSWORD='a09e12e0995dc29446631fa458f3d4b3' psql -h 100.74.28.73 -p 5433 -U postgres -d postgres

• fusionapps.decisions — past architecture decisions
• fusionapps.issues — known issues and fixes
• fusionapps.code_snippets — reference code
• fusionapps.quick_commands — deployment and admin commands