hr-tools/hr_luncheon_voucher/README.md

HR Luncheon Voucher

Manage luncheon vouchers credit and distribution for employees.

Description

This module allows the management of luncheon vouchers attribution and distribution. Employees can indicate which days are not concerned by luncheon vouchers. HR managers can adjust the number of luncheon vouchers to distribute and follow each employee's credit.

Key Models

• Luncheon Voucher Allocation (hr.lv.allocation): tracks each distribution campaign per employee, with a state workflow (Draft → Confirmed → Distributed) and computed counters (acquired, due, distributed, balance).
• Employee extensions (hr.employee): additional fields store running totals of acquired, distributed, and remaining vouchers, plus a default monthly distribution value.
• Meeting type extension (calendar.event.type): a boolean field remove_luncheon_voucher lets you mark event categories that cancel the daily voucher (e.g. off-site meetings, free lunch).

Attribution Rules

A luncheon voucher is acquired for a working day if:

• The employee worked on one or all the attendances of the day (depending on whether the option Half working days cancel luncheon vouchers is enabled).
• There is no meeting that cancels the voucher during that day (e.g. off-site or free lunch meetings).
• An attendance is considered worked as long as there is no leave covering the whole attendance time slot.

The calculation is fully automated when an allocation request is created: the system iterates through each day of the period, checks the working calendar, validates attendance coverage, verifies leaves, and cross-references calendar events.

Allocation Lifecycle

State	Description
Draft	Allocation request created by the wizard. HR can adjust the number of vouchers to distribute.
Confirmed	HR manager validates the figures. Employee counters are updated.
Distributed	Vouchers have been effectively handed out. Final counters are set.

Employee Dashboard

In the employee form view, three stat buttons display the current running totals: Acquired, Distributed, and Remaining (Due) vouchers. HR can also refresh these values on demand.

Installation

Use Odoo normal module installation procedure to install hr_luncheon_voucher.

Dependencies

• base (Odoo core)
• calendar (Odoo core)
• hr (Odoo core)
• hr_holidays (Odoo core)
• resource (Odoo core)
• hr_effective_attendance_period (this repository)

Security / Access Rights

Model	HR Users	HR Managers
hr.lv.allocation	Read only	Full CRUD
generate.lv.allocation.requests	Read only	Full CRUD

Configuration

1. Define cancelling meeting categories. Go to Configuration > Technical > Calendar > Meeting Types and enable the Remove luncheon voucher flag on the relevant categories (e.g. Off-site, Free lunch). Two default categories are pre-loaded by the module.

2. Toggle the half-day rule. Go to Configuration > General Settings > Employees and check/uncheck Half working days cancel luncheon vouchers depending on whether partial attendance should still grant a voucher.

3. Set default monthly distribution per employee. Open each employee's form, go to the Luncheon Vouchers section under HR settings, and enter the Default monthly distribution value. This value is pre-filled when a new allocation is created.

4. Configure effective attendance periods. Go to Configuration > Technical > Resource > Working Times and create Working Time entries for each attendance combination used in your company. Make sure to indicate which periods are effectively attended — the module relies on hr_effective_attendance_period to determine daily presence.

Usage

Calendar Events

When creating a calendar event that cancels luncheon voucher distribution (off-site meeting, free lunch, etc.), simply assign the corresponding meeting category to the event.

Generating Allocations

For each distribution period, the HR manager should:

1. Go to the Employees list view.
2. Select all employees concerned by luncheon vouchers distribution.
3. Click the header button Generate Luncheon Vouchers Allocations.
4. Fill in the wizard: set a campaign name (e.g. "January 2026"), a start date, and an end date.
5. Click Create allocations requests.

A voucher allocation request is created for each selected employee in Draft state. The number of acquired vouchers is computed automatically based on the attribution rules.

Allocation Workflow

1. Confirm an allocation request when the figures are verified. Employee running counters are updated.
2. Distribute the allocation when the vouchers have been effectively handed out. Click Distribute Vouchers to mark the request as distributed.
3. Adjust distribution at any time in Draft state to override the pre-filled distributed quantity.
4. Back to draft allows correcting an already confirmed or distributed allocation.
5. The Vouchers balance column shows the difference between due and distributed vouchers for each allocation.

Monitoring

Each employee form displays three stat buttons — Acquired, Distributed, and Due — giving a real-time summary of the employee's luncheon voucher status. Use the Refresh Luncheon Vouchers button in the form header to recompute these values if needed.

Known Issues / Roadmap

None yet.

Bug Tracker

Bugs are tracked on Gitea Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us smash it by providing a detailed and welcomed feedback.

Credits

Contributors

• Stéphan Sainléger https://github.com/stephansainleger

Funders

The development of this module has been financially supported by:

• Elabore (https://elabore.coop)
• Amaco (https://amaco.org)

Maintainer

This module is maintained by Elabore.