Skip to content

Commit b83320e

Browse files
author
Jani Giannoudis
committed
updated README.md
1 parent 53c98f0 commit b83320e

File tree

1 file changed

+144
-131
lines changed

1 file changed

+144
-131
lines changed

‎README.md‎

Lines changed: 144 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,85 @@
1-
# {CC}.{RegulationName}
1+
# Regulation.{CC}.{Name}
22

3-
> **Payroll Engine Country Regulation Template**
4-
> Replace all `{CC}`, `{RegulationName}`, `{cc}`, `{Provider}` placeholders before use.
5-
> See [TEMPLATE.md](TEMPLATE.md) for step-by-step setup instructions.
6-
7-
Country payroll regulation for **{CC}** — `{RegulationName}`.
3+
{Country} payroll regulation for **{Full Legal Name}** — {Year}.
84

95
Implemented as a [Payroll Engine](https://github.com/Payroll-Engine) regulation.
6+
Targets payroll periods from {Year} onwards. Rates and parameters are sourced
7+
directly from official {AuthorityName} publications.
8+
9+
---
10+
11+
## Status
12+
13+
> **Status:** {e.g. stable / beta / in progress — short note on current phase}
14+
> **Scope:** {e.g. Régimen General — key components covered in one line}
15+
> **Certification:** {e.g. SILTRA/Sistema RED — out of scope | not applicable}
1016
1117
---
1218

1319
## Scope
1420

15-
| Component | Status | Notes |
16-
|---|---|---|
17-
| Base salary (prorata) | ✅ | Calendar-day prorata via Indienst/Uitdienst |
18-
| Tax withholding | 🔲 | To be implemented |
19-
| Social insurance employee | 🔲 | To be implemented |
20-
| Social insurance employer | 🔲 | To be implemented |
21-
| ID validation | 🔲 | National identifier checksum |
21+
| Component | Included |
22+
|:---|:---:|
23+
| {Component 1} | ✅ |
24+
| {Component 2} | ✅ |
25+
| {Component 3 — out of scope} | ❌ |
26+
| {Component 4 — planned} | 🔜 |
2227

2328
---
2429

25-
## Regulation Structure
30+
## Regulation Layers
2631

2732
The regulation is split into a **core layer** (calculation logic) and
2833
**data layers** (annual rates and parameters). Each data source can be
2934
updated independently without touching the calculation scripts.
3035

3136
```
32-
{CC}.{RegulationName} Core — cases, collectors, scripts, wage types
33-
{CC}.{RegulationName}.Data.Tax Tax brackets and rates (official statutory source)
37+
{CC}.{Name} Core — logic, cases, wage types, scripts
38+
{CC}.{Name}.Data.{Source1} {Description} ({Authority})
39+
{CC}.{Name}.Data.{Source2} {Description} ({Authority})
3440
```
3541

36-
Annual updates require only new data files with a matching `validFrom`.
37-
The core regulation and scripts remain unchanged unless the calculation logic itself changes.
42+
Annual updates require only new data files (e.g. `{CC}.{Name}.Data.{Source1}.{Year+1}.json`)
43+
with a matching `validFrom`. The core regulation and scripts remain unchanged unless
44+
the calculation logic itself changes.
45+
46+
| Regulation | Type | Content |
47+
|:---|:---|:---|
48+
| `{CC}.{Name}` | Functional | Cases, WageTypes, Collectors, Scripts |
49+
| `{CC}.{Name}.Data.{Source1}` | Data | {Description} |
50+
| `{CC}.{Name}.Data.{Source2}` | Data | {Description} |
3851

3952
---
4053

4154
## Repository Layout
4255

4356
```
44-
Regulation.{CC}.{RegulationName}/
45-
.github/
46-
workflows/
47-
ci.yml CI build — working-directory: YYYY
48-
release.yml Release trigger on YYYY/Directory.Build.props
49-
YYYY/
57+
Regulation.{CC}.{Name}/
58+
{Year}/
5059
Regulation/
51-
{CC}.{RegulationName}.{YYYY}.json
52-
{CC}.{RegulationName}.Scripts.{YYYY}.json
53-
{CC}.{RegulationName}.Collectors.{YYYY}.json
54-
{CC}.{RegulationName}.Cases.{YYYY}.json
55-
{CC}.{RegulationName}.WageTypes.{YYYY}.json
60+
{CC}.{Name}.Cases.{Year}.json
61+
{CC}.{Name}.Collectors.{Year}.json
62+
{CC}.{Name}.Scripts.{Year}.json
63+
{CC}.{Name}.WageTypes.{Year}.json
5664
Scripts/
57-
WageTypeValueFunction.Action.cs No-Code custom actions (WageTypeValueAction)
58-
CaseValidateFunction.Action.cs No-Code custom actions (CaseValidateAction)
59-
Reports/
60-
README.md
61-
{ReportName}/
62-
Report.json / ReportEndFunction.cs / {ReportName}.frx
63-
parameters.json / Import.pecmd / Script.pecmd / Report.Build.pecmd / Report.Pdf.pecmd / README.md
64-
Docs/
65-
{CC}.{RegulationName}-Analysis.md
66-
{CC}.{RegulationName}-NoCodeDesign.md
67-
{CC}.{RegulationName}-TestSpec.md
65+
WageTypeValueFunction.Action.cs Custom actions (WageTypeValueAction)
66+
CaseValidateFunction.Action.cs Custom actions (CaseValidateAction)
67+
{CC}{Helper1}.cs {Description} (also unit-tested)
68+
{CC}{Helper2}.cs {Description}
6869
Tests/
69-
README.md
7070
{CC}.Test.Setup.json
7171
{CC}.Test.CompanyCases.json
72-
TC01/
73-
Schemas/
74-
PayrollEngine.Exchange.schema.json
75-
Directory.Build.props
76-
regulation-package.json
77-
Regulation.{CC}.{RegulationName}.{YYYY}.csproj
78-
nuget.config
72+
Tests/ Individual test cases (WT-TC*, GUARD-TC*)
73+
Tests.Unit/ xUnit unit tests for algorithm classes
74+
Reports/
75+
{ReportFolder1}/
76+
{ReportFolder2}/
7977
Setup.pecmd
80-
Setup.Regulation.pecmd
81-
Setup.Data.pecmd
82-
Setup.Tests.pecmd
8378
Test.All.pecmd
84-
Test.Preview.pecmd
85-
Delete.pecmd
86-
Delete.Tests.pecmd
87-
Data.Tax.YYYY/
88-
Regulation/
89-
{CC}.{RegulationName}.Data.Tax.{YYYY}.json
90-
Schemas/
91-
PayrollEngine.Exchange.schema.json
92-
Directory.Build.props
93-
regulation-package.json
94-
Regulation.{CC}.{RegulationName}.Data.Tax.{YYYY}.csproj
95-
nuget.config
96-
Setup.pecmd
97-
Delete.pecmd
98-
Regulation.{CC}.{RegulationName}.sln
99-
Test.{YYYY}.pecmd
100-
README.md
101-
TEMPLATE.md
102-
.gitignore
79+
Data.{Source1}.{Year}/
80+
Data.{Source2}.{Year}/
81+
Docs/
82+
Schemas/
10383
```
10484

10585
---
@@ -108,27 +88,34 @@ Regulation.{CC}.{RegulationName}/
10888

10989
**Collectors:**
11090

111-
| Collector | Description | NetPay formula |
112-
|---|---|---|
113-
| `{CC}.GrossIncome` | Gross income — all gross salary components | + |
114-
| `{CC}.Deductions` | Employee deductions — tax + social insurance | − |
115-
| `{CC}.EmployerCost` | Employer social costs | informational |
91+
| Collector | Role | NettoLoon |
92+
|:---|:---|:---:|
93+
| `{CC}.{GrossCollector}` | Gross income — all gross salary components | + |
94+
| `{CC}.{DeductionCollector}` | Employee deductions | − |
95+
| `{CC}.{EmployerCollector}` | Employer social costs | info |
11696

117-
`NetPay` (WT 6500) = `{CC}.GrossIncome` − `{CC}.Deductions`
97+
`NettoLoon (WT {nr})` = `{CC}.{GrossCollector}` − `{CC}.{DeductionCollector}`
11898

11999
**Matrix:**
120100

121-
| Nr | Name | GrossIncome | Deductions | EmployerCost | Action / Expression |
122-
|---:|---|:---:|:---:|:---:|---|
123-
| 10 | ProrataFactor | | | | `{CC}CalculateProrata` — calendar-day factor |
124-
| 1000 | BaseSalary | ✓ | | | `^^BaseSalary × ^$10` |
125-
| 5000 | GrossTotal | | | | `^&GrossIncome` — collector snapshot |
126-
| 5100 | TaxWithheld | | ✓ | | `{CC}CalculateTax` — annual projection |
127-
| 6500 | NetPay | | | | `^&GrossIncome − ^&Deductions` |
128-
129-
**Notes:**
130-
- WT 6500 (`NetPay`) must always have a higher number than all component WageTypes
131-
to ensure collectors are fully populated at net salary calculation time.
101+
| Nr | Name | Gross | Ded | Empl | Action / Expression |
102+
|---:|:---|:---:|:---:|:---:|:---|
103+
| 1 | Guard | | | | `{CC}GuardMandatoryFields` — aborts on missing {Field1}/{Field2} |
104+
| 2 | Guard{X} | | | | `{CC}Guard{X}` — aborts when {Condition} |
105+
| 10 | {TechnicalWT} | | | | `{ActionName}` — sets `{CC}.{RuntimeValue}` |
106+
| 1000 | {GrossWT1} | ✓ | | | `{ActionName}` — {short description} |
107+
| 1100 | {GrossWT2} | ✓ | | | `{expression}` |
108+
| 5000 | {GrossMirror} | | | | `^&{GrossCollector}` — collector mirror, informational |
109+
| 5100 | {TaxWT} | | | | `{ActionName}` — {short description} |
110+
| 5110 | {CreditWT} | | | | `{ActionName}` — negative; {short description} |
111+
| 5130 | {TaxNet} | | ✓ | | `^${5100} + ^${5110}` |
112+
| 6500 | NettoLoon | | | | `^&{GrossCollector} − ^&{DeductionCollector}` |
113+
| 6700 | {EmployerWT1} | | | ✓ | `{ActionName}` — {short description} |
114+
| 6710 | {EmployerWT2} | | | ✓ | `{ActionName}` — {short description} |
115+
116+
> **Notes:**
117+
> - WTs 1–{n} (Guards), {tech WTs}: no collector — runtime setters / control flow.
118+
> - WTs 5100–5120: no collector — intermediate values summed in WT 5130.
132119
133120
---
134121

@@ -137,107 +124,133 @@ Regulation.{CC}.{RegulationName}/
137124
### WageType Actions (`Scripts/WageTypeValueFunction.Action.cs`)
138125

139126
| Action | WT | Description |
140-
|---|---|---|
141-
| `{CC}CalculateProrata` | 10 | Calendar-day prorata factor from Indienst/Uitdienst dates |
142-
| `{CC}CalculateTax` | 5100 | Tax withholding via annual projection |
127+
|:---|---:|:---|
128+
| `{CC}GuardMandatoryFields` | 1 | Validates {Field1} > 0, {Field2} set; aborts on failure |
129+
| `{ActionName}` | {nr} | {short description} |
143130

144131
### Case Validate Actions (`Scripts/CaseValidateFunction.Action.cs`)
145132

146133
| Action | Case | Description |
147-
|---|---|---|
148-
| `{CC}ValidateNationalId` | {CC}.Personal | National ID checksum validation |
134+
|:---|:---|:---|
135+
| `{ValidateAction1}` | `{CC}.{Case1}` | {short description} |
136+
| `{ValidateAction2}` | `{CC}.{Case2}` | {short description} |
149137

150138
---
151139

152140
## Cases
153141

154142
### Employee Cases
155143

156-
| Case | Fields | Description |
157-
|---|---|---|
158-
| `{CC}.Salary` | `{CC}.BaseSalary` | Monthly gross salary |
159-
| `{CC}.Personal` | `{CC}.NationalId` | National identifier |
160-
| `{CC}.Employment` | `{CC}.ContractType`, `{CC}.Indienst`, `{CC}.Uitdienst` | Contract type and employment period |
144+
| Case | Fields | Description | Availability |
145+
|:---|:---|:---|:---|
146+
| `{CC}.{Case1}` | `{CC}.{Field1}`, `{CC}.{Field2}` | {Description} | always |
147+
| `{CC}.{Case2}` | `{CC}.{Field3}` | {Description} | {Condition} is set |
161148

162149
### Company Cases
163150

164151
| Case | Fields | Description |
165-
|---|---|---|
166-
| `{CC}.Configuration` | `{CC}.EmployerId` | Employer registration number |
152+
|:---|:---|:---|
153+
| `{CC}.{CompanyCase1}` | `{CC}.{Field1}` | {Description} |
167154

168155
---
169156

170157
## Payroll Layer Configuration
171158

172159
```json
173160
"layers": [
174-
{ "level": 1, "priority": 1, "regulationName": "{CC}.{RegulationName}" },
175-
{ "level": 1, "priority": 2, "regulationName": "{CC}.{RegulationName}.Data.Tax" }
161+
{ "level": 1, "priority": 1, "regulationName": "{CC}.{Name}" },
162+
{ "level": 1, "priority": 2, "regulationName": "{CC}.{Name}.Data.{Source1}" },
163+
{ "level": 1, "priority": 3, "regulationName": "{CC}.{Name}.Data.{Source2}" }
176164
]
177165
```
178166

179-
PE selects the correct regulation version automatically based on the payrun `EvaluationDate`.
180-
Retro-payruns use historical versions without any manual configuration.
167+
PE selects the correct regulation version automatically based on the
168+
payrun `EvaluationDate` — retro-payruns use historical versions without manual config.
169+
170+
---
171+
172+
## Sub-Projects
173+
174+
| Folder | Content | Version |
175+
|:---|:---|:---|
176+
| `{Year}/` | Functional regulation {Year} | {Year}.1-alpha.dev |
177+
| `Data.{Source1}.{Year}/` | {Source1} data regulation {Year} | {Year}.1-alpha.dev |
178+
| `Data.{Source2}.{Year}/` | {Source2} data regulation {Year} | {Year}.1-alpha.dev |
181179

182180
---
183181

184-
## Setup and Testing
182+
## Quick Start
183+
184+
```pecmd
185+
# Standard payroll
186+
Test.{Year}.pecmd
185187
188+
# {Special scenario, if applicable}
189+
Test.{Scenario}.{Year}.pecmd
186190
```
187-
# Full setup (regulation + data + test tenant)
188-
YYYY/Setup.pecmd
189191

190-
# Run all tests
191-
YYYY/Test.All.pecmd
192+
### Setup and Testing
192193

193-
# Or use the root shortcut
194-
Test.YYYY.pecmd
194+
```
195+
# 1 — Import regulation and data
196+
{Year}/Setup.pecmd
195197
196-
# Cleanup
197-
YYYY/Delete.pecmd
198+
# 2 — Run all tests
199+
{Year}/Test.All.pecmd
198200
```
199201

200-
See [`YYYY/Tests/README.md`](YYYY/Tests/README.md) for the full test index.
202+
---
203+
204+
## Data Sources
205+
206+
| Regulation | Source | Update Cycle |
207+
|:---|:---|:---|
208+
| `Data.{Source1}` | {Authority} — *{Publication name}* | Annual ({Month}) |
209+
| `Data.{Source2}` | {Authority} — *{Publication name}* | Annual ({Month}) |
210+
| `Data.{Source3}` | {Authority} — *{Publication name}* | Semi-annual (1 Jan + 1 Jul) |
201211

202212
---
203213

204214
## Reports
205215

206-
Reports are located in `YYYY/Reports/`. Each report lives in its own subfolder
207-
with all required files co-located. See [`YYYY/Reports/README.md`](YYYY/Reports/README.md)
208-
for the full workflow.
216+
Reports are independent of the test suite and located in `{Year}/Reports/`.
217+
Each report lives in its own subfolder with all required files co-located.
218+
219+
| ID | Name | DB Name | Description |
220+
|:---|:---|:---|:---|
221+
| R01 | {ReportName1} | `{CC}.{ReportName1}` | {Description — period/YTD/annual} |
222+
| R02 | {ReportName2} | `{CC}.{ReportName2}` | {Description} |
209223

210224
---
211225

212-
## Data Sources
226+
## Annual Update Workflow
213227

214-
| Regulation | Content | Source | Update Cycle |
215-
|---|---|---|---|
216-
| `{CC}.{RegulationName}.Data.Tax` | Tax brackets and rates | Official statutory source | Annual |
228+
See [`{Year}/Docs/{CC}.{Name}-UpdateWorkflow.md`]({Year}/Docs/{CC}.{Name}-UpdateWorkflow.md)
229+
for the complete year-over-year update process ({key items: rates, brackets, ceilings, etc.}).
217230

218231
---
219232

220233
## Known Limitations
221234

222-
### Electronic Filing
223-
Electronic declaration / submission to tax authorities is not included.
224-
The regulation provides all calculation inputs required for manual filing.
235+
### {Limitation Title 1}
236+
{Description — what is missing, why, and how the gap can be closed if needed.}
237+
238+
### {Limitation Title 2}
239+
{Description.}
225240

226241
---
227242

228-
## Documentation
243+
## Legal Sources
229244

230-
| File | Description |
231-
|---|---|
232-
| [`YYYY/Docs/{CC}.{RegulationName}-Analysis.md`](YYYY/Docs/{CC}.{RegulationName}-Analysis.md) | System analysis, regulation design, versioning strategy |
233-
| [`YYYY/Docs/{CC}.{RegulationName}-NoCodeDesign.md`](YYYY/Docs/{CC}.{RegulationName}-NoCodeDesign.md) | No-Code / Low-Code action specification |
234-
| [`YYYY/Docs/{CC}.{RegulationName}-TestSpec.md`](YYYY/Docs/{CC}.{RegulationName}-TestSpec.md) | Test case calculations with source references |
235-
| [`YYYY/Tests/README.md`](YYYY/Tests/README.md) | Test index |
245+
- {Law/Ordinance 1} — {short description of what it governs}
246+
- {Law/Ordinance 2} — {short description}
247+
- {Official Website} — https://{url}
236248

237249
---
238250

239251
## See Also
252+
240253
- [Payroll Engine](https://github.com/Payroll-Engine/PayrollEngine)
241254
- [Country Bootstrap Guide](https://github.com/Payroll-Engine/Regulation.COM.Base/blob/main/Docs/Country-Bootstrap.md)
242-
- [Consolidation Template](https://github.com/Payroll-Engine/PayrollEngine.Template.Regulation.Country.Consolidation) — template for COM.Base mapping regulation
255+
- [Country Regulation Template](https://github.com/Payroll-Engine/PayrollEngine.Template.Regulation.Country)
243256
- [Regulation Deployment](https://payrollengine.org/concepts/regulation-deployment)

0 commit comments

Comments
 (0)