171 lines
6.4 KiB
Markdown
171 lines
6.4 KiB
Markdown
# HR Luncheon Voucher
|
|
|
|
[](https://odoo-community.org/page/development-status)
|
|
[](http://www.gnu.org/licenses/agpl-3.0-standalone.html)
|
|
[](https://github.com/elabore-coop/hr-tools)
|
|
|
|
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](https://git.elabore.coop/Elabore/hr-tools/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.
|