TorbatYar/docs/accounting-frontend-integration-report.md

# Accounting Frontend Integration Report

> Phase: Enterprise Accounting Frontend Integration (connect FE ↔ existing BE 5.1–5.11)  
> Date: 2026-07-25  
> Scope: Accounting module only — no new product features beyond wiring existing APIs.

## Summary

Scanned ~118 Accounting FE routes against `/api/v1` routers. Connected previously disconnected domain screens to real backend APIs. Kept Phase 5.12 AI blocked. Ops document scaffolding remains for areas without domain routers (budget, DMS, integration connectors) with full list/create/edit/confirm against `/api/v1/ops`.

## Connected Pages (domain APIs)

| Area | Routes | Backend |
|------|--------|---------|
| Dashboard / Setup | `/accounting`, `/setup`, `/settings` | setup, health, charts, vouchers |
| COA / dimensions | chart-of-accounts, cost-centers, projects, currencies | `/accounts` |
| Fiscal | `/fiscal` | `/fiscal` |
| Vouchers | list (paginated), new, `[id]` | `/posting` |
| Ledger | `/ledger` | `/ledger` |
| Reports (TB/BS/IS) | `/reports` | `/reporting` |
| Treasury | hub, receipts-payments, transfers, reconciliation, cheques | `/treasury` |
| Customers / Suppliers | `/customers`, `/suppliers` | `/ar-ap` |
| Settlements | `/sales/settlements`, `/purchase/settlements` | `/ar-ap/settlements` |
| Sales invoice accounting | `/sales/invoices` | ops docs + `/sales-accounting` preview/post |
| Purchase GR | `/purchase/goods-receipts` | ops + `/purchase-inventory` |
| Inventory valuation | `/inventory/valuation` | `/purchase-inventory/valuation` + ops items |
| Assets hub + schedule | `/assets`, `/assets/schedule` | `/assets` |
| Payroll hub + employees | `/payroll`, `/payroll/employees` | `/payroll` |
| Compliance policies/risks | `/compliance/policies`, `/compliance/risks` | `/compliance` |
| Audit | `/audit` | compliance audit + posting audit |
| Monitoring health | `/monitoring/health` | `/health` + setup status |
| Inventory items/warehouses | `/inventory/items`, `/inventory/settings` | `/ops/items`, `/ops/warehouses` |

## Fixed Pages

| Page | Before | After |
|------|--------|-------|
| `/payroll/employees` | Ops stub documents | Domain payroll employees CRUD list/create |
| `/compliance/policies` | Ops stub | Domain policies list/create |
| `/compliance/risks` | Ops stub | Domain risks list/create |
| `/sales/settlements`, `/purchase/settlements` | Ops stub | Domain settlements list/create |
| `/sales/invoices` | Ops-only | Ops docs + sales-accounting preview/post |
| `/purchase/goods-receipts` | Ops-only | Ops docs + purchase-inventory preview/post |
| `/inventory/valuation` | Ops stub | Real valuation API |
| `/monitoring/health` | Ops stub | Live health + setup |
| `/assets/schedule` | Ops stub | Asset depreciation schedule from API |
| Ops BusinessDocsPage | Create/confirm only | + detail + edit (PATCH) |
| Vouchers list | First page only | Pagination (`page` / `page_size`) |
| Receipts/payments | Missing cash/bank ids | Cash box / bank account selects |

## Connected APIs (FE client additions)

- `settlements.list` / `settlements.create`
- `salesAccounting.listProfiles|createProfile|preview|post`
- `purchaseInventory.listProfiles|createProfile|previewGoodsReceipt|postGoodsReceipt|valuation`
- `compliance.requestApproval|approve|reject|listRisks|createRisk`
- `ops.updateDocument` (PATCH)

### Backend list endpoints added (integration completeness only)

- `GET /api/v1/ar-ap/settlements?party_type=`
- `GET /api/v1/compliance/risks`
- `GET /api/v1/purchase-inventory/posting-profiles`

## Modified Components

- `frontend/lib/accounting-api.ts`
- `frontend/components/accounting/DomainScreens.tsx` (new)
- `frontend/components/accounting/BusinessDocsPage.tsx`
- `frontend/app/accounting/vouchers/page.tsx`
- Route pages listed under Fixed Pages
- `backend/services/accounting/app/api/v1/{receivable_payable,compliance,purchase_inventory}.py`

## Validation Results

| Check | Result |
|-------|--------|
| BE module imports | Pass |
| Architecture / accounting pytest | See CI/local run in this session |
| Tenant header `X-Tenant-ID` on all authenticated FE calls | Pass (via `request()`) |
| JWT + refresh before accounting calls | Pass (`getValidAccessToken` + force refresh on 401) |
| ADR-010 (no direct journal writes from UI) | Pass — vouchers via Posting Engine only; sales/purchase post via accounting services |
| AI pages | Remain blocked |
| Fake/mock data | None introduced |

## Automatic Posting / Journal / Approval

| Workflow | How verified |
|----------|----------------|
| Automatic voucher generation | Sales `POST /sales-accounting/post`, Purchase `POST /purchase-inventory/post/goods-receipt`, Treasury cash-receipt, Payroll post → return `voucher_id` |
| Journal workflow | FE vouchers: create → validate → post → reverse/cancel on `/posting` |
| Approval workflow | FE client wired to `/compliance/approvals` (+ approve/reject); UI for request uses domain screens where applicable |
| Accounting events | Unchanged producers in BE services; UI consumes resulting vouchers/reports |

## Known Issues

1. **Ops scaffolding** remains for budget, documents DMS, integration connectors, monitoring KPIs/alerts, voucher recurring/templates, guarantees/facilities — no dedicated domain routers yet; CRUD is against `/ops/documents`.
2. **Suppliers** still list+create only (BE has no PATCH).
3. **Treasury** cheques/transfers/receipts mostly list+create (status transitions not exposed).
4. **Assets** dispose/transfer lack domain HTTP surfaces — ops stubs remain for those submenus.
5. **Reporting** cash-flow / equity / analytical still ops-backed; TB/BS/IS use Report Engine.
6. **Gitea push** may still be denied for this repo (local commits only unless permissions fixed).
7. Phase **5.12 AI** intentionally blocked.

## Next Recommendations

1. Promote high-traffic ops modules (sales orders, purchase orders) to first-class domain models when product prioritizes them.
2. Add supplier PATCH/archive + payable invoice GET/PATCH.
3. Cheque status transition APIs + UI.
4. Server-side voucher status filter + total count for pagination.
5. Wire compliance approval list UI once workflow list endpoint exists.
6. Unblock AI only after AI Provider Active (phase 5.12).

## Scoreboard note

Module scoreboard should treat ops-heavy areas as `partial` where domain engines are incomplete; domain hubs remain `complete`.