Merge pull request #21 from weorbitant/staging

kevinccbsg · web-flow · commit cb6f7c0bd276 · 2025-12-14T14:24:48.000+01:00
fix: error api and add docs to validate definition of the weekly endpoint
diff --git a/app/_lib/_db/index.ts b/app/_lib/_db/index.ts
@@ -134,7 +134,8 @@ interface LeaderboardEntry {
 }
 
 /**
- * Get all transactions from the last 7 days with user details
+ * Returns all transactions (points given or taken) from the last 7 days.
+ * Includes messages, amounts, timestamps, and who gave/received points.
  */
 export async function getLastWeekTransactions(): Promise<LastWeekTransaction[]> {
   const result = await prisma.$queryRaw<LastWeekTransaction[]>`
@@ -148,7 +149,7 @@ export async function getLastWeekTransactions(): Promise<LastWeekTransaction[]>
     FROM "Transaction" t
     JOIN "User" u_from ON u_from.id = t."fromUserId"
     JOIN "User" u_to ON u_to.id = t."toUserId"
-    WHERE t.timestamp <= datetime('now', '-7 days')
+    WHERE t.timestamp >= datetime('now', '-7 days')
       AND u_from.realName IS NOT NULL
       AND u_to.realName IS NOT NULL
     ORDER BY t.timestamp DESC
@@ -157,7 +158,8 @@ export async function getLastWeekTransactions(): Promise<LastWeekTransaction[]>
 }
 
 /**
- * Get leaderboard with total karma received per user from last 7 days
+ * Retrieves the leaderboard snapshot from 7 days ago.
+ * Returns the leaderboard state as it was exactly 7 days ago (all transactions up to that point).
  */
 export async function getLastWeekLeaderboard(): Promise<LeaderboardEntry[]> {
   const result = await prisma.$queryRaw<LeaderboardEntry[]>`
@@ -172,7 +174,7 @@ export async function getLastWeekLeaderboard(): Promise<LeaderboardEntry[]> {
         ROW_NUMBER() OVER (ORDER BY SUM(t.amount) DESC) AS rank
       FROM "Transaction" t
       WHERE 
-        t.timestamp >= datetime('now', '-7 days')
+        t.timestamp <= datetime('now', '-7 days')
         AND t."toUserId" IS NOT NULL
       GROUP BY t."toUserId"
     ) q
@@ -188,7 +190,8 @@ export async function getLastWeekLeaderboard(): Promise<LeaderboardEntry[]> {
 }
 
 /**
- * Get leaderboard with total karma received per user from today (total karma)
+ * Shows the current leaderboard as of today.
+ * Returns all-time leaderboard up to and including today.
  */
 export async function getTodayLeaderboard(): Promise<LeaderboardEntry[]> {
   const result = await prisma.$queryRaw<LeaderboardEntry[]>`
diff --git a/docs/AI_WEEKLY_SUMMARY_QUERIES.md b/docs/AI_WEEKLY_SUMMARY_QUERIES.md
@@ -0,0 +1,112 @@
+# AI Weekly Summary Queries Documentation
+
+## Overview
+
+This document explains the behavior of the three database queries used by the AI Weekly Summary feature. These queries provide different perspectives on karma transactions and leaderboards for generating weekly summaries.
+
+## Query Functions
+
+### 1. `getLastWeekTransactions()`
+
+**Purpose:** Returns all transactions (points given or taken) from the last 7 days.
+
+**Description:**
+- Returns individual transaction records from the **most recent 7 days** (recent activity)
+- Includes full transaction details: message, amount, timestamp, running total, and user names
+- Used to show what happened in the current week
+
+**SQL Logic:**
+```sql
+WHERE t.timestamp >= datetime('now', '-7 days')
+```
+- Gets transactions where timestamp is **greater than or equal to** 7 days ago
+- This means: transactions from the last 7 days (recent)
+
+**Returns:**
+- Array of `LastWeekTransaction` objects
+- Each transaction includes:
+  - `message`: The transaction message
+  - `amount`: Karma amount (positive or negative)
+  - `timestamp`: When the transaction occurred
+  - `newTotal`: Running total after this transaction
+  - `fromName`: Real name of the user who gave/took karma
+  - `toName`: Real name of the user who received/lost karma
+
+---
+
+### 2. `getLastWeekLeaderboard()`
+
+**Purpose:** Retrieves the leaderboard snapshot from 7 days ago.
+
+**Description:**
+- Returns the leaderboard state **as it was exactly 7 days ago** (historical snapshot)
+- Shows who was leading 7 days ago, before the current week's activity
+- Used to compare "where we were" vs "where we are now"
+
+**SQL Logic:**
+```sql
+WHERE t.timestamp <= datetime('now', '-7 days')
+```
+- Gets transactions where timestamp is **less than or equal to** 7 days ago
+- This means: all transactions up to 7 days ago (historical data)
+- Calculates totals and ranks based only on transactions that existed 7 days ago
+
+**Returns:**
+- Array of `LeaderboardEntry` objects
+- Each entry includes:
+  - `toRealName`: User's real name
+  - `totalReceived`: Total karma received (up to 7 days ago)
+  - `rank`: User's rank in the leaderboard (1 = highest)
+
+---
+
+### 3. `getTodayLeaderboard()`
+
+**Purpose:** Shows the current leaderboard as of today.
+
+**Description:**
+- Returns the **all-time leaderboard** up to and including today
+- Shows the current state of who has the most karma overall
+- Used to show "where we are now"
+
+**SQL Logic:**
+```sql
+WHERE date(t.timestamp) <= date('now')
+```
+- Gets all transactions up to and including today
+- This means: all historical transactions (no time limit)
+- Calculates totals and ranks based on all transactions ever
+
+**Returns:**
+- Array of `LeaderboardEntry` objects
+- Each entry includes:
+  - `toRealName`: User's real name
+  - `totalReceived`: Total karma received (all-time)
+  - `rank`: User's current rank in the leaderboard (1 = highest)
+
+---
+
+## Key Differences
+
+| Query | Time Range | Purpose | Use Case |
+|-------|-----------|---------|----------|
+| `getLastWeekTransactions` | **Last 7 days** (recent) | Show recent activity | "What happened this week?" |
+| `getLastWeekLeaderboard` | **Up to 7 days ago** (historical) | Show past state | "Where were we last week?" |
+| `getTodayLeaderboard` | **All time up to today** | Show current state | "Where are we now?" |
+
+## Visual Timeline Example
+
+```
+Timeline:  [14 days ago]  [7 days ago]  [Today]
+           |--------------|--------------|
+           
+getLastWeekLeaderboard:   [============]  (up to 7 days ago)
+getLastWeekTransactions:              [========]  (last 7 days)
+getTodayLeaderboard:      [========================]  (all time)
+```
+
+## Related Files
+
+- `app/_lib/_db/index.ts`: Query implementations
+- `app/_lib/_agent/agent.ts`: Query usage in AI agent
+- `tests/e2e/aiWeeklySummary/aiWeeklySummary.spec.ts`: Test suite
diff --git a/tests/e2e/aiWeeklySummary/aiWeeklySummary.spec.ts b/tests/e2e/aiWeeklySummary/aiWeeklySummary.spec.ts
@@ -115,14 +115,18 @@ describe('aiWeeklySummary', () => {
       },
     })
     await aiWeeklySummary('C123', 'prompt')
-    const expectedLeaderboard = [
+    // Transaction from today should appear in getLastWeekTransactions (last 7 days) and getTodayLeaderboard (all time)
+    // but NOT in getLastWeekLeaderboard (snapshot from 7 days ago)
+    const expectedLastWeekTransactions = [
       {
-        toRealName: 'User 2',
-        totalReceived: 100,
-        rank: 1,
+        message: 'Test message',
+        amount: 100,
+        timestamp: date,
+        newTotal: 100,
+        fromName: 'User 1',
+        toName: 'User 2',
       },
     ]
-    // current date but in format for example yyyy-mm-ddThh:mm
     const expectedTodayLeaderboard = [
       {
         toRealName: 'User 2',
@@ -131,9 +135,9 @@ describe('aiWeeklySummary', () => {
       },
     ]
     const expectedToolResults = {
-      getLastWeekLeaderboard: expectedLeaderboard,
-      getLastWeekTransactions: [],
-      getTodayLeaderboard: expectedTodayLeaderboard,
+      getLastWeekLeaderboard: [], // Empty - today's transaction is not in snapshot from 7 days ago
+      getLastWeekTransactions: expectedLastWeekTransactions, // Today is within last 7 days
+      getTodayLeaderboard: expectedTodayLeaderboard, // All time up to today
     }
     // Second call: message composition
     expect(mockCreateChatCompletion).toHaveBeenNthCalledWith(
@@ -167,7 +171,7 @@ describe('aiWeeklySummary', () => {
     )
   })
 
-  it('should correctly filter transactions by date: last week vs this week', async () => {
+  it('should correctly filter transactions by date: validates getLastWeekTransactions (last 7 days), getLastWeekLeaderboard (snapshot from 7 days ago), and getTodayLeaderboard (all time)', async () => {
     // Create two users
     const sender1 = await prisma.user.create({
       data: {
@@ -259,23 +263,23 @@ describe('aiWeeklySummary', () => {
 
     await aiWeeklySummary('C123', 'prompt')
 
-    // Expected results: getLastWeekTransactions should include transaction from last week (8 days ago)
+    // Expected results: getLastWeekTransactions should include transaction from this week (3 days ago - within last 7 days)
     const expectedLastWeekTransactions = [
       {
-        message: 'Last week karma',
-        amount: 50,
-        timestamp: lastWeekDate,
-        newTotal: 50,
-        fromName: 'Sender 1',
-        toName: 'Receiver 1',
+        message: 'This week karma',
+        amount: 100,
+        timestamp: thisWeekDate,
+        newTotal: 100,
+        fromName: 'Sender 2',
+        toName: 'Receiver 2',
       },
     ]
 
-    // Expected results: getLastWeekLeaderboard should include transaction from this week (3 days ago), NOT last week
+    // Expected results: getLastWeekLeaderboard should include transaction from last week (8 days ago - snapshot from 7 days ago)
     const expectedLastWeekLeaderboard = [
       {
-        toRealName: 'Receiver 2',
-        totalReceived: 100,
+        toRealName: 'Receiver 1',
+        totalReceived: 50,
         rank: 1,
       },
     ]
