Technical architecture

This page is for developers and implementers. It explains how Planning is built so that you can extend it. It applies to SmartERP Planning 17.0.3 on Odoo 17 Community.

Module map#

[planning-module-map]

web_timeline is the OCA timeline view (based on vis-timeline). Planning extends it instead of modifying it.

Design decisions#

• Shifts are planned against resource.resource. Employees and materials (vehicles, rooms) share one schedule. The employee, user and department of a shift are stored computed fields from the resource.
• The model names are smarterp.planning.*. The planning.* namespace belongs to Odoo Enterprise; sharing it would collide on the same tables.
• Allocated time comes from the calendar engine. Working hours are the intersection of the shift and the resource's valid work intervals (_get_valid_work_intervals), so time off, public holidays and, with hr_contract, contract gaps are respected without extra code.
• Utilisation is a stored table. smarterp.planning.capacity is rebuilt nightly for a rolling window and refreshed at commit for the people and days a change touches. It is not a SQL view, because the calendar engine cannot be reproduced in SQL.
• The schedule's data comes from the server. Workload per day, time off shading, the hover card, drop checks, undo snapshots, bulk actions and the To plan panel are model methods in smarterp_planning_shift_schedule.py, so the schedule and the reports agree.
• Bridges extend by hooks, not by patches. A bridge overrides a small _planning_* method and adds fields and views. The core never imports a bridge.
• Self-service goes through methods, not through writes. Employees may write only the name field of their own shift. Taking, releasing and switching are methods that check eligibility and then write with sudo.
• Raw SQL is used in two searches (_search_role_mismatch, _search_overlap_slot_count), both parameter-free, for speed.

How the core is organised#

Extension points#

These are the methods bridges override. Use the same pattern in your own module.

The schedule's front end#

The view type is timeline with js_class="smarterp_planning_timeline". planning_timeline_view.esm.js registers three classes that extend web_timeline:

Every change still goes through the server's rights and checks; the view only avoids offering what the server would refuse. Browser storage used: smarterp_planning.window (session storage, the visible window), smarterp_planning.empty_rows (local storage, the "Only people with shifts" switch) and smarterp_planning.dashboard.dark (local storage, dashboard theme).

The dashboard is a client action smarterp_planning.dashboard; it calls get_planning_dashboard once and draws the charts as SVG, with line icons from a small set of templates.

Data model#

[planning-data-model]

The full list of fields is in the Data model reference.

Performance notes#

• An index on (resource_id, start_datetime, end_datetime) for active shifts serves conflict checks, busy checks and the schedule.
• Dashboard and utilisation figures use read_group and search_count; there is no per-record loop over the ORM.
• The utilisation refresh works in batches of 50 resources and merges the dirty spans of one transaction into one refresh at commit.
• The schedule limits one request to about 400 days, and the card and drop checks to the shifts and resources involved.

Next#

• Data model
• Security reference
• Automation reference
• Testing and upgrades