feat(reports): align live grouped errors

docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md

@@ -49,11 +49,11 @@ Hermes task landing checklist:
 
 ## Current Baseline
 
-- Current tracking checkpoint: 2026-06-07 report summary aggregate parity checkpoint, prepared as `feat(reports): align summary aggregates`.
+- Current tracking checkpoint: 2026-06-07 live reports error-shape parity checkpoint, prepared as `feat(reports): align live grouped errors`.
-- Latest implementation checkpoint: this checkpoint, prepared as `feat(reports): align summary aggregates`.
+- Latest implementation checkpoint: this checkpoint, prepared as `feat(reports): align live grouped errors`.
-- Latest documentation/tooling checkpoint: this tracker update records P3.46 report summary aggregate parity plus the committed P3.45/P3.44/P3.43/P3.42/P3.41/P3.40 reports baseline, lands the known Hermes plan families into this document, and keeps this file as the active follow-up plan that supersedes `.hermes/plans/*`.
+- Latest documentation/tooling checkpoint: this tracker update records P3.47 live reports grouped error-shape parity plus the committed P3.46/P3.45/P3.44/P3.43/P3.42/P3.41/P3.40 reports baseline, lands the known Hermes plan families into this document, and keeps this file as the active follow-up plan that supersedes `.hermes/plans/*`.
 - Plan landing status: complete for the current known Hermes plans and user-confirmed scope. Future work should update this file directly instead of opening a parallel tracker.
-- Worktree status at this implementation checkpoint: API v2 report summary responses now match inspected Chatwoot `Api::V2::Accounts::ReportsController#summary/#bot_summary`, `V2::Reports::Conversations::MetricBuilder`, `Reports::RawDataSource#aggregate`, and `ReportMetricRegistry` behavior. `/reports/summary` returns raw Chatwoot metric keys plus `previous`, scoped by current/previous ranges, report type/id, and business-hours average selection. `/reports/bot_summary` uses aggregate raw count strategies: `bot_handoffs_count` counts distinct non-null conversations, while `bot_resolutions_count` counts event rows after excluding conversations with bot handoffs in the same scoped range. P3.45 report bot metric timeseries count strategies, P3.44 live additive rollup parity, P3.43 rollup/backfill timezone parity, P3.42 timeseries timezone parity, P3.41 CSV/download parity, and P3.40 raw JSON/date parity for report, live-report, and summary-report endpoints remain implemented. Profile MFA, Facebook callbacks, account WhatsApp calls, onboarding, notification scoping, API v2 year-in-review, and WhatsApp calling toggle parity remain implemented from previous checkpoints. Live API/browser/enterprise smoke still needs the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack.
+- Worktree status at this implementation checkpoint: live reports grouped metrics now match inspected Chatwoot `Api::V2::Accounts::LiveReportsController#set_group_scope` error shape for invalid `group_by`, returning raw `422 { error: "invalid group_by" }` instead of the local `{ success: false, error: ... }` envelope. Focused grouped live-report tests also cover the Chatwoot assignee grouping payload with nil assignee buckets. P3.46 summary aggregate parity, P3.45 report bot metric timeseries count strategies, P3.44 live additive rollup parity, P3.43 rollup/backfill timezone parity, P3.42 timeseries timezone parity, P3.41 CSV/download parity, and P3.40 raw JSON/date parity for report, live-report, and summary-report endpoints remain implemented. Profile MFA, Facebook callbacks, account WhatsApp calls, onboarding, notification scoping, API v2 year-in-review, and WhatsApp calling toggle parity remain implemented from previous checkpoints. Live API/browser/enterprise smoke still needs the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack.
 - Next executable implementation checkpoint: continue Phase 2/3 drift audit for deeper report data-source/metric-builder drift or the next reused-frontend mismatch, Phase 6 placeholder audit, or B12 live smoke from fresh reference/smoke evidence.
 - `go test ./...` passes when run outside the restricted socket sandbox; focused Facebook callback handler/router/route-parity tests pass in the sandbox.
 - Route dump succeeds with `967` registered routes after profile MFA route tracking.
@@ -156,6 +156,7 @@ This table is the shortest authoritative handoff view. If an older lower section
 
 | Priority | Workstream | Current state | Next checkpoint | Commit close rule |
 | --- | --- | --- | --- | --- |
+| 0 | P3.47 live reports grouped error-shape parity | Implemented for reused live-report grouped metrics clients: GoChat now follows inspected Chatwoot `Api::V2::Accounts::LiveReportsController#set_group_scope` and `spec/controllers/api/v2/accounts/live_reports_controller_spec.rb` by returning raw `422 { error: "invalid group_by" }` for invalid grouped live-report requests. Focused tests also cover assignee grouping payloads, including the nil-assignee bucket, open/unattended/unassigned counts, and absence of the local success envelope. | Keep in Review; reopen from B12 live-report smoke or fresh reference evidence for authorization status drift, team lookup `404` behavior, grouped ordering assumptions, or pending/open scope drift. | Focused `LiveReportHandler` tests, full `go test ./...`, and `git diff --check` must pass. No route artifacts change. |
 | 0 | P3.46 report summary aggregate parity | Implemented for reused v2 reports summary clients: GoChat now follows inspected Chatwoot `Api::V2::Accounts::ReportsController#build_summary`, `V2::Reports::Conversations::MetricBuilder#summary/#bot_summary`, `Reports::RawDataSource#aggregate`, and `Reports::ReportMetricRegistry`. `/reports/summary` returns raw Chatwoot metric keys with a `previous` object instead of the local `{ metrics: [...] }` rollup envelope, uses current/previous Unix-second ranges, honors report `type/id` filters, and switches average values to `value_in_business_hours` when requested. `/reports/bot_summary` now applies aggregate raw count strategies: handoffs are distinct non-null conversations, and bot resolutions count event rows after excluding handoff conversations in the same scoped range. | Keep in Review; reopen from B12 reports summary smoke, fresh reference evidence for rollup-backed `Reports::DataSource.for`, invalid timezone/range controller behavior, or summary dimension scope drift for team/label/report-type filters. | Focused Analytics service bot-summary tests, Analytics handler summary tests, escalated full `go test ./...`, and `git diff --check` must pass. No route artifacts change. |
 | 0 | P3.45 report bot raw-count strategy parity | Implemented for reused v2 reports chart clients: GoChat now follows inspected Chatwoot `Reports::RawDataSource#reporting_event_count_scope`, `Reports::ReportMetricRegistry`, and v2 timeseries specs for bot metrics. `bot_handoffs_count` uses the `distinct_conversation` strategy and ignores nil conversation IDs, so duplicate handoff rows for the same conversation count once per bucket. `bot_resolutions_count` uses the `exclude_bot_handoffs` strategy and removes conversations that also have a bot handoff in the same scoped range before timeseries bucketing. Dimension scopes reuse the existing account/inbox/agent/team/label filters. | Keep in Review; reopen from B12 reports smoke or fresh reference evidence for aggregate-value endpoints beyond the current timeseries route, data-source scope behavior that differs for team/label dimensions, or future `ReportMetricRegistry` count strategies. | Focused Analytics service bot-timeseries tests, full `go test ./...`, and `git diff --check` must pass. No route artifacts change. |
 | 0 | P3.44 reporting live additive rollup parity | Implemented for live reporting-event freshness: GoChat now follows inspected Chatwoot `ReportingEventListener#safe_rollup`, `ReportingEvents::RollupService#upsert_rollups`, and `ReportingEvents::EventMetricRegistry` behavior when `AnalyticsService.RecordEvent` persists a raw event. Valid account `reporting_timezone` gates the live write, event `created_at` determines the local rollup date, account/agent/inbox dimensions are emitted only when present, known event metrics expand to Chatwoot rollup metrics, unknown raw events emit no rollup rows, and conflicts add incoming `count`, `sum_value`, and `sum_value_business_hours` to the existing unique row. | Keep in Review; reopen from B12 reports smoke or fresh reference evidence for dispatcher/listener event creation paths that bypass `AnalyticsService.RecordEvent`, Sidekiq retry semantics beyond swallowed live-rollup errors, or report metric registry additions beyond the inspected reference event registry. | Focused Reporting live rollup/repository tests, full `go test ./...`, and `git diff --check` must pass. No route artifacts change. |
@@ -285,6 +286,7 @@ This ledger records the committed parity checkpoints that future slices should b
 
 | Commit | Scope | Verification summary | Follow-up state |
 | --- | --- | --- | --- |
+| `feat(reports): align live grouped errors` | Advances P3.47 live reports grouped error-shape parity by matching Chatwoot `Api::V2::Accounts::LiveReportsController#set_group_scope` and live-report controller specs. GoChat now returns raw `422 { error: "invalid group_by" }` for invalid `/live_reports/grouped_conversation_metrics` requests instead of the local error envelope, and focused tests cover grouped assignee payloads with nil-assignee buckets and open/unattended/unassigned counts. | `go test ./internal/handler/api/v1 -run LiveReportHandler -count=1`; full `go test ./...`; `git diff --check`. Route artifacts are unchanged. | P3.47 moves to Review for current live-report grouped error evidence; continue Phase 2/3 drift audit, Phase 6 placeholder audit, B12 live smoke, or fresh reference/smoke drift. |
 | `feat(reports): align summary aggregates` | Advances P3.46 report summary aggregate parity by matching Chatwoot `Api::V2::Accounts::ReportsController#build_summary`, `V2::Reports::Conversations::MetricBuilder`, `Reports::RawDataSource#aggregate`, and `ReportMetricRegistry`. GoChat `/reports/summary` now returns raw current metric keys plus `previous`, computes current/previous range aggregates from persisted conversations/messages/reporting events, honors report `type/id` dimensions and business-hours averages, and makes `bot_summary` aggregate counts follow the same `distinct_conversation` and `exclude_bot_handoffs` raw count strategies as the current timeseries path. | `go test ./internal/service -run 'Analytics.*Summary\|BotSummary\|BotTimeseries\|AnalyticsReports' -count=1`; `go test ./internal/handler/api/v1 -run AnalyticsHandler -count=1`; escalated full `go test ./...`; `git diff --check`. Route artifacts are unchanged. | P3.46 moves to Review for current summary aggregate evidence; continue Phase 2/3 drift audit for report builder depth, Phase 6 placeholder audit, B12 live smoke, or fresh reference/smoke drift. |
 | `docs: consolidate parity execution tracker` | Documentation-only checkpoint requested before continuing implementation. It records the already-committed `aa159f6 feat(reports): align bot count strategies` implementation baseline, adds a one-page tracking dashboard, and makes the next-turn execution rule explicit: Phase 2/3 drift audit first unless the full B12 live stack is available. | `git diff --check`. No Go code, migrations, or route artifacts changed. | Continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke from this tracker; `.hermes/plans/*` remain source notes only. |
 | `feat(reports): align bot count strategies` | Advances P3.45 report bot raw-count strategy parity by matching Chatwoot `Reports::RawDataSource#reporting_event_count_scope`, `Reports::ReportMetricRegistry`, and v2 report timeseries specs. GoChat now applies `distinct_conversation` for `bot_handoffs_count`, ignores nil handoff conversation IDs, and applies `exclude_bot_handoffs` for `bot_resolutions_count` before bucketing so conversations that both resolve and hand off are not double counted. | `go test ./internal/service -run 'Analytics.*Timeseries\|BotTimeseries\|Reporting.*Rollup\|Backfill' -count=1`; full `go test ./...`; `git diff --check`. Route artifacts are unchanged. | P3.45 moves to Review for current bot metric raw-count evidence; continue Phase 2/3 drift audit for aggregate-value endpoints, report data-source/metric-builder depth, Phase 6 placeholder audit, B12 live smoke, or fresh reference/smoke drift. |
@@ -2548,3 +2550,4 @@ Verification milestone gates:
 - 2026-06-07: P3.45 report bot raw-count strategy checkpoint prepared as `feat(reports): align bot count strategies`; audited Chatwoot `Reports::RawDataSource`, `Reports::ReportMetricRegistry`, and v2 timeseries bot-resolution specs. GoChat `bot_handoffs_count` timeseries now counts distinct non-null conversations per bucket, while `bot_resolutions_count` excludes conversations that also handed off in the scoped range before bucketing. Focused Analytics timeseries tests, escalated full `go test ./...`, and `git diff --check` passed. No route artifacts change.
 - 2026-06-07: Documentation checkpoint prepared as `docs: consolidate parity execution tracker`; confirms `aa159f6 feat(reports): align bot count strategies` is already committed before new implementation work, adds the one-page tracking dashboard, keeps `.hermes/plans/*` as source notes only, and makes Phase 2/3 drift audit the next default action unless the full B12 live stack is available. Verification for this docs-only checkpoint: `git diff --check`.
 - 2026-06-07: P3.46 report summary aggregate checkpoint prepared as `feat(reports): align summary aggregates`; audited Chatwoot v2 reports controller summary builder, conversation metric builder, raw data-source aggregate, metric registry, and reused dashboard `reports.js` summary/bot-summary callers. GoChat `/reports/summary` now returns raw Chatwoot metric keys plus `previous`, derives current/previous aggregates from persisted rows, honors report `type/id` filters and business-hours averages, and fixes `/reports/bot_summary` aggregate counting so handoffs are distinct non-null conversations while bot resolutions count event rows after excluding handoff conversations. Focused Analytics service and handler tests plus escalated full `go test ./...` passed; `git diff --check` passed. No route artifacts change.
+- 2026-06-07: P3.47 live reports grouped error checkpoint prepared as `feat(reports): align live grouped errors`; audited Chatwoot v2 live reports controller `set_group_scope` and request specs. GoChat grouped live reports now return raw `422 { error: "invalid group_by" }` for invalid `group_by` instead of the local error envelope, and focused handler tests cover assignee grouping with nil-assignee buckets and Chatwoot open/unattended/unassigned counts. Focused `LiveReportHandler` tests passed; full `go test ./...` and `git diff --check` passed. No route artifacts change.

internal/handler/api/v1/live_report_handler.go

@@ -64,8 +64,8 @@ func (h *LiveReportHandler) GroupedConversationMetrics(c *gin.Context) {
 
 	groupBy := c.Query("group_by")
 	if groupBy != "team_id" && groupBy != "assignee_id" {
-		// Reference: Chatwoot returns 422 for invalid group_by
+		// Reference: Chatwoot returns 422 with a raw { error } body for invalid group_by.
-		response.AbortWithStatusError(c, http.StatusUnprocessableEntity, response.ErrBadRequest, "invalid group_by, must be team_id or assignee_id")
+		c.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{"error": "invalid group_by"})
 		return
 	}
 

internal/handler/api/v1/live_report_handler_test.go

@@ -36,9 +36,14 @@ func (s *LiveReportHandlerTestSuite) SetupSuite() {
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
 	r.GET("/api/v1/accounts/:account_id/live_reports/conversation_metrics", s.handler.ConversationMetrics)
+	r.GET("/api/v1/accounts/:account_id/live_reports/grouped_conversation_metrics", s.handler.GroupedConversationMetrics)
 	s.router = r
 }
 
+func (s *LiveReportHandlerTestSuite) SetupTest() {
+	s.db.Exec("DELETE FROM conversations")
+}
+
 func TestLiveReportHandlerTestSuite(t *testing.T) {
 	suite.Run(t, new(LiveReportHandlerTestSuite))
 }
@@ -63,3 +68,41 @@ func (s *LiveReportHandlerTestSuite) TestConversationMetrics_Success() {
 	s.Equal(float64(0), body["unassigned"])
 	s.Equal(float64(0), body["pending"])
 }
+
+func (s *LiveReportHandlerTestSuite) TestGroupedConversationMetrics_InvalidGroupByReturnsChatwootError() {
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/accounts/1/live_reports/grouped_conversation_metrics?group_by=invalid_param", nil)
+	s.router.ServeHTTP(w, req)
+	s.Equal(http.StatusUnprocessableEntity, w.Code)
+	var body map[string]interface{}
+	s.NoError(json.Unmarshal(w.Body.Bytes(), &body))
+	s.Equal("invalid group_by", body["error"])
+	s.NotContains(body, "success")
+}
+
+func (s *LiveReportHandlerTestSuite) TestGroupedConversationMetrics_ByAssignee() {
+	agentID := uint(42)
+	firstReply := int64(1760000000)
+	assigned := model.Conversation{AccountID: 1, AssigneeID: &agentID, Status: string(model.ConversationStatusOpen), ChannelType: "web_widget", Channel: "web_widget"}
+	replied := model.Conversation{AccountID: 1, AssigneeID: &agentID, Status: string(model.ConversationStatusOpen), ChannelType: "web_widget", Channel: "web_widget", FirstReplyCreatedAt: &firstReply}
+	unassigned := model.Conversation{AccountID: 1, Status: string(model.ConversationStatusOpen), ChannelType: "web_widget", Channel: "web_widget"}
+	s.Require().NoError(s.db.Create(&assigned).Error)
+	s.Require().NoError(s.db.Create(&replied).Error)
+	s.Require().NoError(s.db.Create(&unassigned).Error)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/accounts/1/live_reports/grouped_conversation_metrics?group_by=assignee_id", nil)
+	s.router.ServeHTTP(w, req)
+	s.Equal(http.StatusOK, w.Code)
+	var body []map[string]interface{}
+	s.NoError(json.Unmarshal(w.Body.Bytes(), &body))
+	s.Len(body, 2)
+	s.Nil(body[0]["assignee_id"])
+	s.Equal(float64(1), body[0]["open"])
+	s.Equal(float64(1), body[0]["unattended"])
+	s.Equal(float64(1), body[0]["unassigned"])
+	s.Equal(float64(agentID), body[1]["assignee_id"])
+	s.Equal(float64(2), body[1]["open"])
+	s.Equal(float64(1), body[1]["unattended"])
+	s.Equal(float64(0), body[1]["unassigned"])
+}