ERP_Distribution/accounts-module-migration-plan.md

Plan: Clone Accounts Module from ERP-core to Distribution

Context

The ERP-core system has a fully implemented Accounts module (7 features) visible in the sidebar. The goal is to replicate all 7 features — with identical UI and independent backend — in the Distribution project (ERP_Distribution). Distribution will get its own C# controllers, services, EF entities, and migrations rather than sharing ERP-core's backend.

Scope: All 7 Features

1. Cash / Bank Accounts (via GL service proxy)
2. Cheque Books (via GL service proxy)
3. Received Cheques (via GL service proxy)
4. Expenses (own ERP-core controllers)
5. Expense Setup (own ERP-core controllers)
6. Bank Deposits (own ERP-core controllers)
7. Opening Balances (own ERP-core controllers)

Important note: Features 1–3 go through a separate General Ledger (GL) microservice proxied at /api/v1/gl/* in ERP-core. The Distribution backend must also proxy to this same GL service, OR the GL service must be updated to support the distribution context. Confirm with the team whether the GL service is shared infrastructure or ERP-specific before implementing features 1–3.

---

Source Files (ERP-core)

Frontend — Frontend/erp-system/

Type	Path
Sidebar nav	components/Layouts/AppSidebar.tsx (lines 209–222)
Pages	app/dashboard/accounts/** (7 feature directories)
Shared components	components/accounts/*.tsx (8 files)
API clients	lib/api/expenses.ts, bank-deposits.ts, general-ledger.ts, opening-balances.ts
Types	types/expenses.ts, bank-deposits.ts, general-ledger.ts, opening-balances.ts
Route guard	lib/nav-routes.ts

Backend — Backend/ERPCore/

Type	Path
Controllers	Controllers/ExpensesController.cs, ExpenseSetupController.cs, BankDepositsController.cs, OpeningBalancesController.cs, GlAccountConfigController.cs
Services	Services/ExpenseService.cs, ExpensePaymentService.cs, ExpenseSetupService.cs, BankDepositService.cs, CashInHandService.cs, OpeningBalanceService.cs, GlAccountConfigService.cs
Entities	Domain/Entities/Expense.cs, ExpenseCategory.cs, BankDeposit.cs, GlAccountConfig.cs, OpeningBalanceRun.cs
DTOs	Dtos/Expenses/ExpenseDtos.cs, Dtos/Accounts/BankDepositDtos.cs, Dtos/OpeningBalances/
Migrations	Migrations/20261007*, 20261008*, 20261018*

---

Target: Distribution Project — C:\Users\lenovo\Desktop\NEWGITEA\ERP_Distribution

---

Implementation Phases

Phase 1 — Explore Distribution Project Structure (Read-only prerequisite)

Before coding, read these files to confirm conventions:

• ERP_Distribution/Distribution/Program.cs — DI registration pattern
• ERP_Distribution/Distribution/Controllers/ (any existing controller) — naming convention
• ERP_Distribution/distribution_fe/components/Layouts/ — sidebar/nav structure
• ERP_Distribution/distribution_fe/lib/api.ts — API client pattern (may differ from ERP-core's per-feature files)
• ERP_Distribution/distribution_fe/app/dashboard/ — existing route structure

Phase 2 — Backend: Domain Entities & DTOs

In ERP_Distribution/Distribution/:

1. Create entity files (copy + namespace-adjust from ERP-core):

   • Domain/Entities/Expense.cs
   • Domain/Entities/ExpenseCategory.cs
   • Domain/Entities/BankDeposit.cs
   • Domain/Entities/GlAccountConfig.cs
   • Domain/Entities/OpeningBalanceRun.cs
   • Status enums: ExpenseStatus.cs, BankDepositStatus.cs

2. Create DTO files:

   • Dtos/Expenses/ExpenseDtos.cs
   • Dtos/Accounts/BankDepositDtos.cs
   • Dtos/OpeningBalances/OpeningBalanceDtos.cs
   • Dtos/GlAccountConfig/GlAccountConfigDtos.cs

3. Register entities in DbContext — add DbSet<> entries to the existing EF DbContext

4. Create EF migration — add-migration AddAccountsModule in Distribution project

Phase 3 — Backend: Services & Controllers

In ERP_Distribution/Distribution/:

1. Create service interfaces and implementations (copy + namespace-adjust):

   • Services/IExpenseServices.cs + ExpenseService.cs
   • Services/IExpenseServices.cs + ExpensePaymentService.cs
   • Services/ExpenseSetupService.cs
   • Services/IBankDepositServices.cs + BankDepositService.cs
   • Services/CashInHandService.cs
   • Services/IOpeningBalanceService.cs + OpeningBalanceService.cs
   • Services/IGlAccountConfigService.cs + GlAccountConfigService.cs

2. Create controllers (copy + namespace-adjust, update route prefix if needed):

   • Controllers/ExpensesController.cs
   • Controllers/ExpenseSetupController.cs
   • Controllers/BankDepositsController.cs
   • Controllers/OpeningBalancesController.cs
   • Controllers/GlAccountConfigController.cs
   • GL Proxy controller — a new controller that proxies /api/v1/gl/* to the shared GL microservice (same pattern as ERP-core)

3. Register services in DI — add to Program.cs:

   builder.Services.AddScoped<IExpenseServices, ExpenseService>();
   builder.Services.AddScoped<IBankDepositServices, BankDepositService>();
   // ... etc.
   

4. Add permissions/policies — mirror NavPolicies from ERP-core for accounts permission codes

Phase 4 — Frontend: Types & API Clients

In ERP_Distribution/distribution_fe/:

1. Copy type files to types/:

   • types/expenses.ts
   • types/bank-deposits.ts
   • types/general-ledger.ts
   • types/opening-balances.ts

2. Copy API client files to lib/api/ (update base URL to distribution backend):

   • lib/api/expenses.ts
   • lib/api/bank-deposits.ts
   • lib/api/general-ledger.ts
   • lib/api/opening-balances.ts
   • Adjust any NEXT_PUBLIC_API_URL references to point to Distribution backend

Phase 5 — Frontend: Components & Pages

In ERP_Distribution/distribution_fe/:

1. Copy shared account components to components/accounts/:

   • OpeningCashBankPanel.tsx
   • OpeningStockPanel.tsx
   • ExpenseForm.tsx
   • ExpensePaymentDialog.tsx
   • ChequePageDialog.tsx
   • ReceivedChequeDialog.tsx
   • expense-badges.tsx
   • bank-deposit-badges.tsx

2. Create page directory structure under app/dashboard/accounts/:

   accounts/
   ├── page.tsx                        (hub page)
   ├── bank-accounts/page.tsx
   ├── bank-accounts/new/page.tsx
   ├── cheque-books/page.tsx
   ├── cheque-books/new/page.tsx
   ├── cheque-books/[chequeBookNo]/page.tsx
   ├── received-cheques/page.tsx
   ├── received-cheques/new/page.tsx
   ├── expenses/page.tsx
   ├── expenses/new/page.tsx
   ├── expenses/[id]/page.tsx
   ├── expense-setup/page.tsx
   ├── bank-deposits/page.tsx
   ├── bank-deposits/new/page.tsx
   ├── bank-deposits/[id]/page.tsx
   └── opening-balances/page.tsx
   

3. Copy each page from ERP-core's equivalent path, adjusting import paths as needed

Phase 6 — Frontend: Sidebar Navigation & Route Guard

1. Add Accounts menu to Distribution's sidebar/nav config (mirror ERP-core AppSidebar.tsx lines 209–222)
2. Update route guard — add accounts permission codes to nav-routes.ts (or equivalent) in the distribution frontend
3. Add permission codes to auth context/provider if Distribution uses role-based nav gating

---

Key Decisions & Risks

Item	Risk	Mitigation
GL service shared vs. ERP-only	GL proxy may not accept Distribution's auth tokens or branch context	Confirm with team; may need a dedicated Distribution GL proxy config
DB schema differences	Distribution's EF context may have different conventions	Review existing migrations before adding new entities
API client base URL	Distribution frontend may use a different env var for the backend URL	Check lib/api.ts pattern before copying API clients
Permission system	Distribution may use different permission codes/claims	Match Distribution's existing RBAC pattern

---

Verification

1. Backend: Run dotnet build in ERP_Distribution/Distribution — zero errors
2. Migration: Run dotnet ef database update — schema applied cleanly
3. API smoke test: Hit GET /api/v1/expenses, GET /api/v1/bank-deposits via Swagger/Postman
4. Frontend: Run npm run dev in distribution_fe — Accounts menu appears in sidebar
5. E2E flow:
   • Create an expense (Draft → Post → Pay)
   • Record a bank deposit and verify cash-in-hand updates
   • Open a cheque book and issue a page
   • Enter opening balances
6. Permissions: Log in as a role without accounts.* codes — verify Accounts menu is hidden