Add monitoring service and database schema

- Implement monitoring service with heartbeat, lease tasks, resume tasks, and task result handling. - Create monitoring time utilities for business date calculations. - Add unit tests for date window resolution and business day handling. - Define database schema for monitoring-related tables including quotas, daily reports, and task management. - Establish migration scripts for creating and dropping monitoring tables.
2026-04-12 09:56:18 +08:00
parent 9b4dd09780
commit 6066f43a7d
67 changed files with 16312 additions and 125 deletions
@@ -15,7 +15,7 @@ type BrandHandler struct {
 }

 func NewBrandHandler(a *bootstrap.App) *BrandHandler {
-	return &BrandHandler{svc: app.NewBrandService(a.DB, a.AuditLogs)}
+	return &BrandHandler{svc: app.NewBrandService(a.DB, a.MonitoringDB, a.AuditLogs)}
 }

 func (h *BrandHandler) List(c *gin.Context) {
@@ -0,0 +1,162 @@
+package transport
+
+import (
+	"errors"
+	"io"
+	"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 MonitoringCallbackHandler struct {
+	svc *app.MonitoringCallbackService
+}
+
+func NewMonitoringCallbackHandler(a *bootstrap.App) *MonitoringCallbackHandler {
+	return &MonitoringCallbackHandler{
+		svc: app.NewMonitoringCallbackService(a.DB, a.MonitoringDB, a.RabbitMQ, a.LLM, a.Logger),
+	}
+}
+
+func (h *MonitoringCallbackHandler) Heartbeat(c *gin.Context) {
+	installationID, installationToken, ok := parseMonitoringInstallationHeaders(c)
+	if !ok {
+		return
+	}
+
+	var req app.MonitoringHeartbeatRequest
+	if err := bindOptionalJSON(c, &req); err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_params", err.Error()))
+		return
+	}
+
+	data, svcErr := h.svc.Heartbeat(c.Request.Context(), installationID, installationToken, req)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringCallbackHandler) LeaseTasks(c *gin.Context) {
+	installationID, installationToken, ok := parseMonitoringInstallationHeaders(c)
+	if !ok {
+		return
+	}
+
+	var req app.MonitoringLeaseTasksRequest
+	if err := bindOptionalJSON(c, &req); err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_params", err.Error()))
+		return
+	}
+
+	data, svcErr := h.svc.LeaseTasks(c.Request.Context(), installationID, installationToken, req)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringCallbackHandler) ResumeTasks(c *gin.Context) {
+	installationID, installationToken, ok := parseMonitoringInstallationHeaders(c)
+	if !ok {
+		return
+	}
+
+	var req app.MonitoringResumeTasksRequest
+	if err := bindOptionalJSON(c, &req); err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_params", err.Error()))
+		return
+	}
+
+	data, svcErr := h.svc.ResumeTasks(c.Request.Context(), installationID, installationToken, req)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringCallbackHandler) TaskResult(c *gin.Context) {
+	taskID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_task_id", "task id must be a number"))
+		return
+	}
+
+	installationID, installationToken, ok := parseMonitoringInstallationHeaders(c)
+	if !ok {
+		return
+	}
+
+	var req app.MonitoringTaskResultRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_params", err.Error()))
+		return
+	}
+
+	data, svcErr := h.svc.HandleTaskResult(c.Request.Context(), installationID, installationToken, taskID, req)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringCallbackHandler) SkipTask(c *gin.Context) {
+	taskID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_task_id", "task id must be a number"))
+		return
+	}
+
+	installationID, installationToken, ok := parseMonitoringInstallationHeaders(c)
+	if !ok {
+		return
+	}
+
+	var req app.MonitoringSkipTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40041, "invalid_params", err.Error()))
+		return
+	}
+
+	data, svcErr := h.svc.SkipTask(c.Request.Context(), installationID, installationToken, taskID, req)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseMonitoringInstallationHeaders(c *gin.Context) (int64, string, bool) {
+	installationID, err := strconv.ParseInt(c.GetHeader("X-Geo-Installation-Id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrUnauthorized(40141, "invalid_installation_id", "installation id header is invalid"))
+		return 0, "", false
+	}
+
+	installationToken := c.GetHeader("X-Geo-Installation-Token")
+	if installationToken == "" {
+		response.Error(c, response.ErrUnauthorized(40141, "missing_installation_token", "installation token header is required"))
+		return 0, "", false
+	}
+
+	return installationID, installationToken, true
+}
+
+func bindOptionalJSON(c *gin.Context, target interface{}) error {
+	err := c.ShouldBindJSON(target)
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, io.EOF) {
+		return nil
+	}
+	return err
+}
@@ -0,0 +1,133 @@
+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 MonitoringHandler struct {
+	svc *app.MonitoringService
+}
+
+type monitoringCollectNowRequest struct {
+	KeywordID *int64 `json:"keyword_id"`
+}
+
+func NewMonitoringHandler(a *bootstrap.App) *MonitoringHandler {
+	return &MonitoringHandler{
+		svc: app.NewMonitoringService(a.DB, a.MonitoringDB),
+	}
+}
+
+func (h *MonitoringHandler) DashboardComposite(c *gin.Context) {
+	brandID, err := parseOptionalInt64(c.Query("brand_id"))
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_brand_id", "brand_id must be a number"))
+		return
+	}
+
+	keywordID, err := parseOptionalInt64Pointer(c.Query("keyword_id"))
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_keyword_id", "keyword_id must be a number"))
+		return
+	}
+
+	days, err := parseOptionalInt(c.Query("days"))
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_days", "days must be a number"))
+		return
+	}
+
+	data, svcErr := h.svc.DashboardComposite(c.Request.Context(), brandID, keywordID, days, c.Query("business_date"))
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringHandler) QuestionDetail(c *gin.Context) {
+	brandID, err := strconv.ParseInt(c.Param("brand_id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_brand_id", "brand_id must be a number"))
+		return
+	}
+
+	questionID, err := strconv.ParseInt(c.Param("question_id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_question_id", "question_id must be a number"))
+		return
+	}
+
+	var aiPlatformID *string
+	if value := c.Query("ai_platform_id"); value != "" {
+		trimmed := value
+		aiPlatformID = &trimmed
+	}
+
+	data, svcErr := h.svc.QuestionDetail(
+		c.Request.Context(),
+		brandID,
+		questionID,
+		c.Query("date_from"),
+		c.Query("date_to"),
+		c.Query("question_hash"),
+		aiPlatformID,
+	)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *MonitoringHandler) CollectNow(c *gin.Context) {
+	brandID, err := strconv.ParseInt(c.Param("brand_id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_brand_id", "brand_id must be a number"))
+		return
+	}
+
+	var req monitoringCollectNowRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40031, "invalid_collect_now_request", "collect-now request is invalid"))
+		return
+	}
+
+	data, svcErr := h.svc.CollectNow(c.Request.Context(), brandID, req.KeywordID)
+	if svcErr != nil {
+		response.Error(c, svcErr)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseOptionalInt64(raw string) (int64, error) {
+	if raw == "" {
+		return 0, nil
+	}
+	return strconv.ParseInt(raw, 10, 64)
+}
+
+func parseOptionalInt64Pointer(raw string) (*int64, error) {
+	if raw == "" {
+		return nil, nil
+	}
+	value, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return nil, err
+	}
+	return &value, nil
+}
+
+func parseOptionalInt(raw string) (int, error) {
+	if raw == "" {
+		return 0, nil
+	}
+	return strconv.Atoi(raw)
+}
@@ -20,6 +20,14 @@ func RegisterRoutes(app *bootstrap.App) {
 	callbacks.POST("/bind", pluginHandler.PluginBindCallback)
 	callbacks.POST("/publish", pluginHandler.PluginPublishCallback)

+	monitoringCallbackHandler := NewMonitoringCallbackHandler(app)
+	monitoringPlugin := app.Engine.Group("/api/plugin/monitoring")
+	monitoringPlugin.POST("/heartbeat", monitoringCallbackHandler.Heartbeat)
+	monitoringPlugin.POST("/tasks/lease", monitoringCallbackHandler.LeaseTasks)
+	monitoringPlugin.POST("/tasks/resume", monitoringCallbackHandler.ResumeTasks)
+	monitoringPlugin.POST("/tasks/:id/result", monitoringCallbackHandler.TaskResult)
+	monitoringPlugin.POST("/tasks/:id/skip", monitoringCallbackHandler.SkipTask)
+
 	protected := app.Engine.Group("/api")
 	protected.Use(auth.Middleware(app.JWT, app.Sessions))
 	protected.Use(middleware.TenantScope())
@@ -89,6 +97,12 @@ func RegisterRoutes(app *bootstrap.App) {
 	brands.PUT("/:id/competitors/:cid", brandHandler.UpdateCompetitor)
 	brands.DELETE("/:id/competitors/:cid", brandHandler.DeleteCompetitor)

+	monitoring := protected.Group("/tenant/monitoring")
+	monitoringHandler := NewMonitoringHandler(app)
+	monitoring.GET("/dashboard/composite", monitoringHandler.DashboardComposite)
+	monitoring.GET("/brands/:brand_id/questions/:question_id/detail", monitoringHandler.QuestionDetail)
+	monitoring.POST("/brands/:brand_id/collect-now", monitoringHandler.CollectNow)
+
 	knowledge := protected.Group("/tenant/knowledge")
 	knowledgeHandler := NewKnowledgeHandler(app)
 	knowledge.GET("/groups", knowledgeHandler.ListGroups)
@@ -29,6 +29,7 @@ func TestProtectedRoutes_RequireAuth(t *testing.T) {
 		{http.MethodGet, "/api/tenant/templates"},
 		{http.MethodGet, "/api/tenant/articles"},
 		{http.MethodGet, "/api/tenant/brands"},
+		{http.MethodGet, "/api/tenant/monitoring/brands/:brand_id/questions/:question_id/detail"},
 		{http.MethodPost, "/api/tenant/brands"},
 	}

@@ -50,6 +51,11 @@ func TestPublicRoutes_NoAuth(t *testing.T) {
 	}{
 		{http.MethodPost, "/api/auth/login"},
 		{http.MethodPost, "/api/auth/refresh"},
+		{http.MethodPost, "/api/plugin/monitoring/heartbeat"},
+		{http.MethodPost, "/api/plugin/monitoring/tasks/lease"},
+		{http.MethodPost, "/api/plugin/monitoring/tasks/resume"},
+		{http.MethodPost, "/api/plugin/monitoring/tasks/:id/result"},
+		{http.MethodPost, "/api/plugin/monitoring/tasks/:id/skip"},
 		{http.MethodGet, "/api/health/live"},
 		{http.MethodGet, "/api/health/ready"},
 	}