From 507ca88641ae06ce92de66a680c89ccc20725a18 Mon Sep 17 00:00:00 2001 From: Josepablo Cruz Date: Thu, 9 Apr 2026 09:15:42 -0600 Subject: [PATCH] chore(srs): Adding rest of endpoints and proposals --- docs/software_requirements_specification.md | 78 ++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/docs/software_requirements_specification.md b/docs/software_requirements_specification.md index b357453..e4409de 100644 --- a/docs/software_requirements_specification.md +++ b/docs/software_requirements_specification.md @@ -1,4 +1,53 @@ -# ETA's Core API +# ETA's Core API (Draft) + +The following is a draft model for the list of resources the core API exposes: + +- The list will give an idea of the interaction with the API from the clients perspective. + +- The list gives an idea of the resources and operations available within the system, to use that information to create the permissions for every resource for every operation. + +- This list will be translated into user stories in a document shared in a sharepoint for traceability and reproducibility. + +## API Principles + + - Applications are the main element of the RBAC system, each application has certain access to the ETA Core resources, like loads, companies directory, among others. + - Each Application has it's own set of permissions. + - Each Application has it's own set of roles with permissions associated. + - Each Application has it's own set of user_sessions. + - New users shall be created and directly assigned to an application. + - Any user shall be able to exists in more than one application at the same time. + - Users may have permissions assigned within an application where it belongs to. + - Users shall have roles assigned within an application where it belongs to. + - Users may have apikeys assigned within an application where it belongs to. + - Users may have sessions assigned within an application where it belongs to. + - Users may have multiple identities, but only one of each category (phone, email). + - Only one identity shall be the main user's identity. + - All resources shall have a list of operations allowed. + - System shall allow an operation to be perform over a resource only if the permission allows it. + - No resource is modified without any type of permission validation: + - User identified by JWT: The JWT is used to retrive the permissions list and use it to validate the authorization. + - User identified by APIKey: The APIKey is used to retrive the permissions list and use it to validate the authorization. + +### Identified resources: + +- **Companies**: A company is represented with a name and description of their operations, it belongs to one of the types: Shipper, Carrier. +- **Company_Documents**: A company documentation stored in an external BLOB solution, this documentation is part of company register procress. +- **Vehicles**: A vehicle to transport goods, used by the Carrier company to make a proposal. An employee can be assigned to only one vehicle at a time. +- **Vehicle_Documents**: Vehicle's documents to legally register it into the system. (Determine if a vehicle requires a registration process). +- **Locations**: A geographical location important to the company, represents warehouses, either owned warehouses or client's warehouses where the goods need to arraive or be loaded. +- **Company_Employees**: User's assigned to the company, the employees shall have at most one of the following predefined roles: `admin`, `staff`, `readonly`, `driver`. +- **Proposals**: A shipment proposal made by the Carrier company, which exposes the public information about the vehicle and the company itself. +- **Loads**: It represents a publication of load to be transported, created by a Shipper company. A load shall be able to receive many proposals, but only accept one. Accepting a proposal creates the unique `shipment_agreement` resource into the load. +- **Load_Templates**: It holds common values to help the user quickly create loads on the front-end. +- **Shipments**: It represents the transport operation of the goods, it is always linked and identified (searched) using the loads identifier. + +- When a load is published, the load object is modifiable by the Shipper company only. (Created by) +- When a proposal is sent, the proposal object is modifiable by the Carrier company only. (Created by) +- When an accepted proposal creates the agreement, the agreement is modified by the Shipper only, the load then exposes the agreement and the rest of the shipment details as part of the view, but in read only mode. For example: Loads.shipment, Loads.shipment_evidences, etc. +- The Shipment is always associated to a load, when the user cancels the shipment with a Carrier, the shipment is not deleted, but reused for the next agreement. +- The user that has the role of driver, reads the associated Load, but only modifies the shipment related tables/objects: load_shipment (GPS tracking, and transport state), shipment_evidences. + +## Proposal of endpoints to expose the resources. Draft of software requirements specification (SRS) to model API endpoints and its responsabilities. @@ -53,6 +102,33 @@ Draft of software requirements specification (SRS) to model API endpoints and it - **/app/{app_id}/auth/refresh**: - **/app/{app_id}/auth/me**: +- **/companies/{company_id}** -> Specific company data or own company updates +- **/companies/{company_id}/documents** +- **/companies/{company_id}/vehicles** +- **/companies/{company_id}/vehicles/{vehicle_id}/documents** +- **/companies/{company_id}/locations** +- **/companies/{company_id}/sectors** +- **/companies/{company_id}/vehicle_types** +- **/companies/{company_id}/privacy_groups** +- **/companies/{company_id}/privacy_groups/{group_id}** +- **/companies/{company_id}/employees** <> Search for users, and add/remove users to the company. Create identities or create users. +- **/companies/{company_id}/loads** <> Available resources expected on Shippers only +- **/companies/{company_id}/loads/templates** +- **/companies/{company_id}/loads/templates/{template_id}** +- **/companies/{company_id}/loads/{load_id}** +- **/companies/{company_id}/proposals** <> Available resources expected on Carriers only +- **/companies/{company_id}/proposals/{proposal_id}** + +- **/shipments** <> Availble resources for both Shipper and Carrier. (TODO: How to split for writing operations, reading and sharing among companies?) +- **/shipments/{shipment_id}** +- **/shipments/{shipment_id}/evidences** +- **/shipments/{shipment_id}/evidences/{evidence_id}** +- **/shipments/{shipment_id}/proposal** +- **/shipments/{shipment_id}/agreement** + +- **/directories/companies** <> Search for public companies +- **/directories/loads** <> Search for private companies + # Admin Authorization Strategy: The system shall have a predefined system application to control all resources.