User Specific Access for Invoice & Payment Receipt

Author(s)

• SANKET MAL
• RESHMI KARAN
• SAYAN MUKHERJEE

Last Updated Date

2024-09-13

---

SRS References

---

Version History

Version	Date	Changes	Author
1.0	2024-09-13	Initial draft	Sanket Mal , Reshmi Karan , Sayan Mukherjee

---

Feature Overview

Objective:
To implement user-based access for viewing invoices for received orders by introducing three scopes: view.invoice.received.order, view.invoice.received.order.own, and view.invoice.received.order.all.

To implement user-based access for viewing payment receipt by introducing three scopes: payment.view, payment.view.own, and payment.view.all.

Scope:
This feature defines a flexible access control system for viewing payment receipt and invoice for received order views based on assigned scopes. The key scopes involved are:

view.invoice.received.order.own and payment.view.own grants users the ability to view only the payment receipt and invoice for received orders that are placed by the dealers or distributors under their direct management respectively. This ensures that users with this scopes can only access payment receipt and invoices from the specific dealers or distributors they are responsible for.

view.invoice.received.order.all and payment.view.all grants users the ability to view all payment receipt and invoices for received orders across the system, regardless any of the dealer or distributor. This scope is typically assigned to higher-level managers or administrators who need broader visibility of orders.

By using these scopes, the feature ensures secure and customizable access to payment receipt and invoices based on user's , supporting a hierarchical view of invoices and payment receipts for managers and administrators while maintaining privacy and control over sensitive data.

Dependencies:

• DAL call for fetching list of dealer id under an user.
• Depends on mass transist call to dealermanagement service for getting list of dealers under a manager.

---

Requirements

This section outlines the functional requirements of the feature, explaining how access to payment receipt and invocices is controlled based on user scopes. These requirements ensure the system behaves as intended when managing and filtering order views.

1. Implement Scopes for Controlling Access : The following three scopes must be implemented to handle different levels of access to the received orders:

   • view.invoice.received.order and payment.view: This scopes is required for users to be able to hit the API that fetches the invoices of received orders and receipt of payment respectively. It allows users to access the API but does not dictate what receipts or invoices they can view. Every user must have this scope to initiate API requests.

   • view.invoice.received.order.own and payment.view.own: This scope grants users the ability to view only the invoices of received orders and payment receipt respectively that were placed by the dealers or distributors they manage. This means users with this scope will only see invoices and payments from dealers under their direct supervision. This scope is typically assigned to managers who oversee specific dealers or distributors.

   • view.invoice.received.order.all and payment.view.all: This scope gives users permission to view all invoices and payments regardless of which dealer or distributor placed the order.

2. Validate User Scopes in API : Inside the API, the system must check which scopes are assigned to the logged-in user to determine what orders they can view:

   • If the user has view.invoice.received.order.all or payment.view.all, they can view all invoices or payment receipt respectively without restriction. No filtering by dealer or distributor is needed in this case.
   • If the user does not have the view.invoice.received.order.all or payment.view.all scope, the API should fetch the email from the user's JWT (JSON Web Token) and use it to identify which dealers or distributors are managed by the user. The system will then filter the invoices or receipts based on the dealers or distributors the manager is responsible for, showing only their own received orders.

3. Ensure Compatibility with JWT Authentication : The system must work with JWT for user authentication, and the user’s email will be extracted from the token. This email is essential for determining which dealers or distributors are under the logged-in user's control, especially when applying the view.invoice.received.order.own or payment.view.own scope.

4. DAL Method to Fetch Dealers Under a Manager : A DAL method must be implemented to retrieve the list of dealers or distributors that a manager oversees, based on their email address. This method will be used to filter the received orders when a user has the received.order.view.own scope. The method will take the manager’s email as a parameter and return a list of dealer or distributor which is the list of dealers or distributors that is under the user's oversees.

5. Filter by dealer Option : Users will have the option to filter invoices or receipts by specifying a dealerIds in the dealerid filter. Depending on the user's scope, the system will handle the filtering as follows:

   • If the user has view.invoice.received.order.all or payment.view.all, the system will simply filter the received invoice or receipt based on the dealerId passed in the filter. This allows the user to see invoice or receipt from any dealers they specify.

   • If the user has view.invoice.received.order.own or payment.view.own, the system must first fetch the list of dealers or distributors that the user manages, based on their email using the helper method. Once the list is retrieved, the system will check that the passing dealerid in filter is present in the the lists of dealerid or not :

     • If yes then invoice and receipt will filter by that dealerid.
     • If no then don't go to dal just return not allowed from helper.

   • But in case of the user who has the scope view.invoice.received.order.all or payment.view.all then without any restriction filter the invoice and receipt by the dealerid which is passed by the filter.

---

Design Specifications

• UI/UX Design:

• Data Models:
  In get/invoice/receivedorder api return paginated list of InvoiceMinimalData and in analytics/receipts/list api return paginated list of ReceiptStructLite.

  public class ServerPaginatedData<T>
  {
      public List<T>? Data { get; set; }
      public long Totalnumber { get; set; }
  }
  public class InvoiceMinimalData
  {
      [XLColumn(Ignore = true)]
      public Guid InvoiceId { get; set; }
      [XLColumn(Header = "Invoice Number")]
      public string? InvoiceNumber { get; set; }
      [XLColumn(Header = "Dealership Type")]
      public InvoicePartyType PartyType { get; set; }
      [XLColumn(Header = "Invoice Date")]
      public DateTime InvoiceDate { get; set; }
      [XLColumn(Header = "Billing Type")]
      public BillingType BillingType { get; set; }
      [XLColumn(Header = "Payment Status")]
      public InvoicePaymentStatus PaymentStatus { get; set; }
      [XLColumn(Header = "Invoice Type")]
      public InvoiceType InvoiceType { get; set; }
      [XLColumn(Header = "Total Amount")]
      public decimal TotalAmount { get; set; }
      [XLColumn(Header = "CGST Amount")]
      public decimal CGSTAmount { get; set; }
      [XLColumn(Header = "SGST Amount")]
      public decimal SGSTAmount { get; set; }
      [XLColumn(Header = "IGST Amount")]
      public decimal IGSTAmount { get; set; }
      [XLColumn(Header = "Total Amount With Tax")]
      public decimal TotalAmountWithTax { get; set; }
      [XLColumn(Header = "Round Off")]
      public decimal? RoundOff { get; set; }
      [XLColumn(Header = "Buyer Name")]
      public string? BuyerName { get; set; }
      [XLColumn(Header = "Seller Name")]
      public string? SellerName { get; set; }
      [XLColumn(Header = "IRN Applicable Status")]
      public bool? IsIrnApplicable { get; set; } = false;
      [XLColumn(Header = "E-Way Bill Applicable Status")]
      public bool? IsEwaybillApplicable { get; set; } = false;
  }
  
  public record ReceiptStructLite
  {
      [JsonIgnore]
      public long Totalnumber { get; set; }
      public Guid TransactionId { get; set; }
      public string? RefNumber { get; set; }
      public string? ReceiptNumber { get; set; }
      public DateTime RefDate { get; set; }
      public DateTime? ChequeDate { get; set; }
      public Guid ConsumerId { get; set; }
      public string? ConsumerName { get; set; }
      public string? ConsumerCode { get; set; }
      public Address? ConsumerAddress { get; set; }
      public PaymentType? PaymentType { get; set; }
      public RefundMethod? RefundMethod { get; set; }
      public decimal Amount { get; set; }
      public string? Notes { get; set; }
      public TransactionType TransactionType {  get; set; }
      public InvoiceList? AttachedInvoice { get; set; }
      public OrderList? AttachedOrder { get; set; }
      public PaymentList? AttachedPayment { get; set; }
  }

• API Interfaces:
  (Define the APIs required for this feature, including endpoints, methods, request/response formats.)

Endpoint	Method	Parameters	Response	Response Status Codes
api/payment/invoice/get/invoice/receivedorder	POST	PageNumber, RowsPerPage, InvoiceType, BillingType, PaymentStatus, ListOfSellerId, InvoiceNumber, OrderNumber, StartDate, EndDate, IsExcel	Paginated list of Invoices	200, 404, 403, 500
api/payment/analytics/receipts/list	POST	TransactionId, StartDate, EndDate, ConsumerId, PaymentType, TransactionType, ReceiptNumber, InvoiceNumber, OrderNumber, PageNumber, RowsPerPage, IsExcel	Paginated list of Receipts	200, 404, 400, 403, 500

• Third-Party Integrations:
  (List any third-party services or tools that need to be integrated.)

• Workflow:
  Flow Chart for get invoice- Flow Chart for get receipt list-

  • User requests for view invoice or receipt.
  • JWT token is validated, extracting the user's email and assigned scopees.
  • If the user has view.invoice.received.order.all or payment.view.all, they are shown all invoice or receipt based on passing filter.
  • If the user has view.invoice.received.order.own or payment.view.own , the manager's dealers are fetched using mass transist from dealer service, and then find dealerid pass by filter is present in the list of dealerid or not . If yes then filter the invoices and payments by the dealerid which pass in filter. Else return Not Allowed from helper.
  • If the user lacks the required scope, access is denied.

---

Development Tasks & Estimates

(Break down the development process into smaller tasks and provide time estimates for each.)

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Modify the API to Retrive invoices based on user and given scope to user	6 hours	MassTransit Integration for Fetching Dealer List from Payment Service to Dealer Service
2	Modify the API to Retrive receipt based on user and given scpe to user	6 hours	MassTransit Integration for Fetching Dealer List from Payment Service to Dealer Service
3	Backend testing for get invoice api	1.5 hours
4	Backend testing for get receipt list api	1.5 hours
5	Database Migration	3 hours	Depend on Fleeto's given data which user should assign view.invoice.received.order.all and payment.view.all scope
6	Database Migration (Update list of manager for every dealer)	3 hours	Depends on given data by Fleeto
7	Total	21 hours

---

Testing & Quality Assurance

• Unit Tests:
  Unit test for API to Retrive Invoices. Unit test for API to Retrive Receipts.

• Integration Tests:
  Test the full workflow, including validating JWT tokens, extracting email addresses, querying dealers, and filtering invoice or receipt by common dealer ID.

• Acceptance Criteria:
  API correctly handles user specific accessed based on their given scopes. An user who have scope view.invoice.received.order.all or payment.view.all can see all invoices or receipts. An user who have scope view.invoice.received.order.own and payment.view.own can view only their under dealers' invoice or receipts.

• Testing Tools:
  xUnit
  Moq

---

Deployment Considerations

(Describe any deployment considerations, including environment configurations, feature toggles, or migration steps.)

• Configuration Changes:

  • Depend on Fleeto's given data which user should assign view.invoice.received.order.all and payment.view.all scope

• Rollout Plan:
  (Outline the plan for rolling out the feature, including any phased releases.)

---

Risks & Mitigations

---

Review & Approval

(Include a section for review and approval by stakeholders.)

• Reviewer:
  Abhishak Kumar Roy

• Approval Date:
  2024-09-16

---

Notes
(Add any additional notes or considerations related to the feature development here.)