Skip to content

Commit 6a29f43

Browse files
author
Jani Giannoudis
committed
Add harmonized doc templates: Year-README, Tests-README, WT-TC and GUARD-TC README patterns
1 parent 8966f38 commit 6a29f43

File tree

4 files changed

+237
-93
lines changed

4 files changed

+237
-93
lines changed

‎YYYY/README.md‎

Lines changed: 105 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,133 @@
1-
# Regulation.{CC}.{RegulationName} {YYYY}
1+
# {CC}.{RegulationName} {YYYY}
22

33
Functional regulation sub-project for year {YYYY}.
4+
For the full scope, WT/Collector Matrix, Cases, Legal Sources, and Known Limitations
5+
see the [repo root README](../README.md).
6+
7+
---
8+
9+
## What's New in {YYYY}
10+
11+
> Replace with the concrete changes that took effect on 1 January {YYYY}.
12+
> Remove this section entirely for the initial year (no predecessor).
13+
14+
| Area | Change |
15+
|:---|:---|
16+
| {Area 1} | {Change description — cite the legal source} |
17+
| {Area 2} | {Change description} |
18+
19+
---
20+
21+
## Scope ({YYYY})
22+
23+
| Component | Status | Notes |
24+
|:---|:---:|:---|
25+
| {Component 1} | ✅ | |
26+
| {Component 2} | ✅ | {Notes on specifics or limitations} |
27+
| {Component 3 — planned} | 🔜 | {Planned for next release / phase} |
28+
| {Component 4 — out of scope} | ❌ | {Reason} |
29+
30+
---
31+
32+
## Sub-project Layout
33+
34+
```
35+
{YYYY}/
36+
Docs/
37+
{CC}.{RegulationName}-Analysis.md
38+
{CC}.{RegulationName}-UncoveredCases.md
39+
{CC}.{RegulationName}-UpdateWorkflow.md
40+
Regulation/
41+
{CC}.{RegulationName}.{YYYY}.json
42+
{CC}.{RegulationName}.Scripts.{YYYY}.json
43+
{CC}.{RegulationName}.Collectors.{YYYY}.json
44+
{CC}.{RegulationName}.Cases.Company.{YYYY}.json
45+
{CC}.{RegulationName}.Cases.Employee.Core.{YYYY}.json
46+
{CC}.{RegulationName}.WageTypes.Guard.{YYYY}.json
47+
{CC}.{RegulationName}.WageTypes.Gross.{YYYY}.json
48+
{CC}.{RegulationName}.WageTypes.Deductions.{YYYY}.json
49+
{CC}.{RegulationName}.WageTypes.Employer.{YYYY}.json
50+
Scripts/
51+
WageTypeValueFunction.Shared.Action.cs
52+
WageTypeValueFunction.Guard.Action.cs
53+
WageTypeValueFunction.{Scope}.Action.cs (one file per domain)
54+
CaseValidateFunction.Action.cs
55+
{CC}{Domain}Algorithm.cs (unit-testable algorithm classes)
56+
Reports/
57+
{ReportName}/
58+
Tests/
59+
README.md
60+
{CC}.Test.Setup.json
61+
{CC}.Test.CompanyCases.json
62+
GUARD-TC{n}-{CC}-{Scope}/
63+
WT-TC{nn}-{CC}-{Scope}/
64+
Tests.Unit/
65+
{CC}{Domain}AlgorithmTests.cs
66+
Schemas/
67+
PayrollEngine.Exchange.schema.json
68+
Setup.pecmd
69+
Test.All.pecmd
70+
Delete.pecmd
71+
```
72+
73+
---
474

575
## Setup
676

7-
```pecmd
77+
```
878
{YYYY}/Setup.pecmd
979
```
1080

11-
Full setup: deletes existing data, imports regulation + data regulation + test tenant.
81+
Full setup: deletes existing data, imports regulation + data regulations + test tenant.
1282

13-
## Run All Tests
83+
## Testing
1484

15-
```pecmd
85+
```
1686
{YYYY}/Test.All.pecmd
1787
```
1888

19-
Or from repo root:
89+
See [Tests/README.md](Tests/README.md) for the full TC catalogue, execution order,
90+
and statutory parameters used in assertions.
91+
92+
## Reports
2093

21-
```pecmd
22-
Test.{YYYY}.pecmd
94+
```
95+
{YYYY}/Reports/Setup.Reports.pecmd
2396
```
2497

98+
See the report-specific README in each report subfolder.
99+
25100
---
26101

27-
## WageType Test Cases
102+
## Design Notes
28103

29-
### Guards
104+
> Add architecture notes that are specific to this year's implementation.
105+
> Use this section for non-obvious design decisions, known approximations, or
106+
> edge cases that differ from the general description in the root README.
107+
> Delete this section if there is nothing year-specific to document.
30108
31-
| TC | Folder | Focus |
32-
|:---|:---|:---|
33-
| GUARD-TC1 | [GUARD-TC1-{CC}-{Scope}](Tests/GUARD-TC1-{CC}-{Scope}/) | Abort when mandatory CaseField missing |
109+
### {Design Topic 1}
34110

35-
### Technical
111+
{Explanation of the design decision, the statutory basis, and any known limitations.}
36112

37-
| TC | Folder | Focus |
38-
|:---|:---|:---|
39-
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](Tests/WT-TC{nn}-{CC}-{Scope}/) | {Description — e.g. contribution base calculation} |
113+
---
40114

41-
### Gross
115+
## Key Parameters ({YYYY})
42116

43-
| TC | Folder | Focus |
44-
|:---|:---|:---|
45-
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](Tests/WT-TC{nn}-{CC}-{Scope}/) | {Description} |
117+
> These values are the primary reference for TC assertions.
118+
> Always cite the source publication and article.
46119
47-
### Deductions / Net
120+
| Parameter | Value | Source |
121+
|:---|---:|:---|
122+
| {Rate 1} | {value} | {Authority} — {Publication / Article} |
123+
| {Ceiling 1} | {value} | {Authority} — {Publication / Article} |
124+
| {Threshold 1} | {value} | {Authority} — {Publication / Article} |
48125

49-
| TC | Folder | Focus |
50-
|:---|:---|:---|
51-
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](Tests/WT-TC{nn}-{CC}-{Scope}/) | {Description} |
126+
---
52127

53-
### Employer
128+
## See Also
54129

55-
| TC | Folder | Focus |
56-
|:---|:---|:---|
57-
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](Tests/WT-TC{nn}-{CC}-{Scope}/) | {Description} |
130+
- [Repo root README](../README.md)
131+
- [Tests/README.md](Tests/README.md)
132+
- [Docs/{CC}.{RegulationName}-UncoveredCases.md](Docs/{CC}.{RegulationName}-UncoveredCases.md)
133+
- [Docs/{CC}.{RegulationName}-Analysis.md](Docs/{CC}.{RegulationName}-Analysis.md)

‎YYYY/Tests/GUARD-TC{n}-{CC}-{Scope}/README.md‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,34 @@
1-
# GUARD-TC{n}-{CC}-{Scope}
1+
# {TC-Folder-Name} — {Short Title}
22

3-
## Purpose
3+
**Type:** ET/CT  |  **Guard WT:** {nr} `{ActionName}`
44

5-
Tests `{CC}GuardMandatoryFields` (WT 1): fires `AbortExecution` when
6-
{description of the missing or inconsistent field that triggers the guard}.
5+
## Purpose
76

8-
Without the guard, a missing {field/lookup} causes all dependent WTs to silently
9-
return `0`, producing a payrun with incorrect results and no visible error.
7+
Verifies that `{ActionName}` fires `{AbortExecution | LogWarning | CaseInvalid}`
8+
when {condition — e.g. the mandatory field X is not set / value Y is out of range}.
9+
Without this guard, {consequence — e.g. the salary chain would silently return 0}.
1010

1111
## Setup
1212

1313
| Field | Value | Note |
1414
|:---|:---|:---|
15-
| `{CC}.{Field1}` | {value} | correctly set |
16-
| `{CC}.{Field2}` | {value} | correctly set |
17-
18-
**Trigger:** {Exact condition that fires the guard — e.g. `{CC}.{RequiredField}` not set,
19-
or `periodStart = {YYYY}-01-01` with no lookup for that year.}
15+
| `{CC}.{TriggerField}` | **(not set / invalid value)** | Provokes Guard failure |
16+
| `{CC}.{OtherField}` | `{value}` | Set — isolates the trigger field |
2017

2118
## Expected Behaviour
2219

23-
1. WT 1 `{CC}GuardMandatoryFields` runs
24-
2. All other CaseField checks pass
25-
3. {Trigger condition} detected
26-
4. `AbortExecution` fires with message: `"{CC} Guard: {field/condition} missing for test.employee@{cc}.test: {detail}"`
27-
5. No WTs run → `wageTypeResults: []`, `collectorResults: []`
20+
1. WT {nr} `{ActionName}` runs
21+
2. `{ConditionCheck}` → {condition met}
22+
3. `{AbortExecution | LogWarning | CaseInvalid}` fires
23+
4. No further WageTypes run (ET only)
24+
5. `wageTypeResults: []`, `collectorResults: []` (ET only)
25+
26+
## Failure Indicator
27+
28+
`wageTypeResult[any].value > 0` → Guard did NOT abort (implementation error)
2829

2930
## Run
3031

3132
```
32-
GUARD-TC{n}-{CC}-{Scope}.pecmd
33+
{TC-Folder-Name}.pecmd
3334
```

‎YYYY/Tests/README.md‎

Lines changed: 93 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
{YYYY}/Setup.pecmd
77
```
88

9-
Full setup: deletes existing data, imports regulation + data regulation + test tenant.
9+
Full setup: deletes existing data, imports regulation + data regulations + test tenant.
1010

1111
## Run All
1212

@@ -25,14 +25,29 @@ For CI/CD (no persistence):
2525

2626
## Teardown
2727

28-
Removes the test payroll and payrun without deleting the regulation:
29-
3028
```pecmd
3129
{YYYY}/Delete.Tests.pecmd
3230
```
3331

3432
---
3533

34+
## TC Naming Convention
35+
36+
**Guard TCs** use `GUARD-TC{N}` where `N` mirrors the Guard WageType number:
37+
38+
| Guard WT | TC Prefix | Covers |
39+
|:---|:---|:---|
40+
| WT 1 `Guard` | `GUARD-TC1` | Mandatory employee fields |
41+
| WT {n} `Guard{X}` | `GUARD-TC{n}` | {Description} |
42+
43+
Multiple scenarios for the same Guard WT share the same TC number and are distinguished
44+
by their directory suffix. Example: `GUARD-TC1-{CC}-{Field1}Missing` and
45+
`GUARD-TC1-{CC}-{Field2}Missing` both test WT 1.
46+
47+
**WT TCs** use `WT-TC{WageTypeNumber}-{CC}-{ShortDescription}`.
48+
49+
---
50+
3651
## Test Suite Structure — `Test.All.pecmd`
3752

3853
`Test.All.pecmd` runs all TCs in a fixed phase order. The order is NOT alphabetical
@@ -42,57 +57,109 @@ or numeric — it reflects **calculation dependencies** and **Company Case state
4257

4358
| Phase | Scope | WTs | Rationale |
4459
|:---|:---|:---|:---|
45-
| 1 — Guards | Guards | 1–{n} | No dependencies; must run first |
46-
| 2 — Technical | Contribution base | {nn} | All contribution WTs depend on this; no own dependencies |
60+
| 1 — Guards | Guard WTs | 1–{n} | No dependencies; must run first |
61+
| 2 — Technical | Contribution base / runtime setters | {nn} | All contribution WTs depend on this; no own dependencies |
4762
| 3 — Gross | Gross income | 1000–{nnnn} | No inter-WT dependencies |
48-
| 4 — Deductions | Employee deductions | 5000–{nnnn} | All read WT {nn} (contribution base) |
63+
| 4 — Deductions | Employee deductions | 5000–{nnnn} | Read contribution base WT; WT {nnn} reads prior-period results |
4964
| 5 — Net | Net pay | 6500 | Reads GrossCollector − DeductionsCollector |
50-
| 6 — Employer | Employer costs | 6600–{nnnn} | All read WT {nn} (contribution base) |
51-
| **Last — ConvenioConfig** | **Company Cases** | **{relevant WTs}** | **Sets non-zero Company Cases — must run last** |
65+
| 6 — Employer | Employer costs | 6600–{nnnn} | Read contribution base WT |
66+
| **Last — Company Cases** | **TCs with non-default Company Cases** | **{relevant WTs}** | **Sets non-zero Company Cases — must run last** |
5267

5368
### Company Case Contamination Rule
5469

5570
`CleanTest` removes the test employee after each TC but **Company Cases persist**
5671
across the entire test run. Any TC that sets a Company Case to a non-default value
57-
**must run in the last phase** — otherwise all subsequent TCs see the modified
58-
Company Case values and produce unexpected results.
72+
**must run in the last phase** — otherwise all subsequent TCs see the modified Company
73+
Case values and produce unexpected results.
5974

6075
See `BestPractices-Testing.md` — *"Company Cases — Shared State in Test.All.pecmd"*.
6176

62-
---
77+
### {WT nn} Dependency Chain
6378

64-
## Business Test Cases
79+
> Add a dependency chain diagram when a central WT is read by many others.
80+
> Example: BaseCotizacion / ProrataFactor / FiscaalLoon patterns.
81+
> Delete this section if not applicable.
6582
66-
| TC | Folder | Key Parameter | Focus |
67-
|:---|:---|:---|:---|
68-
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {e.g. BaseSalary €3.000} | {Description — e.g. Base scenario, full period} |
83+
```
84+
WT {nn} ({TechnicalWTName})
85+
└─ WT {n1} {Name1} (× {rate1}%)
86+
└─ WT {n2} {Name2} (× {rate2}%)
87+
```
6988

7089
---
7190

7291
## Guard Test Cases
7392

74-
| TC | Folder | Trigger | Focus |
93+
| TC | Folder | Type | Trigger | Focus |
94+
|:---|:---|:---:|:---|:---|
95+
| GUARD-TC1 | [GUARD-TC1-{CC}-{Scope}](GUARD-TC1-{CC}-{Scope}/) | ET | `{Field}` not set | AbortExecution: mandatory field missing |
96+
| GUARD-TC{n} | [GUARD-TC{n}-{CC}-{Scope}](GUARD-TC{n}-{CC}-{Scope}/) | CT | {Condition} | CaseInvalid: {validation rule} |
97+
98+
> **ET** = PayrunEmployeeTest  |  **CT** = CaseTest
99+
100+
---
101+
102+
## WT Test Cases
103+
104+
### {Category 1 — e.g. Technical / Contribution Base}
105+
106+
| TC | Folder | Focus |
107+
|:---|:---|:---|
108+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {Description} |
109+
110+
### {Category 2 — e.g. Gross Income}
111+
112+
| TC | Folder | Focus |
113+
|:---|:---|:---|
114+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {Description} |
115+
116+
### {Category 3 — e.g. Employee Deductions}
117+
118+
| TC | Folder | Focus |
119+
|:---|:---|:---|
120+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {Description} |
121+
122+
### {Category 4 — e.g. Employer Costs}
123+
124+
| TC | Folder | Focus |
125+
|:---|:---|:---|
126+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {Description} |
127+
128+
### {Last Phase — Company Case TCs}
129+
130+
| TC | Folder | Focus |
131+
|:---|:---|:---|
132+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {Description — sets Company Case} |
133+
134+
---
135+
136+
## Business Test Cases
137+
138+
> Optional section for integration / end-to-end TCs that cover the full payroll
139+
> calculation chain (all WTs in a single payrun). Delete if not used.
140+
141+
| TC | Folder | Key Input | Focus |
75142
|:---|:---|:---|:---|
76-
| GUARD-TC{n} | [GUARD-TC{n}-{CC}-{Scope}](GUARD-TC{n}-{CC}-{Scope}/) | {missing field/lookup} | AbortExecution on {condition} |
143+
| WT-TC{nn} | [WT-TC{nn}-{CC}-{Scope}](WT-TC{nn}-{CC}-{Scope}/) | {e.g. BaseSalary EUR 3,000} | {Description} |
77144

78145
---
79146

80-
## Test Data
147+
## Test Data Files
81148

82149
| File | Description |
83150
|:---|:---|
84-
| `{CC}.Test.Setup.json` | Tenant, user, division, employee, payroll, payrun |
85-
| `{CC}.Test.CompanyCases.json` | Company cases: employer registration, rate overrides |
151+
| `{CC}.Test.Setup.json` | Tenant, user, division, employee, payroll, payrun + all regulation layers |
152+
| `{CC}.Test.CompanyCases.json` | Company cases: employer registration, rate overrides, timeline data |
86153

87154
---
88155

89156
## Statutory Parameters ({YYYY})
90157

158+
> These values are the primary reference for TC assertions.
159+
> Always cite the source publication and article.
160+
91161
| Parameter | Value | Source |
92162
|:---|:---|:---|
93-
| {Rate name} | {value} | {Authority} — *{Publication name / Article}* |
94-
| {Ceiling name} | {value} | {Authority} — *{Publication name / Article}* |
95-
| {Threshold name} | {value} | {Authority} — *{Publication name / Article}* |
96-
97-
> Replace placeholder values with official statutory parameters.
98-
> Always cite the source publication, article, and effective date.
163+
| {Rate 1} | {value} | {Authority} — *{Publication / Article}* |
164+
| {Ceiling 1} | {value} | {Authority} — *{Publication / Article}* |
165+
| {Threshold 1} | {value} | {Authority} — *{Publication / Article}* |

0 commit comments

Comments
 (0)