# Accounting

COSIF-compliant accounting with double-entry journal postings, chart of accounts, cost centers, and accounting events.

## Prerequisites

- Understanding of Brazilian banking accounting standards (COSIF)
- Admin access with accounting permissions
- Familiarity with double-entry bookkeeping

## COSIF Chart of Accounts

FluxiQ PIX implements 44 COSIF accounts as defined by BCB Circular 4010, seeded during migration #18.

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/accounting/chart-of-accounts` | List all 44 COSIF accounts |
| GET | `/api/v1/accounting/journal-entries` | Journal entries with running balance |
| GET | `/api/v1/accounting/events` | Accounting events list |
| POST | `/api/v1/accounting/events` | Create event (auto-creates journal entry) |
| GET | `/api/v1/accounting/cost-centers` | List cost centers (with search) |
| POST | `/api/v1/accounting/cost-centers` | Create cost center |
| PUT | `/api/v1/accounting/cost-centers/:id` | Update cost center |
| POST | `/api/v1/accounting/cost-centers/:id/toggle-status` | Toggle active/inactive |

## Double-Entry Journal

Every accounting event automatically creates a journal entry with debit and credit legs:

```mermaid
graph LR
    EVENT[Accounting Event<br/>e.g. PIX Credit Transfer] --> JOURNAL[Journal Entry]
    JOURNAL --> DEBIT[Debit Leg<br/>Account A]
    JOURNAL --> CREDIT[Credit Leg<br/>Account B]
    DEBIT --> BAL_A[Running Balance A]
    CREDIT --> BAL_B[Running Balance B]
```

### Example: PIX Credit Transfer

| Account | Debit | Credit |
|---------|-------|--------|
| 1.1.1.00.00 - PIX Receivables | R$ 100.00 | -- |
| 4.1.1.00.00 - PIX Revenue | -- | R$ 100.00 |

## Cost Centers

6 cost centers are seeded during migration #18:

| Code | Name |
|------|------|
| CC001 | PIX Operations |
| CC002 | Settlement |
| CC003 | DICT Management |
| CC004 | Compliance |
| CC005 | Technology |
| CC006 | Administration |

Each journal entry can be assigned to a cost center for expense tracking and reporting.

## Schemas

### ChartOfAccounts

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `code` | string | COSIF account code (e.g., "1.1.1.00.00") |
| `name` | string | Account name |
| `type` | string | ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE |
| `parent_id` | UUID | Parent account (for hierarchy) |
| `is_active` | boolean | Active status |

### JournalEntry

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `account_id` | UUID | FK to chart_of_accounts |
| `event_id` | UUID | FK to accounting_events |
| `debit_amount` | decimal | Debit value (centavos) |
| `credit_amount` | decimal | Credit value (centavos) |
| `running_balance` | decimal | Calculated running balance |
| `cost_center_id` | UUID | Optional FK to cost_centers |

### AccountingEvent

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `event_type` | string | Event type (e.g., "pix_credit_transfer") |
| `reference_id` | string | Transaction/entity reference |
| `description` | string | Human-readable description |
| `amount` | decimal | Event amount |

## Serialization

API responses use camelCase JSON keys (snake_case -> camelCase conversion in the controller):

```json
{
  "data": [{
    "id": "uuid",
    "accountCode": "1.1.1.00.00",
    "accountName": "PIX Receivables",
    "debitAmount": 10000,
    "creditAmount": 0,
    "runningBalance": 150000,
    "costCenter": "CC001"
  }]
}
```

## Expected Outcome

After configuring accounting:

- 44 COSIF accounts available in chart of accounts
- Double-entry journal entries auto-created from accounting events
- Running balance calculated per account
- 6 cost centers for expense categorization
- All amounts in centavos (integer) for precision