feat(SQL): Adding subscriptions and resource counter tables

db/Models/eta_rbac_requirements.md

@@ -26,20 +26,22 @@ This document translates SQL constraints from the schema into software requireme
 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.
+7. A role-permission assignment shall reference an existing role and permission.
 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.
+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` and `expires_at`.
+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`.
@@ -49,54 +51,57 @@ This document translates SQL constraints from the schema into software requireme
 ## 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.
+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 `truck_type`.
+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 `truck_plate`.
+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 truck plate (`(company_id, truck_plate)` 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 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.
+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
 
@@ -110,19 +115,24 @@ This document translates SQL constraints from the schema into software requireme
 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.
+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
 
@@ -135,26 +145,30 @@ This document translates SQL constraints from the schema into software requireme
 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.
+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. 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.
+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
 
@@ -168,29 +182,30 @@ This document translates SQL constraints from the schema into software requireme
 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).
+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 shall include `status_notes` (NOT NULL).
+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 Permission Model
+## 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.
+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. 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.
+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
 
@@ -198,7 +213,36 @@ This document translates SQL constraints from the schema into software requireme
 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).
+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.