Skip to content

[ADD] l10n_sk_hr_payroll_health: shared assessments and current text514 - #34

Closed
votrelec wants to merge 4 commits into
Data-Dance:19.0from
votrelec:feat/sk-health-514-text
Closed

votrelec wants to merge 4 commits into
Data-Dance:19.0from
votrelec:feat/sk-health-514-text

Conversation

@votrelec

@votrelec votrelec commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

The legacy health statement reconstructs employee bases and rates from GROSS and rounded premiums, puts everyone in one disability group, and cannot represent the published minimum-top-up/OP fields correctly. This adds a current text514 path driven by the same assessment facts as payroll.

The base module provides the common OP/base calculation and reviewed monthly insurance calendars. Calendar intervals distinguish employment, actual 2D work/rest days, the single 2Y day, benefit days and minimum exceptions. Reviews and revisions retain their original facts, reviewer and time; company rules, protected API/default paths and parent locks cover changes to both headers and children.

The OCA adapter uses those facts for employee premiums, disability rates and the monthly minimum. Computed payslips retain their original insurer, income category, actual rates, bases, premiums and calendar source. The declaration verifies all matching monetary lines instead of trusting the first row of a repeated rule code. Later employee-card edits do not silently reclassify a historical source.

The native health workflow offers the insurer-published 2023+ UTF8 text format with both disability groups, OP/other income, the separate employee top-up, original N and full corrective O filings. It keeps the existing XML API default and the common generate/reset/filed-attachment workflow. Two small declaration-base hooks supply format-specific attachment metadata and a truthful validation message. Existing filed bytes remain available after corrections. A superseded calendar requires a payroll-source review before new generation.

Validation:

  • Follow-up concurrency audit reproduced a stale calendar review after a committed child-only edit. The parent now advances a non-key version so PostgreSQL retries the stale transaction. All57 base tests pass, including the real two-transaction case; earlier237/928 counts below precede this additional guard and must not be presented as its regression.

  • 237 native tests pass on the public modules without private adapters.

  • Ordinary stock payroll Officer HTTP workflow passes twice: actual UI onchange, calculation, confirmation, TXT download, calendar review/revision and loaded Slovak fields/Python errors. The stock Officer group implies HR Manager; this was not tested as system administrator or Payroll Manager.

  • 928 tests pass in the shared payroll assembly with its installed accounting, corrections, annual-tax and employment adapters. That assembly includes separately tested pending sickness/average fixes; the clean public run above excludes private adapters.

  • Native Odoo POT export, full Slovak merge, Ruff 0.13.0 and diff whitespace checks pass. Canonical English/Slovak documentation is updated; the generated documentation site was not rebuilt because its source generator is not published here.

Scope is explicit: this does not submit 601 notices, fabricate legacy assessment evidence, automatically build additive corrections or consolidate multiple independent correction sources into a single employee-month. Those need their corresponding source adapters. Calendar review is factual HR evidence, not proof of submission to an insurer. The new payroll integration was verified with the OCA engine; the engine-neutral source alone does not establish an Enterprise integration.

Primary interfaces and interpretation: published514 text specification, Health Insurance Act, insurer minimum-advance guidance.

@Rad0van

Rad0van commented Nov 10, 2026

Copy link
Copy Markdown
Member

Thank you for this. The text514 codec is careful, and the field list matches the published structure: we checked the VšZP struktura-vykazu-1.rtf against your pinned SHA-256 and went through every header, aggregate and body field. We applied the branch on current 19.0 (the only conflicts were the l10n_sk_hr_payroll_oca version line in the manifest and the two docs) and ran it under sk_SK on both engines. On Community with OCA payroll, all 77 new tests pass, and the 392 existing tests in the SK payroll and declaration modules give the same result as on 19.0. On Enterprise, the existing suites are also unchanged, but the new tests error (see 3).

Before this can merge, there is one design question, plus a few points that depend on its answer.

Design

  1. Recorded bases should be one mechanism for every fund, not a health-only snapshot. In cssk-public#25 we agreed that every fund rule, in both engines, records on the payslip the base it actually charged, and that the declarations read those recorded bases instead of rebuilding them from GROSS. l10n_sk_health_assessment_snapshot (l10n_sk_hr_payroll_oca/models/health_assessment.py:31) is a JSON blob in the OCA bridge only, it is health-specific, and it is read through an OCA-only method (_l10n_sk_health_assessment_facts, line 216). Social insurance, which needs this more than health does (MVP, VPP, ELDP), would then need a second mechanism, and the declarations would need two readers. Could you reshape it as follows?

    • One per-fund record of {fund, base, rate, amount, side} written by each fund rule. Health is one fund, with its extra facts (OP, OP income, other income, top-up, insured days, disability, insurer) alongside.
    • The pure calculation and the record shape go in l10n_sk_hr_payroll_base, as you already did with health_assessment.py.
    • A single accessor in l10n_cssk_payroll_declaration_base, for example _payslip_fund_bases(slip), that every declaration calls. Each engine bridge provides the storage.

    This PR can still populate only the health fund. What matters is that MVP/VPP/ELDP can then be switched over without a second design.

  2. Payslips without recorded facts: the agreed behaviour differs by declaration. Since 2026-11-10 the rule is:

    • The monthly annexes (MVP, VPP and the health statement) fall back to the gross-based figures and show a visible warning that names the payslips concerned.
    • ELDP and corrective filings are refused until the payslips have been recomputed.

    At the moment, an original (N) text514 refuses any payslip computed before upgrade (health_assessment.py:230, "no matching retained health assessment"), and confirmed payslips can never gain a snapshot (compute_sheet skips them, line 193). So the first month after upgrade cannot be filed in the new format at all, and the legacy XML path keeps rebuilding from GROSS with no warning. Please:

    • make the N filing fall back with a warning (message plus chatter note listing the payslips);
    • keep the refusal for O filings;
    • add tests for both cases. Neither the missing-snapshot path nor the contract-mismatch path (lines 230 and 236) is covered today.
  3. Enterprise engine. Today Enterprise gets none of this, and two things break or diverge for it:

    • The menu action now defaults to export_format = 'text2023' (views/l10n_sk_health_views.xml:83). On an Enterprise database every new statement created from the menu therefore fails, with "The installed payroll engine has no retained health-assessment adapter" (models/text514.py:103-107). Before this PR it generated XML. Please keep the menu default on XML until both engines provide the adapter, or choose the default according to which engine is installed.
    • The new tests in l10n_sk_hr_payroll_health (test_text514_lifecycle.py, and the reworked test_later_profile_at_another_insurer_…) create employees with the OCA-only struct_id. On Enterprise that gives 12 errors (Invalid field 'struct_id' in 'hr.employee'). The module is engine-neutral, so these tests should either skip without the OCA engine or build their payslips the way test_health.py does, through self.engine.

    We will do the Enterprise bridge ourselves at merge. Having this PR not break Enterprise in the meantime is enough.

Correctness

  1. A reviewed calendar silently overrides the contract's ZŤP flag. l10n_sk_health_is_disabled (l10n_sk_hr_payroll_base/models/hr_version.py:118) takes disability only from the calendar whenever a reviewed calendar exists. If a reviewed calendar lacks a disabled interval for an employee with l10n_sk_ztp = True, the payslip switches to the standard rates and to the minimum top-up without any message. Please refuse the calculation (or at least warn) when the calendar and the contract disagree.

  2. No calendar kind for 2P or 2S. The ÚDZS methodology (bulletin 1/2026) uses 2P for an employee in employment with an OP claim who is also an employee on another ground at the same employer. With such a registration there is nothing to enter, and because op_employment counts only kind 2 (health_calendar.py:64), the OP ratio becomes 0. Strike days (2S) also have no kind: under § 16 ods. 8 písm. d) the advance for them is 0. Please either add both kinds, or refuse with a clear message when they would be needed.

  3. DoBPŠ and the minimum top-up when a calendar exists. Without a calendar, the HEALTH_DOPLATOK rule still zeroes the minimum for dobps. With a calendar, the minimum depends only on whether a state interval was entered. A reviewed calendar for a student that misses the state interval therefore charges a top-up. A guard in l10n_sk_health_calendar_minimum, or a review-time check that a DoBPŠ month has state days, would close this.

  4. § 16a ods. 5 opt-out preconditions. The opt-out only requires a non-empty evidence string (hr_version.py:35). The statute allows it only while the employee has concurrent employers in the month. Where a reviewed calendar exists and has no other_employment days, the opt-out should be refused for that month.

  5. OP rounding. employee_assessment rounds the OP up to the cent (health_assessment.py:58). Before this PR it was not rounded at all, and § 16 ods. 16–18 says nothing about rounding the OP. The effect is at most a cent on the base, but because it is a change in money, please cite the insurer guidance you are relying on, in the docstring and in the PR.

  6. Implicit dependency. models/text514.py:118 searches l10n.sk.health.calendar, but l10n_sk_hr_payroll_health depends neither on l10n_sk_hr_payroll_base nor on an engine. This works today only because the engine check comes first. Please declare the dependency, or guard the lookup.

  7. Concurrency. Bumping write_date with raw SQL (models/health_calendar.py:156-175) to make a stale REPEATABLE READ transaction retry is sound, and the two-cursor test proves it. Two small requests:

    • say in a comment that the retry depends on Odoo's serialization-failure retry, which only happens for RPC/HTTP requests, so a job or a script calling action_review must handle SerializationFailure itself;
    • wrap the concurrency test in mute_logger('odoo.sql_db'), because the expected failure is logged at ERROR ("bad query … could not serialize access"). That reads as a failure in CI logs.

Tests (coverage measured on the touched modules, 89% overall)

  1. The money and compliance paths that are not exercised, in order of risk:
    • the confirmation refusal when sources changed after the computation (health_assessment.py:280);
    • the base-versus-premium mismatch guard (line 186);
    • the refusal for an agreement without a 2D day source, and the PN calendar-source disagreements (lines 104–122, 250–256);
    • "excluded source contains health premiums" (l10n_sk_health.py:168);
    • most of the codec's own refusals: IBAN syntax, payer number, insurer code, payment day (text514.py:124-170).

Conventions

  1. Changelogs:
    • The new entries are bare bullets at the top of [Unreleased], with no Added/Changed/Fixed sections and no version line for the bumped versions.
    • l10n_sk_hr_payroll_oca has a Carry-over to 18.0 section, and 19.0.1.25.0 belongs there ("not yet on 18.0").
    • In l10n_sk_hr_payroll_health and l10n_sk_hr_payroll_base the Unreleased heading underline levels are inconsistent (~~~ and ---).
  2. l10n_cssk_payroll_declaration_base/doc/cs.md still says verified: 19.0.1.5.1 while the manifest is 19.0.1.5.2. The en/sk pages were bumped, but the Czech one was not.
  3. Missing spaces before digits run through the strings, docs and commit messages: "insurer-published2023+", "January2023", "All57", "Section16a(5)". Several are user-facing msgids, so the Slovak catalogue inherits them. Please run a pass for [a-z][0-9] in the msgids.
  4. The last commit, "Force concurrent health calendar review to retry after interval edits", has no [FIX]/[IMP] tag. New-file copyright headers are mixed (Copyright 2026 votrelec in health_calendar.py and models/health_calendar.py, and Data Dance s.r.o., votrelec elsewhere). Please use one form.

Size

  1. At about 5,000 lines across four shared modules, this is hard to review as a single unit, and point 1 will reshape part of it anyway. We would suggest three PRs, each mergeable on its own:

    • (a) the per-fund recorded-bases mechanism, with health as the first fund, the OCA bridge, and the fallback/refusal policy from point 2;
    • (b) the reviewed monthly insurance calendars;
    • (c) the text514 codec and its declaration path, on top of (a), plus the two small declaration-base hooks.

    The declaration-base hooks in (c) are fine as they are: the CZ declarations are unaffected by them.

@votrelec

Copy link
Copy Markdown
Contributor Author

Review follow-up: shared fund records

Thank you for the detailed engine and published-format checks. I reproduced three calendar/profile cases on the public source: a reviewed calendar dropping version disability, a minimum opt-out without calendar concurrency, and health contributions on a student agreement. The three regressions fail before the fix; the first local correction passes 33 health calculation tests. This is not the full review resolution yet.

I am reshaping #34 into the shared per-fund recorded-base mechanism, with health as the first fund, one declaration accessor, and the requested monthly-original warning fallback versus corrective/ELDP refusal. The existing precise historical evidence will remain readable without rewriting confirmed payslips. #37 will consume this same mechanism for social funds rather than introduce a second recording design.

The reviewed calendars and text514 path will be split into their own dependent contributions. XML will remain usable without the recorded-base adapter, and engine-specific fixtures will be kept separate from engine-neutral tests. I will leave the Enterprise bridge to you as offered.

I have also started the independent #35 fixes: explicit assertion language, cleanup of Enterprise payroll-note dependencies belonging only to the test's own company, muted expected serialization errors, the conventional schema pin, and Czech verified metadata. The first registration batch passes 30 Community tests; this does not claim an Enterprise run. The remaining source guards, storage-migration workflow, 2P/2S policy, catalogue/style pass and documentation hooks are being handled with the corresponding split.

@votrelec

votrelec commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Broader contribution roadmap and architecture alignment

To make the final direction clearer beyond the individual reviews: the intended contribution is to fill gaps in standard Slovak company accounting and payroll in this repository, using its existing applications as the foundation. It is not a replacement payroll engine or a second accounting ledger. I would like to agree on the extension boundaries early, rather than submit large changes that diverge from this repository's architecture or Enterprise bridge.

The remaining work is grouped as follows; this is a roadmap, not a claim that these features are complete:

  1. Recorded statutory fund bases first. Following your review of [ADD] l10n_sk_hr_payroll_health: shared assessments and current text514 #34 and issue [19.0] MVP annex reuses gross base for all social funds on student/pension OOP #25, one engine-neutral record shape in l10n_sk_hr_payroll_base, actual bases recorded by the fund rules, storage in the engine bridge, and one declaration accessor in l10n_cssk_payroll_declaration_base. Health is the first consumer; [FIX] l10n_sk_hr_payroll: retain individual social fund bases for MVP #37's social funds will use the same mechanism. Precise historical records remain readable without rewriting confirmed payslips. Monthly originals retain your requested explicit warning fallback; corrective declarations and ELDP require precise evidence. I will leave the Enterprise bridge to you as offered and keep engine-specific tests separate.
  2. Dependent health contributions. Separate reviewed day calendars (including disability, students, concurrent employers and the 2P/2S policy), then the 514 codec/declaration. Rebase [ADD] l10n_sk_hr_payroll_health_registration: reviewed601 notices #35's 601 registration and correction work on those pieces. Small common declaration hooks remain cooperative and country-neutral where appropriate.
  3. Payroll lifecycle and corrections. Complete the native absence/PN/OCR, leave/average-earnings, mid-period insurance-profile and benefit cases; complete financial settlement of already-paid corrections. Preserve historical contracts, recorded bases, filed bytes and native accounting entries. Full native refunds and statutory replacement declarations are distinct workflows. Engine-wide fixes go to OCA/payroll where appropriate; Slovak rules and adapters stay here.
  4. Annual payroll/tax continuity. Keep monthly tax corrections, annual settlement revisions, actual payment/refund evidence and prescribed employee/authority outputs consistent. Prefer the existing declaration and accounting workflows over parallel filing/payment models. Bring any reusable pieces forward as focused contributions after checking the native equivalents.
  5. Company accounting closure. Follow through on the vehicle disposal/road-tax, withholding and financial-transaction-tax contributions and their integration into the existing asset, GL, VAT and corporate-return/annual-statement flows. Shared framework changes will be separated from country-specific forms. There should be no second asset register, bank ledger or tax calculation duplicating an existing native source.
  6. Cross-module acceptance and dated rules. Validate a complete accounting year, opening/closing continuity, upgrades retaining historical data, standard user access, translations and effective-dated parameters/forms. Future form versions will only be claimed when published and verified; XML/XSD validation is distinct from actual acceptance by an authority.

The immediate implementation remains the A/B/C split you requested, rather than expanding #34 again. Local review fixes and tests will be carried over, but I am not treating their current passing results as verification of the reshaped architecture or of Enterprise.

Could you flag any of these workstreams that overlap existing functionality or planned work for this repository, so I can avoid duplication? In particular, does the proposed ownership of the shared fund schema/accessor and bridge storage match your intended architecture, and should the replacement fund-core PR supersede #34 with B/C as dependent PRs? Also, should documentation-topic registration be supplied as a snippet since guide/topics.yaml is absent from this checkout?

I will continue the agreed shared fund implementation while these questions are open, and keep the remaining pieces small enough to review by responsibility. Your direction on module boundaries and ordering will take precedence over the tentative roadmap.

@Rad0van

Rad0van commented Nov 10, 2026

Copy link
Copy Markdown
Member

Thank you for laying this out. The direction matches ours, and agreeing the boundaries now is the right order. Answers to your questions:

1. Ownership of the shared fund records. Yes, that's the architecture we want:

  • l10n_sk_hr_payroll_base: the abstract mixin and the record shape (fund, side, base, rate, amount, plus a free extra field), with the generic checks. No storage there.
  • Each engine bridge: the storage and the writing from its own fund rules. You do l10n_sk_hr_payroll_oca; we write the Enterprise side, as offered.
  • l10n_cssk_payroll_declaration_base: one plural accessor that returns, for a set of payslips, their fund records plus the payslips that have none. The policy then sits in one place: monthly originals and ELDP fall back to gross with a warning naming those payslips, and corrective filings refuse them.
  • Each declaration (MVP, VPP, health) keeps its own mapping from fund records to its XML attributes.

Please keep the engine-neutral tests in the base and the engine-specific fixtures in each bridge. Pin message-matching tests to en_US, since we run everything with sk_SK loaded.

2. Ordering. Yes. Open the fund core as a new PR that references #34 and #37, and close #34 once it is up. Then the reviewed calendars (B) and the 514 format and declaration (C) as dependent PRs, with #35 rebased on C. Keep the confirmation and locking changes from #37 in their own PR, as you planned.

3. Overlap with what already exists. Please build on these rather than alongside them:

4. Guide topics. guide/ is not published, so put the guide/topics.yaml line you want in the PR description and we'll add it at merge.

One change to the policy from #25: ELDP falls back to gross with the warning, like the monthly originals, instead of refusing. ELDP is now only for periods before 2026 (#41), and those payslips will never carry fund records, so a refusal would block every remaining ELDP, including the one-off § 293gl filings due by 31 December 2026. Corrective filings still refuse.

#42 is reviewed separately; we'll merge it.

@votrelec

Copy link
Copy Markdown
Contributor Author

Superseded by #43 for shared fund core A, following the agreed ordering. Reviewed calendars B and the 514 codec/declaration C are retained for dependent contributions; #35 will be rebased on C. Confirmation/source locking remains separate. Closing this combined proposal as requested once the new core is up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants