# Admin Daybook Closing API

## Overview

The daybook closing system tracks multiple cash balance closures per day. Each close's opening balance is automatically carried forward from the previous close (or previous day's final close).

## Endpoints

### Create a Close

```
POST /api/admin/daybook/close
```

**Request Body:**
```json
{
  "business_date": "2026-07-16",
  "closing_balance": 30000,
  "remarks": "Morning cash verification"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `business_date` | string | Yes | Date in `YYYY-MM-DD` format |
| `closing_balance` | number | Yes | The closing balance entered/calculated |
| `remarks` | string | No | Optional note |

**Auto-calculated fields (server):**
- `opening_balance` — last closing balance from any previous date/close, or `0` if first ever close
- `close_no` — auto-incremented within the business date (1, 2, 3...)
- `closed_at` — current server timestamp
- `closed_by` — admin's `uid` from JWT token

**Response (201 Created):**
```json
{
  "status": "success",
  "message": "Daybook close created successfully",
  "data": {
    "id": 1,
    "business_date": "2026-07-16",
    "close_no": 1,
    "opening_balance": 28750,
    "closing_balance": 30000,
    "closed_at": "2026-07-16T04:00:00.000Z",
    "closed_by": 1,
    "remarks": "Morning cash verification"
  }
}
```

---

### Get Daybook Entries

```
GET /api/admin/daybook?date=2026-07-16
GET /api/admin/daybook?from=2026-07-01&to=2026-07-16
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `date` | string | Get closes for a single date (`YYYY-MM-DD`) |
| `from` | string | Start date for range (`YYYY-MM-DD`, requires `to`) |
| `to` | string | End date for range (`YYYY-MM-DD`, requires `from`) |

Defaults to today if no params provided.

**Response (200 OK):**
```json
{
  "status": "success",
  "count": 4,
  "data": [
    {
      "id": 1,
      "business_date": "2026-07-16",
      "close_no": 1,
      "opening_balance": 28750,
      "closing_balance": 30000,
      "closed_at": "2026-07-16T04:00:00.000Z",
      "closed_by": { "uid": 1, "name": "Admin User" },
      "remarks": "Morning cash verification"
    }
  ]
}
```

---

### Get Close by ID

```
GET /api/admin/daybook/close/:id
```

**Response (200 OK):**
```json
{
  "status": "success",
  "data": {
    "id": 1,
    "business_date": "2026-07-16",
    "close_no": 1,
    "opening_balance": 28750,
    "closing_balance": 30000,
    "closed_at": "2026-07-16T04:00:00.000Z",
    "closed_by": { "uid": 1, "name": "Admin User" },
    "remarks": "Morning cash verification"
  }
}
```

---

### Get Latest Close

```
GET /api/admin/daybook/latest
```

Returns the single most recent close across all dates — useful for showing the current opening balance on the Flutter dashboard.

**Response (200 OK):**
```json
{
  "status": "success",
  "data": {
    "id": 4,
    "business_date": "2026-07-15",
    "close_no": 4,
    "opening_balance": 25100,
    "closing_balance": 28750,
    "closed_at": "2026-07-15T16:00:00.000Z",
    "closed_by": { "uid": 1, "name": "Admin User" },
    "remarks": null
  }
}
```

If no closes exist:
```json
{
  "status": "success",
  "data": null,
  "message": "No closes found. Opening balance will be 0."
}
```

---

### Ledger Daybook Entries

```
GET /api/admin/ledger-daybook?from=2026-07-01&to=2026-07-15
```

Returns all `ledger_day_wise` entries for the admin's company within a date range.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `from` | string | Yes | Start date (`YYYY-MM-DD`) |
| `to` | string | Yes | End date (`YYYY-MM-DD`) |

**Response (200 OK):**
```json
{
  "status": "success",
  "count": 2,
  "data": [
    {
      "date": "2026-07-15",
      "ledger": "Cash A/c",
      "particulars": "LN-1001-Rajesh",
      "voucher_type": "Principal",
      "voucher_number": "RCP-001",
      "credit": 0,
      "debit": 5000
    },
    {
      "date": "2026-07-15",
      "ledger": "Cash A/c",
      "particulars": "LN-1001-Rajesh",
      "voucher_type": "Interest",
      "voucher_number": "RCP-001",
      "credit": 0,
      "debit": 200
    }
  ]
}
```

**Fields:**
- `date` — entry date
- `ledger` — ledger name (e.g. "Cash A/c")
- `particulars` — description (e.g. "loan_id-customer_name")
- `voucher_type` — type (Principal, Interest, etc.)
- `voucher_number` — receipt/voucher reference
- `credit` — credit amount
- `debit` — debit amount

---

## Business Logic

```text
opening_balance =
    SELECT closing_balance FROM daybook_closing
    WHERE com_id = :com_id
    ORDER BY business_date DESC, close_no DESC
    LIMIT 1

If no result → opening_balance = 0

close_no =
    SELECT MAX(close_no) FROM daybook_closing
    WHERE com_id = :com_id AND business_date = :business_date

If null → close_no = 1, else close_no = max + 1
```

## Files

| File | Purpose |
|------|---------|
| `models/DaybookClosing.js` | Sequelize model |
| `controllers/DaybookController.js` | Business logic |
| `routes/daybook.js` | Route definitions |
| `models/index.js` | Model registration + Staff association |
| `server.js` | Table auto-create + route mount |