Reorganize repo: backend/, deploy/, docs/ layout + AGENTS.md

Restructure the monorepo into clear top-level directories: - backend/: Go module root (cmd, internal, pkg, configs, migrations, docs/swagger, scripts, tests, go.mod, Makefile, .air.toml) - deploy/: Docker (Dockerfile, docker-compose*), quickstart, fluentd - docs/: project documentation + reports/ (moved from repo root) - AGENTS.md: new AI coding-agent guide at repo root Update all references to the new layout: - Dockerfile: COPY backend/go.mod, COPY backend/ (context = repo root) - docker-compose files: context ../.., dockerfile deploy/docker/Dockerfile, env_file ../../.env, volume mounts ../../backend:/app - deploy/quickstart/compose.yaml: dockerfile deploy/docker/Dockerfile - CI: working-directory: backend for go commands, file deploy/docker/Dockerfile, coverage path backend/coverage.out, health_check backend/scripts/ - backend/Makefile: docker target uses -f ../deploy/docker/Dockerfile ../ - README: architecture tree, quickstart, config paths updated Move root stray scripts (rename_models.*, run_m11_tests.sh, verify_build.sh, gorm_bool_main.go) to backend/scripts/legacy/. All moves via git mv to preserve history. Build, vet, SQLite tests, and docker compose config verified.
2026-07-07 14:44:12 +08:00
parent d4ef996f49
commit aeddedf2a3
1348 changed files with 176 additions and 57 deletions
@@ -0,0 +1,64 @@
+package reporting
+
+import (
+	"time"
+)
+
+// TimeseriesPoint represents a single data point in a timeseries.
+type TimeseriesPoint struct {
+	Timestamp time.Time `json:"timestamp"`
+	Value     float64   `json:"value"`
+}
+
+// AggregateResult holds a single aggregate value for a metric.
+type AggregateResult struct {
+	Metric string  `json:"metric"`
+	Value  float64 `json:"value"`
+}
+
+// SummaryResult holds the summary (totals/averages) for a metric over a range.
+type SummaryResult struct {
+	Metric    string  `json:"metric"`
+	Total     float64 `json:"total"`
+	Average   float64 `json:"average"`
+	Count     int     `json:"count"`
+}
+
+// DataSourceParams defines the parameters for a data source query.
+// Reference: Chatwoot Reports::DataSource — for(account, metric, dimension_type, dimension_id,
+// range, group_by, timezone_offset, business_hours)
+type DataSourceParams struct {
+	AccountID         uint
+	Metric            string
+	DimensionType     DimensionType
+	DimensionID       uint
+	Since             time.Time
+	Until             time.Time
+	GroupBy           string // day, week, month
+	TimezoneOffset    int    // hours offset from UTC
+	BusinessHours     bool
+}
+
+// DataSource is the interface for fetching report data (timeseries, aggregate, summary).
+// Reference: Chatwoot Reports::DataSource base class.
+type DataSource interface {
+	// Timeseries returns a time-bucketed series of data points.
+	Timeseries(params DataSourceParams) ([]TimeseriesPoint, error)
+	// Aggregate returns a single aggregate value for the metric.
+	Aggregate(params DataSourceParams) (*AggregateResult, error)
+	// Summary returns total, average, and count for the metric over the range.
+	Summary(params DataSourceParams) (*SummaryResult, error)
+}
+
+// RawDataSource queries raw reporting_events for timeseries/aggregate/summary.
+// Reference: Chatwoot Reports::RawDataSource
+type RawDataSource struct{}
+
+// NewRawDataSource creates a new raw data source.
+func NewRawDataSource() *RawDataSource {
+	return &RawDataSource{}
+}
+
+// Note: Timeseries, Aggregate, Summary implementations on RawDataSource will be
+// wired through ReportingService which holds the DB connection.
+// The DataSource interface allows swapping between RawDataSource and RollupDataSource.
@@ -0,0 +1,184 @@
+package reporting
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/gochat/gochat/internal/channel"
+	applogger "github.com/gochat/gochat/pkg/logger"
+	"gorm.io/gorm"
+)
+
+// ReportingEventListener listens for conversation events and creates reporting events.
+// Reference: Chatwoot's various reporting listeners that track first_response_time,
+// resolution_time, reply_time on conversation lifecycle events.
+type ReportingEventListener struct {
+	channel.BaseListener
+	db *gorm.DB
+}
+
+func NewReportingEventListener(db *gorm.DB) *ReportingEventListener {
+	return &ReportingEventListener{db: db}
+}
+
+func (l *ReportingEventListener) Name() string {
+	return "reporting_event_listener"
+}
+
+func (l *ReportingEventListener) OnEvent(ctx context.Context, event *channel.ChannelEvent) error {
+	switch event.Type {
+	case channel.EventConversationCreated:
+		return l.onConversationCreated(ctx, event)
+	case channel.EventConversationResolved:
+		return l.onConversationResolved(ctx, event)
+	case channel.EventConversationAssigned:
+		return l.onConversationAssigned(ctx, event)
+	case channel.EventMessageCreated:
+		return l.onMessageCreated(ctx, event)
+	default:
+		return nil
+	}
+}
+
+// onConversationCreated records the conversation creation time as a potential first_response start.
+func (l *ReportingEventListener) onConversationCreated(ctx context.Context, event *channel.ChannelEvent) error {
+	conv, err := l.ExtractConversation(event)
+	if err != nil {
+		return fmt.Errorf("reporting: extract conversation: %w", err)
+	}
+
+	now := time.Now()
+	reportingEvent := &ReportingEvent{
+		AccountID:      conv.AccountID,
+		Name:           "conversation_created",
+		Value:          0,
+		ConversationID: &conv.ID,
+		InboxID:        &conv.InboxID,
+		EventStartTime: now,
+		EventEndTime:   now,
+	}
+
+	if conv.AssigneeID != nil {
+		reportingEvent.UserID = conv.AssigneeID
+	}
+
+	if err := l.db.WithContext(ctx).Create(reportingEvent).Error; err != nil {
+		applogger.L().Error("reporting: failed to create conversation_created event", "error", err)
+		return err
+	}
+	return nil
+}
+
+// onConversationResolved records resolution_time for the conversation.
+func (l *ReportingEventListener) onConversationResolved(ctx context.Context, event *channel.ChannelEvent) error {
+	conv, err := l.ExtractConversation(event)
+	if err != nil {
+		return fmt.Errorf("reporting: extract conversation: %w", err)
+	}
+
+	now := time.Now()
+	// Calculate resolution time as the duration from conversation creation to resolution.
+	resolutionDuration := now.Sub(conv.CreatedAt).Seconds()
+
+	reportingEvent := &ReportingEvent{
+		AccountID:      conv.AccountID,
+		Name:           "resolution_time",
+		Value:          resolutionDuration,
+		ConversationID: &conv.ID,
+		InboxID:        &conv.InboxID,
+		EventStartTime: conv.CreatedAt,
+		EventEndTime:   now,
+	}
+
+	if conv.AssigneeID != nil {
+		reportingEvent.UserID = conv.AssigneeID
+	}
+
+	// Also record a resolutions_count event
+	countEvent := &ReportingEvent{
+		AccountID:      conv.AccountID,
+		Name:           "resolutions_count",
+		Value:          1,
+		ConversationID: &conv.ID,
+		InboxID:        &conv.InboxID,
+		EventStartTime: now,
+		EventEndTime:   now,
+	}
+	if conv.AssigneeID != nil {
+		countEvent.UserID = conv.AssigneeID
+	}
+
+	if err := l.db.WithContext(ctx).Create(reportingEvent).Error; err != nil {
+		applogger.L().Error("reporting: failed to create resolution_time event", "error", err)
+		return err
+	}
+	if err := l.db.WithContext(ctx).Create(countEvent).Error; err != nil {
+		applogger.L().Error("reporting: failed to create resolutions_count event", "error", err)
+		return err
+	}
+	return nil
+}
+
+// onConversationAssigned records first_response start time when a conversation is assigned.
+func (l *ReportingEventListener) onConversationAssigned(ctx context.Context, event *channel.ChannelEvent) error {
+	conv, err := l.ExtractConversation(event)
+	if err != nil {
+		return fmt.Errorf("reporting: extract conversation: %w", err)
+	}
+
+	now := time.Now()
+	reportingEvent := &ReportingEvent{
+		AccountID:      conv.AccountID,
+		Name:           "first_response",
+		Value:          0, // start time recorded; actual duration calculated on first agent reply
+		ConversationID: &conv.ID,
+		InboxID:        &conv.InboxID,
+		EventStartTime: conv.CreatedAt,
+		EventEndTime:   now,
+	}
+
+	if conv.AssigneeID != nil {
+		reportingEvent.UserID = conv.AssigneeID
+	}
+
+	if err := l.db.WithContext(ctx).Create(reportingEvent).Error; err != nil {
+		applogger.L().Error("reporting: failed to create first_response event", "error", err)
+		return err
+	}
+	return nil
+}
+
+// onMessageCreated records reply_time when an agent sends a message in a conversation.
+func (l *ReportingEventListener) onMessageCreated(ctx context.Context, event *channel.ChannelEvent) error {
+	msg, err := l.ExtractMessage(event)
+	if err != nil {
+		return nil // not all message events carry a message
+	}
+
+	// Only track outgoing (agent) messages for reply_time
+	if msg.MessageType != "outgoing" || msg.SenderType != "agent" {
+		return nil
+	}
+
+	now := time.Now()
+	reportingEvent := &ReportingEvent{
+		AccountID:      msg.AccountID,
+		Name:           "reply_time",
+		Value:          0, // actual duration depends on previous message timestamp
+		ConversationID: &msg.ConversationID,
+		InboxID:        &msg.InboxID,
+		EventStartTime: now,
+		EventEndTime:   now,
+	}
+
+	if msg.SenderID != nil {
+		reportingEvent.UserID = msg.SenderID
+	}
+
+	if err := l.db.WithContext(ctx).Create(reportingEvent).Error; err != nil {
+		applogger.L().Error("reporting: failed to create reply_time event", "error", err)
+		return err
+	}
+	return nil
+}
@@ -0,0 +1,87 @@
+package reporting
+
+// AggregateType defines how a metric should be aggregated.
+type AggregateType string
+
+const (
+	AggregateCount   AggregateType = "count"
+	AggregateAverage AggregateType = "average"
+)
+
+// MetricDefinition describes a single reporting metric.
+// Reference: Chatwoot Reports::ReportMetricRegistry
+type MetricDefinition struct {
+	AggregateType    AggregateType
+	RawEventName     string // maps to ReportingEvent.Name
+	RollupMetric     RollupMetric
+	SummaryKey       string // key used in summary output
+}
+
+// ReportMetricRegistry provides the catalog of all supported reporting metrics.
+// Reference: Chatwoot ReportMetricRegistry — defines all metrics with their aggregate type,
+// raw event name, rollup metric, and summary key.
+var ReportMetricRegistry = map[string]MetricDefinition{
+	"avg_first_response_time": {
+		AggregateType:    AggregateAverage,
+		RawEventName:     "first_response",
+		RollupMetric:     MetricFirstResponse,
+		SummaryKey:       "avg_first_response_time",
+	},
+	"avg_resolution_time": {
+		AggregateType:    AggregateAverage,
+		RawEventName:     "resolution_time",
+		RollupMetric:     MetricResolutionTime,
+		SummaryKey:       "avg_resolution_time",
+	},
+	"resolutions_count": {
+		AggregateType:    AggregateCount,
+		RawEventName:     "resolutions_count",
+		RollupMetric:     MetricResolutionsCount,
+		SummaryKey:       "resolutions_count",
+	},
+	"reply_time": {
+		AggregateType:    AggregateAverage,
+		RawEventName:     "reply_time",
+		RollupMetric:     MetricReplyTime,
+		SummaryKey:       "reply_time",
+	},
+	"first_response": {
+		AggregateType:    AggregateAverage,
+		RawEventName:     "first_response",
+		RollupMetric:     MetricFirstResponse,
+		SummaryKey:       "first_response",
+	},
+	"resolution_time": {
+		AggregateType:    AggregateAverage,
+		RawEventName:     "resolution_time",
+		RollupMetric:     MetricResolutionTime,
+		SummaryKey:       "resolution_time",
+	},
+	"bot_resolutions_count": {
+		AggregateType:    AggregateCount,
+		RawEventName:     "bot_resolutions_count",
+		RollupMetric:     MetricBotResolutionsCount,
+		SummaryKey:       "bot_resolutions_count",
+	},
+	"bot_handoffs_count": {
+		AggregateType:    AggregateCount,
+		RawEventName:     "bot_handoffs_count",
+		RollupMetric:     MetricBotHandoffsCount,
+		SummaryKey:       "bot_handoffs_count",
+	},
+}
+
+// GetMetricDefinition returns the metric definition for a given metric key.
+func GetMetricDefinition(key string) (MetricDefinition, bool) {
+	def, ok := ReportMetricRegistry[key]
+	return def, ok
+}
+
+// AllMetricKeys returns all registered metric keys.
+func AllMetricKeys() []string {
+	keys := make([]string, 0, len(ReportMetricRegistry))
+	for k := range ReportMetricRegistry {
+		keys = append(keys, k)
+	}
+	return keys
+}
@@ -0,0 +1,32 @@
+package reporting
+
+// Model types are defined in the model package to avoid duplication and ensure
+// a single source of truth for GORM migrations and cross-package references.
+// This file only re-exports them for convenience within the reporting package.
+
+import (
+	"github.com/gochat/gochat/internal/model"
+)
+
+// Re-export model types for convenient use within the reporting package.
+type ReportingEvent = model.ReportingEvent
+type ReportingEventsRollup = model.ReportingEventsRollup
+type DimensionType = model.DimensionType
+type RollupMetric = model.RollupMetric
+
+// Re-export constants.
+const (
+	DimensionAccount = model.DimensionAccount
+	DimensionAgent   = model.DimensionAgent
+	DimensionInbox   = model.DimensionInbox
+	DimensionTeam    = model.DimensionTeam
+)
+
+const (
+	MetricResolutionsCount    = model.MetricResolutionsCount
+	MetricFirstResponse       = model.MetricFirstResponse
+	MetricResolutionTime      = model.MetricResolutionTime
+	MetricReplyTime           = model.MetricReplyTime
+	MetricBotResolutionsCount = model.MetricBotResolutionsCount
+	MetricBotHandoffsCount    = model.MetricBotHandoffsCount
+)
@@ -0,0 +1,83 @@
+package reporting
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// ReportingService provides CRUD and aggregation queries for reporting events and rollups.
+// Reference: Chatwoot Reports::ReportingEventService + Reports::ReportingEventsRollupService
+type ReportingService struct {
+	db *gorm.DB
+}
+
+func NewReportingService(db *gorm.DB) *ReportingService {
+	return &ReportingService{db: db}
+}
+
+// CreateEvent records a new reporting event.
+func (s *ReportingService) CreateEvent(ctx context.Context, event *ReportingEvent) error {
+	return s.db.WithContext(ctx).Create(event).Error
+}
+
+// GetEvent retrieves a single reporting event by ID.
+func (s *ReportingService) GetEvent(ctx context.Context, id uint) (*ReportingEvent, error) {
+	var event ReportingEvent
+	if err := s.db.WithContext(ctx).First(&event, id).Error; err != nil {
+		return nil, err
+	}
+	return &event, nil
+}
+
+// ListEventsByAccount returns all reporting events for an account within a time range.
+func (s *ReportingService) ListEventsByAccount(ctx context.Context, accountID uint, since, until time.Time) ([]ReportingEvent, error) {
+	var events []ReportingEvent
+	err := s.db.WithContext(ctx).Where("account_id = ? AND event_start_time >= ? AND event_start_time <= ?", accountID, since, until).
+		Find(&events).Error
+	return events, err
+}
+
+// ListEventsByAccountAndName returns events filtered by account, metric name, and time range.
+func (s *ReportingService) ListEventsByAccountAndName(ctx context.Context, accountID uint, name string, since, until time.Time) ([]ReportingEvent, error) {
+	var events []ReportingEvent
+	err := s.db.WithContext(ctx).Where("account_id = ? AND name = ? AND event_start_time >= ? AND event_start_time <= ?", accountID, name, since, until).
+		Find(&events).Error
+	return events, err
+}
+
+// CreateRollup records a rollup aggregation row. Uses upsert to handle the unique index constraint.
+func (s *ReportingService) CreateRollup(ctx context.Context, rollup *ReportingEventsRollup) error {
+	return s.db.WithContext(ctx).Where("account_id = ? AND date = ? AND dimension_type = ? AND dimension_id = ? AND metric = ?",
+		rollup.AccountID, rollup.Date, rollup.DimensionType, rollup.DimensionID, rollup.Metric).
+		Assign(map[string]interface{}{
+			"count":                    rollup.Count,
+			"sum_value":                rollup.SumValue,
+			"sum_value_business_hours": rollup.SumValueBusinessHours,
+		}).FirstOrCreate(rollup).Error
+}
+
+// GetRollups returns rollup records for an account within a date range.
+func (s *ReportingService) GetRollups(ctx context.Context, accountID uint, dimensionType DimensionType, dimensionID uint, since, until time.Time) ([]ReportingEventsRollup, error) {
+	var rollups []ReportingEventsRollup
+	err := s.db.WithContext(ctx).Where("account_id = ? AND dimension_type = ? AND dimension_id = ? AND date >= ? AND date <= ?",
+		accountID, dimensionType, dimensionID, since, until).
+		Find(&rollups).Error
+	return rollups, err
+}
+
+// GetRollupsByMetric returns rollup records for a specific metric.
+func (s *ReportingService) GetRollupsByMetric(ctx context.Context, accountID uint, dimensionType DimensionType, dimensionID uint, metric RollupMetric, since, until time.Time) ([]ReportingEventsRollup, error) {
+	var rollups []ReportingEventsRollup
+	err := s.db.WithContext(ctx).Where("account_id = ? AND dimension_type = ? AND dimension_id = ? AND metric = ? AND date >= ? AND date <= ?",
+		accountID, dimensionType, dimensionID, metric, since, until).
+		Find(&rollups).Error
+	return rollups, err
+}
+
+// DeleteRollupsByDate removes rollup records for a given date range (for re-computation).
+func (s *ReportingService) DeleteRollupsByDate(ctx context.Context, accountID uint, since, until time.Time) error {
+	return s.db.WithContext(ctx).Where("account_id = ? AND date >= ? AND date <= ?", accountID, since, until).
+		Delete(&ReportingEventsRollup{}).Error
+}