# Phase 4 — Manual Invoice Report

**Status:** Complete — awaiting approval to start Phase 5  
**Date:** 2026-10-07  
**Scope:** Manual contract-wise + milestone-wise invoice creation (API, permissions, transactions). No auto-invoice, UI, or payments.

---

## APIs

| Method | Path | Permission |
|--------|------|------------|
| GET | `/api/v1/project/invoices` | `invoices-view` (+ bridges) |
| GET | `/api/v1/project/invoices/{id}` | `invoices-view` |
| POST | `/api/v1/project/invoices/contract-wise` | `invoices-create` |
| POST | `/api/v1/project/invoices/milestone-wise` | `invoices-create` |

### Contract-wise body

```json
{ "contract_id": 1, "amount": 300000, "issue_date": optional, "due_date": optional, "notes": optional }
```

No milestone allocations stored.

### Milestone-wise body

```json
{
  "contract_id": 1,
  "allocations": [
    { "milestone_id": 10, "amount": 150000 },
    { "milestone_id": 11, "amount": 200000 }
  ]
}
```

Reuses `MilestoneInvoiceabilityService` for eligibility / remaining / over-invoice / wrong-contract checks.

---

## Business rules enforced

1. Contract-wise → no milestone rows  
2. Milestone-wise → ≥1 allocation; approved only; amount ≤ remaining  
3. Multi-milestone + partial supported  
4. Contract ceiling: SUM(non-cancelled invoice totals) + new ≤ `contract_value`  
5. DB transaction + `lockForUpdate` on contract/milestones  
6. Status on create: `issued`; `source`: `manual`; `outstanding_amount` = total  

---

## Permissions (`config/actions.php`)

- `project.invoices-view`
- `project.invoices-create`
- `project.invoices-manage`

---

## Tests

`ProjectInvoiceApiTest` — **11 passed** (scenarios 1–8, 11–12 + list/show + auth + contract ceiling)  
Also re-ran Phase 3 invoiceability + permission smoke — **27 passed** combined.

---

## Explicitly NOT done

- Auto-invoice on approval (Phase 5)  
- Milestone CRUD / ApprovalEngine UI (still model-level for milestones)  
- Invoice management UI (Phase 6)  
- Payments (Phase 7)  
- Cancel / void invoice endpoint  

---

## STOP

Phase 4 complete. **Awaiting explicit approval for Phase 5 — Automatic Invoice.**