Skip to content

11.3 Bill-Run and Invoice Generation

Sprint: Sprint 11 - Billing
Feature ID: 11.3
Subtasks: 11.3.1, 11.3.2, 11.3.3

Objective

Deliver "Bill-Run and Invoice Generation" within Sprint 11 - Billing.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 11.2.1
  • 11.3.1
  • 5.5.1
  • 11.3.2
  • Sprint 01 (object storage)

Subtasks

11.3.1 Invoice line composition

  • ID: 11.3.1
  • Title: Implement invoice line builder (fee, addons, overage, VAS, tax)
  • Description: A domain service composing invoice lines for a subscriber-period: monthly tariff fee, addon fees, overage charges, VAS fees, and taxes; compute sub_total, tax, grand_total with BigDecimal and TRY currency (FR-22).
  • Business Purpose: Accurate invoice composition (FR-22).
  • Inputs: FR-22, analysis Section 4.6.
  • Outputs: Line-composition service + tests.
  • Acceptance Criteria:
  • For a subscriber with a fee, an addon, and overage, the invoice has the expected lines and totals; tax is applied; rounding uses a defined scale.
  • Dependencies: 11.2.1
  • Complexity: M

11.3.2 Bill-run job and trigger endpoint

  • ID: 11.3.2
  • Title: Implement bill-run generating invoices for active postpaid subscribers
  • Description: A bill-run process (scheduled monthly + manual POST /api/v1/billing/runs admin trigger) that, for each active postpaid subscriber due in the cycle, composes an invoice, persists it ISSUED, and emits invoice.generated.v1. Idempotent per (subscriber, period) so a re-run does not duplicate invoices. Must process 100K subscribers under 30 minutes (NFR-02) via batching/ parallelism.
  • Business Purpose: Automated monthly invoicing (FR-21, AC-02 step 1-2).
  • Inputs: FR-21, NFR-02, event-catalog invoice.generated.v1, AC-02.
  • Outputs: Bill-run job + admin endpoint + event.
  • Acceptance Criteria:
  • Triggering a run creates one ISSUED invoice per eligible subscriber and emits invoice.generated.v1; a re-run for the same period creates no duplicates; a batched run meets the NFR-02 throughput target in a load test.
  • Dependencies: 11.3.1, 5.5.1
  • Complexity: L

11.3.3 Invoice PDF rendering and storage

  • ID: 11.3.3
  • Title: Render invoice PDF and store the reference
  • Description: Render each invoice to PDF and store it in MinIO (local FS only as a dev fallback), recording pdf_ref (object reference) on the invoice; the PDF is served via a time-limited pre-signed URL from the read API and referenced in notifications (ADR-006, FR-23).
  • Business Purpose: Deliver a human-readable invoice document (FR-23, AC-02).
  • Inputs: FR-23, analysis Section 7.1 (MinIO).
  • Outputs: PDF renderer + storage adapter.
  • Acceptance Criteria:
  • Each generated invoice has a stored PDF whose pdf_ref resolves; the PDF lists the invoice lines and totals.
  • Dependencies: 11.3.2, Sprint 01 (object storage)
  • Complexity: M

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • Line-composition service + tests.
  • Bill-run job + admin endpoint + event.
  • PDF renderer + storage adapter.

Definition of Done

  • All subtasks (11.3.1, 11.3.2, 11.3.3) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).