Locate the fiscal period for accounting work

Purpose

Staff and scheduled processes locate existing periods without silently extending the calendar.

How It Works

Accounting work asks for a period using the business unit and, when appropriate, a date. The answer includes the year needed to interpret that period. A current-period request follows open accounting work rather than simply the calendar month. A dated request can locate historical closed periods. Missing coverage leaves staff responsible for extending the calendar. Scheduled work reports the same gap instead of changing configuration implicitly. Staff can generate the missing year and retry the work.

Relationships

Calendar maintenance supplies the years these lookups search.

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: Accounting work resolves dates consistently against the unit’s calendar.Missing calendar coverage is reported without implicit generation.
Surfaces: consoleapijob
Intent sources: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3

Controls

17 controls apply, from the corpus control catalogue.

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

Permissions

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

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	The current period is the earliest open period in the earliest open year and is returned with that year; a unit with no open year receives the legacy no-current-period refusal. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3 proved by `ATS-ACC-BKS-010-01`, `TST-ACC-BKS-054`, `TST-ACC-BKS-086`	calculation	service	test services-accounting:modules/books/tests/integration/services/persistence/fiscal-periods.queries.integration.spec.js#moves on to the first open period once the earlier ones are closed
`02`must prove Confirmed	A date lookup returns its containing period and year whether open or closed, and an uncovered date is not found without generating a calendar. proved by `ATS-ACC-BKS-009-12`, `ATS-ACC-BKS-010-02`, `ATS-ACC-BKS-018-09`, `TST-ACC-BKS-054`, `TST-ACC-BKS-086`, `TST-ACC-BKS-187`	calculation	service	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 404 to the day after the last year, generating nothing
`03`must prove Confirmed	The boundary days of a year resolve to its own first and last periods rather than neighbouring years. proved by `ATS-ACC-BKS-010-02`, `TST-ACC-BKS-054`, `TST-ACC-BKS-086`	calculation	service	test services-accounting:modules/books/tests/integration/services/persistence/fiscal-periods.queries.integration.spec.js#answers the year’s last period on the year’s last day, not the next year
`04` Confirmed	A lookup refuses input that is not a valid calendar date.	validation	api	test services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 400 to a date that is not a date
`05` Confirmed	Both lookups require fiscal-year read permission and are confined to the workspace’s units. proved by `ATS-ACC-BKS-010-04`	permission	api, database	test services-accounting:modules/books/tests/e2e/configuration-security.e2e.spec.js#reads the fiscal period for a date
`06`must prove Confirmed	A recurring-batch roll outside its unit’s generated calendar fails with the date and unit identified rather than creating another year. proved by `ATS-ACC-BKS-010-03`, `ATS-ACC-BKS-010-05`, `TST-ACC-BKS-187`	policy	service	test services-accounting:modules/maintenance/tests/integration/services/scheduling/schedules-end-to-end.integration.spec.js#fails the roll dated in no fiscal year of the unit, with the sentence naming the date and the unit

Scenarios

Id	Given	When	Then	Provenance
`01`	The July-start 2026–2027 calendar is open.	Staff locate the period containing October 18, 2026.	The response identifies October as the fourth period of that fiscal year.	test react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts#ACT-ACC-0023

Planning

Implementation

Locate the fiscal period for accounting work ​

Purpose ​

How It Works ​

Relationships ​