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 and permission.
8. The pair (role_id, permission_id) shall be unique.
9. A role-permission assignment shall include created_at and updated_at timestamps.
10. Deleting an application, role, or permission shall delete related role-permission assignments.
11. A user-role assignment shall reference an existing user and role.
12. The pair (user_id, role_id) shall be unique.
13. A user-role assignment shall include created_at and updated_at, and may include expires_at.
14. Deleting a user, role, or application shall delete related user-role assignments.
15. 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, updated_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 type shall be one of: NotSet, Shipper, Carrier.
3. Company type shall default to NotSet.
4. Company privacy_enabled shall default to 0.
5. Company disabled shall default to 0.
6. Company disabled_reason, when present, shall be stored as up to 255 characters.
7. A location shall belong to an existing company.
8. A location shall include state, city, country, zipcode, and address_line1.
9. Location type shall be one of: loading, unloading, both.
10. Location type shall default to both.
11. Location coordinates, when present, shall be stored as decimal latitude and longitude values.
12. 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 vehicle_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 vehicle_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 vehicle plate ((company_id, vehicle_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 shipment proposal shall belong to an existing load and an existing user (created_by).
22. If a proposed vehicle is deleted, the shipment proposal vehicle reference shall be set to NULL.
23. Deleting a load shall delete shipment proposals.
24. Deleting the creator user shall delete shipment proposals.
25. A shipment agreement shall reference an existing load, shipment proposal, and accepting user.
26. A load shall have at most one shipment agreement (load_id unique).
27. Deleting a load, shipment proposal, or accepting user shall delete shipment agreements.
28. A load shipment shall belong to an existing load.
29. A load shipment status shall be one of: Assigned, Loading, Transit, Unloading, Delivered.
30. A load shipment status shall default to Assigned.
31. Shipment tracking coordinates, when present, shall be stored as decimal latitude and longitude values.
32. Each load shall have at most one load shipment (load_id unique).
33. Deleting a load shall delete related load shipments.
34. A shipment evidence record shall belong to an existing load.
35. Shipment evidence type shall be one of: loading, unloading.
36. A load shall have at most one evidence per evidence type ((load_id, type) unique).
37. Deleting a load shall delete related shipment evidences.

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. A company sector record shall include created_at and updated_at timestamps.
12. Deleting a company shall delete its company sectors.
13. A company vehicle type shall belong to an existing company.
14. A company shall not repeat the same vehicle type ((company_id, vehicle_type) unique).
15. A company vehicle type record shall include created_at and updated_at timestamps.
16. Deleting a company shall delete its company vehicle types.
17. A company-location-sector assignment shall reference an existing location and existing company sector.
18. A location shall not repeat the same sector ((location_id, sector_id) unique).
19. A company-location-sector record shall include created_at and updated_at timestamps.
20. Deleting a location or company sector shall delete related company-location-sector assignments.
21. A vehicle-type assignment shall reference an existing vehicle and existing company vehicle type.
22. A vehicle shall not repeat the same type ((vehicle_id, type_id) unique).
23. A vehicle-type assignment shall include created_at and updated_at timestamps.
24. Deleting a vehicle or company vehicle type shall delete related vehicle-type assignments.
25. A user-location assignment shall reference an existing user and existing location.
26. A user shall not repeat the same location ((user_id, location_id) unique).
27. A user-location assignment shall include created_at and updated_at timestamps.
28. 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. A user-application assignment shall include created_at and updated_at timestamps.
11. Deleting a user or application shall delete related user-application assignments.
12. A company-user assignment shall reference an existing user and existing company.
13. A company-user assignment shall include created_at and updated_at timestamps.
14. A user shall be assigned to only one company (user_id unique in company_users).
15. Deleting a user or company shall delete related company-user assignments.
16. A privacy group shall belong to an existing company.
17. Privacy group names shall be unique per company ((company_id, name) unique).
18. Deleting a company shall delete its privacy groups.
19. A privacy group company rule shall reference an existing company, privacy group, and allowed company.
20. An allowed company shall not be repeated within the same privacy group ((group_id, allowed_company_id) unique).
21. A privacy group company rule shall include created_at and updated_at timestamps.
22. 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. A load alert email record shall include created_at and updated_at timestamps.
4. Deleting a load shall delete load alert emails.
5. A warehouse alert email record shall belong to an existing warehouse location.
6. The same email shall not be repeated for the same warehouse ((warehouse_id, email) unique).
7. A warehouse alert email record shall include created_at and updated_at timestamps.
8. 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 may include notes.
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 may include status_notes.
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 User 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 and an existing user owner.
4. An API key record shall include created_at and updated_at timestamps.
5. API key active status shall default to 1 (true).
6. Deleting an application or user shall delete related API keys.
7. A user-permission assignment shall belong to an existing application, permission, and user.
8. A user-permission assignment shall include created_at and updated_at, and may include expires_at.
9. A user shall not repeat the same permission assignment ((user_id, permission_id) unique).
10. Deleting an application, permission, or user shall delete related user-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 may include status_notes.
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.

14. Subscription and Billing Constraints

1. A subscription plan shall belong to an existing application.
2. A subscription plan shall include provider, provider_plan_id, and internal name unique within its application ((application_id, name) unique).
3. The pair (provider, provider_plan_id) shall be unique.
4. A subscription plan shall include amount with 4 decimal precision and default 0.0000.
5. Subscription plan currency shall default to MXN when not provided.
6. Subscription plan limits shall default to: limit_users=2, limit_loads=4, limit_shipments=4, limit_privacy_allowed=0.
7. A subscription plan shall include created_at and updated_at timestamps.
8. A company subscription shall reference an existing company and subscription plan.
9. A company shall have at most one company subscription (company_id unique in company_subscriptions).
10. Company subscription status shall be one of: Pending, Active, PastDue, Unpaid, Cancelled, Paused.
11. Company subscription status shall default to Unpaid.
12. A company subscription shall include provider_subscription_id.
13. A company subscription may include start_date, current_period_start, current_period_end, cancelled_at, and cancelled_at_period_end.
14. A company subscription shall include created_at and updated_at timestamps.
15. Company and plan rows referenced by company subscriptions shall not be deletable while dependent subscriptions exist (ON DELETE NO ACTION).
16. A payment method shall belong to an existing company.
17. A payment method shall include provider, provider_payment_id, last4, brand, and name.
18. The pair (provider, provider_payment_id) shall be unique among payment methods.
19. Payment method is_primary shall default to 0.
20. A payment method shall include created_at and updated_at timestamps.
21. A company row referenced by payment methods shall not be deletable while dependent payment methods exist (ON DELETE NO ACTION).
22. A company limits record shall belong to an existing company.
23. A company shall have at most one limits record (company_id unique).
24. Company limits shall default to: available_users=2, available_shipments=4, available_loads=4, privacy_allowed=0.
25. A company limits record shall include created_at and updated_at timestamps.
26. Deleting a company shall delete related company limits records.