Merge pull request #77 from ontrack-features-t2-2026/fix/ppi-live-task-adapter-20260824

feat(ppi): connect task widget to authorised live endpoint

Author: Clupai8o0

docs/ppi-f02-unit-summary-handover.md

@@ -81,19 +81,19 @@ The future frontend adapter can replace the mock call inside
 `ProgressDashboardComponent.loadPeerProgressUnitSummary()` without redesigning
 the presentational component.
 
-### Nullability the frontend types do not yet allow
+### Task-level adapter nullability
 
 doubtfire-api#16 returns `null` for `last_updated_at` and `target_grade` in
-several documented states. Before the adapter lands, `PeerProgressIndicator`
-needs `lastUpdatedAt: string | null` and `targetGrade: number | null`.
+several documented states. The task-level live adapter now maps those values to
+`PeerProgressIndicator.lastUpdatedAt: string | null` and
+`PeerProgressIndicator.targetGrade: number | null`.
 
 ### The mock must not reach a production build
 
-Both PPI surfaces render a fixture today: this component and the already-merged
-`f-ppi-widget` on the task sheet. Both are now gated on
+The unit-level summary in this document remains mock-backed and is gated on
 `environment.production`, so a built application shows the unavailable state
-rather than a fabricated percentage. Remove both guards in the same change that
-lands the live adapter, and not before.
+rather than a fabricated percentage. The task-sheet `f-ppi-widget` now uses the
+authorised project/task API route and does not render a fixture in production.
 
 ## Validation
 

docs/ppi-help-text-pack.md

@@ -33,8 +33,8 @@ These rules apply to both views:
 1. A group result is shown as one combined percentage.
 2. It must not display names, student IDs, project IDs, individual results, individual
    task statuses, marks, feedback, raw group size or rankings.
-3. A genuine `0%` is a real value. It must not be presented as missing, suppressed or
-   unavailable data.
+3. A displayed `0%` is a real privacy-bucket value. It must not be presented as missing,
+   suppressed or unavailable data, but it may represent a small percentage that rounds to zero.
 4. A suppressed result explains that the group value is hidden for privacy without
    revealing the exact group size.
 5. Unavailable and stale states describe a data or timing condition. They must not sound
@@ -124,16 +124,16 @@ Suggested accessible name:
   same target grade. It does not show names, individual results, raw group size or
   rankings. It does not assess your own work or predict your grade.
 
-### 3.2 Genuine zero result
+### 3.2 Rounded zero result
 
 **Template state:** `@case ('no-data')`
 
 - **Label:** Peer task progress
-- **Tooltip or short help text:** The group percentage is currently 0%. This is a real
-  result, not missing data.
-- **Expanded explanation:** No students in the privacy-protected group have submitted
-  this task yet. This is not feedback about your own progress. The percentage may change
-  as submissions are made.
+- **Tooltip or short help text:** The privacy-protected group percentage currently rounds
+  to 0%. This is a displayed value, not missing data.
+- **Expanded explanation:** The API rounds percentages into privacy-safe bands, so 0% may
+  include a small number of submissions. It is not feedback about your own progress. The
+  displayed percentage may change as submissions are made.
 
 ### 3.3 Small-group suppression
 
@@ -204,14 +204,14 @@ claim that live unit-level data has been delivered.
   and does not show names, individual results, raw group size, marks, feedback or
   rankings.
 
-### 4.2 Genuine zero group result
+### 4.2 Rounded zero group result
 
 - **Label:** Unit progress overview
-- **Tooltip or short help text:** Anonymous group progress is currently 0%. This is a real
-  value, not missing data.
+- **Tooltip or short help text:** Anonymous group progress currently rounds to 0%. This is
+  a displayed value, not missing data.
 - **Expanded explanation:** Your own progress remains separate from the group result. A
-  group value of 0% only describes the current aggregate. It is not feedback about your
-  work and does not predict your grade.
+  displayed group value of 0% may include a small value that rounds to zero. It is not
+  feedback about your work and does not predict your grade.
 
 ### 4.3 Small-group suppression
 

src/app/api/fixtures/peer-progress-indicator.fixtures.spec.ts

@@ -13,7 +13,7 @@ import {
 const assertContractShape = (fixture: PeerProgressIndicator) => {
   expect(typeof fixture.taskDefinitionId).toBe('number');
   expect(typeof fixture.unitId).toBe('number');
-  expect(typeof fixture.targetGrade).toBe('number');
+  expect(fixture.targetGrade === null || typeof fixture.targetGrade === 'number').toBe(true);
 
   // submittedPercentage can be number or null
   expect(
@@ -24,7 +24,7 @@ const assertContractShape = (fixture: PeerProgressIndicator) => {
   expect(typeof fixture.isStale).toBe('boolean');
   expect(typeof fixture.isFeatureEnabled).toBe('boolean');
 
-  expect(typeof fixture.lastUpdatedAt).toBe('string');
+  expect(fixture.lastUpdatedAt === null || typeof fixture.lastUpdatedAt === 'string').toBe(true);
   expect(typeof fixture.unavailableMessage).toBe('string');
 };
 
@@ -61,7 +61,7 @@ describe('PeerProgressIndicator Fixture Regression Tests', () => {
     expect(FIXTURE_NORMAL.isFeatureEnabled).toBe(true);
   });
 
-  it('ZERO_PERCENT fixture correctly represents genuine 0%', () => {
+  it('ZERO_PERCENT fixture keeps a displayed 0% distinct from unavailable data', () => {
     expect(FIXTURE_ZERO_PERCENT.submittedPercentage).toBe(0);
     expect(FIXTURE_ZERO_PERCENT.isSuppressed).toBe(false);
   });

src/app/api/models/peer-progress-indicator-state.spec.ts

@@ -28,7 +28,7 @@ describe('resolvePeerProgressState', () => {
     expect(result.data).toEqual(NORMAL_STATE);
   });
 
-  it('returns no-data when nobody has submitted yet', () => {
+  it('keeps a rounded zero distinct from unavailable data', () => {
     const result = resolvePeerProgressState(false, null, ZERO_PERCENT_STATE);
     expect(result.state).toBe('no-data');
   });
@@ -39,6 +39,16 @@ describe('resolvePeerProgressState', () => {
     expect(result.message).toBe(SUPPRESSED_STATE.unavailableMessage);
   });
 
+  it('prioritises privacy suppression when a response is also stale', () => {
+    const result = resolvePeerProgressState(false, null, {
+      ...STALE_STATE,
+      isSuppressed: true,
+    });
+
+    expect(result.state).toBe('hidden');
+    expect(result.data?.submittedPercentage).toBeNull();
+  });
+
   it('returns unavailable for a generically unavailable response', () => {
     const result = resolvePeerProgressState(false, null, UNAVAILABLE_STATE);
     expect(result.state).toBe('unavailable');

src/app/api/models/peer-progress-indicator.ts

@@ -1,13 +1,13 @@
 export interface PeerProgressIndicator {
   taskDefinitionId: number; // ID of the task definition
   unitId: number; // ID of the unit
-  targetGrade: number; // Student’s selected target grade (0–3)
+  targetGrade: number | null; // Valid server-side target grade, or null when unavailable
 
   submittedPercentage: number | null; // null when suppressed/unavailable/disabled
   isSuppressed: boolean; // true when cohort too small
   isStale: boolean; // true when data is outdated
   isFeatureEnabled: boolean; // false when unit disables PPI
 
-  lastUpdatedAt: string; // ISO timestamp
+  lastUpdatedAt: string | null; // ISO timestamp, or null when no snapshot was used
   unavailableMessage: string; // safe message for suppressed/unavailable/stale/disabled
 }

src/app/api/services/peer-progress-indicator.service.ts

@@ -1,5 +1,7 @@
+import {HttpClient} from '@angular/common/http';
 import {Injectable} from '@angular/core';
-import {Observable, of} from 'rxjs';
+import {Observable, map, of} from 'rxjs';
+import API_URL from 'src/app/config/constants/apiUrl';
 import {PeerProgressIndicator} from '../models/peer-progress-indicator';
 import {PeerProgressUnitSummary} from '../models/peer-progress-unit-summary';
 import {
@@ -11,28 +13,40 @@ import {
   ZERO_PERCENT_STATE,
 } from './mock/peer-progress-indicator.mock';
 
+interface PeerProgressIndicatorResponse {
+  task_definition_id: number;
+  unit_id: number;
+  target_grade: number | null;
+  submitted_percentage: number | null;
+  is_suppressed: boolean;
+  is_stale: boolean;
+  is_feature_enabled: boolean;
+  last_updated_at: string | null;
+  unavailable_message: string;
+}
+
 @Injectable({
   providedIn: 'root',
 })
 export class PeerProgressIndicatorService {
-  constructor() {}
-
-  // At the moment, it returns mock PPI data for the given state. In future, this will call the real backend API.
+  constructor(private httpClient: HttpClient) {}
 
-  getIndicator(
-    taskDefinitionId: number,
-    unitId: number,
-    targetGrade: number,
-    state: 'normal' | 'zero' | 'suppressed' | 'unavailable' | 'stale' | 'disabled',
-  ): Observable<PeerProgressIndicator> {
-    const base = this.resolveState(state);
+  getIndicator(projectId: number, taskDefinitionId: number): Observable<PeerProgressIndicator> {
+    const url = `${API_URL}/projects/${projectId}/task_def_id/${taskDefinitionId}/peer_progress`;
 
-    return of({
-      ...base,
-      taskDefinitionId,
-      unitId,
-      targetGrade,
-    });
+    return this.httpClient.get<PeerProgressIndicatorResponse>(url).pipe(
+      map((response) => ({
+        taskDefinitionId: response.task_definition_id,
+        unitId: response.unit_id,
+        targetGrade: response.target_grade,
+        submittedPercentage: response.submitted_percentage,
+        isSuppressed: response.is_suppressed,
+        isStale: response.is_stale,
+        isFeatureEnabled: response.is_feature_enabled,
+        lastUpdatedAt: response.last_updated_at,
+        unavailableMessage: response.unavailable_message,
+      })),
+    );
   }
 
   /**

src/app/api/services/spec/peer-progress-indicator.service.spec.ts

@@ -1,106 +1,93 @@
-import {beforeEach, describe, expect, it} from 'vitest';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {provideHttpClient, withInterceptorsFromDi, withXhr} from '@angular/common/http';
+import {HttpTestingController, provideHttpClientTesting} from '@angular/common/http/testing';
 import {TestBed} from '@angular/core/testing';
-import {
-  DISABLED_STATE,
-  NORMAL_STATE,
-  STALE_STATE,
-  SUPPRESSED_STATE,
-  UNAVAILABLE_STATE,
-  ZERO_PERCENT_STATE,
-} from '../mock/peer-progress-indicator.mock';
+import {PeerProgressIndicator} from 'src/app/api/models/peer-progress-indicator';
+import API_URL from 'src/app/config/constants/apiUrl';
+import {DISABLED_STATE, NORMAL_STATE, SUPPRESSED_STATE} from '../mock/peer-progress-indicator.mock';
 import {PeerProgressIndicatorService} from '../peer-progress-indicator.service';
 
 describe('PeerProgressIndicatorService', () => {
   let service: PeerProgressIndicatorService;
+  let httpMock: HttpTestingController;
 
   beforeEach(() => {
     TestBed.configureTestingModule({
-      providers: [PeerProgressIndicatorService],
+      providers: [
+        PeerProgressIndicatorService,
+        provideHttpClient(withXhr(), withInterceptorsFromDi()),
+        provideHttpClientTesting(),
+      ],
     });
 
     service = TestBed.inject(PeerProgressIndicatorService);
+    httpMock = TestBed.inject(HttpTestingController);
   });
 
-  it('should return normal state', () => {
-    service.getIndicator(1, 10, 2, 'normal').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(NORMAL_STATE.submittedPercentage);
-      expect(result.isSuppressed).toBe(NORMAL_STATE.isSuppressed);
-      expect(result.isFeatureEnabled).toBe(NORMAL_STATE.isFeatureEnabled);
-
-      // overwritten fields
-      expect(result.taskDefinitionId).toBe(1);
-      expect(result.unitId).toBe(10);
-      expect(result.targetGrade).toBe(2);
-    });
+  afterEach(() => {
+    httpMock.verify({ignoreCancelled: true});
   });
 
-  it('should return zero percent state', () => {
-    service.getIndicator(2, 20, 1, 'zero').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(ZERO_PERCENT_STATE.submittedPercentage);
-      expect(result.isSuppressed).toBe(ZERO_PERCENT_STATE.isSuppressed);
+  it('requests the authorised project/task route without client-supplied cohort parameters', () => {
+    service.getIndicator(7, 99).subscribe();
 
-      expect(result.taskDefinitionId).toBe(2);
-      expect(result.unitId).toBe(20);
-      expect(result.targetGrade).toBe(1);
-    });
-  });
+    const request = httpMock.expectOne(`${API_URL}/projects/7/task_def_id/99/peer_progress`);
 
-  it('should return suppressed state', () => {
-    service.getIndicator(3, 30, 0, 'suppressed').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(SUPPRESSED_STATE.submittedPercentage);
-      expect(result.isSuppressed).toBe(true);
-      expect(result.unavailableMessage).toBe(SUPPRESSED_STATE.unavailableMessage);
+    expect(request.request.method).toBe('GET');
+    expect(request.request.params.keys()).toEqual([]);
 
-      expect(result.taskDefinitionId).toBe(3);
-      expect(result.unitId).toBe(30);
-      expect(result.targetGrade).toBe(0);
+    request.flush({
+      task_definition_id: 99,
+      unit_id: 1,
+      target_grade: 2,
+      submitted_percentage: 40,
+      is_suppressed: false,
+      is_stale: false,
+      is_feature_enabled: true,
+      last_updated_at: '2026-08-23T00:00:00Z',
+      unavailable_message: '',
     });
   });
 
-  it('should return unavailable state', () => {
-    service.getIndicator(4, 40, 3, 'unavailable').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(UNAVAILABLE_STATE.submittedPercentage);
-      expect(result.unavailableMessage).toBe(UNAVAILABLE_STATE.unavailableMessage);
+  it('maps the complete snake-case response and preserves nullable fields', () => {
+    let result: PeerProgressIndicator | undefined;
 
-      expect(result.taskDefinitionId).toBe(4);
-      expect(result.unitId).toBe(40);
-      expect(result.targetGrade).toBe(3);
+    service.getIndicator(7, 99).subscribe((value) => {
+      result = value;
     });
-  });
 
-  it('should return stale state', () => {
-    service.getIndicator(5, 50, 2, 'stale').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(STALE_STATE.submittedPercentage);
-      expect(result.isStale).toBe(true);
-      expect(result.unavailableMessage).toBe(STALE_STATE.unavailableMessage);
-
-      expect(result.taskDefinitionId).toBe(5);
-      expect(result.unitId).toBe(50);
-      expect(result.targetGrade).toBe(2);
+    httpMock.expectOne(`${API_URL}/projects/7/task_def_id/99/peer_progress`).flush({
+      task_definition_id: 99,
+      unit_id: 1,
+      target_grade: null,
+      submitted_percentage: null,
+      is_suppressed: false,
+      is_stale: false,
+      is_feature_enabled: true,
+      last_updated_at: null,
+      unavailable_message: 'Peer progress is currently unavailable.',
     });
-  });
-
-  it('should return disabled state', () => {
-    service.getIndicator(6, 60, 1, 'disabled').subscribe((result) => {
-      expect(result.submittedPercentage).toBe(DISABLED_STATE.submittedPercentage);
-      expect(result.isFeatureEnabled).toBe(false);
-      expect(result.unavailableMessage).toBe(DISABLED_STATE.unavailableMessage);
 
-      expect(result.taskDefinitionId).toBe(6);
-      expect(result.unitId).toBe(60);
-      expect(result.targetGrade).toBe(1);
+    expect(result).toEqual({
+      taskDefinitionId: 99,
+      unitId: 1,
+      targetGrade: null,
+      submittedPercentage: null,
+      isSuppressed: false,
+      isStale: false,
+      isFeatureEnabled: true,
+      lastUpdatedAt: null,
+      unavailableMessage: 'Peer progress is currently unavailable.',
     });
   });
 
-  it('should fall back to unavailable state for unknown keys', () => {
-    service.getIndicator(99, 99, 0, 'unknown' as 'normal').subscribe((result) => {
-      expect(result.unavailableMessage).toBe(UNAVAILABLE_STATE.unavailableMessage);
-      expect(result.submittedPercentage).toBeNull();
+  it('cancels the live HTTP request when the caller unsubscribes', () => {
+    const subscription = service.getIndicator(7, 99).subscribe();
+    const request = httpMock.expectOne(`${API_URL}/projects/7/task_def_id/99/peer_progress`);
 
-      expect(result.taskDefinitionId).toBe(99);
-      expect(result.unitId).toBe(99);
-      expect(result.targetGrade).toBe(0);
-    });
+    subscription.unsubscribe();
+
+    expect(request.cancelled).toBe(true);
   });
 
   describe('getMockUnitSummary', () => {

src/app/projects/states/dashboard/directives/task-dashboard/directives/task-description-card/ppi-widget/ppi-widget.component.html

@@ -33,7 +33,7 @@
   @case ('no-data') {
     <div class="ppi-widget ppi-widget--muted">
       <mat-icon aria-hidden="false" aria-label="No data icon">hourglass_empty</mat-icon>
-      <span>No peer submissions yet</span>
+      <span>Peer submission progress rounds to 0% for your target grade</span>
     </div>
   }
   @case ('stale') {