[MIG] hr_luncheon_voucher: migrate to 18.0
This commit is contained in:
Stéphan Sainléger
170
hr_luncheon_voucher/README.md
Normal file
170
hr_luncheon_voucher/README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user