Add employment details to officer search results

WIP

Author: DMalone87

backend/database/models/officer.py

@@ -176,7 +176,9 @@ def search(
         name: str | None = None,
         rank: str | None = None,
         unit: list[str] | None = None,
+        unit_uid: str | None = None,
         agency: list[str] | None = None,
+        agency_uid: str | None = None,
         badge_number: list[str] | None = None,
         ethnicity: list[str] | None = None,
         active_after: date | None = None,
@@ -215,10 +217,10 @@ def search(
 
         match_clauses.append("MATCH (o:Officer)")
 
-        if unit or active_after or active_before or badge_number or agency:
+        if unit or unit_uid or active_after or active_before or badge_number or agency:
             match_clauses.append("MATCH (o)-[]-(e:Employment)-[]-(u:Unit)")
 
-        if agency:
+        if agency or agency_uid:
             match_clauses.append("MATCH (u)-[:ESTABLISHED_BY]->(a:Agency)")
 
         # Build WHERE clauses and params
@@ -237,6 +239,10 @@ def search(
             where_clauses.append("ANY(n IN $agency WHERE a.name CONTAINS n)")
             params["agency"] = agency
 
+        if agency_uid:
+            where_clauses.append("a.uid = $agency_uid")
+            params["agency_uid"] = agency_uid
+
         if badge_number:
             where_clauses.append(
                 "ANY(n IN $badge_number WHERE e.badge_number CONTAINS n)")
@@ -249,6 +255,10 @@ def search(
         if unit:
             where_clauses.append("ANY(n IN $unit WHERE u.name CONTAINS n)")
             params["unit"] = unit
+        
+        if unit_uid:
+            where_clauses.append("u.uid = $unit_uid")
+            params["unit_uid"] = unit_uid
 
         # Combine query
         match_str = "\n".join(match_clauses)
@@ -275,3 +285,68 @@ def search(
             rows, _ = db.cypher_query(cypher_query, params,
                                       resolve_objects=inflate)
             return [row[0] for row in rows]
+
+    @classmethod
+    def include_employment(
+        cls,
+        uids: list[str],
+        unit_uid: str | None = None,
+        agency_uid: str | None = None,
+    ):
+        """
+        Include employment details for a list of officers.
+
+        Coalesces employment at the agency level:
+        - earliest_date / latest_date come from all matching employments
+        for the officer at that agency
+        - other values come from the most recent matching employment
+        """
+
+        cy = """
+        UNWIND $uids AS officer_uid
+        MATCH (o:Officer {uid: officer_uid})-[:HELD_BY]-(e:Employment)-[:IN_UNIT]-(u:Unit)-[:ESTABLISHED_BY]-(a:Agency)
+        WHERE ($unit_uid IS NULL OR u.uid = $unit_uid)
+        AND ($agency_uid IS NULL OR a.uid = $agency_uid)
+
+        WITH o, a, u, e
+        ORDER BY coalesce(e.latest_date, e.earliest_date) DESC
+
+        WITH
+            o,
+            a,
+            head(collect({e: e, u: u})) AS rep,
+            min(e.earliest_date) AS earliest_date,
+            max(e.latest_date) AS latest_date
+
+        RETURN
+            o.uid AS officer_uid,
+            {
+                agency_uid: a.uid,
+                agency_name: a.name,
+                state: a.hq_state,
+                unit_uid: rep.u.uid,
+                unit_name: rep.u.name,
+                badge_number: rep.e.badge_number,
+                highest_rank: rep.e.highest_rank,
+                salary: rep.e.salary,
+                earliest_date: earliest_date,
+                latest_date: latest_date
+            } AS item
+        """
+        logging.warning("Cypher query for employment:\n%s", cy)
+
+        params = {
+            "uids": uids,
+            "unit_uid": unit_uid,
+            "agency_uid": agency_uid,
+        }
+
+        results, _ = db.cypher_query(cy, params)
+
+        employment_map: dict[str, list[dict]] = {}
+        for row in results:
+            officer_uid = row[0]
+            item = row[1]
+            employment_map.setdefault(officer_uid, []).append(item)
+
+        return employment_map

backend/dto/officer.py

@@ -16,6 +16,8 @@ class OfficerSearchParams(PaginatedRequest):
     middle_name: Optional[str] = None
     last_name: Optional[str] = None
     suffix: Optional[str] = None
+    unit_uid: Optional[str] = None
+    agency_uid: Optional[str] = None
 
     # Other filters
     rank: List[str] = []
@@ -26,6 +28,25 @@ class OfficerSearchParams(PaginatedRequest):
     badge_number: List[str] = Field([], alias="badge_number")
     ethnicity: List[str] = []
 
+    # Include params
+    include: Optional[List[str]] = Field(
+        None, description="Related entities to include in the response."
+    )
+
+    @field_validator("include")
+    def validate_include(cls, v):
+        allowed_includes = {
+            "employment"
+        }
+        if v:
+            invalid = set(v) - allowed_includes
+            if invalid:
+                raise ValueError(
+                    f"Invalid include parameters: {', '.join(invalid)}")
+        return v
+
+
+
     # Derived fields (computed below)
     @field_validator("unit", mode="before")
     def ensure_list(cls, v):

backend/routes/officers.py

@@ -457,6 +457,7 @@ def get_all_officers():
         "rank": request.args.getlist("rank"),
         "badge_number": request.args.getlist("badge_number"),
         "ethnicity": request.args.getlist("ethnicity"),
+        "include": request.args.getlist("include"),
     }
     try:
         params = OfficerSearchParams(**raw)
@@ -487,7 +488,9 @@ def get_all_officers():
         name=params.officer_name,
         rank=params.officer_rank,
         unit=params.unit,
+        unit_uid=params.unit_uid,
         agency=params.agency,
+        agency_uid=params.agency_uid,
         badge_number=params.badge_number,
         ethnicity=params.ethnicity,
         active_after=params.active_after,
@@ -506,6 +509,23 @@ def get_all_officers():
         page = [item.model_dump() for item in all_officers if item]
         return_func = jsonify
     else:
+      if params.include:
+          if "employment" in params.include:
+              employment_map = Officer.include_employment(
+                uids = [row.get("uid") for row in results],
+                unit_uid = params.unit_uid if params.unit_uid else None,
+                agency_uid = params.agency_uid if params.agency_uid else None, 
+              )
+              logging.warning("Employment map: %s", employment_map)
+          # build page
+          page = []
+          for row in results:
+            item = {
+                **row.to_dict(),
+                "employment_history": employment_map.get(row.get("uid"), [])
+            }
+            page.append(item)
+      else:      
         page = [row.to_dict() for row in results]
         return_func = ordered_jsonify
     # logging.warning('response is --------------------------------\n%s', page)