Extend and maintain a unit’s fiscal calendar

Purpose

Controllers keep complete accounting periods available for forthcoming work.

How It Works

The controller reviews the selected unit’s years and expands a year to inspect its periods. Generation extends the existing calendar rather than asking staff to construct each month. A preview helps staff recognize the next year before they save it. Staff can rename a year for familiar reporting terminology. Its underlying dates and period identities remain stable. Deletion is available only at the calendar’s end and can fail when the year is no longer removable. Closing periods is a separate workflow owned by month-end close.

Relationships

Unit creation initializes the calendar; fiscal-close workflows manage its periods’ standing.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: The calendar contains consecutive years made of complete monthly periods.Generation respects the five-year start-date limit.Removal is limited to the latest fully open year.
Surfaces: consoleapi
Intent sources: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D10.2services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D15

Controls

23 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-DAT-001 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005

Permissions

Key	Checked at	Scope
`accounting.fiscal-years.read`	api	tenant
`accounting.fiscal-years.create`	api	tenant
`accounting.fiscal-years.update`	api	tenant
`accounting.fiscal-years.delete`	api	tenant

Business Rules

9 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 9 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Generation creates one to five years, defaulting to one, after the latest existing year or, with no calendar, from the unit’s fiscal year containing the workspace’s current month. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3 proved by `ATS-ACC-BKS-009-01`, `ATS-ACC-BKS-009-11`, `ATS-ACC-BKS-009-12`, `TST-ACC-BKS-054`	calculation	api, service	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers the two years asked for, each following the one before
`02`must prove Confirmed	January-start years use one calendar-year name, other years use both calendar years, and each has twelve open monthly periods named with two-digit period suffixes. ✓ A valid configuration completes the stated operation. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3 proved by `ATS-ACC-BKS-009-02`, `TST-ACC-BKS-168`	calculation	service	test services-accounting:modules/books/tests/unit/fiscal-year-rules.spec.js#names the year by both calendar years it spans
`03`must prove Confirmed	No generated year starts after the calendar date five years from the workspace’s current date, using February 28 for a leap-day anniversary in a common year, and an out-of-range request writes no years. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D10.2 proved by `ATS-ACC-BKS-009-03`, `TST-ACC-BKS-087`, `TST-ACC-BKS-168`	validation	service	test services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js#writes none of the years, not even the years within reach
`04`must prove Confirmed	At commit the database requires month-boundary years, uninterrupted succession and exactly twelve monthly periods matching each year. proved by `ATS-ACC-BKS-001-16`, `ATS-ACC-BKS-009-04`, `ATS-ACC-BKS-009-11`, `TST-ACC-BKS-068`, `TST-ACC-BKS-087`	invariant	database	test services-accounting:modules/books/tests/integration/db/fiscal-years.table.integration.spec.js#refuses a year leaving a gap after the latest, in Rhythm 1.0’s sentence
`05`must prove Confirmed	Only the year name is editable; attempts to change dates, status or periods are refused, and renamed years retain the existing period names. proved by `ATS-ACC-BKS-009-05`, `TST-ACC-BKS-054`, `TST-ACC-BKS-087`	lifecycle	service	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 409 to a changed start date, naming the column
`06`must prove Confirmed	Only the unit’s latest year can be deleted, with every period still open, and an older-year refusal identifies the latest year. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3 proved by `ATS-ACC-BKS-009-06`, `TST-ACC-BKS-054`, `TST-ACC-BKS-087`	lifecycle	service	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 409 naming the latest year
`07`must prove Confirmed	A year becomes closed when every period closes and reopens when a period reopens; period-status changes belong to fiscal close rather than configuration. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D15 proved by `ATS-ACC-BKS-009-07`, `TST-ACC-BKS-068`	invariant	database	test services-accounting:modules/books/tests/integration/db/fiscal-years.table.integration.spec.js#closes the year when its last open period is closed
`08`must prove Confirmed	Generation uses the workspace’s date and time zone rather than the server’s date. proved by `ATS-ACC-BKS-009-08`, `TST-ACC-BKS-087`	calculation	service	test services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js#starts from the tenant’s month, where the UTC date is already the next month
`09` Confirmed	Year lists order by start date and unit, include each year’s twelve periods and support unit and status filters.	policy	api, service	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers every year by start date, then business unit

Scenarios

Id	Given	When	Then	Provenance
`01`	A July-start calendar contains 2026–2027 and 2027–2028.	The controller generates a year, renames the first year and removes the latest year.	Generation appends the year, renaming preserves period names, and the deletion action moves to the preceding year.	test react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts#ACT-ACC-0023
`02`	The workspace date is in October 2026.	Staff request five further years including one beginning in July 2032.	The entire request is refused with the allowed start-date limit and no years are saved.	test react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts#ACT-ACC-0023

Planning

Implementation

Extend and maintain a unit’s fiscal calendar ​

Purpose ​

How It Works ​

Relationships ​