Revenue Recognition (Advanced) — Integration

​

Integration Summary

​

Transport (frozen)

​

RPC: fa_process_revenue_recognition

fa_process_revenue_recognition(
  p_organization_id uuid,
  p_recognition_date date,
  p_fiscal_period_id uuid,
  p_user_id uuid
) RETURNS TABLE(
  schedule_id uuid,
  recognition_amount numeric,
  journal_entry_id uuid
);

1. Select active fa_revenue_schedules for p_organization_id that intersect the fiscal period identified by p_fiscal_period_id (via fa_fiscal_periods), have remaining_to_recognize > 0, and satisfy date window rules per spec.
2. For each schedule, insert at most one fa_revenue_recognitions row for (revenue_schedule_id, fiscal_period_id) (UNIQUE).
3. Update fa_revenue_schedules.total_recognized in the same transaction as the insert.
4. Phase 1 GL scope (DEFERRED): Do not call fa_create_journal_entry() from fa_process_revenue_recognition() in Phase 1. Recognition rows are written with journal_entry_id IS NULL and journal_entry_line_id IS NULL. A Phase 2 task will post GL via FA-02 and back-fill the linkage. This boundary keeps Phase 1 self-contained and decoupled from FA-02’s not-yet-frozen RPC signature.
5. Inserts MUST use ON CONFLICT (revenue_schedule_id, fiscal_period_id) DO NOTHING so the function is idempotent on retry.

​

Event: revenue_recognized

{
  event_type: 'revenue_recognized';
  organization_id: uuid;
  recognition_id: uuid;
  revenue_schedule_id: uuid;
  fiscal_period_id: uuid;
  recognition_amount: number;
  recognition_date: date; // processing date
  recognition_period_start: date;
  recognition_period_end: date;
  journal_entry_id?: uuid;
  journal_entry_line_id?: uuid;
}

​

HTTP: Recognize revenue (optional wrapper)

{
  recognition_date: string; // ISO date
  fiscal_period_id: string;
  schedule_ids?: string[]; // optional filter; same-org only
}

{
  recognition_count: number;
  total_recognized: number;
  recognitions: Array<{
    recognition_id: string;
    revenue_schedule_id: string;
    recognition_amount: number;
    journal_entry_id?: string;
    journal_entry_line_id?: string;
  }>;
}

​

GL mapping (FA-02)

​

Planned consumers (Phase 2)

• invoice_sent (FA-05), contract_signed (FA-13) — auto-create schedules/contracts; not in Phase 1.

​

Spec reference

• FA-18 spec
• FA-18 plan