NHSDigital
diff --git a/‎src/eligibility_signposting_api/model/campaign_config.py‎
Lines changed: 85 additions & 33 deletions b/‎src/eligibility_signposting_api/model/campaign_config.py‎
Lines changed: 85 additions & 33 deletions
diff --git a/‎src/eligibility_signposting_api/services/processors/campaign_evaluator.py‎
Lines changed: 6 additions & 4 deletions b/‎src/eligibility_signposting_api/services/processors/campaign_evaluator.py‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎src/rules_validation_api/app.py‎
Lines changed: 55 additions & 11 deletions b/‎src/rules_validation_api/app.py‎
Lines changed: 55 additions & 11 deletions
diff --git a/‎src/rules_validation_api/validators/campaign_config_validator.py‎
Lines changed: 9 additions & 0 deletions b/‎src/rules_validation_api/validators/campaign_config_validator.py‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎tests/fixtures/builders/model/rule.py‎
Lines changed: 4 additions & 1 deletion b/‎tests/fixtures/builders/model/rule.py‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎tests/integration/in_process/test_eligibility_endpoint.py‎
Lines changed: 4 additions & 5 deletions b/‎tests/integration/in_process/test_eligibility_endpoint.py‎
Lines changed: 4 additions & 5 deletions
@@ -4,7 +4,7 @@
 import re
 import typing
 from collections import Counter
-from datetime import UTC, date, datetime
+from datetime import UTC, date, datetime, time
 from enum import StrEnum
 from functools import cached_property
 from operator import attrgetter
@@ -33,6 +33,7 @@
 IterationVersion = NewType("IterationVersion", int)
 IterationID = NewType("IterationID", str)
 IterationDate = NewType("IterationDate", date)
+IterationTime = NewType("IterationTime", time)
 RuleName = NewType("RuleName", str)
 RuleDescription = NewType("RuleDescription", str)
 RulePriority = NewType("RulePriority", int)
@@ -50,6 +51,38 @@
 RuleText = NewType("RuleText", str)
 
 
+class DateUtil:
+    @staticmethod
+    def parse_date_yyyymmdd(v: str | date) -> date:
+        if isinstance(v, date):
+            return v
+        v_str = str(v)
+        if not re.fullmatch(r"\d{8}", v_str):
+            msg = f"Invalid format: {v_str}. Must be YYYYMMDD."
+            raise ValueError(msg)
+        try:
+            return datetime.strptime(v_str, "%Y%m%d").date()  # noqa: DTZ007
+        except ValueError as err:
+            msg = f"Invalid date value: {v_str}."
+            raise ValueError(msg) from err
+
+    @staticmethod
+    def parse_time_hhmmss(v: str | time | None) -> time | None:
+        if not v:
+            return None
+        if isinstance(v, time):
+            return v
+        v_str = str(v).strip()
+        if re.fullmatch(r"^\d{2}:\d{2}:\d{2}$", v_str):
+            try:
+                return datetime.strptime(v_str, "%H:%M:%S").time()  # noqa: DTZ007
+            except ValueError as err:
+                msg = f"Invalid time value: {v_str}."
+                raise ValueError(msg) from err
+        msg = f"Invalid format: {v_str}. Must be HH:MM:SS."
+        raise ValueError(msg)
+
+
 class RuleType(StrEnum):
     filter = "F"
     suppression = "S"
@@ -262,6 +295,7 @@ class Iteration(BaseModel):
     version: IterationVersion = Field(..., alias="Version")
     name: IterationName = Field(..., alias="Name")
     iteration_date: IterationDate = Field(..., alias="IterationDate")
+    iteration_time: IterationTime | None = Field(default=None, alias="IterationTime")
     iteration_number: int | None = Field(None, alias="IterationNumber")
     approval_minimum: int | None = Field(None, alias="ApprovalMinimum")
     approval_maximum: int | None = Field(None, alias="ApprovalMaximum")
@@ -277,35 +311,49 @@ class Iteration(BaseModel):
 
     model_config = {"populate_by_name": True, "arbitrary_types_allowed": True, "extra": "ignore"}
 
-    def __init__(self, **data: dict[str, typing.Any]) -> None:
-        super().__init__(**data)
-        # Ensure each rule knows its parent iteration
-        for rule in self.iteration_rules:
-            rule.set_parent(self)
+    @model_validator(mode="after")
+    def _link_parent_to_iteration_rules(self) -> typing.Self:
+        for iteration in self.iteration_rules:
+            iteration.set_parent(self)
+        return self
 
     @field_validator("iteration_date", mode="before")
     @classmethod
     def parse_dates(cls, v: str | date) -> date:
-        if isinstance(v, date):
-            return v
-
-        v_str = str(v)
+        return DateUtil.parse_date_yyyymmdd(v)
 
-        if not re.fullmatch(r"\d{8}", v_str):
-            msg = f"Invalid format: {v_str}. Must be YYYYMMDD with 8 digits."
-            raise ValueError(msg)
-
-        try:
-            return datetime.strptime(v_str, "%Y%m%d").date()  # noqa: DTZ007
-        except ValueError as err:
-            msg = f"Invalid date value: {v_str}. Must be a valid calendar date in YYYYMMDD format."
-            raise ValueError(msg) from err
+    @field_validator("iteration_time", mode="before")
+    @classmethod
+    def parse_times(cls, v: str | time) -> time | None:
+        return DateUtil.parse_time_hhmmss(v)
 
     @field_serializer("iteration_date", when_used="always")
     @staticmethod
     def serialize_dates(v: date, _info: SerializationInfo) -> str:
         return v.strftime("%Y%m%d")
 
+    @field_serializer("iteration_time", when_used="always")
+    @staticmethod
+    def serialize_time(v: time, _info: SerializationInfo) -> str | None:
+        return v.strftime("%H:%M:%S") if v else None
+
+    _parent: CampaignConfig | None = PrivateAttr(default=None)
+
+    def set_parent(self, parent: CampaignConfig) -> None:
+        self._parent = parent
+
+    @cached_property
+    def iteration_datetime(self) -> datetime:
+        if self.iteration_time:
+            iteration_time = self.iteration_time
+        elif self._parent:
+            iteration_time = self._parent.iteration_time
+        else:
+            msg = f"No iteration_time and no parent linked for iteration {self.id}"
+            raise ValueError(msg)
+
+        return datetime.combine(self.iteration_date, iteration_time).replace(tzinfo=UTC)
+
     def __str__(self) -> str:
         return json.dumps(self.model_dump(by_alias=True), indent=2)
 
@@ -321,7 +369,7 @@ class CampaignConfig(BaseModel):
     reviewer: list[str] | None = Field(None, alias="Reviewer")
     iteration_frequency: Literal["X", "D", "W", "M", "Q", "A"] = Field(..., alias="IterationFrequency")
     iteration_type: Literal["A", "M", "S", "O"] = Field(..., alias="IterationType")
-    iteration_time: str | None = Field(None, alias="IterationTime")
+    iteration_time: IterationTime = Field(default=IterationTime(time(0, 0, 0)), alias="IterationTime")
     default_comms_routing: str | None = Field(None, alias="DefaultCommsRouting")
     start_date: StartDate = Field(..., alias="StartDate")
     end_date: EndDate = Field(..., alias="EndDate")
@@ -331,29 +379,33 @@ class CampaignConfig(BaseModel):
 
     model_config = {"populate_by_name": True, "arbitrary_types_allowed": True, "extra": "ignore"}
 
+    @model_validator(mode="after")
+    def _link_parent_to_iterations(self) -> typing.Self:
+        for iteration in self.iterations:
+            iteration.set_parent(self)
+
+        return self
+
     @field_validator("start_date", "end_date", mode="before")
     @classmethod
     def parse_dates(cls, v: str | date) -> date:
-        if isinstance(v, date):
-            return v
-
-        v_str = str(v)
-
-        if not re.fullmatch(r"\d{8}", v_str):
-            msg = f"Invalid format: {v_str}. Must be YYYYMMDD with 8 digits."
-            raise ValueError(msg)
+        return DateUtil.parse_date_yyyymmdd(v)
 
-        try:
-            return datetime.strptime(v_str, "%Y%m%d").date()  # noqa: DTZ007
-        except ValueError as err:
-            msg = f"Invalid date value: {v_str}. Must be a valid calendar date in YYYYMMDD format."
-            raise ValueError(msg) from err
+    @field_validator("iteration_time", mode="before")
+    @classmethod
+    def parse_times(cls, v: str | time) -> time | None:
+        return DateUtil.parse_time_hhmmss(v)
 
     @field_serializer("start_date", "end_date", when_used="always")
     @staticmethod
     def serialize_dates(v: date, _info: SerializationInfo) -> str:
         return v.strftime("%Y%m%d")
 
+    @field_serializer("iteration_time", when_used="always")
+    @staticmethod
+    def serialize_time(v: time, _info: SerializationInfo) -> str | None:
+        return v.strftime("%H:%M:%S") if v else None
+
     @model_validator(mode="after")
     def check_start_and_end_dates_sensible(self) -> typing.Self:
         if self.start_date > self.end_date:
 
@@ -31,7 +31,7 @@ def get_campaign_with_latest_iteration(self, active_campaigns: list[CampaignConf
 
         for cc in active_campaigns:
             try:
-                valid_items.append((cc.current_iteration.iteration_date, cc))
+                valid_items.append((cc.current_iteration.iteration_datetime, cc))
             except StopIteration:
                 logger.info(
                     "Skipping campaign ID %s as no active iteration was found.",
@@ -41,13 +41,15 @@ def get_campaign_with_latest_iteration(self, active_campaigns: list[CampaignConf
         if not valid_items:
             latest_campaign = None
         else:
-            max_date = max(item[0] for item in valid_items)
-            cc_with_max_iteration_date: list[CampaignConfig] = [item[1] for item in valid_items if item[0] == max_date]
+            max_date_time = max(item[0] for item in valid_items)
+            cc_with_max_iteration_date: list[CampaignConfig] = [
+                item[1] for item in valid_items if item[0] == max_date_time
+            ]
             if len(cc_with_max_iteration_date) > 1:
                 err_msg = (
                     f"Ambiguous result: '{len(cc_with_max_iteration_date)}' active iterations "
                     f"for target {cc_with_max_iteration_date[0].target} "
-                    f"found for date '{max_date}' "
+                    f"found for datetime '{max_date_time}' "
                     f"across campaign(s) {[cc.id for cc in cc_with_max_iteration_date]}"
                 )
                 raise ValueError(err_msg)
 
@@ -3,6 +3,8 @@
 import logging
 import sys
 from collections import defaultdict
+from datetime import UTC, datetime
+from operator import attrgetter
 from pathlib import Path
 
 from pydantic import ValidationError
@@ -74,18 +76,60 @@ def main() -> None:  # pragma: no cover
 
 
 def display_current_iteration(result: RulesValidation) -> None:
-    no_of_iterations = 0
-    try:
-        no_of_iterations = len(result.campaign_config.iterations)
-        current = result.campaign_config.current_iteration
-    except StopIteration:
-        current = None
-    if current is None:
-        sys.stdout.write(f"{YELLOW}No active iteration could be determined{RESET}\n")
-        sys.stdout.write(f"{YELLOW}Total iterations configured: {RESET}{GREEN}{no_of_iterations}{RESET}\n")
+    config = result.campaign_config
+    iterations = config.iterations
+    is_campaign_live = config.campaign_live
+    today = datetime.now(tz=UTC).date()
+
+    no_of_iterations = len(iterations)
+    is_campaign_expired = config.end_date < today
+
+    # ---- Current Iteration ----
+    if is_campaign_live:
+        sys.stdout.write(f"{YELLOW}Campaign is {RESET}{GREEN}LIVE{RESET}\n")
+        try:
+            current = config.current_iteration
+            if current:
+                sys.stdout.write(
+                    f"{YELLOW}Current active Iteration Number: {RESET}{GREEN}{current.iteration_number}{RESET}\n"
+                )
+                tz = current.iteration_datetime.tzinfo
+                sys.stdout.write(
+                    f"{YELLOW}Current active Iteration's date&time: "
+                    f"{RESET}{GREEN}{current.iteration_datetime} ({tz}){RESET}\n"
+                )
+        except StopIteration:
+            sys.stdout.write(f"{YELLOW}No active iteration could be determined{RESET}\n")
+
     else:
-        sys.stdout.write(f"{YELLOW}Current Iteration Number: {RESET}{GREEN}{current.iteration_number}{RESET}\n")
-        sys.stdout.write(f"{YELLOW}Total iterations configured: {RESET}{GREEN}{no_of_iterations}{RESET}\n")
+        sys.stdout.write(f"{YELLOW}Campaign is {RESET}{GREEN}NOT LIVE{RESET} ")
+
+        if is_campaign_expired:
+            sys.stdout.write(f"{YELLOW}[EXPIRED on {config.end_date}]{RESET}\n")
+        else:
+            sys.stdout.write(f"{YELLOW}[To be STARTED on {RESET}{GREEN}{config.start_date}{RESET}{YELLOW}]{RESET}\n")
+
+    # ---- Next Iteration ----
+    if not is_campaign_expired:
+        sorted_iterations = sorted(iterations, key=attrgetter("iteration_date"))
+
+        try:
+            next_iteration = next((i for i in sorted_iterations if i.iteration_date > today), None)
+
+            if next_iteration:
+                sys.stdout.write(
+                    f"{YELLOW}Next active Iteration Number: {RESET}{GREEN}{next_iteration.iteration_number}{RESET}\n"
+                )
+                tz = next_iteration.iteration_datetime.tzinfo
+                sys.stdout.write(
+                    f"{YELLOW}Next active Iteration's date&time: "
+                    f"{RESET}{GREEN}{next_iteration.iteration_datetime} ({tz}){RESET}\n"
+                )
+        except StopIteration:
+            sys.stdout.write(f"{YELLOW}No next active iteration could be determined{RESET}\n")
+
+    # ---- Total Iterations ----
+    sys.stdout.write(f"{YELLOW}Total iterations configured: {RESET}{GREEN}{no_of_iterations}{RESET}\n")
 
 
 if __name__ == "__main__":  # pragma: no cover
 
@@ -34,6 +34,15 @@ def validate_iterations_have_unique_id(self) -> typing.Self:
             raise ValueError(msg)
         return self
 
+    @model_validator(mode="after")
+    def validate_iterations_have_unique_number(self) -> typing.Self:
+        numbers = [iteration.iteration_number for iteration in self.iterations]
+        duplicates = {i_id for i_id, count in Counter(numbers).items() if count > 1}
+        if duplicates:
+            msg = f"Iterations contain duplicate numbers: {', '.join(str(i) for i in duplicates)}"
+            raise ValueError(msg)
+        return self
+
     @model_validator(mode="after")
     def validate_campaign_has_iteration_within_schedule(self) -> typing.Self:
         errors: list[str] = []
 
@@ -1,4 +1,4 @@
-from datetime import UTC, date, datetime, timedelta
+from datetime import UTC, date, datetime, time, timedelta
 from operator import attrgetter
 from random import randint
 
@@ -16,6 +16,7 @@
     Iteration,
     IterationCohort,
     IterationRule,
+    IterationTime,
     RuleAttributeLevel,
     RuleAttributeName,
     RuleComparator,
@@ -89,13 +90,15 @@ class IterationFactory(ModelFactory[Iteration]):
     default_comms_routing = "defaultcomms"
     actions_mapper = Use(ActionsMapperFactory.build)
     rules_mapper = None
+    iteration_time = None
 
 
 class RawCampaignConfigFactory(ModelFactory[CampaignConfig]):
     iterations = Use(IterationFactory.batch, size=2)
     id = "42-hi5tch-hi5kers-gu5ide-t2o-t3he-gal6axy"
     start_date = Use(past_date)
     end_date = Use(future_date)
+    iteration_time = IterationTime(time(0, 0, 0))
 
 
 class CampaignConfigFactory(RawCampaignConfigFactory):
 
@@ -33,15 +33,15 @@
 from tests.integration.conftest import UNIQUE_CONSUMER_HEADER
 
 
-def today():
+def today() -> date:
     return datetime.now(UTC).date()
 
 
-def yesterday():
+def yesterday() -> date:
     return datetime.now(UTC).date() - timedelta(days=1)
 
 
-def tomorrow():
+def tomorrow() -> date:
     return datetime.now(UTC).date() + timedelta(days=1)
 
 
@@ -1532,11 +1532,10 @@ def test_if_multiple_active_iterations_with_same_iteration_datetime_for_the_same
                 )
             ),
         )
-
         err_msg = (
             "Ambiguous result: '2' active iterations "
             "for target RSV "
-            f"found for date '{previous_day}' "
+            f"found for datetime '{previous_day} 00:00:00+00:00' "
             "across campaign(s) ['RSV_campaign_id_1', 'RSV_campaign_id_2']"
         )
         assert any(err_msg in message for message in caplog.messages), (