--- id: CAP-ACC-BKS-010 title: Locate the fiscal period for accounting work feature: FEAT-ACC-BKS-03 product_area: accounting module: books revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' purpose: >- Staff and scheduled processes locate existing periods without silently extending the calendar. outcomes: - Accounting work resolves dates consistently against the unit’s calendar. - Missing calendar coverage is reported without implicit generation. concepts: - CON-ACC-BKS-003 actors: - ACT-ACC-002 - ACT-ACC-004 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: accounting.fiscal-years.read where_checked: api scope: tenant rules: - id: BR-CAP-ACC-BKS-010-01 proved_by: [ATS-ACC-BKS-010-01, TST-ACC-BKS-054, TST-ACC-BKS-086] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' - id: BR-CAP-ACC-BKS-010-02 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] statement: >- A date lookup returns its containing period and year whether open or closed, and an uncovered date is not found without generating a calendar. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 404 to the day after the last year, generating nothing origin: none - id: BR-CAP-ACC-BKS-010-03 proved_by: [ATS-ACC-BKS-010-02, TST-ACC-BKS-054, TST-ACC-BKS-086] statement: >- The boundary days of a year resolve to its own first and last periods rather than neighbouring years. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-ACC-BKS-010-04 proved_by: [] statement: A lookup refuses input that is not a valid calendar date. kind: validation enforced_at: - api must_prove: false provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 400 to a date that is not a date origin: none - id: BR-CAP-ACC-BKS-010-05 proved_by: [ATS-ACC-BKS-010-04] statement: >- Both lookups require fiscal-year read permission and are confined to the workspace’s units. kind: permission enforced_at: - api - database must_prove: false provenance: test source: >- services-accounting:modules/books/tests/e2e/configuration-security.e2e.spec.js#reads the fiscal period for a date origin: none - id: BR-CAP-ACC-BKS-010-06 proved_by: [ATS-ACC-BKS-010-03, ATS-ACC-BKS-010-05, TST-ACC-BKS-187] statement: >- A recurring-batch roll outside its unit’s generated calendar fails with the date and unit identified rather than creating another year. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none scenarios: - id: SC-CAP-ACC-BKS-010-01 given: The July-start 2026–2027 calendar is open. when: 'Staff locate the period containing October 18, 2026.' then: The response identifies October as the fourth period of that fiscal year. provenance: test source: >- react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts#ACT-ACC-0023 edge_cases: [] constraints: [] depends_on: - CAP-ACC-BKS-009 related: - CAP-ACC-BKS-018 journeys: - JNY-ACC-BKS-003 open_questions: [] evidence: - >- Verified source file: react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts - 'Verified source file: services-accounting:aws/accounting.service.ts' - >- Verified source file: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md - >- Verified source file: services-accounting:modules/books/db/fiscal-periods.table.ts - >- Verified source file: services-accounting:modules/books/tests/e2e/configuration-security.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/services/persistence/fiscal-periods.queries.integration.spec.js - >- Verified source file: services-accounting:modules/maintenance/tests/integration/services/scheduling/schedules-end-to-end.integration.spec.js controls: [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] exercised_by: [FAS-ACC-BKS-03-01, FAS-ACC-BKS-03-02, FAS-ACC-BKS-03-03, FAS-ACC-BKS-03-04, FAS-ACC-BKS-03-05, FAS-ACC-BKS-06-05] suites: [TST-ACC-BKS-054, TST-ACC-BKS-086, TST-ACC-BKS-187] --- # 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.