--- id: CAP-ACC-BKS-009 title: Extend and maintain a unit’s fiscal calendar feature: FEAT-ACC-BKS-03 product_area: accounting module: books revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - CAP-ACC-CFG-012 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D10.2' - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D15' purpose: Controllers keep complete accounting periods available for forthcoming work. 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. concepts: - CON-ACC-BKS-003 actors: - ACT-ACC-001 - ACT-ACC-002 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: accounting.fiscal-years.read where_checked: api scope: tenant - key: accounting.fiscal-years.create where_checked: api scope: tenant - key: accounting.fiscal-years.update where_checked: api scope: tenant - key: accounting.fiscal-years.delete where_checked: api scope: tenant rules: - id: BR-CAP-ACC-BKS-009-01 proved_by: [ATS-ACC-BKS-009-01, ATS-ACC-BKS-009-11, ATS-ACC-BKS-009-12, TST-ACC-BKS-054] statement: >- 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. kind: calculation enforced_at: - api - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers the two years asked for, each following the one before origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' - id: BR-CAP-ACC-BKS-009-02 proved_by: [ATS-ACC-BKS-009-02, TST-ACC-BKS-168] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/unit/fiscal-year-rules.spec.js#names the year by both calendar years it spans origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' examples: positive: A valid configuration completes the stated operation. - id: BR-CAP-ACC-BKS-009-03 proved_by: [ATS-ACC-BKS-009-03, TST-ACC-BKS-087, TST-ACC-BKS-168] statement: >- 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. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js#writes none of the years, not even the years within reach origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D10.2' - id: BR-CAP-ACC-BKS-009-04 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] statement: >- At commit the database requires month-boundary years, uninterrupted succession and exactly twelve monthly periods matching each year. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-ACC-BKS-009-05 proved_by: [ATS-ACC-BKS-009-05, TST-ACC-BKS-054, TST-ACC-BKS-087] statement: >- Only the year name is editable; attempts to change dates, status or periods are refused, and renamed years retain the existing period names. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 409 to a changed start date, naming the column origin: none - id: BR-CAP-ACC-BKS-009-06 proved_by: [ATS-ACC-BKS-009-06, TST-ACC-BKS-054, TST-ACC-BKS-087] statement: >- Only the unit’s latest year can be deleted, with every period still open, and an older-year refusal identifies the latest year. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers 409 naming the latest year origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3' - id: BR-CAP-ACC-BKS-009-07 proved_by: [ATS-ACC-BKS-009-07, TST-ACC-BKS-068] statement: >- A year becomes closed when every period closes and reopens when a period reopens; period-status changes belong to fiscal close rather than configuration. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- services-accounting:modules/books/tests/integration/db/fiscal-years.table.integration.spec.js#closes the year when its last open period is closed origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D15' - id: BR-CAP-ACC-BKS-009-08 proved_by: [ATS-ACC-BKS-009-08, TST-ACC-BKS-087] statement: >- Generation uses the workspace’s date and time zone rather than the server’s date. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-ACC-BKS-009-09 proved_by: [] statement: >- Year lists order by start date and unit, include each year’s twelve periods and support unit and status filters. kind: policy enforced_at: - api - service must_prove: false provenance: test source: >- services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js#answers every year by start date, then business unit origin: none scenarios: - id: SC-CAP-ACC-BKS-009-01 given: A July-start calendar contains 2026–2027 and 2027–2028. when: >- The controller generates a year, renames the first year and removes the latest year. then: >- Generation appends the year, renaming preserves period names, and the deletion action moves to the preceding year. provenance: test source: >- react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0023.spec.ts#ACT-ACC-0023 - id: SC-CAP-ACC-BKS-009-02 given: The workspace date is in October 2026. when: Staff request five further years including one beginning in July 2032. then: >- The entire request is refused with the allowed start-date limit and no years are saved. 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-001 related: - CAP-ACC-BKS-010 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/db/fiscal-years.table.ts - >- Verified source file: services-accounting:modules/books/tests/e2e/fiscal-years.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/db/fiscal-years.table.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.queries.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/unit/fiscal-year-rules.spec.js controls: [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] 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] suites: [TST-ACC-BKS-054, TST-ACC-BKS-068, TST-ACC-BKS-087, TST-ACC-BKS-168] --- # 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.