249 lines
16 KiB
Markdown
249 lines
16 KiB
Markdown
# 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.
|