odoo19-module-development

Category: Tools & Productivity | Uploader: ignify-rd | Downloads: 0 | Version: v1.0（Latest）
Changelog: Source: GitHub https://github.com/ignify-rd/odoo19-module-development-skill
Directory Structure

Current level: Root
📁 .github/
- 📁 workflows/
  - 📄 cd.yml 1.7 KB
  - 📄 ci.yml 5.3 KB
📁 bin/
- 📄 odoo-skill.js 1.1 KB
📁 references/
- 📄 odoo-19-actions.md 10.1 KB
- 📄 odoo-19-controller.md 7.7 KB
- 📄 odoo-19-data.md 8.2 KB
- 📄 odoo-19-decorator.md 9.5 KB
- 📄 odoo-19-development.md 12.0 KB
- 📄 odoo-19-field.md 9.8 KB
- 📄 odoo-19-manifest.md 6.2 KB
- 📄 odoo-19-migration.md 4.7 KB
- 📄 odoo-19-mixins.md 7.5 KB
- 📄 odoo-19-model.md 16.4 KB
- 📄 odoo-19-owl.md 7.7 KB
- 📄 odoo-19-performance.md 8.3 KB
- 📄 odoo-19-reports.md 10.9 KB
- 📄 odoo-19-security.md 12.0 KB
- 📄 odoo-19-testing.md 9.5 KB
- 📄 odoo-19-transaction.md 5.9 KB
- 📄 odoo-19-translation.md 5.8 KB
- 📄 odoo-19-view.md 12.0 KB
📁 src/
- 📁 commands/
  - 📄 init.js 2.4 KB
  - 📄 update.js 846 B
- 📁 utils/
  - 📄 logger.js 416 B
📄 .gitignore 30 B
📄 package-lock.json 1.2 KB
📄 package.json 931 B
📄 README.md 4.3 KB
📄 SKILL.md 43.6 KB
SKILL.md

---
name: odoo19-module-development
description: >-
  Use when writing, reviewing, debugging, or scaffolding any Odoo 19 module.
  Covers module structure, models, views, security, menus, data files, wizards,
  OWL components, custom HTML/JS/CSS dashboards, and common Odoo 19 pitfalls.
  Integrates ui-ux-pro-max for custom UI design (dashboards, portals, landing
  pages) using HTML + JS + CSS instead of standard Odoo XML views. Triggers on
  .py or .xml inside Odoo addons, __manifest__.py, ir.model.access.csv,
  res.groups.privilege, mail.thread, @api.depends, @api.ondelete, @api.private,
  models.Constraint, OWL component, ir.actions.client, static/src/js,
  static/src/scss, custom dashboard, or Odoo 19 development.
---

# Odoo 19 Module Development

## Overview

Complete guide for building Odoo 19 custom modules. Covers every layer from models to views to security, with Odoo 19-specific syntax changes and real-world patterns from production HR/ERP modules.

For deep-dive API reference on any specific topic, read the corresponding guide from `references/`.

## Quick Reference — Topic Index

| Topic          | Reference File                        | When to Use                                          |
| -------------- | ------------------------------------- | ---------------------------------------------------- |
| Actions        | `references/odoo-19-actions.md`       | Window actions, server actions, cron jobs, menus      |
| API Decorators | `references/odoo-19-decorator.md`     | @api.depends, @api.constrains, @api.ondelete         |
| Controllers    | `references/odoo-19-controller.md`    | HTTP endpoints, routes, web controllers              |
| Data Files     | `references/odoo-19-data.md`          | XML/CSV data, sequences, cron, noupdate              |
| Fields         | `references/odoo-19-field.md`         | Field types, attributes, relational fields           |
| Manifest       | `references/odoo-19-manifest.md`      | __manifest__.py configuration                        |
| Migration      | `references/odoo-19-migration.md`     | Pre/post migration scripts, version upgrades         |
| Mixins         | `references/odoo-19-mixins.md`        | mail.thread, mail.activity.mixin, tracking           |
| Models & ORM   | `references/odoo-19-model.md`         | CRUD, search, domains, recordsets, _read_group       |
| OWL Components | `references/odoo-19-owl.md`           | Frontend OWL components, hooks, services             |
| Performance    | `references/odoo-19-performance.md`   | N+1 prevention, batch ops, optimization              |
| Reports        | `references/odoo-19-reports.md`       | QWeb PDF/HTML reports, paper formats                 |
| Security       | `references/odoo-19-security.md`      | Groups, ACL, record rules, privilege system          |
| Testing        | `references/odoo-19-testing.md`       | TransactionCase, HttpCase, mocking                   |
| Transactions   | `references/odoo-19-transaction.md`   | Savepoints, UniqueViolation, serialization           |
| Translation    | `references/odoo-19-translation.md`   | i18n, PO files, translatable fields                  |
| Views & XML    | `references/odoo-19-view.md`          | List/form/search/kanban views, xpath inheritance     |

## Odoo 19 Breaking Changes (MUST KNOW)

These changes will cause errors if you use old syntax:

| Change                | Old (Odoo 17-)                       | New (Odoo 19)                                       |
| --------------------- | ------------------------------------ | --------------------------------------------------- |
| List view tag         | `<tree>`                             | `<list>`                                            |
| Dynamic attributes    | `attrs="{'invisible': [...]}"` | `invisible="..."` (direct expression)               |
| Delete validation     | Override `unlink()`                  | `@api.ondelete(at_uninstall=False)`                 |
| Field aggregation     | `group_operator=`                    | `aggregator=`                                       |
| SQL constraints       | `_sql_constraints = [...]`           | `models.Constraint(...)`                            |
| DB indexes            | `index=True` only                    | `models.Index(...)` declarative                     |
| Security groups       | `category_id` on `res.groups`        | `privilege_id` + `res.groups.privilege`             |
| Kanban template       | `t-name="kanban-box"`                | `t-name="card"`                                     |
| QWeb output           | `t-esc`                              | `t-out`                                             |
| Private methods       | `_` prefix convention                | `@api.private` decorator (enforced)                 |
| read_group            | `read_group()`                       | `_read_group()` / `formatted_read_group()`          |
| Batch create          | Single dict                          | List of dicts: `create([{...}, {...}])`             |
| Search view grouping  | `<group expand='0'>` wrapper         | Place `<filter>` elements directly in `<search>`   |

## Module Structure

```
my_module/
├── __init__.py              # from . import models[, controllers, wizard]
├── __manifest__.py          # Module metadata
├── models/
│   ├── __init__.py          # from . import model_file
│   └── my_model.py
├── views/
│   ├── my_model_views.xml   # List, form, search, kanban views
│   └── menu.xml             # Menus (or inline in views file)
├── security/
│   ├── ir.model.access.csv  # Model-level ACL
│   └── my_module_security.xml  # Groups, privileges, record rules
├── data/
│   ├── ir_sequence_data.xml # Sequences
│   └── ir_cron_data.xml     # Scheduled actions
├── wizard/
│   ├── __init__.py
│   └── my_wizard.py
├── controllers/
│   ├── __init__.py
│   └── my_controller.py
├── static/
│   ├── description/
│   │   └── icon.png         # Module icon (128x128)
│   └── src/
│       ├── js/
│       ├── xml/
│       └── scss/
├── report/
│   └── my_report.xml
└── tests/
    ├── __init__.py
    └── test_my_model.py
```

## __manifest__.py

```python
{
    'name': 'My Module',
    'version': '19.0.1.0.0',
    'category': 'Human Resources',
    'author': 'Your Name',
    'website': 'https://example.com',
    'summary': 'One-line summary',
    'description': """
        Detailed description.
    """,
    'depends': ['base', 'hr', 'mail'],
    'data': [
        # Load order matters: security → data → views → menus
        'security/my_module_security.xml',
        'security/ir.model.access.csv',
        'data/ir_sequence_data.xml',
        'data/ir_cron_data.xml',
        'views/my_model_views.xml',
        'views/menu.xml',
        'wizard/my_wizard_views.xml',
    ],
    'assets': {
        'web.assets_backend': [
            'my_module/static/src/js/my_component.js',
            'my_module/static/src/xml/my_component.xml',
            'my_module/static/src/scss/my_style.scss',
        ],
    },
    'external_dependencies': {'python': ['requests']},
    'installable': True,
    'application': True,
    'auto_install': False,
    'license': 'LGPL-3',
}
```

## Model Definition

```python
from odoo import api, fields, models, _
from odoo.exceptions import UserError, ValidationError

class MyModel(models.Model):
    _name = 'my.model'
    _description = 'My Model'
    _inherit = ['mail.thread', 'mail.activity.mixin']
    _order = 'date_start desc, id desc'
    _rec_name = 'display_name'

    # === Basic Fields ===
    name = fields.Char(string='Name', required=True, copy=False,
                       default=lambda self: _('New'), tracking=True)
    description = fields.Text(string='Description')
    active = fields.Boolean(default=True)

    # === Relational Fields ===
    employee_id = fields.Many2one('hr.employee', string='Employee',
                                   required=True, tracking=True, index=True,
                                   domain="[('company_id', 'in', [company_id, False])]")
    department_id = fields.Many2one('hr.department',
                                     related='employee_id.department_id', store=True)
    line_ids = fields.One2many('my.model.line', 'parent_id', string='Lines')
    tag_ids = fields.Many2many('my.model.tag', string='Tags')

    # === Selection / State ===
    state = fields.Selection([
        ('draft', 'Draft'),
        ('confirmed', 'Confirmed'),
        ('done', 'Done'),
    ], string='State', default='draft', tracking=True)

    # === Date Fields ===
    date_start = fields.Date(string='Start Date', required=True)
    date_end = fields.Date(string='End Date')

    # === Computed Fields ===
    days_remaining = fields.Integer(compute='_compute_days_remaining', store=False)
    total_amount = fields.Float(compute='_compute_total', store=True, digits=(10, 2))

    # === SQL Constraint (Odoo 19 syntax) ===
    _check_dates = models.Constraint(
        'CHECK(date_end IS NULL OR date_end >= date_start)',
        'End date must be after start date!',
    )

    # === Compute Methods ===
    @api.depends('date_end')
    def _compute_days_remaining(self):
        today = fields.Date.today()
        for rec in self:
            if rec.date_end:
                rec.days_remaining = (rec.date_end - today).days
            else:
                rec.days_remaining = 0

    @api.depends('line_ids.amount')
    def _compute_total(self):
        for rec in self:
            rec.total_amount = sum(rec.line_ids.mapped('amount'))

    # === Onchange ===
    @api.onchange('employee_id')
    def _onchange_employee_id(self):
        if self.employee_id:
            self.department_id = self.employee_id.department_id

    # === Constraints ===
    @api.constrains('date_start', 'date_end')
    def _check_date_range(self):
        for rec in self:
            if rec.date_end and rec.date_end < rec.date_start:
                raise ValidationError(_('End date must be after start date.'))

    # === Delete Validation (Odoo 19) ===
    @api.ondelete(at_uninstall=False)
    def _unlink_if_draft(self):
        if any(rec.state != 'draft' for rec in self):
            raise UserError(_('Cannot delete non-draft records.'))

    # === CRUD Overrides ===
    @api.model_create_multi
    def create(self, vals_list):
        for vals in vals_list:
            if not vals.get('name') or vals['name'] == _('New'):
                vals['name'] = self.env['ir.sequence'].next_by_code('my.model')
        return super().create(vals_list)

    # === Action Methods (called from buttons) ===
    def action_confirm(self):
        for rec in self:
            rec.state = 'confirmed'

    def action_done(self):
        for rec in self:
            rec.state = 'done'
```

## Views XML

```xml
<?xml version="1.0" encoding="utf-8"?>
<odoo>
    <!-- List View (NOT <tree>) -->
    <record id="view_my_model_list" model="ir.ui.view">
        <field name="name">my.model.list</field>
        <field name="model">my.model</field>
        <field name="arch" type="xml">
            <list string="My Models"
                  decoration-info="state == 'draft'"
                  decoration-success="state == 'done'"
                  multi_edit="1" sample="1">
                <field name="name"/>
                <field name="employee_id" widget="many2one_avatar_employee"/>
                <field name="date_start"/>
                <field name="total_amount" optional="show"/>
                <field name="state" widget="badge"
                       decoration-info="state == 'draft'"
                       decoration-success="state == 'done'"/>
            </list>
        </field>
    </record>

    <!-- Form View -->
    <record id="view_my_model_form" model="ir.ui.view">
        <field name="name">my.model.form</field>
        <field name="model">my.model</field>
        <field name="arch" type="xml">
            <form string="My Model">
                <header>
                    <button name="action_confirm" type="object"
                            string="Confirm" class="btn-primary"
                            invisible="state != 'draft'"/>
                    <button name="action_done" type="object"
                            string="Done"
                            invisible="state != 'confirmed'"/>
                    <field name="state" widget="statusbar"
                           statusbar_visible="draft,confirmed,done"/>
                </header>
                <sheet>
                    <div class="oe_button_box" name="button_box">
                        <button name="action_view_lines" type="object"
                                class="oe_stat_button" icon="fa-list">
                            <field name="line_count" widget="statinfo"
                                   string="Lines"/>
                        </button>
                    </div>
                    <widget name="web_ribbon" title="Done"
                            bg_color="text-bg-success"
                            invisible="state != 'done'"/>
                    <div class="oe_title">
                        <label for="name"/>
                        <h1><field name="name" readonly="id"/></h1>
                    </div>
                    <group>
                        <group string="Employee Info">
                            <field name="employee_id"/>
                            <field name="department_id"/>
                        </group>
                        <group string="Dates">
                            <field name="date_start"/>
                            <field name="date_end"/>
                            <field name="days_remaining"/>
                        </group>
                    </group>
                    <notebook>
                        <page string="Lines">
                            <field name="line_ids">
                                <list editable="bottom">
                                    <field name="description"/>
                                    <field name="amount"/>
                                </list>
                            </field>
                            <group class="oe_subtotal_footer">
                                <field name="total_amount"/>
                            </group>
                        </page>
                        <page string="Notes">
                            <field name="description" placeholder="Notes..."/>
                        </page>
                    </notebook>
                </sheet>
                <chatter/>
            </form>
        </field>
    </record>

    <!-- Search View (NO <group expand='0'> in Odoo 19) -->
    <record id="view_my_model_search" model="ir.ui.view">
        <field name="name">my.model.search</field>
        <field name="model">my.model</field>
        <field name="arch" type="xml">
            <search string="Search">
                <field name="name"/>
                <field name="employee_id"/>
                <filter string="Draft" name="draft"
                        domain="[('state', '=', 'draft')]"/>
                <filter string="Done" name="done"
                        domain="[('state', '=', 'done')]"/>
                <separator/>
                <filter string="Employee" name="group_employee"
                        context="{'group_by': 'employee_id'}"/>
                <filter string="State" name="group_state"
                        context="{'group_by': 'state'}"/>
            </search>
        </field>
    </record>

    <!-- Window Action -->
    <record id="action_my_model" model="ir.actions.act_window">
        <field name="name">My Models</field>
        <field name="res_model">my.model</field>
        <field name="view_mode">list,form,kanban</field>
        <field name="context">{'search_default_group_employee': 1}</field>
        <field name="help" type="html">
            <p class="o_view_nocontent_smiling_face">
                Create your first record!
            </p>
        </field>
    </record>

    <!-- Menu -->
    <menuitem id="menu_root" name="My Module"
              web_icon="my_module,static/description/icon.png"
              groups="group_my_user" sequence="90"/>
    <menuitem id="menu_list" name="Records"
              parent="menu_root" action="action_my_model" sequence="10"/>
</odoo>
```

## Security (Odoo 19 Privilege System)

### security/my_module_security.xml

```xml
<?xml version="1.0" encoding="utf-8"?>
<odoo>
    <!-- Step 1: Create privilege (replaces category_id) -->
    <record id="res_groups_privilege_my_module" model="res.groups.privilege">
        <field name="name">My Module</field>
        <field name="sequence">90</field>
        <field name="category_id" ref="base.module_category_human_resources"/>
    </record>

    <!-- Step 2: Define groups with privilege_id -->
    <record id="group_my_user" model="res.groups">
        <field name="name">User</field>
        <field name="sequence">5</field>
        <field name="privilege_id" ref="res_groups_privilege_my_module"/>
        <field name="implied_ids" eval="[(4, ref('base.group_user'))]"/>
    </record>

    <record id="group_my_manager" model="res.groups">
        <field name="name">Manager</field>
        <field name="sequence">10</field>
        <field name="privilege_id" ref="res_groups_privilege_my_module"/>
        <field name="implied_ids" eval="[(4, ref('group_my_user'))]"/>
    </record>

    <!-- Step 3: Record rules -->
    <data noupdate="1">
        <!-- User sees own records -->
        <record id="rule_my_model_user" model="ir.rule">
            <field name="name">My Model: user own records</field>
            <field name="model_id" ref="model_my_model"/>
            <field name="domain_force">[('create_uid', '=', user.id)]</field>
            <field name="groups" eval="[(4, ref('group_my_user'))]"/>
        </record>

        <!-- Manager sees all -->
        <record id="rule_my_model_manager" model="ir.rule">
            <field name="name">My Model: manager all</field>
            <field name="model_id" ref="model_my_model"/>
            <field name="domain_force">[(1, '=', 1)]</field>
            <field name="groups" eval="[(4, ref('group_my_manager'))]"/>
        </record>

        <!-- Multi-company (global rule) -->
        <record id="rule_my_model_multi_company" model="ir.rule">
            <field name="name">My Model: multi-company</field>
            <field name="model_id" ref="model_my_model"/>
            <field name="global" eval="True"/>
            <field name="domain_force">
                ['|', ('company_id', '=', False), ('company_id', 'in', company_ids)]
            </field>
        </record>
    </data>
</odoo>
```

### security/ir.model.access.csv

```csv
id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
access_my_model_user,my.model.user,model_my_model,group_my_user,1,0,0,0
access_my_model_manager,my.model.manager,model_my_model,group_my_manager,1,1,1,1
```

**Critical:** For models defined in OTHER modules, prefix with module name:
```csv
access_hr_employee_user,hr.employee.user,hr.model_hr_employee,group_my_user,1,0,0,0
```

## Common Odoo 19 Pitfalls

### 1. Search View — No `<group expand='0'>`
```xml
<!-- WRONG: causes RELAXNG validation error -->
<search>
  <group expand="0" string="Group By">
    <filter name="group_emp" context="{'group_by': 'employee_id'}"/>
  </group>
</search>

<!-- CORRECT: filters directly in search -->
<search>
  <filter name="group_emp" string="Employee"
          context="{'group_by': 'employee_id'}"/>
</search>
```

### 2. Model Already Exists
```python
# WRONG: creates duplicate model
class ContractType(models.Model):
    _name = 'hr.contract.type'

# CORRECT: extend existing model
class ContractType(models.Model):
    _inherit = 'hr.contract.type'
```

### 3. External ID Prefix
```csv
# WRONG: model defined in 'hr' module
model_id:id
model_hr_employee

# CORRECT: prefix with source module
model_id:id
hr.model_hr_employee
```

### 4. Field Editable on Create, Readonly After Save
```xml
<!-- Use readonly="id" — False when creating (id=0), True after save -->
<field name="employee_id" readonly="id"/>
```

### 5. Multi-Company Consistency
When working with employees, ensure `user.company_id`, `employee.company_id`, and `resource_resource.company_id` all match.

### 6. Computed Field Not Searchable
```python
# Non-stored computed fields need explicit search method
is_expiring = fields.Boolean(
    compute='_compute_is_expiring',
    store=False,
    search='_search_is_expiring'
)

def _search_is_expiring(self, operator, value):
    today = fields.Date.today()
    return [('date_end', '<=', today + timedelta(days=30))]
```

## Naming Conventions

| Entity        | Convention                       | Example                           |
| ------------- | -------------------------------- | --------------------------------- |
| Model name    | Dotted lowercase                 | `my.module.model`                 |
| Python class  | CamelCase                        | `MyModuleModel`                   |
| Field         | snake_case + suffix              | `employee_id`, `line_ids`         |
| Compute       | `_compute_<field>`               | `_compute_total_amount`           |
| Onchange      | `_onchange_<field>`              | `_onchange_employee_id`           |
| Action method | `action_<verb>`                  | `action_confirm`                  |
| Private method| `_<name>` + `@api.private`       | `_set_state`                      |
| View ID       | `view_<model>_<type>`            | `view_my_model_form`              |
| Action ID     | `action_<model>`                 | `action_my_model`                 |
| Menu ID       | `menu_<path>`                    | `menu_my_module_root`             |
| Rule ID       | `rule_<model>_<purpose>`         | `rule_my_model_user`              |
| Group ID      | `group_<module>_<role>`          | `group_my_module_manager`         |

## Data Files

### Sequence
```xml
<data noupdate="1">
    <record id="seq_my_model" model="ir.sequence">
        <field name="name">My Model Sequence</field>
        <field name="code">my.model</field>
        <field name="prefix">MM/</field>
        <field name="padding">4</field>
    </record>
</data>
```

### Cron Job
```xml
<data noupdate="1">
    <record id="cron_check_expiry" model="ir.cron">
        <field name="name">My Model: Check Expiry</field>
        <field name="model_id" ref="model_my_model"/>
        <field name="state">code</field>
        <field name="code">model._cron_check_expiry()</field>
        <field name="interval_number">1</field>
        <field name="interval_type">days</field>
        <field name="active">True</field>
    </record>
</data>
```

## Wizard Pattern

```python
class MyWizard(models.TransientModel):
    _name = 'my.model.wizard'
    _description = 'My Wizard'

    date = fields.Date(required=True, default=fields.Date.context_today)
    note = fields.Text()

    def action_confirm(self):
        active_ids = self.env.context.get('active_ids', [])
        records = self.env['my.model'].browse(active_ids)
        # Process records...
        return {'type': 'ir.actions.act_window_close'}
```

## View Inheritance (xpath)

```xml
<record id="view_partner_form_inherit" model="ir.ui.view">
    <field name="name">res.partner.form.inherit.my_module</field>
    <field name="model">res.partner</field>
    <field name="inherit_id" ref="base.view_partner_form"/>
    <field name="arch" type="xml">
        <xpath expr="//field[@name='phone']" position="after">
            <field name="my_custom_field"/>
        </xpath>
    </field>
</record>
```

## Anti-Patterns to Avoid

| Anti-Pattern                       | Correct Approach                              |
| ---------------------------------- | --------------------------------------------- |
| `<tree>` tag                       | `<list>` tag                                  |
| `attrs="{'invisible': [...]}"` | `invisible="expression"`                      |
| `_sql_constraints = [...]`         | `models.Constraint(...)`                      |
| `category_id` on `res.groups`      | `privilege_id` + `res.groups.privilege`       |
| `t-esc` in templates               | `t-out`                                       |
| `search()` in loop                 | Single `search()` with `IN` domain            |
| `create()` in loop                 | Batch `create([{...}, {...}])`                |
| Override `unlink()` for validation | `@api.ondelete(at_uninstall=False)`           |
| `eval()` for parsing               | `ast.literal_eval()`                          |
| `t-raw` for content                | `t-out` (XSS safe)                            |
| `read_group()`                     | `_read_group()` / `formatted_read_group()`    |
| `getattr(record, field)`           | `record[field]` (__getitem__)                 |

---

## Custom UI with HTML/JS/CSS (Instead of Odoo XML Views)

When building custom dashboards, landing pages, or rich interactive UIs inside Odoo 19 modules, **use HTML + JS + CSS via OWL components and QWeb templates** instead of standard Odoo form/list views.

**REQUIRED:** Use the `ui-ux-pro-max` skill for design system generation before building any custom UI. Run:

```bash
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system -p "Project Name"
```

### When to Use Custom UI vs Odoo Views

| Use Case                          | Approach                    |
| --------------------------------- | --------------------------- |
| CRUD data management              | Standard Odoo XML views     |
| Dashboard with charts/KPIs        | **Custom HTML/JS/CSS**      |
| Landing page / portal page        | **Custom HTML/JS/CSS**      |
| Complex interactive forms         | **Custom HTML/JS/CSS**      |
| Kanban with rich card layout      | **Custom HTML/JS/CSS**      |
| Simple list/form with filters     | Standard Odoo XML views     |
| Report / PDF generation           | QWeb report templates       |
| Admin settings page               | Standard Odoo XML views     |

### Architecture: Custom UI in Odoo 19

```
my_module/
├── controllers/
│   └── main.py                    # HTTP endpoints serving JSON data
├── static/
│   └── src/
│       ├── js/
│       │   ├── dashboard.js       # OWL component (main UI)
│       │   └── services/          # RPC services for backend calls
│       ├── xml/
│       │   └── dashboard.xml      # QWeb template for OWL component
│       ├── scss/
│       │   └── dashboard.scss     # Custom styles
│       └── css/
│           └── dashboard.css      # Plain CSS (if not using SCSS)
├── views/
│   └── dashboard_views.xml        # ir.actions.client action
└── __manifest__.py                # Register assets in web.assets_backend
```

### Step 1: Design System (REQUIRED before coding)

Use `ui-ux-pro-max` to generate your design system:

```bash
# For a HR dashboard
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "HR dashboard enterprise professional" --design-system -p "HR Dashboard"

# Get stack-specific guidelines
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "dashboard cards charts" --stack html-tailwind

# Get UX best practices
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "animation accessibility loading" --domain ux
```

### Step 2: OWL Component (JS)

```javascript
/** @odoo-module **/

import { Component, useState, onWillStart } from "@odoo/owl";
import { registry } from "@web/core/registry";
import { useService } from "@web/core/utils/hooks";

class MyDashboard extends Component {
    static template = "my_module.Dashboard";
    static props = { ...MyDashboard.props, action: { type: Object, optional: true } };

    setup() {
        this.orm = useService("orm");
        this.action = useService("action");
        this.state = useState({
            data: [],
            loading: true,
            stats: { total: 0, pending: 0, done: 0 },
        });
        onWillStart(async () => {
            await this.loadData();
        });
    }

    async loadData() {
        this.state.loading = true;
        try {
            // Use ORM service for RPC calls
            const records = await this.orm.searchRead(
                "my.model",
                [["state", "!=", "cancelled"]],
                ["name", "state", "total_amount", "employee_id"],
                { limit: 100, order: "date_start desc" }
            );
            this.state.data = records;
            this.state.stats = {
                total: records.length,
                pending: records.filter(r => r.state === "draft").length,
                done: records.filter(r => r.state === "done").length,
            };
        } finally {
            this.state.loading = false;
        }
    }

    onCardClick(recordId) {
        this.action.doAction({
            type: "ir.actions.act_window",
            res_model: "my.model",
            res_id: recordId,
            views: [[false, "form"]],
            target: "current",
        });
    }
}

// Register as a client action
registry.category("actions").add("my_module.dashboard", MyDashboard);
```

### Step 3: QWeb Template (XML)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
    <t t-name="my_module.Dashboard">
        <div class="my_dashboard o_action">
            <!-- Loading State -->
            <div t-if="state.loading" class="d-flex justify-content-center align-items-center"
                 style="min-height: 400px;">
                <div class="spinner-border text-primary" role="status">
                    <span class="visually-hidden">Loading...</span>
                </div>
            </div>

            <div t-else="" class="container-fluid p-4">
                <!-- KPI Cards Row -->
                <div class="row g-3 mb-4">
                    <div class="col-md-4">
                        <div class="card shadow-sm border-0 h-100 cursor-pointer"
                             style="border-radius: 12px;">
                            <div class="card-body">
                                <div class="text-muted small fw-semibold text-uppercase">Total</div>
                                <div class="fs-2 fw-bold text-primary mt-1">
                                    <t t-out="state.stats.total"/>
                                </div>
                            </div>
                        </div>
                    </div>
                    <div class="col-md-4">
                        <div class="card shadow-sm border-0 h-100"
                             style="border-radius: 12px;">
                            <div class="card-body">
                                <div class="text-muted small fw-semibold text-uppercase">Pending</div>
                                <div class="fs-2 fw-bold text-warning mt-1">
                                    <t t-out="state.stats.pending"/>
                                </div>
                            </div>
                        </div>
                    </div>
                    <div class="col-md-4">
                        <div class="card shadow-sm border-0 h-100"
                             style="border-radius: 12px;">
                            <div class="card-body">
                                <div class="text-muted small fw-semibold text-uppercase">Done</div>
                                <div class="fs-2 fw-bold text-success mt-1">
                                    <t t-out="state.stats.done"/>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>

                <!-- Data Grid -->
                <div class="row g-3">
                    <t t-foreach="state.data" t-as="record" t-key="record.id">
                        <div class="col-md-6 col-lg-4">
                            <div class="card shadow-sm border-0 h-100 cursor-pointer"
                                 style="border-radius: 12px; transition: transform 0.2s, box-shadow 0.2s;"
                                 t-on-click="() => this.onCardClick(record.id)">
                                <div class="card-body">
                                    <h6 class="card-title fw-bold mb-2">
                                        <t t-out="record.name"/>
                                    </h6>
                                    <div class="d-flex justify-content-between align-items-center">
                                        <span class="badge"
                                              t-attf-class="badge {{ record.state === 'done' ? 'bg-success' : record.state === 'draft' ? 'bg-info' : 'bg-warning' }}">
                                            <t t-out="record.state"/>
                                        </span>
                                        <span class="text-muted">
                                            <t t-out="record.total_amount"/> VND
                                        </span>
                                    </div>
                                </div>
                            </div>
                        </div>
                    </t>
                </div>
            </div>
        </div>
    </t>
</templates>
```

### Step 4: Custom Styles (SCSS)

```scss
// static/src/scss/dashboard.scss
.my_dashboard {
    background: #f8f9fc;
    min-height: 100vh;

    .card {
        transition: transform 0.2s ease, box-shadow 0.2s ease;

        &:hover {
            transform: translateY(-2px);
            box-shadow: 0 8px 25px rgba(0, 0, 0, 0.1) !important;
        }
    }

    // KPI cards gradient accent
    .card-body {
        position: relative;

        &::before {
            content: '';
            position: absolute;
            top: 0;
            left: 0;
            right: 0;
            height: 3px;
            border-radius: 12px 12px 0 0;
        }
    }

    // Responsive adjustments
    @media (max-width: 768px) {
        .container-fluid {
            padding: 1rem !important;
        }
    }
}
```

### Step 5: Client Action (XML)

```xml
<!-- views/dashboard_views.xml -->
<odoo>
    <record id="action_my_dashboard" model="ir.actions.client">
        <field name="name">My Dashboard</field>
        <field name="tag">my_module.dashboard</field>
    </record>

    <menuitem id="menu_dashboard" name="Dashboard"
              parent="menu_root" action="action_my_dashboard"
              sequence="1"/>
</odoo>
```

### Step 6: Register Assets in Manifest

```python
'assets': {
    'web.assets_backend': [
        'my_module/static/src/scss/dashboard.scss',
        'my_module/static/src/js/dashboard.js',
        'my_module/static/src/xml/dashboard.xml',
    ],
},
```

### Custom UI Controller Pattern (for REST-like API)

When your custom UI needs data beyond simple ORM calls:

```python
# controllers/main.py
from odoo import http
from odoo.http import request

class MyDashboardController(http.Controller):

    @http.route('/my_module/dashboard/stats', type='json', auth='user')
    def get_dashboard_stats(self):
        """Return aggregated stats for the dashboard."""
        Model = request.env['my.model']
        results = Model._read_group(
            domain=[('state', '!=', 'cancelled')],
            groupby=['state'],
            aggregates=['total_amount:sum', '__count'],
        )
        return {
            'stats': [{
                'state': state,
                'total_amount': total,
                'count': count,
            } for state, total, count in results],
        }
```

### UI Design Rules (from ui-ux-pro-max)

When building custom HTML/JS/CSS UI inside Odoo, follow these rules:

| Rule                      | Do                                                        | Don't                                            |
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------ |
| Icons                     | Use Font Awesome (bundled in Odoo) or SVG                 | Use emojis as icons                              |
| Colors                    | Use Bootstrap 5 classes (`text-primary`, `bg-success`)    | Hardcode hex colors everywhere                   |
| Spacing                   | Use Bootstrap utilities (`p-4`, `mb-3`, `g-3`)            | Use arbitrary pixel values                       |
| Cards                     | `border-radius: 12px`, `shadow-sm`, hover lift effect     | Flat boxes with no visual hierarchy              |
| Typography                | Use Odoo's default font stack, `fw-bold`/`fw-semibold`    | Import external fonts that clash with Odoo       |
| Hover states              | `transition: transform 0.2s, box-shadow 0.2s`            | Scale transforms that shift layout               |
| Interactive elements      | Add `cursor-pointer` to all clickable cards/buttons       | Leave default cursor on interactive elements     |
| Loading states            | Show spinner or skeleton during async operations          | Show empty screen while loading                  |
| Responsive                | Use Bootstrap grid (`col-md-4`, `col-lg-3`)               | Fixed-width layouts                              |
| Accessibility             | `role`, `aria-label`, min 4.5:1 contrast ratio            | Color as the only indicator                      |
| Dark mode                 | Test with Odoo's dark mode (`o_dark` class on `<body>`)   | Ignore dark mode compatibility                   |
| Contrast (light mode)     | `text-dark` or `#0F172A` for body text                    | Light gray text (`text-muted` for body copy)     |

### Pre-Delivery Checklist for Custom Odoo UI

- [ ] Design system generated via `ui-ux-pro-max` before coding
- [ ] No emojis used as icons — Font Awesome or SVG only
- [ ] All clickable elements have `cursor-pointer`
- [ ] Hover states with smooth transitions (150-300ms)
- [ ] Loading spinner shown during async data fetch
- [ ] Works in Odoo dark mode (`o_dark`)
- [ ] Responsive at mobile (375px) and desktop (1440px)
- [ ] Accessible: `aria-label` on icon buttons, color contrast 4.5:1+
- [ ] Uses Bootstrap 5 utilities (not custom CSS for spacing/colors)
- [ ] Assets registered in `__manifest__.py` under `web.assets_backend`
- [ ] Client action registered with `ir.actions.client` and correct `tag`
- [ ] OWL component uses `useService("orm")` for RPC, not raw `fetch()`

---

## Server Access & Remote Debugging

When the user provides server credentials (e.g. `ubuntu@192.168.1.1`, `root@myserver.com`), **SSH in immediately** to gather information — do NOT ask for permission first. The user providing credentials IS the authorization.

**IMPORTANT: READ-ONLY by default.** Only use SSH for reading/checking (logs, config, status, disk). **NEVER deploy, restart, install, update, or modify anything on the server unless the user explicitly asks to deploy.** Providing server credentials authorizes inspection, NOT deployment.

### Auto-SSH Triggers

If the user mentions a server address in any of these forms, treat it as authorization to SSH:
- `user@ip` or `user@hostname`
- "server is at 192.168.x.x"
- "check on production/staging server"
- Providing a `.pem` key path or SSH config

### What to Check (in order)

```bash
# 1. Odoo service status
ssh user@host "systemctl status odoo 2>/dev/null || supervisorctl status odoo 2>/dev/null || ps aux | grep odoo"

# 2. Odoo version & config
ssh user@host "cat /etc/odoo/odoo.conf 2>/dev/null || cat /opt/odoo/odoo.conf 2>/dev/null || find / -name 'odoo.conf' -type f 2>/dev/null | head -3"

# 3. Odoo log (last 50 lines for errors)
ssh user@host "tail -50 /var/log/odoo/odoo-server.log 2>/dev/null || journalctl -u odoo --no-pager -n 50 2>/dev/null"

# 4. Custom addons path & installed modules
ssh user@host "grep -E 'addons_path|server_wide_modules' /etc/odoo/odoo.conf 2>/dev/null"

# 5. Database info
ssh user@host "grep -E 'db_name|db_host|db_port' /etc/odoo/odoo.conf 2>/dev/null"

# 6. Python/pip packages (check for missing dependencies)
ssh user@host "pip3 list 2>/dev/null | grep -i odoo || /opt/odoo/venv/bin/pip list 2>/dev/null"

# 7. Disk & memory
ssh user@host "df -h / && free -h"

# 8. Check if module exists on server
ssh user@host "ls -la /opt/odoo/custom-addons/my_module/ 2>/dev/null || find /opt -name '__manifest__.py' -path '*/my_module/*' 2>/dev/null"
```

### Common Server Tasks

| Task                              | Command                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------- |
| Restart Odoo                      | `ssh user@host "sudo systemctl restart odoo"`                                |
| Update a module                   | `ssh user@host "sudo -u odoo odoo -d dbname -u my_module --stop-after-init"` |
| Install a module                  | `ssh user@host "sudo -u odoo odoo -d dbname -i my_module --stop-after-init"` |
| Copy module to server             | `scp -r ./my_module user@host:/opt/odoo/custom-addons/`                      |
| Tail live logs                    | `ssh user@host "tail -f /var/log/odoo/odoo-server.log"`                      |
| Check Odoo port                   | `ssh user@host "ss -tlnp \| grep 8069"`                                      |
| PostgreSQL check                  | `ssh user@host "sudo -u postgres psql -l"`                                   |
| List installed modules in DB      | `ssh user@host "sudo -u postgres psql -d dbname -c \"SELECT name, state FROM ir_module_module WHERE state='installed' ORDER BY name;\""` |

### Deploy Module Flow (ONLY when user explicitly requests deploy)

**Do NOT run these commands unless the user says "deploy", "push to server", "update on server", or similar.**

```bash
# 1. Copy module
scp -r ./my_module user@host:/opt/odoo/custom-addons/

# 2. Fix ownership
ssh user@host "sudo chown -R odoo:odoo /opt/odoo/custom-addons/my_module"

# 3. Update/Install
ssh user@host "sudo -u odoo odoo -d dbname -u my_module --stop-after-init"

# 4. Restart service
ssh user@host "sudo systemctl restart odoo"

# 5. Check logs for errors
ssh user@host "tail -20 /var/log/odoo/odoo-server.log"
```

### Troubleshooting Patterns

| Symptom                           | Check                                                    |
| --------------------------------- | -------------------------------------------------------- |
| 502 Bad Gateway                   | `systemctl status odoo` + `tail /var/log/nginx/error.log`|
| Module not found                  | Verify `addons_path` in `odoo.conf` includes custom dir  |
| Access denied / security error    | Check `ir.model.access.csv` loaded + user groups         |
| XML validation error              | `tail -50 /var/log/odoo/odoo-server.log \| grep -i error`|
| Module won't update               | Clear assets: `rm -rf /tmp/odoo-assets-*` + restart      |
| Database locked                   | `sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE state='active';"` |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
odoo19-module-development

Directory Structure

SKILL.md

Report

Notice
