SELV Requisition district batch approval endpoint (WIP)

As requested in https://openlmis.atlassian.net/browse/SELV3-61 new Approval screen need to be introduced for the SELV project. You can look into the mockup here.

In order to achieve the goal, we can create the UI for the new Batch Approval page just for the SELV project in selv-v3-ui repository. As for the backend part, there is a slight issue. Search endpoint for requisitions is returning them without the line items so we would need to retrieve them one by one which may be a performance issue for us,

In order to maximize the performance new endpoint would be needed in the Requisition service to fetch the data. To satisfy the requirements we would need to group requisition line items from different facilities in the same district. Mozambique would have 3 levels of geographic zones:

country
province
district

Obviously, districts would be the largest group and there would be ~161 of them, each would have 15-20 facilities at most. Fortunately, there would be only a single supervisory node per district which would allow us to group the data bu supervisory nodes than geographic zones (Requisition service is more aware of supervisory nodes than geographic zones).

The endpoint wouldn’t need any parameters so it could look like this:
GET {serverUrl}/api/requisitionSummary

and below you can see example response:

{
    "program": {
        "id": "fabfd914-1bb1-470c-9e5d-f138b3ce70b8", // PAV
        "href": "https://selv.org.mz/api/programs/fabfd914-1bb1-470c-9e5d-f138b3ce70b8"
    },
    "processingPeriod": { // Janeiro - 2020
        "id": "d6a6ee22-6104-4f03-b4aa-e992623109d5",
        "href": "https://selv.org.mz/api/processingPeriods/d6a6ee22-6104-4f03-b4aa-e992623109d5"
    },
    "lineItems": [
        {
            "orderable": {
                "id": "37cead00-608f-41ef-928e-3d79e8701c36", // BCG
                "href": "https://selv.org.mz/api/orderables/37cead00-608f-41ef-928e-3d79e8701c36"
            },
            "supervisoryNodeSummaries": [
                {
                    "supervisoryNode": { // 10202-ANCUABE
                        "id": "95411544-6c25-4a2c-a8a4-4bc06f812681", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/95411544-6c25-4a2c-a8a4-4bc06f812681"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 2,
                            "stockOnHand": 20,
                            "requestedQuantity": 20
                        }
                    ]
                },
                {
                    "supervisoryNode": { // 10302-ANGOCHE
                        "id": "9ed5df34-4d0d-40f9-85f9-7a27a9db6db7", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/9ed5df34-4d0d-40f9-85f9-7a27a9db6db7"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 1,
                            "stockOnHand": 91,
                            "requestedQuantity": 100
                        },
                        {
                            "versionNumber": 2,
                            "stockOnHand": 11,
                            "requestedQuantity": 10
                        }
                    ]
                },
                {
                    "supervisoryNode": { // 10702-BUZI
                        "id": "7fda7a49-dd53-42dc-82c6-80512e3125d1", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/7fda7a49-dd53-42dc-82c6-80512e3125d1"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 1,
                            "stockOnHand": 4,
                            "requestedQuantity": 2
                        }
                    ]
                }
            ]
        },
        {
            "orderable": {
                "id": "2dbc3abd-9a13-4bf5-ae42-789cc044eab4", // IPV
                "href": "https://selv.org.mz/api/orderables/2dbc3abd-9a13-4bf5-ae42-789cc044eab4"
            },
            "supervisoryNodeSummaries": [
                {
                    "supervisoryNode": { // 10202-ANCUABE
                        "id": "95411544-6c25-4a2c-a8a4-4bc06f812681", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/95411544-6c25-4a2c-a8a4-4bc06f812681"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 2,
                            "stockOnHand": 20,
                            "requestedQuantity": 20
                        }
                    ]
                },
                {
                    "supervisoryNode": { // 10302-ANGOCHE
                        "id": "9ed5df34-4d0d-40f9-85f9-7a27a9db6db7", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/9ed5df34-4d0d-40f9-85f9-7a27a9db6db7"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 1,
                            "stockOnHand": 91,
                            "requestedQuantity": 100
                        },
                        {
                            "versionNumber": 2,
                            "stockOnHand": 11,
                            "requestedQuantity": 10
                        }
                    ]
                },
                {
                    "supervisoryNode": { // 10702-BUZI
                        "id": "7fda7a49-dd53-42dc-82c6-80512e3125d1", 
                        "href": "https://selv.org.mz/api/supervisoryNodes/7fda7a49-dd53-42dc-82c6-80512e3125d1"
                    },
                    "orderableVersions": [
                        {
                            "versionNumber": 1,
                            "stockOnHand": 4,
                            "requestedQuantity": 2
                        }
                    ]
                }
            ]
        }
    ]
}

Looking at the JSON above you can see, that under each line item there is a reference to orderable, but there is no regular info stored in requisition line items like i.e. stock on hand or requested quantity. Those can be found under the supervisoryNodeSummaries field, which would contain an array of a simple orderable summary for each supervisory node. This object would contain the following fields:

supervisoryNode - with id and href fields
orderableVersions - some facilities in a district (in opposition to others) could create a requisition after a change is introduced to specific orderable and this field is designed to support multiple orderable versions in a district, here are fields that we need to include:
- orderableVersionNumber
- stockOnHand
- requestedQuantity

We don’t need price info or other orderable details since we can fetch those from UI cache.

If it comes to managing access to this resource there is an idea of showing approves all the districts at once. I could see that if we want to include this endpoint into the core Requisition service it could be a potential risk of exposing the data for too many users. In this case, we could potentially also check for supervisory nodes that approving user has access to and show just those. The other idea would be to introduce a new right that would just allow users to use the endpoint and get info for all supervisory nodes. It could be named VIEW_REQUISITION_SUMMARY.

If this endpoint is not fitting the design of core Requisition service fully we could maybe mark this endpoint as experimental and discourage other implementations to use it.