Prefill Pipeline

The prefill pipeline fetches data from ClickHouse and generates an invoice preview without saving anything to PostgreSQL. This allows users to review the pre-filled data before committing to a draft.

Sequence Diagram

Request

curl -X POST http://localhost:8081/api/v1/invoices/prefill \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "application_key": "APP-001",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28"
  }'

If period_start and period_end are omitted, the system defaults to the previous calendar month.

Response

The response contains the full invoice preview including financial calculations and line items, but nothing is saved to the database:

{
  "data": {
    "application_key": "APP-001",
    "customer_key": "CUST-001",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28",
    "deal_type": "SUP",
    "currency": "UZS",
    "base_amount": "15000000.00",
    "overtime_hours": "5.50",
    "overtime_amount": "825000.00",
    "total_amount": "15825000.00",
    "total_hours": "45.50",
    "is_overtime": true,
    "line_items": [
      {
        "line_type": "support",
        "description": "Monthly support — February 2026",
        "time_seconds": 0,
        "billable_seconds": 0,
        "unit_price": "15000000.00",
        "quantity": "1",
        "line_total": "15000000.00",
        "rate_tier": "standard",
        "rate_multiplier": "1.0",
        "source": "auto"
      },
      {
        "line_type": "task",
        "description": "PROJ-456: Implement user dashboard",
        "jira_key": "PROJ-456",
        "time_seconds": 7200,
        "billable_seconds": 7200,
        "unit_price": "150000.00",
        "quantity": "2.00",
        "line_total": "300000.00",
        "rate_tier": "standard",
        "rate_multiplier": "1.0",
        "source": "auto"
      }
    ],
    "customer": {
      "company_name": "Acme Corp",
      "tin": "123456789"
    },
    "application": {
      "application_name": "Acme Support",
      "deal_type": "SUP",
      "monthly_limit": 40
    }
  }
}

Pipeline Steps in Detail

1. Fetch Application

Queries cdm.jira_applications by application_key. Returns deal type, currency, amounts, monthly limit, and project labels for worklog mapping.

2. Fetch Customer

Queries cdm.jira_customers by the application's customer_key. Returns company details needed for the invoice template (name, TIN, SWIFT/BIC, signer info).

3. Fetch Worklogs

Queries tempo.worklogs_flat joined with jira.jira_issues for the given period. Filters by the application's labels (project labels). Excludes employees marked in employee_exclusions. Also fetches linked_issue_key from jira.jira_issues for SUP-* task linking via Jira "duplicates" relation.

4. Categorize & Calculate

• Apply minimum billable (1800 seconds per worklog)
• Assign rate tiers based on issue type, priority, and work time
• Calculate financials based on deal type (SUP/HR/FP)
• Build line items grouped by issue

5. Return Preview

The complete prefill result is returned to the frontend for display. The user can review and modify everything before generating the actual draft.

Error Cases

Error	HTTP Status	When
Application not found	404	Invalid application_key
Customer not found	404	Application's customer missing from ClickHouse
No worklogs found	200	Valid but empty — returns zero amounts
ClickHouse timeout	500	Query exceeds 15s timeout