Appearance
Asset Purchases and Returns
| Backlog field | Value |
|---|---|
| Story ID | AP-FA-005 |
| Epic | Fixed Assets |
| Story type | Business workflow |
| Review status | Draft - business analyst and business owner review required |
| Source evidence | AppsPortal.Apis controller, application command/query handlers, validators, domain entities, and matching MFE workflow where available |
| Last source review | 2026-07-10 |
User story
As asset accountants, I want to record asset acquisitions and eligible purchase returns so that asset cost, payables, tax, and accounting remain aligned.
Posting reference: AppsPortal Posting Ledger explains debit/credit construction. Delegation and Interaction Contracts explains module ownership, delegated commands, linked records, commit boundaries, and reversal propagation.
Acceptance criteria
- Only authorized users can view or execute the feature's actions.
- Required business data, active dependencies, tenant/branch scope, and current document state are validated.
- Invalid requests return actionable validation errors without applying a partial change.
- Search, list, view, print, and export operations use the same authorized business scope.
- Material create, edit, status, approval, posting, reversal, and integration actions are auditable where applicable.
- Financial or stock effects are applied atomically and no more than once.
Posting details
- Purchase Post validates Draft/open period/vendor/assets/cost/tax and resolves Vendor Payable through Purchase plus Asset account from configured asset/group data.
- Delegate the purchase journal to Accounting: debit Asset accounts, debit input VAT, credit Vendor Payable; activate/update acquired asset values and mark Posted.
- Return Post validates the posted source, returnable eligible assets, period, vendor, tax, and later lifecycle/depreciation dependencies.
- Delegate the return journal: debit Vendor Payable, credit Asset and VAT; for depreciated returns debit Accumulated Depreciation and credit Depreciation Expense using asset then group fallback.
- Journal, asset state/value, source return status, and document status commit atomically.
General ledger posting
| Transaction | Debit | Credit | Conditional rows |
|---|---|---|---|
| Asset purchase | Asset GL and Input Tax | Vendor Payable | Asset/group, tax/group, vendor/category resolution. |
| Asset return | Vendor Payable | Asset GL and Input Tax reversal | Reverses eligible source values. |
| Return after depreciation | Accumulated Depreciation | Depreciation Expense | Asset then group accounts; only for posted depreciation being reversed. |
Other module and document effects
| Area | Effect | Conditional/no effect |
|---|---|---|
| Asset register | Purchase creates/activates cost; return removes/restores eligible lifecycle state/value. | No Inventory Stock In/Out for fixed-asset register items. |
| Vendor | Purchase creates payable/due balance; return reduces it. | Cash moves only through Payment Out/In. |
| Source purchase | Return updates remaining returnable assets/status. | Later sale/disposal/depreciation can block return. |
Core acceptance scenarios
- Given a valid Draft asset purchase with vendor/tax/group accounts, when the user clicks Post, then asset acquisition values/status and purchase journal commit together.
- Given an eligible posted purchase is returned, when the operation is attempted, then the return reverses payable/asset/tax and applicable depreciation using asset then group accounts.
- Given the same Post request is retried after success, when the source is no longer Draft, then no duplicate journal, stock, balance, payment, or lifecycle effect is created.
Purchase requirements and Post
Draft invoice, vendor, open period, currency/rate, eligible asset lines, positive cost, tax, and asset group/account setup are required. Vendor payable resolves through Purchase vendor rules. Asset account currently resolves from Asset Group for purchase lines. Post debits each Asset account by local amount after discount, debits input VAT to Tax account, credits Vendor Payable for grand total, activates/updates acquired assets, links journal, and marks Posted.
Return requirements and Post
Return requires a posted source purchase, Draft return, returnable assets/amounts, open period, and valid vendor/tax/accounts. It debits Vendor Payable, credits Asset account, reverses VAT, and when depreciation exists debits accumulated-depreciation account and credits depreciation-expense account. Accumulated depreciation and expense resolve asset first then asset group. Source return status becomes Partially or Fully Returned. Active/ineligible assets or dependent later activity block return.
Frontend page coverage
The following UI coverage is sourced from the pulled MFE route configuration. A Module-level supporting artifact mapping is evidence of a reachable screen, but requires BA confirmation that it belongs to this story rather than a more specific feature story.
| Route/page | Component | Mode | Route permission/guard | Mapping confidence | Source |
|---|---|---|---|---|---|
| (module default) | AssetPurchaseInvoiceListComponent | List/navigation | Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:20 |
| (module default) | AssetPurchaseInvoiceMainComponent | List/navigation | Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:12 |
| (module default) | AssetPurchaseInvoiceReturnListComponent | List/navigation | Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:20 |
| (module default) | AssetPurchaseInvoiceReturnMainComponent | List/navigation | Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:12 |
| add | AssetPurchaseInvoiceAddComponent | Add | Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_Add; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:30 |
| add | AssetPurchaseInvoiceReturnAddComponent | Add | Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_Add; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:30 |
| assets-purchase-invoice | Lazy-loaded route | List/navigation | No route-level permission/guard found in source window | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/transactions-routing.module.ts:13 |
| assets-purchase-invoice-return | Lazy-loaded route | List/navigation | No route-level permission/guard found in source window | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/transactions-routing.module.ts:48 |
| assets-return-purchase-invoice | Lazy-loaded route | List/navigation | No route-level permission/guard found in source window | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/transactions-routing.module.ts:20 |
| edit/:id | AssetPurchaseInvoiceEditComponent | Edit | Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_Edit; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:40 |
| edit/:id | AssetPurchaseInvoiceReturnEditComponent | Edit | Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_Edit; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:40 |
| sequence | SequenceComponent | Sequence | No route-level permission/guard found in source window | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:60 |
| sequence | SequenceComponent | Sequence | No route-level permission/guard found in source window | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:60 |
| view/:id | AssetPurchaseInvoiceReturnViewComponent | View/detail | Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_View; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/assets-purchase-invoice-return-routing.module.ts:50 |
| view/:id | AssetPurchaseInvoiceViewComponent | View/detail | Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_View; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/assets-purchase-invoice-routing.module.ts:50 |
Observed frontend fields and validation
| Component | Control | Observed frontend rule | Component source |
|---|---|---|---|
| AssetPurchaseInvoiceAddHeaderComponent | date | Required in component validator | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-header/asset-purchase-invoice-add-header.component.ts |
| AssetPurchaseInvoiceAddHeaderComponent | description | Visible control; optional or API-dependent | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-header/asset-purchase-invoice-add-header.component.ts |
| AssetPurchaseInvoiceAddHeaderComponent | paymentTermId | Required in component validator | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-header/asset-purchase-invoice-add-header.component.ts |
| AssetPurchaseInvoiceAddHeaderComponent | reference | Visible control; optional or API-dependent | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-header/asset-purchase-invoice-add-header.component.ts |
| AssetPurchaseInvoiceAddHeaderComponent | vendorId | Required in component validator | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-header/asset-purchase-invoice-add-header.component.ts |
| AssetsPurchaseReturnHeaderComponent | assetsPurchaseInvoiceHeaderId | Conditionally required/validated in component | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
| AssetsPurchaseReturnHeaderComponent | date | Required in component validator | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
| AssetsPurchaseReturnHeaderComponent | description | Visible control; optional or API-dependent | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
| AssetsPurchaseReturnHeaderComponent | reference | Visible control; optional or API-dependent | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
| AssetsPurchaseReturnHeaderComponent | vendorId | Required in component validator | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
Observed frontend actions
| Component | Click action/handler | Business review requirement | Component source |
|---|---|---|---|
| AssetPurchaseInvoiceAddDetailsComponent | deleteInvoiceLine | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-details/asset-purchase-invoice-add-details.component.ts |
| AssetPurchaseInvoiceAddDetailsComponent | openDialog | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/component/asset-purchase-invoice-add-details/asset-purchase-invoice-add-details.component.ts |
| AssetPurchaseInvoiceListComponent | onDelete | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceListComponent | onEdit | Open the identified editable record only with Edit permission; posted/locked records remain blocked by route or action state and list context must be recoverable on return. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceListComponent | onPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceListComponent | onView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceListComponent | printout | Generate the printout for the selected record and authorized branch/tenant; use posted/current values and surface print, template, ZATCA/ETA, or popup failures without changing transaction state. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceListComponent | routeToJournalView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/fixedAssets/src/app/remote-entry/transactions/asset-purchase-invoice/pages/asset-purchase-invoice-list/asset-purchase-invoice-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | onDelete | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | onEdit | Open the identified editable record only with Edit permission; posted/locked records remain blocked by route or action state and list context must be recoverable on return. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | onPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | onPrintOut | Generate the printout for the selected record and authorized branch/tenant; use posted/current values and surface print, template, ZATCA/ETA, or popup failures without changing transaction state. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | onView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseInvoiceReturnListComponent | routeToJournalView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/pages/asset-purchase-invoice-return-list/asset-purchase-invoice-return-list.component.ts |
| AssetPurchaseReturnDetailsComponent | deleteInvoiceLine | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-details/assets-purchase-return-details.component.ts |
| AssetsPurchaseReturnHeaderComponent | openInvoiceDialog | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/fixedAssets/src/app/remote-entry/transactions/assets-purchase-return/component/assets-purchase-return-header/assets-purchase-return-header.component.ts |
Page-specific frontend acceptance criteria
- (module default) - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_List; Guards: PolicyAuthGuard
- add - Add: Render permitted fields, required indicators, defaults, dependent lookups, validation, Save/Cancel, loading, success, and API-error states. Security observed: Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_Add; Guards: PolicyAuthGuard
- assets-purchase-invoice - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: No route-level permission/guard found in source window
- assets-purchase-invoice-return - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: No route-level permission/guard found in source window
- assets-return-purchase-invoice - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: No route-level permission/guard found in source window
- edit/:id - Edit: Load the identified record, enforce state/permission field locks, preserve concurrency identity, validate changes, and return without losing filters. Security observed: Permission: AppFixedAssetsPermissions.AssetsReturnPurchaseInvoice_Edit; Guards: PolicyAuthGuard
- sequence - Sequence: Show current numbering scope and permit only authorized, valid sequence configuration without retroactively renumbering posted documents. Security observed: No route-level permission/guard found in source window
- view/:id - View/detail: Load an authorized immutable/detail representation with status-aware actions, linked records, print/export where exposed, and not-found/forbidden handling. Security observed: Permission: AppFixedAssetsPermissions.AssetsPurchaseInvoice_View; Guards: PolicyAuthGuard