feat: implement geometry domain with repository, service, and data conversion utilities

db/query/geometries.sql

@@ -161,3 +161,23 @@ WHERE geometry_id = $1;
 -- name: DeleteEntityGeometry :exec
 DELETE FROM entity_geometries
 WHERE entity_id = $1 AND geometry_id = $2;
+
+-- name: GetEntityGeometriesByPairs :many
+SELECT
+    e.id AS entity_id,
+    e.name AS entity_name,
+    e.description AS entity_description,
+    g.id AS geometry_id,
+    g.geo_type,
+    g.draw_geometry,
+    g.binding,
+    g.time_start,
+    g.time_end
+FROM (
+    SELECT unnest(@entity_ids::uuid[]) as eid, unnest(@geometry_ids::uuid[]) as gid
+) as pairs
+JOIN entities e ON e.id = pairs.eid
+JOIN entity_geometries eg ON eg.entity_id = e.id AND eg.geometry_id = pairs.gid
+JOIN geometries g ON g.id = pairs.gid
+WHERE e.is_deleted = false
+AND g.is_deleted = false;

internal/dtos/request/geometry.go

@@ -11,9 +11,7 @@ type SearchGeometryDto struct {
 }
 
 type SearchGeometriesByEntityNameDto struct {
-	// Entity name keyword for searching. FE will render the result list by entity name.
 	Name string `json:"name" query:"name" validate:"required,max=255"`
-	// Cursor is entity UUID (id < cursor).
 	Cursor string `json:"cursor" query:"cursor" validate:"omitempty,uuid"`
 	Limit  int    `json:"limit" query:"limit" validate:"omitempty,min=1,max=100"`
 }

internal/dtos/response/geometryEntitySearch.go

@@ -2,8 +2,7 @@ package response
 
 import "encoding/json"
 
-// SearchGeometriesByEntityNameResponse groups geometries by matched entities.
+
-// Cursor pagination is based on entity_id (descending).
 type SearchGeometriesByEntityNameResponse struct {
 	Items      []*EntityGeometriesSearchItem `json:"items"`
 	NextCursor string                       `json:"next_cursor,omitempty"`

internal/gen/sqlc/geometries.sql.go

@@ -191,6 +191,74 @@ func (q *Queries) DeleteGeometry(ctx context.Context, id pgtype.UUID) error {
 	return err
 }
 
+const getEntityGeometriesByPairs = `-- name: GetEntityGeometriesByPairs :many
+SELECT
+    e.id AS entity_id,
+    e.name AS entity_name,
+    e.description AS entity_description,
+    g.id AS geometry_id,
+    g.geo_type,
+    g.draw_geometry,
+    g.binding,
+    g.time_start,
+    g.time_end
+FROM (
+    SELECT unnest($1::uuid[]) as eid, unnest($2::uuid[]) as gid
+) as pairs
+JOIN entities e ON e.id = pairs.eid
+JOIN entity_geometries eg ON eg.entity_id = e.id AND eg.geometry_id = pairs.gid
+JOIN geometries g ON g.id = pairs.gid
+WHERE e.is_deleted = false
+AND g.is_deleted = false
+`
+
+type GetEntityGeometriesByPairsParams struct {
+	EntityIds   []pgtype.UUID `json:"entity_ids"`
+	GeometryIds []pgtype.UUID `json:"geometry_ids"`
+}
+
+type GetEntityGeometriesByPairsRow struct {
+	EntityID          pgtype.UUID     `json:"entity_id"`
+	EntityName        string          `json:"entity_name"`
+	EntityDescription pgtype.Text     `json:"entity_description"`
+	GeometryID        pgtype.UUID     `json:"geometry_id"`
+	GeoType           int16           `json:"geo_type"`
+	DrawGeometry      json.RawMessage `json:"draw_geometry"`
+	Binding           []byte          `json:"binding"`
+	TimeStart         pgtype.Int4     `json:"time_start"`
+	TimeEnd           pgtype.Int4     `json:"time_end"`
+}
+
+func (q *Queries) GetEntityGeometriesByPairs(ctx context.Context, arg GetEntityGeometriesByPairsParams) ([]GetEntityGeometriesByPairsRow, error) {
+	rows, err := q.db.Query(ctx, getEntityGeometriesByPairs, arg.EntityIds, arg.GeometryIds)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []GetEntityGeometriesByPairsRow{}
+	for rows.Next() {
+		var i GetEntityGeometriesByPairsRow
+		if err := rows.Scan(
+			&i.EntityID,
+			&i.EntityName,
+			&i.EntityDescription,
+			&i.GeometryID,
+			&i.GeoType,
+			&i.DrawGeometry,
+			&i.Binding,
+			&i.TimeStart,
+			&i.TimeEnd,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const getGeometriesByIDs = `-- name: GetGeometriesByIDs :many
 SELECT 
     id, geo_type, draw_geometry, binding, time_start, time_end, project_id,
@@ -476,6 +544,86 @@ func (q *Queries) SearchGeometries(ctx context.Context, arg SearchGeometriesPara
 	return items, nil
 }
 
+const searchGeometriesByEntityName = `-- name: SearchGeometriesByEntityName :many
+WITH matched_entities AS (
+    SELECT
+        e.id,
+        e.name,
+        e.description
+    FROM entities e
+    WHERE e.is_deleted = false
+      AND ($1::text IS NULL OR e.name ILIKE '%' || $1::text || '%')
+      AND ($2::uuid IS NULL OR e.id < $2::uuid)
+    ORDER BY e.id DESC
+    LIMIT $3
+)
+SELECT
+    me.id AS entity_id,
+    me.name AS entity_name,
+    me.description AS entity_description,
+    g.id AS geometry_id,
+    g.geo_type,
+    g.draw_geometry,
+    g.binding,
+    g.time_start,
+    g.time_end
+FROM matched_entities me
+LEFT JOIN entity_geometries eg
+    ON eg.entity_id = me.id
+LEFT JOIN geometries g
+    ON g.id = eg.geometry_id
+   AND g.is_deleted = false
+ORDER BY me.id DESC, g.id DESC
+`
+
+type SearchGeometriesByEntityNameParams struct {
+	Name       pgtype.Text `json:"name"`
+	CursorID   pgtype.UUID `json:"cursor_id"`
+	LimitCount int32       `json:"limit_count"`
+}
+
+type SearchGeometriesByEntityNameRow struct {
+	EntityID          pgtype.UUID `json:"entity_id"`
+	EntityName        string      `json:"entity_name"`
+	EntityDescription pgtype.Text `json:"entity_description"`
+	GeometryID        pgtype.UUID `json:"geometry_id"`
+	GeoType           pgtype.Int2 `json:"geo_type"`
+	DrawGeometry      []byte      `json:"draw_geometry"`
+	Binding           []byte      `json:"binding"`
+	TimeStart         pgtype.Int4 `json:"time_start"`
+	TimeEnd           pgtype.Int4 `json:"time_end"`
+}
+
+func (q *Queries) SearchGeometriesByEntityName(ctx context.Context, arg SearchGeometriesByEntityNameParams) ([]SearchGeometriesByEntityNameRow, error) {
+	rows, err := q.db.Query(ctx, searchGeometriesByEntityName, arg.Name, arg.CursorID, arg.LimitCount)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []SearchGeometriesByEntityNameRow{}
+	for rows.Next() {
+		var i SearchGeometriesByEntityNameRow
+		if err := rows.Scan(
+			&i.EntityID,
+			&i.EntityName,
+			&i.EntityDescription,
+			&i.GeometryID,
+			&i.GeoType,
+			&i.DrawGeometry,
+			&i.Binding,
+			&i.TimeStart,
+			&i.TimeEnd,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const updateGeometry = `-- name: UpdateGeometry :one
 UPDATE geometries
 SET 

internal/models/geometry.go

@@ -20,6 +20,18 @@ type GeometryEntity struct {
 	UpdatedAt    *time.Time      `json:"updated_at"`
 }
 
+type EntityGeometriesSearchEntity struct {
+	EntityID          string          `json:"entity_id"`
+	EntityName        string          `json:"name"`
+	EntityDescription string          `json:"description"`
+	GeometryID        string          `json:"id"`
+	GeoType           int16           `json:"geo_type"`
+	DrawGeometry      json.RawMessage `json:"draw_geometry"`
+	Binding           json.RawMessage `json:"binding,omitempty"`
+	TimeStart         *int32          `json:"time_start,omitempty"`
+	TimeEnd           *int32          `json:"time_end,omitempty"`
+}
+
 func (g *GeometryEntity) ToResponse() *response.GeometryResponse {
 	if g == nil {
 		return nil

internal/repositories/geometryRepository.go

@@ -5,6 +5,7 @@ import (
 	"crypto/md5"
 	"encoding/json"
 	"fmt"
+	"strings"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgtype"
@@ -21,7 +22,7 @@ type GeometryRepository interface {
 	GetByID(ctx context.Context, id pgtype.UUID) (*models.GeometryEntity, error)
 	GetByIDs(ctx context.Context, ids []string) ([]*models.GeometryEntity, error)
 	Search(ctx context.Context, params sqlc.SearchGeometriesParams) ([]*models.GeometryEntity, error)
-	SearchByEntityName(ctx context.Context, name string, cursorID *pgtype.UUID, limit int32) ([]EntityGeometriesSearchRow, error)
+	SearchByEntityName(ctx context.Context, params sqlc.SearchGeometriesByEntityNameParams) ([]*models.EntityGeometriesSearchEntity, error)
 	Create(ctx context.Context, params sqlc.CreateGeometryParams) (*models.GeometryEntity, error)
 	Update(ctx context.Context, params sqlc.UpdateGeometryParams) (*models.GeometryEntity, error)
 	Delete(ctx context.Context, id pgtype.UUID) error
@@ -57,20 +58,6 @@ func (r *geometryRepository) WithTx(tx pgx.Tx) GeometryRepository {
 	}
 }
 
-// EntityGeometriesSearchRow is a "flattened" row shape for searching geometries by entity name.
-// FE will display entity list by entity_name, while still having geometries in the same response.
-type EntityGeometriesSearchRow struct {
-	EntityID          string          `json:"entity_id"`
-	EntityName        string          `json:"name"`
-	EntityDescription string          `json:"description"`
-	GeometryID        string          `json:"id"`
-	GeoType           int16           `json:"geo_type"`
-	DrawGeometry      json.RawMessage `json:"draw_geometry"`
-	Binding           json.RawMessage `json:"binding,omitempty"`
-	TimeStart         *int32          `json:"time_start,omitempty"`
-	TimeEnd           *int32          `json:"time_end,omitempty"`
-}
-
 func (r *geometryRepository) generateQueryKey(prefix string, params any) string {
 	b, _ := json.Marshal(params)
 	hash := fmt.Sprintf("%x", md5.Sum(b))
@@ -396,121 +383,124 @@ func (r *geometryRepository) DeleteEntityGeometry(ctx context.Context, entityID
 	})
 }
 
-func (r *geometryRepository) SearchByEntityName(
+func (r *geometryRepository) getSearchByIDsWithFallback(ctx context.Context, pairs []string) ([]*models.EntityGeometriesSearchEntity, error) {
-	ctx context.Context,
+	if len(pairs) == 0 {
-	name string,
+		return []*models.EntityGeometriesSearchEntity{}, nil
-	cursorID *pgtype.UUID,
+	}
-	limit int32,
+	keys := make([]string, len(pairs))
-) ([]EntityGeometriesSearchRow, error) {
+	for i, pair := range pairs {
-	// Cursor is entity_id (not geometry_id) so FE can render entities as the primary list.
+		keys[i] = fmt.Sprintf("geometry:search:item:%s", pair)
-	const q = `
+	}
-WITH matched_entities AS (
+	raws := r.c.MGet(ctx, keys...)
-    SELECT
-        e.id,
-        e.name,
-        e.description
-    FROM entities e
-    WHERE e.is_deleted = false
-      AND ($1::text = '' OR e.name ILIKE '%' || $1::text || '%')
-      AND ($2::uuid IS NULL OR e.id < $2::uuid)
-    ORDER BY e.id DESC
-    LIMIT $3
-)
-SELECT
-    me.id AS entity_id,
-    me.name AS entity_name,
-    COALESCE(me.description, '') AS entity_description,
-    g.id AS geometry_id,
-    g.geo_type,
-    g.draw_geometry,
-    g.binding,
-    g.time_start,
-    g.time_end
-FROM matched_entities me
-LEFT JOIN entity_geometries eg
-    ON eg.entity_id = me.id
-LEFT JOIN geometries g
-    ON g.id = eg.geometry_id
-   AND g.is_deleted = false
-ORDER BY me.id DESC, g.id DESC
-`
 
-	var cursor pgtype.UUID
+	var results []*models.EntityGeometriesSearchEntity
-	if cursorID != nil {
+	missingToCache := make(map[string]any)
-		cursor = *cursorID
+
-	} else {
+	var missingEntityIds []pgtype.UUID
-		cursor = pgtype.UUID{Valid: false}
+	var missingGeometryIds []pgtype.UUID
+
+	for i, b := range raws {
+		if len(b) == 0 {
+			parts := strings.Split(pairs[i], ":")
+			if len(parts) == 2 {
+				eID := pgtype.UUID{}
+				gID := pgtype.UUID{}
+				if err := eID.Scan(parts[0]); err == nil {
+					if err := gID.Scan(parts[1]); err == nil {
+						missingEntityIds = append(missingEntityIds, eID)
+						missingGeometryIds = append(missingGeometryIds, gID)
+					}
+				}
+			}
+		}
 	}
 
-	rows, err := r.db.Query(ctx, q, name, cursor, limit)
+	dbMap := make(map[string]*models.EntityGeometriesSearchEntity)
+	if len(missingEntityIds) > 0 {
+		dbRows, err := r.q.GetEntityGeometriesByPairs(ctx, sqlc.GetEntityGeometriesByPairsParams{
+			EntityIds:   missingEntityIds,
+			GeometryIds: missingGeometryIds,
+		})
+		if err == nil {
+			for _, row := range dbRows {
+				item := &models.EntityGeometriesSearchEntity{
+					EntityID:          convert.UUIDToString(row.EntityID),
+					EntityName:        row.EntityName,
+					EntityDescription: convert.TextToString(row.EntityDescription),
+					GeometryID:        convert.UUIDToString(row.GeometryID),
+					GeoType:           row.GeoType,
+					DrawGeometry:      row.DrawGeometry,
+					Binding:           row.Binding,
+					TimeStart:         convert.Int4ToPtr(row.TimeStart),
+					TimeEnd:           convert.Int4ToPtr(row.TimeEnd),
+				}
+				key := fmt.Sprintf("%s:%s", item.EntityID, item.GeometryID)
+				dbMap[key] = item
+			}
+		}
+	}
+
+	for i, b := range raws {
+		if len(b) > 0 {
+			var u models.EntityGeometriesSearchEntity
+			if err := json.Unmarshal(b, &u); err == nil {
+				results = append(results, &u)
+			}
+		} else {
+			if item, ok := dbMap[pairs[i]]; ok {
+				results = append(results, item)
+				missingToCache[keys[i]] = item
+			}
+		}
+	}
+
+	if len(missingToCache) > 0 {
+		_ = r.c.MSet(ctx, missingToCache, constants.NormalCacheDuration)
+	}
+
+	return results, nil
+}
+
+func (r *geometryRepository) SearchByEntityName(ctx context.Context, params sqlc.SearchGeometriesByEntityNameParams) ([]*models.EntityGeometriesSearchEntity, error) {
+
+	queryKey := r.generateQueryKey("geometry:search:entity", params)
+	var cachedPairs []string
+	if err := r.c.Get(ctx, queryKey, &cachedPairs); err == nil && len(cachedPairs) > 0 {
+		return r.getSearchByIDsWithFallback(ctx, cachedPairs)
+	}
+
+	rows, err := r.q.SearchGeometriesByEntityName(ctx, params)
 	if err != nil {
 		return nil, err
 	}
-	defer rows.Close()
+	var geometries []*models.EntityGeometriesSearchEntity
+	var pairs []string
+	geometryToCache := make(map[string]any)
 
-	out := make([]EntityGeometriesSearchRow, 0)
+	for _, row := range rows {
-	for rows.Next() {
+		item := &models.EntityGeometriesSearchEntity{
-		var entityID pgtype.UUID
+			EntityID:          convert.UUIDToString(row.EntityID),
-		var entityName pgtype.Text
+			EntityName:        row.EntityName,
-		var entityDesc pgtype.Text
+			EntityDescription: convert.TextToString(row.EntityDescription),
-		var geoID pgtype.UUID
+			GeometryID:        convert.UUIDToString(row.GeometryID),
-		var geoType pgtype.Int2
+			GeoType:           convert.Int2ToInt16(row.GeoType),
-		var draw json.RawMessage
+			DrawGeometry:      row.DrawGeometry,
-		var binding json.RawMessage
+			Binding:           row.Binding,
-		var timeStart pgtype.Int4
+			TimeStart:         convert.Int4ToPtr(row.TimeStart),
-		var timeEnd pgtype.Int4
+			TimeEnd:           convert.Int4ToPtr(row.TimeEnd),
-
+		}
-		if err := rows.Scan(
+		pair := fmt.Sprintf("%s:%s", item.EntityID, item.GeometryID)
-			&entityID,
+		geometries = append(geometries, item)
-			&entityName,
+		pairs = append(pairs, pair)
-			&entityDesc,
+		geometryToCache[fmt.Sprintf("geometry:search:item:%s", pair)] = item
-			&geoID,
-			&geoType,
-			&draw,
-			&binding,
-			&timeStart,
-			&timeEnd,
-		); err != nil {
-			return nil, err
 	}
 
-		var ts *int32
+	if len(geometryToCache) > 0 {
-		if timeStart.Valid {
+		_ = r.c.MSet(ctx, geometryToCache, constants.NormalCacheDuration)
-			v := timeStart.Int32
-			ts = &v
 	}
-		var te *int32
+	if len(pairs) > 0 {
-		if timeEnd.Valid {
+		_ = r.c.Set(ctx, queryKey, pairs, constants.ListCacheDuration)
-			v := timeEnd.Int32
-			te = &v
 	}
 
-		row := EntityGeometriesSearchRow{
+	return geometries, nil
-			EntityID:          convert.UUIDToString(entityID),
-			EntityName:        entityName.String,
-			EntityDescription: entityDesc.String,
-			GeometryID:        convert.UUIDToString(geoID),
-			GeoType:           geoType.Int16,
-			DrawGeometry:      draw,
-			Binding:           binding,
-			TimeStart:         ts,
-			TimeEnd:           te,
-		}
-
-		// Entity with no geometry will have NULL geometry_id.
-		if !geoID.Valid {
-			row.GeometryID = ""
-			row.GeoType = 0
-			row.DrawGeometry = nil
-			row.Binding = nil
-			row.TimeStart = nil
-			row.TimeEnd = nil
-		}
-
-		out = append(out, row)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return out, nil
 }

internal/services/geometryService.go

@@ -86,16 +86,20 @@ func (s *geometryService) SearchGeometriesByEntityName(
 		limit = 20
 	}
 
-	var cursorID *pgtype.UUID
+	var cursorID pgtype.UUID
 	if req.Cursor != "" {
 		id, err := convert.StringToUUID(req.Cursor)
 		if err != nil {
 			return nil, fiber.NewError(fiber.StatusBadRequest, "Invalid cursor format")
 		}
-		cursorID = &id
+		cursorID = id
 	}
 
-	rows, err := s.geometryRepo.SearchByEntityName(ctx, req.Name, cursorID, limit)
+	rows, err := s.geometryRepo.SearchByEntityName(ctx, sqlc.SearchGeometriesByEntityNameParams{
+		Name:       convert.StringToText(req.Name),
+		CursorID:   cursorID,
+		LimitCount: limit,
+	})
 	if err != nil {
 		return nil, fiber.NewError(fiber.StatusInternalServerError, "Failed to search geometries by entity name")
 	}
@@ -116,7 +120,6 @@ func (s *geometryService) SearchGeometriesByEntityName(
 			order = append(order, row.EntityID)
 		}
 
-		// LEFT JOIN: entity might have no geometry.
 		if row.GeometryID == "" || len(row.DrawGeometry) == 0 {
 			continue
 		}
@@ -138,7 +141,6 @@ func (s *geometryService) SearchGeometriesByEntityName(
 
 	nextCursor := ""
 	if len(order) > 0 {
-		// Use last entity id in the current page as the cursor for the next page (id < cursor).
 		nextCursor = order[len(order)-1]
 	}
 

pkg/convert/convert.go

@@ -143,6 +143,13 @@ func Int2ToInt16Ptr(v pgtype.Int2) *int16 {
 	return &int16Val
 }
 
+func Int2ToInt16(v pgtype.Int2) int16 {
+	if v.Valid {
+		return v.Int16
+	}
+	return 0
+}
+
 func PtrFloat64ToInt4(v *float64) pgtype.Int4 {
 	if v == nil {
 		return pgtype.Int4{Valid: false}