GoETAAPI/db/Models/eta_rbac_requirements.md

ETA RBAC and Domain Data Requirements

This document translates SQL constraints from the schema into software requirements language.

1. Global Requirements

1. The system shall store all data in the schema u947463964_etaviaporte.
2. Each table shall use an auto-generated unsigned integer id as primary key.
3. Every foreign-keyed record shall reference an existing parent record.

2. Users and Authentication

1. A user shall provide name and last_name.
2. A user record shall always include created_at and updated_at timestamps.
3. An auth identity shall always belong to an existing user.
4. An auth identity shall include provider and identifier.
5. The combination of provider and identifier shall be unique.
6. Auth identity flags is_primary and is_verified shall default to 0 (false).
7. Deleting a user shall delete the user auth identities.

3. Applications, Roles, and Permissions

1. An application shall include unique name and unique slug.
2. A role shall always belong to an existing application.
3. A role name shall be unique within its application.
4. A permission shall always belong to an existing application.
5. A permission name shall be unique within its application.
6. A permission record shall include created_at and updated_at timestamps.
7. A role-permission assignment shall reference an existing role, permission, and application.
8. The pair (role_id, permission_id) shall be unique.
9. Deleting an application, role, or permission shall delete related role-permission assignments.
10. A user-role assignment shall reference an existing user, role, and application.
11. The pair (user_id, role_id) shall be unique.
12. Deleting a user, role, or application shall delete related user-role assignments.
13. A user shall be allowed to have multiple roles as long as each (user_id, role_id) pair is unique.

4. Verification and Sessions

1. A verification token shall belong to an existing auth identity.
2. A verification token shall include unique token_hash.
3. Verification token purpose shall be one of: email_verification, phone_verification, password_reset.
4. A verification token shall include created_at and expires_at.
5. Deleting an auth identity shall delete related verification tokens.
6. A session shall belong to an existing user.
7. A session shall include unique session_token_hash.
8. A session shall include created_at, updated_at, and expires_at.
9. Deleting a user shall delete related sessions.

5. Companies and Locations

1. A company shall include name.
2. Company privacy_enabled shall default to 0.
3. Company disabled shall default to 0.
4. A location shall belong to an existing company.
5. A location shall include state, city, country, zipcode, and address_line1.
6. Location type shall be one of: loading, unloading, both.
7. Location type shall default to both.
8. Location coordinates, when present, shall be stored as decimal latitude and longitude values.
9. Deleting a company shall delete its locations.

6. Loads, Vehicles, and Shipment Lifecycle

1. A load shall belong to an existing company and an existing creator user.
2. Load status shall be one of: Draft, Published, Completed, Closed, Cancelled.
3. Load status shall default to Draft.
4. A load shall include product, sector, and truck_type.
5. Load privacy_enabled shall default to 0.
6. Load disabled shall default to 0.
7. If an origin or destination location is deleted, the corresponding load reference shall be set to NULL.
8. Deleting the load creator user shall delete the load.
9. Deleting the load company shall delete the load.
10. A vehicle shall belong to an existing company.
11. A vehicle shall include VIN and truck_plate.
12. Vehicle status shall be one of: Available, Busy.
13. Vehicle status shall default to Available.
14. A company shall not repeat the same vehicle VIN ((company_id, VIN) unique).
15. A company shall not repeat the same truck plate ((company_id, truck_plate) unique).
16. A driver shall be assigned to at most one vehicle at a time (driver_id unique).
17. A load shall be assigned to at most one vehicle at a time (load_id unique).
18. If a driver user is deleted, the vehicle driver reference shall be set to NULL.
19. If an assigned load is deleted, the vehicle load reference shall be set to NULL.
20. Deleting a company shall delete its vehicles.
21. A load shipment shall belong to an existing load.
22. A load shipment status shall be one of: Assigned, Loading, Transit, Unloading, Delivered.
23. A load shipment status shall default to Assigned.
24. Shipment tracking coordinates, when present, shall be stored as decimal latitude and longitude values.
25. Each load shall have at most one load shipment (load_id unique).
26. Deleting a load shall delete its load shipment.
27. A shipment evidence record shall belong to an existing load.
28. Shipment evidence type shall be one of: loading, unloading.
29. A load shall have at most one evidence per evidence type ((load_id, type) unique).
30. Deleting a load shall delete shipment evidences.
31. A shipment proposal shall belong to an existing load and an existing user (created_by).
32. If a proposed vehicle is deleted, the shipment proposal vehicle reference shall be set to NULL.
33. Deleting a load shall delete shipment proposals.
34. Deleting the creator user shall delete shipment proposals.
35. A shipment agreement shall reference an existing load, shipment proposal, and accepting user.
36. A load shall have at most one shipment agreement (load_id unique).
37. Deleting a load, shipment proposal, or accepting user shall delete shipment agreements.

7. Master Data and Categorization

1. Sector names in meta_sectors shall be unique.
2. A sector record shall include created_at and updated_at timestamps.
3. Vehicle type names in meta_vehicle_types shall be unique.
4. A vehicle type record shall include created_at and updated_at timestamps.
5. Product names in meta_products shall be unique.
6. A product record shall include created_at and updated_at timestamps.
7. A city record shall include city, state, and country.
8. A city record shall include created_at and updated_at timestamps.
9. A company sector shall belong to an existing company.
10. A company shall not repeat the same sector ((company_id, sector) unique).
11. Deleting a company shall delete its company sectors.
12. A company vehicle type shall belong to an existing company.
13. A company shall not repeat the same vehicle type ((company_id, truck_type) unique).
14. Deleting a company shall delete its company vehicle types.
15. A location-category assignment shall reference an existing location and existing company sector.
16. A location shall not repeat the same category ((location_id, category_id) unique).
17. Deleting a location or company sector shall delete related location-category assignments.
18. A vehicle-type assignment shall reference an existing vehicle and existing company vehicle type.
19. A vehicle shall not repeat the same type ((vehicle_id, type_id) unique).
20. Deleting a vehicle or company vehicle type shall delete related vehicle-type assignments.
21. A user-location assignment shall reference an existing user and existing location.
22. A user shall not repeat the same location ((user_id, location_id) unique).
23. Deleting a user or location shall delete related user-location assignments.

8. Templates, Memberships, and Privacy

1. A load template shall belong to an existing company and creator user.
2. A load template shall include name.
3. A user shall not create duplicate load template names inside the same company ((company_id, created_by, name) unique).
4. Deleting a company shall delete related load templates.
5. Deleting a creator user shall delete related load templates.
6. Deleting an origin or destination location referenced by a load template shall set that location reference to NULL.
7. A user-application assignment shall reference an existing user and existing application.
8. A user shall be allowed to be added to multiple applications.
9. A user shall not be assigned to the same application more than once ((user_id, application_id) unique).
10. Deleting a user or application shall delete related user-application assignments.
11. A company-user assignment shall reference an existing user and existing company.
12. A company-user assignment shall include created_at.
13. A user shall be assigned to only one company (user_id unique in company_users).
14. Deleting a user or company shall delete related company-user assignments.
15. A privacy group shall belong to an existing company.
16. Privacy group names shall be unique per company ((company_id, name) unique).
17. Deleting a company shall delete its privacy groups.
18. A privacy group company rule shall reference an existing company, privacy group, and allowed company.
19. An allowed company shall not be repeated within the same privacy group ((group_id, allowed_company_id) unique).
20. Deleting a company or privacy group shall delete related privacy group company rules.

9. Alert Email Constraints

1. A load alert email record shall belong to an existing load.
2. The same email shall not be repeated for the same load ((load_id, email) unique).
3. Deleting a load shall delete load alert emails.
4. A warehouse alert email record shall belong to an existing warehouse location.
5. The same email shall not be repeated for the same warehouse ((warehouse_id, email) unique).
6. Deleting a warehouse location shall delete warehouse alert emails.

10. Identity and Access Interpretation

1. A user shall be authorized using an identity provider and identifier pair, such as email address or phone number.
2. A provider-specific identifier shall map to one and only one auth identity record.
3. A role and permission model shall be scoped by application.

11. Company Compliance and Documents

1. A company status record shall belong to an existing company.
2. A company shall have at most one company status record (company_id unique).
3. Company status shall be one of: Registered, InReview, Enabled, Disabled.
4. Company status shall default to Registered.
5. A company status record shall include notes (NOT NULL).
6. A company status record shall include created_at and updated_at timestamps.
7. Deleting a company shall delete related company status records.
8. A company document shall belong to an existing company.
9. A company document shall include document_id and name.
10. Company document status shall be one of: New, InReview, Approved, Rejected.
11. Company document status shall default to New.
12. A company document shall include status_notes (NOT NULL).
13. A company document record shall include created_at and updated_at timestamps.
14. A company shall not repeat document names ((company_id, name) unique).
15. Deleting a company shall delete related company documents.

12. API Key and Permission Model

1. An API key record shall include name and key_hash.
2. API key hashes shall be globally unique.
3. An API key shall belong to an existing application.
4. An API key record shall include created_at and updated_at timestamps.
5. Deleting an application shall delete related API keys.
6. An API key permission record shall belong to an existing application, permission, and API key.
7. API key permission assignments shall include created_at.
8. An API key shall not repeat the same permission assignment ((apikey_id, permission_id) unique).
9. Deleting an application, permission, or API key shall delete related API key permission assignments.

13. Vehicle Documents

1. A vehicle document shall belong to an existing company and an existing vehicle.
2. A vehicle document shall include document_id and name.
3. Vehicle document status shall be one of: New, InReview, Approved, Rejected.
4. Vehicle document status shall default to New.
5. A vehicle document shall include status_notes (NOT NULL).
6. A vehicle document record shall include created_at and updated_at timestamps.
7. A company shall not repeat vehicle document names ((company_id, name) unique).
8. Deleting a company or vehicle shall delete related vehicle documents.