feat(admin-brand): add question expansion service and related functionality

- Implemented QuestionExpansionService for generating and materializing questions based on combinations and AI distillation.
- Added question metadata classification logic to infer intent and layer of questions.
- Created API handlers for question expansion operations including combination preview, AI distillation, metadata classification, and materialization.
- Introduced database migrations to support new question-related fields and constraints in brand_questions and brand_keywords tables.
- Added caching mechanism for AI distillation results to improve performance.
- Defined JSON schemas for question distillation responses to ensure data integrity.

server/internal/tenant/transport/question_expansion_handler.go

@@ -0,0 +1,102 @@
+package transport
+
+import (
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/geo-platform/tenant-api/internal/bootstrap"
+	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/tenant/app"
+)
+
+type QuestionExpansionHandler struct {
+	svc *app.QuestionExpansionService
+}
+
+func NewQuestionExpansionHandler(a *bootstrap.App) *QuestionExpansionHandler {
+	return &QuestionExpansionHandler{svc: a.QuestionExpansion}
+}
+
+func (h *QuestionExpansionHandler) CombinationPreview(c *gin.Context) {
+	brandID, ok := parseBrandIDParam(c)
+	if !ok {
+		return
+	}
+	var req app.QuestionCombinationRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+	data, err := h.svc.GenerateByCombination(c.Request.Context(), brandID, req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *QuestionExpansionHandler) AIDistill(c *gin.Context) {
+	brandID, ok := parseBrandIDParam(c)
+	if !ok {
+		return
+	}
+	var req app.QuestionDistillRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+	data, err := h.svc.GenerateByAIDistill(c.Request.Context(), brandID, req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *QuestionExpansionHandler) ClassifyMetadata(c *gin.Context) {
+	brandID, ok := parseBrandIDParam(c)
+	if !ok {
+		return
+	}
+	var req struct {
+		Texts []string `json:"texts" binding:"required,min=1"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+	data, err := h.svc.ClassifyMetadata(c.Request.Context(), brandID, req.Texts)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *QuestionExpansionHandler) Materialize(c *gin.Context) {
+	brandID, ok := parseBrandIDParam(c)
+	if !ok {
+		return
+	}
+	var req app.MaterializeQuestionsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+	data, err := h.svc.MaterializeQuestions(c.Request.Context(), brandID, req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseBrandIDParam(c *gin.Context) (int64, bool) {
+	brandID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || brandID <= 0 {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_id", "brand id must be a number"))
+		return 0, false
+	}
+	return brandID, true
+}

server/internal/tenant/transport/router.go

@@ -176,6 +176,7 @@ func RegisterRoutes(app *bootstrap.App) {
 
 	brands := tenantProtected.Group("/brands")
 	brandHandler := NewBrandHandler(app)
+	questionExpansionHandler := NewQuestionExpansionHandler(app)
 	brands.GET("", brandHandler.List)
 	brands.GET("/library-summary", brandHandler.Summary)
 	brands.POST("", brandHandler.Create)
@@ -188,6 +189,10 @@ func RegisterRoutes(app *bootstrap.App) {
 	brands.DELETE("/:id/keywords/:kid", brandHandler.DeleteKeyword)
 	brands.GET("/:id/questions", brandHandler.ListQuestions)
 	brands.POST("/:id/questions", brandHandler.CreateQuestion)
+	brands.POST("/:id/questions/combination-preview", questionExpansionHandler.CombinationPreview)
+	brands.POST("/:id/questions/ai-distill", questionExpansionHandler.AIDistill)
+	brands.POST("/:id/questions/classify-metadata", questionExpansionHandler.ClassifyMetadata)
+	brands.POST("/:id/questions/materialize", questionExpansionHandler.Materialize)
 	brands.PUT("/:id/questions/:qid", brandHandler.UpdateQuestion)
 	brands.DELETE("/:id/questions/:qid", brandHandler.DeleteQuestion)
 	brands.GET("/:id/competitors", brandHandler.ListCompetitors)