feat(api): /api/insights/feedback persists thumbs with provider attribution

v1.4.16 phase B5e: ship the POST endpoint that backs the per-rec
thumbs-up / thumbs-down UI. Body is the four rec-attributes the
client just rendered (id, text-snapshot, severity, metric-source +
time-range) plus the boolean verdict; server-fills providerType +
promptVersion via `resolveFeedbackAttribution()` so the client cannot
poison the daily aggregator's slice by claiming a thumbs-down was
attributed to a rival provider.

Idempotent via the existing `withIdempotency()` wrapper — a retry
with the same Idempotency-Key replays the cached response with
`X-Idempotent-Replay: true`. The dedup unique key on the model
(userId, recommendationId, recommendationText) returns 409 when the
same rec-text is re-rated — that's by design, the aggregator wants
per-text signal not per-id signal so a regeneration that rewrites
the same id with new text re-rates cleanly.

The attribution helper prefers `chainProviderType` over `providerType`
in the latest insights.generate audit row so when the B5b multi-
provider chain falls through to a secondary, the feedback row
reflects the working provider not the configured one. Falls back to
"unknown" + the current PROMPT_VERSION constant when no audit row
exists yet — the aggregator buckets that separately.

Audit row: action `insights.recommendation.feedback`, details carry
the feedback id, severity, helpful, providerType, promptVersion.

Tests:
  - 7 unit tests for the Zod request schema (valid path, severity
    poisoning, time-range poisoning, empty fields, stringified bool,
    extra-field stripping)
  - 5 unit tests for `pickProviderType()` priority + fallback
  - 4 integration tests: 201 happy path with provider attribution,
    409 dedup, 422 validation, fallback to unknown when no audit row

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marc-André BombeckandClaude Opus 4.7 committed 2026-05-10 01:30:06 +02:00
1 parent badc893853
commit 8255e3e49a
6 files changed
+591

No files matched your search

@@ -0,0 +1,48 @@
import { describe, it, expect } from "vitest";
import {
FEEDBACK_ATTRIBUTION_FALLBACK,
pickProviderType,
} from "../feedback-attribution";
import { PROMPT_VERSION } from "@/lib/ai/prompts/insight-generator";
describe("pickProviderType", () => {
it("prefers chainProviderType when present", () => {
// chainProviderType captures the runner's chosen entry across the
// multi-provider chain (B5b). When a fallback fires, the working
// provider differs from the user's primary — the feedback row must
// reflect the working provider, not the configured one.
const got = pickProviderType({
chainProviderType: "openai",
providerType: "codex",
});
expect(got).toBe("openai");
});
it("falls back to providerType when chainProviderType is missing", () => {
const got = pickProviderType({ providerType: "codex" });
expect(got).toBe("codex");
});
it("falls back to 'unknown' when neither field is present", () => {
const got = pickProviderType({});
expect(got).toBe("unknown");
});
it("ignores non-string values", () => {
const got = pickProviderType({
chainProviderType: 123 as unknown as string,
providerType: { name: "evil" } as unknown as string,
});
expect(got).toBe("unknown");
});
});
describe("FEEDBACK_ATTRIBUTION_FALLBACK", () => {
it("uses 'unknown' for the providerType so the aggregator groups separately", () => {
expect(FEEDBACK_ATTRIBUTION_FALLBACK.providerType).toBe("unknown");
});
it("snapshots the current PROMPT_VERSION so the row is persistable", () => {
expect(FEEDBACK_ATTRIBUTION_FALLBACK.promptVersion).toBe(PROMPT_VERSION);
});
});
+86
View File
@@ -0,0 +1,86 @@
/**
* v1.4.16 phase B5e — server-side resolver for the provider/prompt
* attribution that gets stamped on every `RecommendationFeedback` row.
*
* The client cannot supply these fields — that would let any user
* poison the daily aggregator's slice (`(severity x provider x prompt)
* helpful-rate`) by claiming a thumbs-down was attributed to a rival
* provider. So the API endpoint reads the user's most recent
* `insights.generate` audit row, pulls `chainProviderType` (or its
* legacy fallback `providerType`) plus the current `PROMPT_VERSION`
* constant, and stamps those on the row.
*
* If no audit row exists yet (the user is rating a per-status insight
* that pre-dates the comprehensive generate flow), we fall back to
* "unknown" + the current PROMPT_VERSION so the row is still
* persistable and the aggregator can group "unknown" separately.
*/
import { prisma } from "@/lib/db";
import { PROMPT_VERSION } from "@/lib/ai/prompts/insight-generator";
export interface FeedbackAttribution {
providerType: string;
promptVersion: string;
}
/** Default attribution when no `insights.generate` row exists yet. */
export const FEEDBACK_ATTRIBUTION_FALLBACK: Readonly<FeedbackAttribution> = {
providerType: "unknown",
promptVersion: PROMPT_VERSION,
};
interface AuditDetailsShape {
providerType?: unknown;
chainProviderType?: unknown;
}
function parseAuditDetails(raw: string | null): AuditDetailsShape {
if (!raw) return {};
try {
const parsed = JSON.parse(raw);
if (parsed && typeof parsed === "object") return parsed as AuditDetailsShape;
} catch {
// Treat unparseable details as absent — the fallback applies.
}
return {};
}
/**
* Pure helper exported for unit tests so we can pin the priority order
* (chainProviderType > providerType > "unknown") without hitting the
* DB. The current PROMPT_VERSION constant is always returned because
* the generator itself doesn't yet stash a per-payload prompt version
* (research §3.B notes this is a v1.4.17 ratchet item; reading the
* constant snapshots whatever's deployed when the rating fires).
*/
export function pickProviderType(details: AuditDetailsShape): string {
if (typeof details.chainProviderType === "string") {
return details.chainProviderType;
}
if (typeof details.providerType === "string") return details.providerType;
return FEEDBACK_ATTRIBUTION_FALLBACK.providerType;
}
/**
* Resolve the (providerType, promptVersion) tuple to stamp on a
* `RecommendationFeedback` row. Reads the latest `insights.generate`
* audit row for the user. Falls back to the safe defaults when no
* audit row exists.
*/
export async function resolveFeedbackAttribution(
userId: string,
): Promise<FeedbackAttribution> {
const latest = await prisma.auditLog.findFirst({
where: { userId, action: "insights.generate" },
orderBy: { createdAt: "desc" },
select: { details: true },
});
if (!latest) return { ...FEEDBACK_ATTRIBUTION_FALLBACK };
const details = parseAuditDetails(latest.details);
return {
providerType: pickProviderType(details),
promptVersion: PROMPT_VERSION,
};
}
@@ -0,0 +1,72 @@
import { describe, it, expect } from "vitest";
import { recommendationFeedbackRequestSchema } from "../recommendation-feedback";
describe("recommendationFeedbackRequestSchema", () => {
const baseValid = {
recommendationId: "rec-1",
recommendationText: "Discuss home BP log with your physician.",
recommendationSeverity: "important" as const,
metricSourceType: "bloodPressure",
metricSourceTimeRange: "last7days" as const,
helpful: true,
};
it("accepts a valid payload", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse(baseValid);
expect(parsed.success).toBe(true);
});
it("rejects an unknown severity (defence against poisoning the aggregator)", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
recommendationSeverity: "wat",
});
expect(parsed.success).toBe(false);
});
it("rejects an unknown time-range value", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
metricSourceTimeRange: "lastFortnight",
});
expect(parsed.success).toBe(false);
});
it("rejects an empty recommendation id", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
recommendationId: "",
});
expect(parsed.success).toBe(false);
});
it("rejects an empty recommendation text", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
recommendationText: "",
});
expect(parsed.success).toBe(false);
});
it("rejects a non-boolean helpful field (catches stringified-boolean clients)", () => {
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
helpful: "true",
});
expect(parsed.success).toBe(false);
});
it("rejects extra fields when stripping isn't desired (helpful is the only thumbs verb)", () => {
// Zod default behaviour: passthrough is OFF; unknown keys are
// dropped. We don't use .strict() so a future field can be added
// additively, but the parsed value must not carry the extra field.
const parsed = recommendationFeedbackRequestSchema.safeParse({
...baseValid,
providerType: "codex",
});
expect(parsed.success).toBe(true);
if (parsed.success) {
expect("providerType" in parsed.data).toBe(false);
}
});
});
@@ -0,0 +1,53 @@
import { z } from "zod/v4";
/**
* v1.4.16 phase B5e — request body for `POST /api/insights/feedback`.
*
* Mirrors the `RecommendationFeedback` Prisma model fields the client
* is allowed to specify. `providerType` and `promptVersion` are NOT
* part of the request shape — the server fills them from the user's
* most recent cached payload + the current PROMPT_VERSION constant
* so the client can't tamper with the attribution that the daily
* aggregator slices on for the admin AI quality dashboard.
*
* Severity + dataWindow are constrained to the same vocabulary as the
* AI schema (`aiRecommendationSchema` / `aiRecommendationRationaleSchema`)
* so a bogus rating attempt with `severity = "wat"` is rejected at the
* edge instead of poisoning the aggregator.
*/
export const recommendationFeedbackSeverity = z.enum([
"info",
"suggestion",
"important",
"urgent",
]);
export const recommendationFeedbackTimeRange = z.enum([
"last7days",
"last30days",
"last90days",
"allTime",
]);
export const recommendationFeedbackRequestSchema = z.object({
/**
* Stable per-payload rec id. Dedup happens on
* (userId, recommendationId, recommendationText).
*/
recommendationId: z.string().min(1).max(200),
/**
* Snapshot of the rec text at submission time. Dedup partner so a
* regeneration that rewrites the same id with new text counts as a
* different row — that's intentional, the aggregator wants per-text
* signal not per-id signal.
*/
recommendationText: z.string().min(1).max(2000),
recommendationSeverity: recommendationFeedbackSeverity,
metricSourceType: z.string().min(1).max(80),
metricSourceTimeRange: recommendationFeedbackTimeRange,
helpful: z.boolean(),
});
export type RecommendationFeedbackRequest = z.infer<
typeof recommendationFeedbackRequestSchema
>;