# Expense Module Plan

> **Status:** implemented 2026-10-07 (phases 1–5) using the §10 defaults. Deviations from this plan are listed in
> §11 and in `Backend/PROGRESS.md` / `Frontend/PROGRESS.md`. Not yet verified against a live GL service.
> **Lives under:** the existing **Accounts** nav item (`NavItemId = 12`, `/dashboard/accounts`).
> **GL transport:** `docs/12-GENERAL-LEDGER-INTEGRATION.md` (typed calls via `IGeneralLedgerService`).
> **Reference implementation to mirror:** `PurchaseInvoicePaymentService` (call GL before commit, so a
> failed post rolls back the whole operation).

---

## 1. Goal

Record day-to-day business expenses that don't come through procurement (electricity bill, rent,
salaries paid outside payroll, stationery, …). Users can:

- pick a **category** (Utility, Rental, Salaries, Other),
- pick a **title** under it (Utility → Electricity, Water, …),
- enter the **amount**, date, payee and bill reference,
- **pay** it now or later (in one or more installments) from a GL cash/bank account,
- see the **payment status** (Unpaid / Partially Paid / Paid).

Every posted expense and every payment creates a real GL journal entry, so the P&L shows it.

---

## 2. Concepts

```
ExpenseCategory  (Utility, Rental, Salaries, Other)   ← seeded, admins can add more
   └── ExpenseTitle  (Electricity, Water, …)          ← seeded, admins can add more
          └── default GL expense account code

Expense          (one bill: category + title + amount + status)
   └── ExpensePayment  (0..n installments, each posts a GL entry)
```

### 2.1 Seeded categories and titles

| Category | Seeded titles |
|---|---|
| **Utility** | Electricity, Water, Telephone, Internet, Gas |
| **Rental** | Building Rent, Vehicle Rent, Equipment Rent |
| **Salaries** | Staff Salaries, Wages, Overtime, Bonus, EPF / ETF Contribution |
| **Other** | Stationery, Transport, Repairs & Maintenance, Cleaning, Miscellaneous |

- Seeded rows have `IsSystem = true`. They **cannot be deleted or renamed**, only deactivated.
- Users with the `accounts.expense-setup` permission can add **custom titles** under any category,
  and **custom categories**.
- Every title has a **GL expense account code**. Seeded titles default to the codes in
  `appsettings.json` (§5). Users can override the code per title.

---

## 3. Data model (backend)

All new entities go in `Domain/Entities/`, with configurations in `Infra/Persistence/Configurations/`
and one EF migration.

### 3.1 `ExpenseCategory`

| Field | Type | Notes |
|---|---|---|
| ExpenseCategoryId | int PK | |
| Code | string(30), unique | `UTILITY`, `RENTAL`, `SALARIES`, `OTHER`, or user-defined |
| Name | string(100), unique | |
| IsSystem | bool | seeded = true |
| IsActive | bool | |
| SortOrder | int | |
| CreatedBy / CreatedAt / UpdatedBy / UpdatedAt | | standard audit columns |

### 3.2 `ExpenseTitle`

| Field | Type | Notes |
|---|---|---|
| ExpenseTitleId | int PK | |
| ExpenseCategoryId | int FK | |
| Name | string(100) | unique **within** the category |
| GlExpenseAccountCode | string(20) | the account debited when an expense with this title is posted |
| IsSystem | bool | |
| IsActive | bool | |
| SortOrder | int | |
| audit columns | | |

### 3.3 `Expense` (header)

| Field | Type | Notes |
|---|---|---|
| ExpenseId | int PK | |
| DocNo | string | `EXP-{branch}-{yyyy}-{seq}` via `NumberSequenceService` (DocType `EXPENSE`) |
| BranchId | int FK | branch-scoped like other documents (`BRANCH_ISOLATION_PLAN.md`) |
| ExpenseDate | DateOnly | the bill date, which is also the GL entry date on posting |
| DueDate | DateOnly? | optional, used for "overdue" in the list |
| ExpenseCategoryId | int FK | |
| ExpenseTitleId | int FK | must belong to the chosen category |
| Payee | string(150)? | free text (e.g. "CEB", "Landlord – Mr. Silva") |
| VendorId | int? FK | optional link to an existing vendor |
| BillReference | string(50)? | the supplier's bill/account number |
| Description | string(500)? | |
| Amount | decimal(18,2) | > 0 |
| PaidAmount | decimal(18,2) | maintained by payments |
| BalanceAmount | decimal(18,2) | `Amount - PaidAmount` |
| Status | enum `ExpenseStatus` | `Draft`, `Posted`, `Cancelled` |
| PaymentStatus | enum `ExpensePaymentStatus` | `Unpaid`, `PartiallyPaid`, `Paid`, derived from Paid/Balance |
| GlExpenseAccountCode | string(20) | **snapshot** of the title's code at posting time |
| GlJournalNo | string? | the accrual journal entry |
| PeriodMonth | string(7)? | optional "covers" period, e.g. `2026-09` for September's electricity |
| RowVersion | uint | ETag concurrency, same as `PurchaseInvoice` |
| audit columns | | |

### 3.4 `ExpensePayment`

Mirrors `PurchaseInvoicePayment` field for field:

| Field | Type | Notes |
|---|---|---|
| ExpensePaymentId | int PK | |
| ExpenseId | int FK | |
| Amount | decimal(18,2) | ≤ Expense.BalanceAmount |
| PaymentDate | DateTime | same `ResolvePaymentDate` rule (no future dates, one day of slack) |
| PaymentMethod | enum | `Cash`, `BankTransfer`, `Cheque`, `Card` |
| GlBankAccountId | long | account from `IGeneralLedgerService.ListBankAccountsAsync` |
| BankAccountName | string | snapshot |
| ChequeNo | string? | required when method = Cheque |
| Reference | string? | |
| GlJournalNo | string? | |
| CreatedBy / CreatedAt | | |

### 3.5 Enums (`Domain/Enums/`)

`ExpenseStatus { Draft, Posted, Cancelled }`
`ExpensePaymentStatus { Unpaid, PartiallyPaid, Paid }`
`ExpensePaymentMethod { Cash, BankTransfer, Cheque, Card }`

---

## 4. Workflow and GL postings

```
 Draft ──Post──► Posted (Unpaid) ──Pay──► Partially Paid ──Pay──► Paid
   │                │
   └──Delete        └──Cancel (only if PaidAmount = 0) ──► Cancelled
```

| Action | Rule | GL entry |
|---|---|---|
| **Create (Draft)** | Editable, no GL impact | — |
| **Post** | Draft only. Snapshots the title's GL code. | **Dr** title's expense account / **Cr** Accrued Expenses (`Expense:GlAccruedExpensesCode`) |
| **Pay** | Posted and Balance > 0, installments allowed | **Dr** Accrued Expenses / **Cr** selected cash/bank account |
| **Post & Pay** (one click, the common "paid in cash right now" case) | Draft. Runs Post and a full Pay in **one transaction**. | Both entries above |
| **Cancel** | Posted with no payments | Reversing entry: **Dr** Accrued / **Cr** expense account |
| **Delete** | Draft only | — |

All GL calls happen inside `_uow.ExecuteInTransactionAsync` **before** the local rows are saved,
the same pattern as `PurchaseInvoicePaymentService`. If GL is down or rejects the entry, nothing is saved.
`SourceModule = "EXPENSE"` / `"EXPENSE_PAYMENT"`, `Reference = DocNo`.

**Why accrue then pay** (rather than Dr Expense / Cr Bank on payment): unpaid bills still show
in the P&L for the month they belong to, and the Accrued Expenses balance equals the total unpaid bills.
"Post & Pay" keeps the one-step case fast.

---

## 5. Configuration (`appsettings.json`)

```json
"Expense": {
  "GlAccruedExpensesCode": "2300",
  "DefaultGlAccountCodes": {
    "UTILITY":  "6100",
    "RENTAL":   "6200",
    "SALARIES": "6300",
    "OTHER":    "6900"
  }
}
```

Seeded titles take their category's default code. The actual codes must match the GL service's chart
of accounts. **Confirm them with the GL owner before seeding** (open question Q3).

---

## 6. API (`Controllers/ExpensesController.cs`, `ExpenseSetupController.cs`)

Policy: `NavPolicies.Prefix + "accounts"`, same door as the cheque/bank screens.

### Setup (categories and titles)

| Method | Route | Purpose |
|---|---|---|
| GET | `/api/v1/expense-categories?includeInactive=` | list categories, each with its titles |
| POST | `/api/v1/expense-categories` | add a custom category |
| PUT | `/api/v1/expense-categories/{id}` | rename (non-system only) / toggle active |
| POST | `/api/v1/expense-categories/{id}/titles` | add a custom title |
| PUT | `/api/v1/expense-titles/{id}` | rename (non-system only) / change GL code / toggle active |

### Expenses

| Method | Route | Purpose |
|---|---|---|
| GET | `/api/v1/expenses` | paged list. Filters: branch, category, title, status, paymentStatus, date range, search (DocNo/payee/reference) |
| GET | `/api/v1/expenses/{id}` | detail + payments (ETag header) |
| POST | `/api/v1/expenses` | create draft |
| PUT | `/api/v1/expenses/{id}` | update draft (`If-Match`) |
| DELETE | `/api/v1/expenses/{id}` | delete draft |
| POST | `/api/v1/expenses/{id}/post` | post (accrue) |
| POST | `/api/v1/expenses/{id}/post-and-pay` | post + full payment, body = payment request |
| POST | `/api/v1/expenses/{id}/cancel` | cancel (reason required) |
| GET | `/api/v1/expenses/{id}/payments` | payment history |
| POST | `/api/v1/expenses/{id}/payments` | add a payment / installment |
| GET | `/api/v1/expenses/summary?from=&to=&branchId=` | totals by category → title, plus paid/unpaid totals (for the dashboard cards) |

### New error codes (`System/Errors/ErrorCodes`)

`EXPENSE_NOT_DRAFT`, `EXPENSE_NOT_PAYABLE`, `EXPENSE_PAYMENT_EXCEEDS_BALANCE`,
`EXPENSE_HAS_PAYMENTS`, `EXPENSE_TITLE_CATEGORY_MISMATCH`, `EXPENSE_TITLE_INACTIVE`,
`EXPENSE_SYSTEM_ROW_READONLY`, `EXPENSE_BANK_ACCOUNT_NOT_FOUND`, `EXPENSE_CHEQUE_NO_REQUIRED`.

---

## 7. Backend file checklist

| Layer | Files |
|---|---|
| Entities | `ExpenseCategory.cs`, `ExpenseTitle.cs`, `Expense.cs`, `ExpensePayment.cs` |
| Enums | `ExpenseStatus.cs`, `ExpensePaymentStatus.cs`, `ExpensePaymentMethod.cs` |
| EF config | `ExpenseConfiguration.cs` (all four tables, seed data, indexes, check constraint `Amount > 0`, **MariaDB-safe quoting**, see commit c97a7e9) |
| DbContext | 4 `DbSet`s in `ErpDbContext.cs` |
| DTOs | `Dtos/Expense/ExpenseDtos.cs`, `ExpenseSetupDtos.cs` + FluentValidation validators |
| Services | `ExpenseSetupService`, `ExpenseService`, `ExpensePaymentService` (+ interfaces) |
| Controllers | `ExpenseSetupController`, `ExpensesController` |
| Nav / perms | `SubNavItemConfiguration`: `accounts.expenses` (id 23, sort 4) and `accounts.expense-setup` (id 24, sort 5); `PermissionConfiguration` entries |
| Number seq | DocType `EXPENSE` |
| Audit | `IAuditService` entries on create/post/pay/cancel |
| Program.cs | DI registrations |
| Migration | `AddExpenseModule` |

---

## 8. Frontend (`Frontend/erp-system/app/dashboard/accounts/`)

| Route | Screen |
|---|---|
| `expenses/page.tsx` | List: summary cards (This month total · Unpaid · Overdue), filter bar (category, title, status, payment status, dates), table with **payment status badge** (Unpaid red / Partial amber / Paid green) |
| `expenses/new/page.tsx` | Form: Branch · Date · **Category** dropdown → **Title** dropdown (filtered by category, with an inline "+ Add title" if permitted) · Payee/Vendor · Bill ref · Period · Amount · Description. Buttons: **Save Draft**, **Post**, **Post & Pay** (opens the payment dialog) |
| `expenses/[id]/page.tsx` | Detail, GL journal no, payment history, **Add Payment** dialog (amount defaults to balance · date · method · cash/bank account from `bankAccountsApi` · cheque no · reference), Cancel |
| `expense-setup/page.tsx` | Categories as tabs or accordion → titles table (name, GL code, active, system lock icon); add/edit dialogs |

API client: `lib/api/expenses.ts`. Types: `types/expense.ts`. Reuse the payment dialog pattern from the
purchase-invoice payment screen.

---

## 9. Implementation phases

1. **Setup data**: entities, config, seed, migration, setup API + setup screen.
2. **Expense CRUD**: draft create/edit/delete, list/detail screens, DocNo sequence.
3. **GL posting**: Post, Cancel, Post & Pay, config codes.
4. **Payments**: installments, payment status, cheque method.
5. **Reporting**: summary endpoint, list cards, export to CSV.
6. Docs: add `docs/16-BACKEND-EXPENSES.md` (or extend `00-CORE.md` nav), update `Backend/PROGRESS.md` / `Frontend/PROGRESS.md`.

---

## 10. Open questions

| # | Question | Default if not answered |
|---|---|---|
| Q1 | One title per expense, or **multiple lines** per expense (e.g. one bill covering electricity + water)? | One title per expense. Lines can be added later without breaking the API. |
| Q2 | Can users add **new categories**, or only new titles under the four fixed ones? | **Decided 2026-10-08: titles only.** The four categories are fixed; the create-category endpoint and UI were removed. |
| Q3 | Real GL account codes for Accrued Expenses and each category? | Placeholders in §5 |
| Q4 | **Salaries vs. HRM Payroll:** payroll runs don't post to GL today. If payroll GL posting is added later, the "Salaries" category could double-count. Should Salaries expenses be blocked or warned once payroll posts? | Allow for now, add a warning note on the Salaries category |
| Q5 | Tax (VAT) on expenses: capture input tax separately? | Out of scope for phase 1, amount is gross |
| Q6 | Attachments (scan of the bill)? | Out of scope for phase 1 |
| Q7 | Approval step before posting (maker/checker)? | No. Post permission is enough. |
| Q8 | Recurring expenses (monthly rent auto-draft)? | Phase 2 |

---

## 11. As built: deviations from this plan

- **Nav/permission ids:** sub-items 44 (`accounts.expenses`) and 45 (`accounts.expense-setup`), permissions 54/55.
  Ids 23/24 in §7 were already taken.
- **Config (§5):** only `Expense:GlAccruedExpensesCode` is in `appsettings.json`. The per-category default codes are
  seeded directly (`ExpenseConfiguration.cs`), because `HasData` cannot read configuration. Change them per title on
  the Expense Setup screen.
- **GL accounts (2026-10-08):** GL generates account codes itself (its `POST /accounts` takes no code), so the
  planned 6100–6900 codes could never exist. The dev GL now has `2300` Accrued Expenses (liability) and a
  non-postable `5200` Operating Expenses control account with children `5200-01` Utilities, `5200-02` Rent,
  `5200-03` Salaries & Wages and `5200-04` Other Expenses. The seed and migration `UpdateExpenseGlCodes` point the
  seeded titles at those. Another GL instance will generate its own codes, so check them on Expense Setup.
- **Status columns:** categories and titles use the codebase's `EntityStatus` (Active/Inactive) instead of an `IsActive` bool.
- **Payments:** one submission can have several lines (cash + bank). It posts **one** GL journal, and each line becomes
  an `ExpensePayment` row that shares that journal number. `PaymentMethod`, `ChequeNo` and `Reference` apply to the
  whole submission.
- **Cancel:** also allowed on a Draft (no GL entry). A Posted expense with no payments gets a reversing entry dated today
  (`GlReversalJournalNo`). The reason is stored in `CancelReason`.
- **No FluentValidation:** request validation uses DataAnnotations plus service checks, matching the rest of the API.
- **Audit:** no explicit `IAuditService` calls. The DbContext's ChangeTracker audit captures every insert and update.