Skip to main content

Product Context

Objective​

Develop a custom application on Zoho Creator for the centralized management of Digital Stream Budgets, Contracts, and Invoices. The system replaces SharePoint to ensure referential integrity, automate financial calculations, and manage Rolling Forecasts.

[!TIP] Per una spiegazione semplice del funzionamento del sistema per utenti non tecnici, consulta docs/productBehaviors.md. Per i dettagli tecnici sull'importazione e sincronizzazione dei dati, consulta docs/importData.md.

Use Cases (Functional Requirements)​

UC1: Budget Planning & Rolling Forecast​

  • Goal: Manage budget versions with rolling forecasts and automatic recalculation.
  • Core: Parent-Child (Bucket → Quarterly Versions). Manual inputs: proposed (team forecast), approved (authorized budget). Auto-calculated: total_contracts, committed, spent.
  • Inheritance: New versions duplicate source version (proposed + approved values) and auto-recalculate actuals for the target FY.

Details: See productBehaviors.md for metrics and workflow.

UC2: Contract Management & FIFO Erosion​

  • Goal: Manage real and placeholder contracts, auto-allocate across FYs, avoid double-counting via manual FIFO erosion.
  • Allocation: Pro-rata daily split across FY periods (subform fy_allocation).
  • Erosion: User clicks "Proposed Contracts Value Erosion" button to consume oldest Proposed placeholders when approving real contracts. Tracked via erosion_applied field.

See productBehaviors.md for FIFO examples.

UC3: Financial Monitoring & Forecasting​

  • Goal: Real-time budget health monitoring across strategic dimensions (Domain, Stream, Bucket, Capex/Opex).
  • Key Metrics: expectation management ('proposed' vs 'approved'),remaining_estimate (variance), closing_forecast (max of approved/committed), progress tracking (spent vs committed).

See productBehaviors.md for analysis dimensions.

UC4: Invoice Register & Reconciliation​

  • Goal: Track cash outflow vs. commitments with FY competence.
  • Reconciliation: Match Invoices to Contracts via code. Allocate to FY via invoice_fy_allocation (default: invoice_date FY, or service period split).
  • **Impact:**Updates total_invoiced on Contract and spent_amount on Budget Version (FY-specific).

UC5: Historical Analysis & Audit​

  • Goal: Compare versions over time for audit and trend analysis.
  • Comparison: Track changes in proposed and approved across quarters; compare performance across FYs.

Testing Framework​

  • Gherkin Scenarios: All use cases verified via behavior-driven tests in tests.md.
  • Python Automation: Logic engine simulation in zoho_simulation skill (../.agent/skills/zoho_simulation/scripts/logic_engine.py) + Behave steps in tests/features/steps/.
  • Coverage: UC1, UC2, UC3, UC4, UC5 fully covered with automated regression tests.