Merge pull request #4796 from bcgov/1456-registration-app-tables-have-meaningful-metadata

1456 Update registration tables with comments

Author: Sepehr-Sobhani

bc_obps/compliance/migrations/0052_update_timestamp_metadata.py

@@ -16,34 +16,34 @@ class BcGreenhouseGasId(BaseModel):
     id = models.CharField(
         primary_key=True,
         max_length=255,
-        db_comment="The BCGHG ID of an operation or facility",
+        db_comment="The BCGHG (BC Greenhouse Gas) ID assigned to an operation or facility. Primary key.",
         validators=[
             RegexValidator(regex=BCGHG_ID_REGEX, message="BCGHG ID should be 11 digits, starting with 1 or 2.")
         ],
     )
     issued_at = models.DateTimeField(
         auto_now_add=True,
-        db_comment="The time the BCGHG ID was issued by an IRC user",
+        db_comment="The time the BCGHG (BC Greenhouse Gas) ID was issued by an IRC user",
     )
     issued_by = models.ForeignKey(
         User,
         on_delete=models.PROTECT,
-        db_comment="The IRC user who issued the BCGHG ID",
+        db_comment="The IRC user who issued the BCGHG (BC Greenhouse Gas) ID. Foreign key to erc.user",
         blank=True,
         null=True,
         related_name="bc_greenhouse_gas_id_issued_by",
     )
     comments = models.TextField(
         blank=True,
-        db_comment="Comments from admins in the case that a BCGHG ID is revoked",
+        db_comment="Comments from admins in the case that a BCGHG (BC Greenhouse Gas) ID is revoked",
     )
     history = HistoricalRecords(
         table_name='erc_history"."bc_greenhouse_gas_id_history',
         history_user_id_field=models.UUIDField(null=True, blank=True),
     )
 
     class Meta:
-        db_table_comment = "Table to store BCGHG ID metadata. Once an operation or facility meets the criteria for an ID, then it is issued one."
+        db_table_comment = "Table to store BCGHG (BC Greenhouse Gas) ID metadata. Once an operation or facility meets the criteria for an ID, then it is issued one."
         db_table = f'{Schemas.ERC.value}"."{RegistrationTableNames.BC_GREENHOUSE_GAS_ID.value}'
 
     Rls = BcGreenhouseGasIdRls

bc_obps/registration/migrations/0184_update_registration_metadata.py

@@ -20,37 +20,37 @@ class Statuses(models.TextChoices):
     id = models.CharField(
         primary_key=True,
         max_length=255,
-        db_comment="The BC OBPS regulated operation ID of an operation when operation is approved",
+        db_comment="The BC OBPS (Output-Based Pricing System) regulated operation ID of an operation when operation is approved",
     )
     issued_at = models.DateTimeField(
         auto_now_add=True,
-        db_comment="The time the BC OBPS Regulated Operation ID was issued by an IRC user",
+        db_comment="The time the BC OBPS (Output-Based Pricing System) Regulated Operation ID was issued by an IRC user",
     )
     issued_by = models.ForeignKey(
         User,
         on_delete=models.PROTECT,
-        db_comment="The IRC user who issued the BC OBPS Regulated Operation ID",
+        db_comment="The IRC user who issued the BC OBPS (Output-Based Pricing System) Regulated Operation ID. Foreign key to erc.user",
         blank=True,
         null=True,
         related_name="bc_obps_regulated_operation_issued_by",
     )
     comments = models.TextField(
         blank=True,
-        db_comment="Comments from admins in the case that a BC OBPS Regulated Operation ID is revoked",
+        db_comment="Comments from admins in the case that a BC OBPS (Output-Based Pricing System) Regulated Operation ID is revoked",
     )
     status = models.CharField(
         max_length=1000,
         choices=Statuses.choices,
         default=Statuses.ACTIVE,
-        db_comment="The status of an operation.",
+        db_comment="The status of the BC OBPS (Output-Based Pricing System) Regulated Operation ID (Active or Inactive). Inactive indicates the ID has been revoked.",
     )
     history = HistoricalRecords(
         table_name='erc_history"."bc_obps_regulated_operation_history',
         history_user_id_field=models.UUIDField(null=True, blank=True),
     )
 
     class Meta:
-        db_table_comment = "Table to store BC OBPS Regulated Operation metadata. Once an operation has been approved as a BC OBPS Regulated Operations (IRC has determined the operation meets certain criteria and should be included in the program), then it is issued an ID."
+        db_table_comment = "Table to store BC OBPS (Output-Based Pricing System) Regulated Operation metadata. Once an operation has been approved as a BC OBPS (Output-Based Pricing System) Regulated Operations (IRC has determined the operation meets certain criteria and should be included in the program), then it is issued an ID."
         db_table = f'{Schemas.ERC.value}"."{RegistrationTableNames.BC_OBPS_REGULATED_OPERATION.value}'
 
     Rls = BcObpsRegulatedOperationRls

bc_obps/registration/models/bc_greenhouse_gas_id.py

@@ -12,7 +12,7 @@ class Contact(UserAndContactCommonInfo, TimeStampedModel):
         BusinessRole,
         on_delete=models.DO_NOTHING,
         related_name="contacts",
-        db_comment="The role assigned to this contact which defines the permissions the contact has.",
+        db_comment="The business role of this contact within the operator/operation (e.g. Operation Representative). Foreign key to erc.business_role",
     )
     address = models.ForeignKey(
         Address,
@@ -28,6 +28,7 @@ class Contact(UserAndContactCommonInfo, TimeStampedModel):
         blank=True,
         on_delete=models.DO_NOTHING,
         related_name="contacts",
+        db_comment="The operator this contact belongs to. Foreign key to erc.operator",
     )
 
     history = HistoricalRecords(

bc_obps/registration/models/bc_obps_regulated_operation.py

@@ -22,7 +22,7 @@ class Document(TimeStampedModel, ScannedFileStorageMixin):
         DocumentType,
         on_delete=models.DO_NOTHING,
         related_name="documents",
-        db_comment="Type of document, e.g., boundary map",
+        db_comment="The type of this document (e.g. boundary map, process flow diagram). Foreign key to erc.document_type",
     )
     description = models.CharField(max_length=1000, blank=True, null=True, db_comment="Description of the document")
     operation = models.ForeignKey(
@@ -31,7 +31,7 @@ class Document(TimeStampedModel, ScannedFileStorageMixin):
         null=True,
         on_delete=models.DO_NOTHING,
         related_name="documents",
-        db_comment="The operation that the document is about",
+        db_comment="The operation this document is associated with. Foreign key to erc.operation",
     )
     history = HistoricalRecords(
         table_name='erc_history"."document_history',

bc_obps/registration/models/contact.py

@@ -17,7 +17,7 @@ class DocumentType(BaseModel):
     )
 
     class Meta:
-        db_table_comment = "Table that contains types of documents."
+        db_table_comment = "Lookup table containing valid document types that can be attached to operations (e.g. boundary map, process flow diagram, new entrant application, opt in signed statutory declaration). Documents are classified by type to allow the system to retrieve specific document kinds."
         db_table = f'{Schemas.ERC.value}"."{RegistrationTableNames.DOCUMENT_TYPE.value}'
 
     Rls = DocumentTypeRls

bc_obps/registration/models/document.py

@@ -5,8 +5,16 @@
 
 class EventBaseModel(TimeStampedModel):
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, db_comment="Primary key to identify the event")
-    effective_date = models.DateTimeField(db_comment="The effective date of the event")
-    operation = models.ForeignKey(Operation, null=True, blank=True, on_delete=models.PROTECT)
+    effective_date = models.DateTimeField(
+        db_comment="The date on which the closure, restart, shutdown, or transfer takes effect operationally"
+    )
+    operation = models.ForeignKey(
+        Operation,
+        null=True,
+        blank=True,
+        on_delete=models.PROTECT,
+        db_comment="The operation associated with this event. Foreign key to erc.operation",
+    )
     facilities = models.ManyToManyField(Facility, blank=True)
 
     class Meta(TimeStampedModel.Meta):

bc_obps/registration/models/document_type.py

@@ -17,42 +17,43 @@ class Statuses(models.TextChoices):
         max_length=100,
         choices=Statuses.choices,
         default=Statuses.TO_BE_TRANSFERRED,
+        db_comment="The status of the transfer event (e.g. To be transferred, Transferred, Complete)",
     )
     from_operator = models.ForeignKey(
         Operator,
         on_delete=models.PROTECT,
         related_name="transfer_events_from",
-        db_comment="The operator who is transferring the operation or facility.",
+        db_comment="The operator transferring the operation or facility to another operator. Foreign key to erc.operator",
     )
     to_operator = models.ForeignKey(
         Operator,
         on_delete=models.PROTECT,
         related_name="transfer_events_to",
-        db_comment="The operator who is receiving the operation or facility.",
+        db_comment="The operator receiving the operation or facility. Foreign key to erc.operator",
     )
     from_operation = models.ForeignKey(
         Operation,
         on_delete=models.PROTECT,
         null=True,
         blank=True,
         related_name="transfer_events_from",
-        db_comment="The operation that facilities are being transferred from.",
+        db_comment="The operation that facilities are being transferred away from (null if the entire operation is being transferred). Foreign key to erc.operation",
     )
     to_operation = models.ForeignKey(
         Operation,
         on_delete=models.PROTECT,
         null=True,
         blank=True,
         related_name="transfer_events_to",
-        db_comment="The operation that facilities are being transferred to.",
+        db_comment="The operation that facilities are being transferred into (null if no target operation yet exists). Foreign key to erc.operation",
     )
     history = HistoricalRecords(
         table_name='erc_history"."transfer_event_history',
         history_user_id_field=models.UUIDField(null=True, blank=True),
     )
 
     class Meta(EventBaseModel.Meta):
-        db_table_comment = "Transfer events for operations and/or facilities."
+        db_table_comment = "Records transfer events where ownership of operations or facilities moves from one operator to another. The from_operator and to_operator fields identify the parties involved. The facilities M2M field (inherited from EventBaseModel) lists which facilities are being transferred."
         db_table = f'{Schemas.ERC.value}"."{RegistrationTableNames.TRANSFER_EVENT.value}'
         default_related_name = "transfer_events"
 

bc_obps/registration/models/event/event_base_model.py

@@ -24,39 +24,43 @@ class Types(models.TextChoices):
     operation = models.ForeignKey(
         Operation,
         on_delete=models.PROTECT,
-        db_comment="The operation who currently owns the facility (see the FacilityDesignatedOperationTimeline for past and upcoming ownership)",
+        db_comment="The operation that currently owns this facility (historical ownership is tracked in erc.facility_designated_operation_timeline). Foreign key to erc.operation",
         related_name="facilities",
     )
     name = models.CharField(
         max_length=1000,
-        db_comment="The name of the facility when the operation owned it",
+        db_comment="The current name of the facility",
         unique=True,
     )
     is_current_year = models.BooleanField(
-        blank=True, null=True, db_comment="The facility's starting date is within the current year or preceeding year"
+        blank=True, null=True, db_comment="The facility's starting date is within the current year or preceding year"
     )
     starting_date = models.DateTimeField(
         blank=True, null=True, db_comment="The date of the facility starting operations"
     )
-    type = models.CharField(max_length=100, choices=Types.choices, db_comment="The type of the facility")
+    type = models.CharField(
+        max_length=100,
+        choices=Types.choices,
+        db_comment="The type of the facility. Valid values: Single Facility, Large Facility, Medium Facility, Small Aggregate, Electricity Import",
+    )
     address = models.ForeignKey(
         Address,
         on_delete=models.PROTECT,
-        db_comment="The address of the facility",
+        db_comment="The address of the facility. Foreign key to erc.address",
         blank=True,
         null=True,
         related_name='%(class)s_address',
     )
     swrs_facility_id = models.IntegerField(
-        db_comment="A facility's SWRS facility ID.",
+        db_comment="A facility's SWRS (Single Window Reporting System) facility ID. Only populated for facilities imported from the SWRS dataset.",
         blank=True,
         null=True,
     )
     bcghg_id = models.OneToOneField(
         "BcGreenhouseGasId",
         on_delete=models.PROTECT,
         max_length=1000,
-        db_comment="A facility's BCGHG identifier.",
+        db_comment="A facility's BCGHG (BC Greenhouse Gas) identifier. Foreign key to erc.bc_greenhouse_gas_id",
         blank=True,
         null=True,
     )
@@ -84,7 +88,7 @@ class Types(models.TextChoices):
     )
 
     class Meta(TimeStampedModel.Meta):
-        db_table_comment = "Contains data on facilities that emit carbon emissions and must report them to Clean Growth. A Linear Facilities Operation is made up of several different facilities whereas a Single Facility Operation has only one facility. In the case of a single facility operation, much of the data in this table will overlap with the parent record in the operation table."
+        db_table_comment = "Contains data on facilities that emit carbon emissions and must report them to Clean Growth. A facility is a distinct location or unit within an industrial operation. A Linear Facilities Operation (LFO) is made up of several different facilities whereas a Single Facility Operation (SFO) has only one facility. In the case of an SFO, much of the data in this table will overlap with the parent record in the operation table."
         db_table = f'{Schemas.ERC.value}"."{RegistrationTableNames.FACILITY.value}'
         verbose_name_plural = "Facilities"
         triggers = [