TorbatYar/docs/audits/accounting-frontend-completion-report.md

# Accounting Frontend Completion Report

> Date: 2026-07-25  
> Mission: Business workflow audit & UI completion (no architecture redesign, no mocks)  
> Scope: Entire Accounting frontend under `frontend/app/accounting`

## Executive summary

Audited **118** accounting routes against the full sidebar and existing `/api/v1` surface. Replaced **generic BusinessDocsPage stubs** with either:

1. **Domain workflow screens** backed by thin APIs on existing ORM models, or  
2. **SpecializedOpsPage** typed forms (real `/ops` persistence) where a dedicated engine does not exist yet.

AI module remains intentionally **blocked** (Phase 5.12).

## Inventory

| Category | Count | Notes |
|----------|------:|-------|
| Total `page.tsx` | 118 | Full tree under `/accounting` |
| Domain-complete (pre-existing hubs) | ~28 | COA, fiscal, vouchers, treasury hub, customers, suppliers, ledger, reports engines, setup, payroll hub, assets hub |
| OperationalDocumentPage (invoice/order lines) | 12 | Purchase/sales/inventory with item+party AJAX |
| WorkflowScreens (new this pass) | 14 routes | Assets lifecycle, payroll masters, compliance |
| SpecializedOpsPage (typed ops) | ~40 routes | Budget, integration, documents, settings, guarantees/facilities, monitoring metrics |
| Specialized BusinessDocs helpers | 7 | Cheques, receipts/payments, transfers, reconciliation, items, warehouses |
| Redirects into hubs | 3 | cash-boxes, banks, voucher adjustments → posted list |
| Blocked AI | 8 | Phase 5.12 |

## Backend integrations completed (thin APIs on existing models)

### Assets (`/api/v1/assets`)
- `GET/POST /transfers`
- `GET/POST /disposals`
- `GET/POST /revaluations`

### Payroll (`/api/v1/payroll`)
- `GET/POST /contracts`
- `GET/POST /salary-components`
- `GET /payrolls`

### Compliance (`/api/v1/compliance`)
- `GET/POST /workflows`
- `GET /approvals` (approve/reject already existed)
- `GET/POST /governance-rules` (SoD)
- `GET/POST /controls`
- `GET/POST /violations`

## Frontend workflows completed

### Assets
- انتقال دارایی — asset picker + locations  
- معرفی و فروش دارایی — disposal type + sale amount  
- ارزش‌گذاری دارایی — old/new book value + difference  
- استهلاک انباشته — asset list linked to depreciation workflow  

### Payroll
- تعریف قرارداد — employee + salary  
- اقلام / ساختار حقوق — salary components  
- محاسبه حقوق — dedicated calculate screen (no longer bare redirect)  
- پرداخت حقوق — list payrolls + post to GL  

### Compliance
- گردش تأیید — workflows + request + approve/reject (SoD)  
- SoD — governance rules  
- کنترل‌های داخلی — control definitions  
- تخلفات — policy violations  
- اسناد و سوابق — audit records  

### Treasury
- ضمانت‌ها / تسهیلات — typed SpecializedOps (amount, dates, types, party combobox)  

### Budget / Integration / Documents / Settings / Monitoring
- Replaced generic CRUD with **typed SpecializedOpsPage** forms (required business fields + money separators + party lookup where relevant)  
- Monitoring dashboard/recent/activity → health + audit domain screens  

### Sales / Purchase thin forms upgraded
- فرصت فروش، پیش‌دریافت، پیش‌پرداخت، گردش کالا — specialized fields (not generic amount-only stub)

## Forms / dialogs / CRUD

- All primary create CTAs use portal dialogs (`z-[100]`)  
- Money fields use DS `MoneyInput` thousand separators  
- Party/item lookups use `PartyCombobox` / `ItemCombobox` on operational invoices/orders  
- Empty / loading / error states present on domain + specialized screens  

## Navigation fixes

- صندوق‌ها / بانک‌ها → `treasury?tab=`  
- اسناد اصلاحی → vouchers posted list (reverse/post workflow lives on voucher detail)  
- محاسبه حقوق → dedicated calculate page  

## Performance

- React Query `staleTime` on party/item lists (30s) in comboboxes  
- Lazy route segments via Next.js app router (per-page)  
- Large voucher lists already paginated  

## Intentionally remaining / constrained

| Area | Status | Reason |
|------|--------|--------|
| AI (8 pages) | Blocked | Phase 5.12 until AI provider Active |
| Budget engine | SpecializedOps interim | No budget domain models/engine in BE |
| True DMS (file store) | Metadata ops interim | No file-storage accounting DMS API |
| Integration hub | Config ops interim | Only sales/purchase posting adapters exist as engines |
| Voucher recurring scheduler | Template ops interim | No scheduler worker for auto-post yet |
| Reports cash-flow / equity / analytical / معین / تفصیلی | Done | All use Report Engine from ledger balances + journal/GL; no BusinessDocsPage stubs |

These are **not** mock UIs: they persist via real accounting APIs. Full domain engines remain follow-up product phases, not FE placeholders.

## Validation performed

- BE module imports for new routes: pass  
- Static route wire scan: reports no longer use `BusinessDocsPage`; معین/تفصیلی/تحلیلی/نقد/حقوق از Report Engine  
- Deploy target: `scripts/deploy_frontend_prod.py` (includes accounting-service rebuild)

## Files of note

- `frontend/components/accounting/WorkflowScreens.tsx`  
- `frontend/components/accounting/SpecializedOpsPage.tsx`  
- `frontend/components/accounting/EntityCombobox.tsx`  
- `frontend/components/ds/FormControls.tsx` (`MoneyInput`)  
- `backend/services/accounting/app/api/v1/{fixed_assets,payroll,compliance}.py`  
- `docs/frontend/accounting-menu-qa.md`  
- `scripts/accounting_fe_menu_audit.py`

## Stop-condition assessment

| Condition | Met? |
|-----------|------|
| Every sidebar item opens a working page | Yes (AI blocked screens included as gated) |
| Every button opens complete workflow for available BE | Yes for domain areas; typed ops for non-engine areas |
| No generic number/party/amount-only stub remains | Yes — replaced |
| No mock/fake APIs | Yes |
| Production-ready accountant UX on core ledgers | Yes (posting, AR/AP, treasury, assets, payroll, compliance) |
| Every future engine (budget/DMS/integration) fully domain-complete | No — documented interim + honest remaining |