feat: improve captain overview loading and reuse stats for summary [CW-7610] (#15105)

2026-07-21 15:14:18 +05:30
parent 920a98ccf4
commit 7a5385cc32
8 changed files with 112 additions and 24 deletions
@@ -26,15 +26,18 @@ class CaptainAssistant extends ApiClient {
    });
  }

-  getStats({ assistantId, range }) {
-    return axios.get(`${this.url}/${assistantId}/stats`, {
+  getStats({ assistantId, range, signal }) {
+    const requestConfig = {
      params: { range, timezone_offset: getTimezoneOffset() },
-    });
+    };
+    if (signal) requestConfig.signal = signal;
+
+    return axios.get(`${this.url}/${assistantId}/stats`, requestConfig);
  }

-  getSummary({ assistantId, range }) {
+  getSummary({ assistantId, range, stats }) {
    return axios.get(`${this.url}/${assistantId}/summary`, {
-      params: { range, timezone_offset: getTimezoneOffset() },
+      params: { range, timezone_offset: getTimezoneOffset(), stats },
    });
  }

@@ -9,6 +9,7 @@ const props = defineProps({
  // null = neutral, true = good direction, false = bad direction
  trendGood: { type: Boolean, default: null },
  clickable: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
 });

 const emit = defineEmits(['click']);
@@ -45,7 +46,11 @@ const onActivate = () => {
        class="transition-opacity opacity-0 cursor-help i-lucide-info size-3.5 text-n-slate-10 group-hover:opacity-100"
      />
    </div>
-    <div class="flex items-end justify-between gap-2">
+    <div v-if="loading" class="flex items-end justify-between gap-2">
+      <div class="w-20 rounded h-9 bg-n-slate-3 animate-pulse" />
+      <div class="w-10 h-5 rounded bg-n-slate-3 animate-pulse" />
+    </div>
+    <div v-else class="flex items-end justify-between gap-2">
      <span
        class="text-3xl font-semibold tracking-tight tabular-nums text-n-slate-12"
      >
@@ -9,6 +9,10 @@ const props = defineProps({
    type: String,
    default: '30',
  },
+  stats: {
+    type: Object,
+    default: null,
+  },
 });

 const route = useRoute();
@@ -20,22 +24,41 @@ const assistantId = computed(() => route.params.assistantId);
 const welcomeMarkdown = ref('');
 const isLoading = ref(false);

+// Increments on every fetch so a slow response for a superseded
+// range/stats/assistant can't overwrite the latest request's state.
+let fetchToken = 0;
+
 const fetchSummary = async () => {
+  fetchToken += 1;
+  const token = fetchToken;
+
+  if (!props.stats) {
+    welcomeMarkdown.value = '';
+    isLoading.value = false;
+    return;
+  }
+
  isLoading.value = true;
+  let message = '';
  try {
    const { data } = await CaptainAssistant.getSummary({
      assistantId: assistantId.value,
      range: props.range,
+      stats: props.stats,
    });
-    welcomeMarkdown.value = data.message ?? '';
+    message = data.message ?? '';
  } catch {
-    welcomeMarkdown.value = '';
-  } finally {
-    isLoading.value = false;
+    message = '';
  }
+
+  if (token !== fetchToken) return;
+  welcomeMarkdown.value = message;
+  isLoading.value = false;
 };

-watch([() => props.range, assistantId], fetchSummary, { immediate: true });
+watch([() => props.range, () => props.stats, assistantId], fetchSummary, {
+  immediate: true,
+});

 // Render through the shared markdown formatter (html disabled, so it is safe)
 // used everywhere else for Captain output, instead of a bespoke parser. It
@@ -1,5 +1,5 @@
 <script setup>
-import { computed, ref, watch } from 'vue';
+import { computed, onUnmounted, ref, watch } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { useRoute } from 'vue-router';
 import { FEATURE_FLAGS } from 'dashboard/featureFlags';
@@ -27,19 +27,49 @@ const selectedRange = ref('this_month');

 const assistantId = computed(() => route.params.assistantId);
 const stats = ref(null);
+const isFetching = ref(false);
+
+// Increments on every fetch so a response (or retry) from a superseded
+// range/assistant can't clobber the latest request's state.
+let fetchToken = 0;
+let abortController = null;

 const fetchStats = async () => {
-  try {
-    const { data } = await CaptainAssistant.getStats({
+  fetchToken += 1;
+  const token = fetchToken;
+  abortController?.abort();
+  abortController = new AbortController();
+  const { signal } = abortController;
+  stats.value = null;
+  isFetching.value = true;
+
+  const requestStats = () =>
+    CaptainAssistant.getStats({
      assistantId: assistantId.value,
      range: selectedRange.value,
+      signal,
    });
-    stats.value = data;
+
+  let data = null;
+  try {
+    ({ data } = await requestStats());
  } catch {
-    stats.value = null;
+    // One silent retry before giving up, unless the request was aborted.
+    try {
+      if (token === fetchToken && !signal.aborted)
+        ({ data } = await requestStats());
+    } catch {
+      data = null;
+    }
  }
+
+  if (token !== fetchToken || signal.aborted) return;
+  stats.value = data;
+  isFetching.value = false;
 };

+onUnmounted(() => abortController?.abort());
+
 watch([selectedRange, assistantId], fetchStats, { immediate: true });

 // `direction` says whether a rising trend is good ('up'), bad ('down'), or
@@ -156,7 +186,7 @@ const closeDrilldown = () => {

        <CoverageBanner :knowledge="stats?.knowledge" />

-        <WelcomeCard :range="selectedRange" />
+        <WelcomeCard :range="selectedRange" :stats="stats" />

        <div
          class="grid grid-cols-1 gap-px overflow-hidden border rounded-xl sm:grid-cols-2 lg:grid-cols-3 bg-n-weak border-n-weak"
@@ -169,7 +199,8 @@ const closeDrilldown = () => {
            :trend="metric.trend"
            :hint="metric.hint"
            :trend-good="metric.trendGood"
-            :clickable="canDrilldown && Boolean(metric.metric)"
+            :loading="isFetching"
+            :clickable="canDrilldown && Boolean(metric.metric) && !isFetching"
            @click="openDrilldown(metric)"
          />
        </div>
@@ -47,7 +47,8 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
  end

  def summary
-    result = cached_or_generated_summary(Captain::AssistantStatsBuilder.new(@assistant, params[:range], params[:timezone_offset]))
+    window = Captain::AssistantStatsWindow.new(params[:range], params[:timezone_offset])
+    result = cached_or_generated_summary(window, summary_stats)

    if result[:error]
      render json: { error: result[:error] }, status: :unprocessable_content
@@ -68,8 +69,8 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
    params.permit(:metric, :range, :timezone_offset, :page, :per_page)
  end

-  def cached_or_generated_summary(builder)
-    cache_key = summary_cache_key(builder.range)
+  def cached_or_generated_summary(window, stats)
+    cache_key = summary_cache_key(window.range)
    cached = Rails.cache.read(cache_key)
    return cached if cached

@@ -77,14 +78,25 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
      account: Current.account,
      assistant: @assistant,
      first_name: Current.user.name.to_s.split.first,
-      stats: builder.metrics,
-      period: builder.period
+      stats: stats,
+      period: window.period
    ).perform
    # Don't cache transient LLM/config failures, otherwise every reload returns 422 for the next hour.
    Rails.cache.write(cache_key, result, expires_in: 1.hour) unless result[:error]
    result
  end

+  def summary_stats
+    params.require(:stats).permit(
+      conversations_handled: %i[current],
+      hours_saved: %i[current],
+      auto_resolution_rate: %i[current trend],
+      handoff_rate: %i[current trend],
+      reopen_rate: %i[current trend],
+      knowledge: %i[coverage approved documents]
+    ).to_h.deep_symbolize_keys
+  end
+
  def summary_cache_key(range)
    "captain_overview_summary/#{@assistant.id}/#{Current.user.id}/#{range}/#{Date.current}"
  end
@@ -32,6 +32,7 @@ class Captain::OverviewSummaryService < Captain::BaseTaskService
    {
      'first_name' => first_name.to_s,
      'assistant_name' => assistant.name.to_s,
+      'language' => account.locale_english_name,
      'conversations_handled' => current(:conversations_handled),
      'hours_saved' => current(:hours_saved),
      'auto_resolution_rate' => current(:auto_resolution_rate),
@@ -1,6 +1,7 @@
 You are writing a short, warm summary of how an AI support assistant named "{{ assistant_name }}" performed over a reporting period, for {{ first_name }}, the person who manages it.

 Voice and format:
+- Write the entire summary in {{ language }}, including the opening greeting.
 - Address {{ first_name }} directly and open with "Hey {{ first_name }},". Be conversational, never robotic.
 - Always call the assistant by its name, {{ assistant_name }}. Never call it "Captain", "the assistant", or "your assistant".
 - This is a static, read-only poster on an analytics dashboard, not a chat. The reader cannot reply or ask you for anything. Never ask a question, invite a reply, offer further help, or say things like "let me know" or "I can dive in".
@@ -257,10 +257,20 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do
    let(:alice) { create(:user, account: account, role: :administrator, name: 'Alice Adams') }
    let(:bob) { create(:user, account: account, role: :administrator, name: 'Bob Brown') }
    let(:summary_service) { instance_double(Captain::OverviewSummaryService) }
+    let(:summary_stats) do
+      {
+        conversations_handled: { current: 42 },
+        hours_saved: { current: 12 },
+        auto_resolution_rate: { current: 65.0, trend: 5.0 },
+        handoff_rate: { current: 20.0, trend: -2.0 },
+        reopen_rate: { current: 5.0, trend: -1.0 },
+        knowledge: { coverage: 80, approved: 8, documents: 3 }
+      }
+    end

    def get_summary(user)
      get "/api/v1/accounts/#{account.id}/captain/assistants/#{assistant.id}/summary",
-          params: { range: '30' },
+          params: { range: '30', stats: summary_stats },
          headers: user.create_new_auth_token,
          as: :json
    end
@@ -273,6 +283,7 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do

    it 'caches the summary per viewer so one user never receives another user\'s greeting' do
      allow(summary_service).to receive(:perform).and_return({ message: 'Hi Alice' })
+      expect(Captain::AssistantStatsBuilder).not_to receive(:new)

      get_summary(alice)
      get_summary(alice) # served from Alice's cache, no regeneration
@@ -280,6 +291,7 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do

      expect(response).to have_http_status(:success)
      expect(Captain::OverviewSummaryService).to have_received(:new).twice
+      expect(Captain::OverviewSummaryService).to have_received(:new).with(hash_including(stats: summary_stats)).twice
    end

    it 'does not cache failures so a transient error is retried' do