# 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.