# Publication Performance Calibration Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build the first publication performance calibration loop: score optimized revisions, register publications, manually record performance snapshots, and generate calibration observations while keeping a future adapter boundary. **Architecture:** Add a focused calibration domain beside the existing optimization workflow. Persist calibration data through the existing repository abstraction so local SQLite and Cloudflare D1 stay aligned. The first implementation uses a manual performance adapter only; future platform adapters will normalize into the same `PerformanceSnapshot` shape. **Tech Stack:** Next.js 16 App Router, React 19, TypeScript, Zod 4, Vitest, better-sqlite3, Cloudflare D1, existing API key guard. --- ## File Structure - Create `src/lib/calibration/types.ts`: domain types for rubric versions, scoring runs, publication records, sparse performance snapshots, adapter input/output, and calibration events. - Create `src/lib/calibration/validation.ts`: Zod schemas for API inputs and stored calibration objects. - Create `src/lib/calibration/scoring.ts`: deterministic v1 GEO scoring rubric and calibration event generation. - Create `src/lib/calibration/manual-adapter.ts`: first `PerformanceAdapter` implementation that normalizes user-entered metrics. - Create `src/lib/calibration/__tests__/validation.test.ts`: validation tests for sparse metrics and adapter-safe snapshots. - Create `src/lib/calibration/__tests__/scoring.test.ts`: scoring and calibration-event tests. - Modify `src/lib/db/schema.ts`: add local SQLite tables. - Modify `migrations/0002_publication_performance_calibration.sql`: add D1 migration with the same tables. - Modify `src/lib/db/repositories.ts`: add row types and SQLite helpers. - Modify `src/lib/db/repository.ts`: extend `AppRepository` with calibration methods. - Modify `src/lib/db/sqlite-repository.ts`: expose calibration methods. - Modify `src/lib/db/d1-repository.ts`: expose calibration methods for Cloudflare. - Modify `src/lib/db/__tests__/repository.test.ts`: test local persistence round trip. - Modify `src/lib/db/__tests__/d1-repository.test.ts`: test D1 SQL/binds for one representative write. - Create `src/app/api/jobs/[jobId]/calibration/score/route.ts`: create a scoring run for latest optimized revision. - Create `src/app/api/jobs/[jobId]/publications/route.ts`: create and list publication records for a job. - Create `src/app/api/publications/[publicationId]/performance/route.ts`: record a manual performance snapshot and calibration event. - Modify `src/app/api/__tests__/jobs.test.ts`: route-level coverage for score, publication, and performance endpoints. - Create `src/components/performance-calibration-panel.tsx`: compact UI for score, publication registration, and manual snapshot entry. - Modify `src/app/page.tsx`: wire the calibration panel after optimization. - Modify `src/app/globals.css`: add small calibration form/result styles. ## Task 1: Calibration Domain Types And Validation **Files:** - Create: `src/lib/calibration/types.ts` - Create: `src/lib/calibration/validation.ts` - Create: `src/lib/calibration/__tests__/validation.test.ts` - [ ] **Step 1: Write failing validation tests** Create `src/lib/calibration/__tests__/validation.test.ts`: ```ts import { describe, expect, it } from "vitest"; import { manualPerformanceInputSchema, publicationInputSchema, performanceSnapshotSchema, } from "../validation"; describe("calibration validation", () => { it("accepts a publication URL and normalizes optional notes", () => { const parsed = publicationInputSchema.parse({ platform: "official_site", url: "https://example.com/articles/geo", published_at: "2026-06-24T12:00:00.000Z", notes: " 官网首发 ", }); expect(parsed.platform).toBe("official_site"); expect(parsed.notes).toBe("官网首发"); }); it("keeps sparse manual metrics absent instead of turning them into zeroes", () => { const parsed = manualPerformanceInputSchema.parse({ window_label: "T+7d", views: "1200", clicks: "", inquiries: undefined, comments: "3", feedback_summary: "用户追问案例依据", }); expect(parsed.metrics).toEqual({ views: 1200, comments: 3, }); expect(parsed.feedback_summary).toBe("用户追问案例依据"); }); it("rejects unsafe raw adapter credentials in snapshots", () => { expect(() => performanceSnapshotSchema.parse({ id: "perf_test", publication_id: "pub_test", source: "manual", window_label: "T+3d", metrics: { views: 10 }, feedback_summary: "", raw_reference: "cookie=sessionid=secret", snapshot_at: "2026-06-24T12:00:00.000Z", }), ).toThrow(/raw_reference/); }); }); ``` - [ ] **Step 2: Run the failing validation tests** Run: ```bash npm test -- src/lib/calibration/__tests__/validation.test.ts ``` Expected: FAIL because `src/lib/calibration/validation.ts` does not exist. - [ ] **Step 3: Add calibration domain types** Create `src/lib/calibration/types.ts`: ```ts import type { PublishPlatform, QaReport } from "../domain/types"; export type CalibrationDirection = | "better_than_expected" | "as_expected" | "worse_than_expected" | "needs_more_data"; export type PerformanceSource = | "manual" | `adapter:${string}`; export interface RubricDimension { id: string; label: string; weight: number; description: string; } export interface RubricVersion { id: string; version: string; name: string; dimensions: RubricDimension[]; formula: "weighted_average_0_to_10"; is_active: boolean; created_at: string; } export interface ScoringRun { id: string; job_id: string; revision: number; rubric_version_id: string; dimension_scores: Record; composite_score: number; rationale: string; created_at: string; } export interface PublicationRecord { id: string; job_id: string; revision: number; platform: PublishPlatform; url: string; published_at: string; status: "draft" | "published" | "archived"; notes: string; created_at: string; updated_at: string; } export interface PerformanceMetrics { views?: number; impressions?: number; clicks?: number; inquiries?: number; likes?: number; comments?: number; shares?: number; saves?: number; average_position?: number; } export interface PerformanceSnapshot { id: string; publication_id: string; source: PerformanceSource; window_label: string; metrics: PerformanceMetrics; feedback_summary: string; raw_reference?: string; snapshot_at: string; } export interface CalibrationEvent { id: string; publication_id: string; scoring_run_id: string; performance_snapshot_id: string; direction: CalibrationDirection; observations: string[]; recommended_action: string; created_at: string; } export interface AdapterFetchInput { publication: PublicationRecord; window_label: string; } export interface PerformanceAdapter { source: PerformanceSource; fetch(input: AdapterFetchInput): Promise; } export interface CalibrationContext { scoringRun: ScoringRun; qaReport: QaReport; snapshot: PerformanceSnapshot; } ``` - [ ] **Step 4: Add validation schemas** Create `src/lib/calibration/validation.ts`: ```ts import { z } from "zod"; import { publishPlatformSchema } from "../domain/validation"; import type { CalibrationDirection, CalibrationEvent, PerformanceMetrics, PerformanceSnapshot, PublicationRecord, RubricVersion, ScoringRun, } from "./types"; const optionalTextSchema = z .preprocess((value) => (value == null ? "" : value), z.string()) .transform((value) => value.trim()); function optionalMetric(value: unknown) { if (value == null || value === "") return undefined; const numberValue = typeof value === "number" ? value : Number(value); return Number.isFinite(numberValue) && numberValue >= 0 ? numberValue : value; } const metricsShape = { views: z.preprocess(optionalMetric, z.number().nonnegative().optional()), impressions: z.preprocess(optionalMetric, z.number().nonnegative().optional()), clicks: z.preprocess(optionalMetric, z.number().nonnegative().optional()), inquiries: z.preprocess(optionalMetric, z.number().nonnegative().optional()), likes: z.preprocess(optionalMetric, z.number().nonnegative().optional()), comments: z.preprocess(optionalMetric, z.number().nonnegative().optional()), shares: z.preprocess(optionalMetric, z.number().nonnegative().optional()), saves: z.preprocess(optionalMetric, z.number().nonnegative().optional()), average_position: z.preprocess(optionalMetric, z.number().nonnegative().optional()), }; export const performanceMetricsSchema = z .object(metricsShape) .transform((metrics) => Object.fromEntries( Object.entries(metrics).filter(([, value]) => value !== undefined), ) as PerformanceMetrics, ); export const publicationInputSchema = z.object({ platform: publishPlatformSchema, url: z.string().trim().url(), published_at: z.string().datetime(), notes: optionalTextSchema.default(""), }); export const manualPerformanceInputSchema = z .object({ window_label: z.string().trim().min(1), feedback_summary: optionalTextSchema.default(""), raw_reference: optionalTextSchema.optional(), ...metricsShape, }) .transform(({ window_label, feedback_summary, raw_reference, ...metrics }) => ({ window_label, feedback_summary, raw_reference, metrics: performanceMetricsSchema.parse(metrics), })); function rejectUnsafeRawReference(value: string | undefined) { if (!value) return value; if (/cookie|sessionid|token|secret|api[_-]?key|authorization/i.test(value)) { throw new Error("raw_reference must not contain credentials"); } return value; } export const rubricVersionSchema = z.object({ id: z.string().trim().min(1), version: z.string().trim().min(1), name: z.string().trim().min(1), dimensions: z.array( z.object({ id: z.string().trim().min(1), label: z.string().trim().min(1), weight: z.number().positive(), description: z.string().trim().min(1), }), ), formula: z.literal("weighted_average_0_to_10"), is_active: z.boolean(), created_at: z.string().datetime(), }) satisfies z.ZodType; export const scoringRunSchema = z.object({ id: z.string().trim().min(1), job_id: z.string().trim().min(1), revision: z.number().int().positive(), rubric_version_id: z.string().trim().min(1), dimension_scores: z.record(z.string(), z.number().min(0).max(5)), composite_score: z.number().min(0).max(10), rationale: z.string().trim(), created_at: z.string().datetime(), }) satisfies z.ZodType; export const publicationRecordSchema = z.object({ id: z.string().trim().min(1), job_id: z.string().trim().min(1), revision: z.number().int().positive(), platform: publishPlatformSchema, url: z.string().trim().url(), published_at: z.string().datetime(), status: z.enum(["draft", "published", "archived"]), notes: z.string().trim(), created_at: z.string().datetime(), updated_at: z.string().datetime(), }) satisfies z.ZodType; export const performanceSnapshotSchema = z .object({ id: z.string().trim().min(1), publication_id: z.string().trim().min(1), source: z.union([z.literal("manual"), z.templateLiteral(["adapter:", z.string()])]), window_label: z.string().trim().min(1), metrics: performanceMetricsSchema, feedback_summary: z.string().trim(), raw_reference: z.string().trim().optional(), snapshot_at: z.string().datetime(), }) .transform((snapshot) => ({ ...snapshot, raw_reference: rejectUnsafeRawReference(snapshot.raw_reference), })) satisfies z.ZodType; export const calibrationDirectionSchema = z.enum([ "better_than_expected", "as_expected", "worse_than_expected", "needs_more_data", ]) satisfies z.ZodType; export const calibrationEventSchema = z.object({ id: z.string().trim().min(1), publication_id: z.string().trim().min(1), scoring_run_id: z.string().trim().min(1), performance_snapshot_id: z.string().trim().min(1), direction: calibrationDirectionSchema, observations: z.array(z.string().trim().min(1)), recommended_action: z.string().trim().min(1), created_at: z.string().datetime(), }) satisfies z.ZodType; ``` - [ ] **Step 5: Run validation tests** Run: ```bash npm test -- src/lib/calibration/__tests__/validation.test.ts ``` Expected: PASS. - [ ] **Step 6: Commit Task 1** ```bash git add src/lib/calibration/types.ts src/lib/calibration/validation.ts src/lib/calibration/__tests__/validation.test.ts git commit -m "新增发布校准领域类型" ``` ## Task 2: Deterministic GEO Scoring And Manual Adapter **Files:** - Create: `src/lib/calibration/scoring.ts` - Create: `src/lib/calibration/manual-adapter.ts` - Create: `src/lib/calibration/__tests__/scoring.test.ts` - [ ] **Step 1: Write failing scoring tests** Create `src/lib/calibration/__tests__/scoring.test.ts`: ```ts import { describe, expect, it } from "vitest"; import type { OptimizedArticle, QaReport } from "../../domain/types"; import { createManualPerformanceAdapter } from "../manual-adapter"; import { GEO_RUBRIC_V1, createCalibrationEvent, scoreOptimizedArticle, } from "../scoring"; const article: OptimizedArticle = { job_id: "job_123", revision: 2, title: "示例科技 GEO 内容优化方案", summary: "示例科技有限公司面向市场团队提供GEO内容优化服务。", body_markdown: "## 服务能力\n示例科技有限公司提供GEO内容优化服务，帮助市场团队提升AI搜索可见性。\n## 可信依据\n文章保留事实卡中的8年经验描述。", image_suggestions: [], changed_sections: ["title", "body"], requires_user_confirmation: [], }; const qaReport: QaReport = { job_id: "job_123", revision: 2, overall_status: "warn", checks: [ { rule_id: "hallucination_risk", status: "warn", evidence: "8年经验", reason: "需要人工复核经验年限依据。", suggested_fix: "确认事实卡。", target_agent: "body", }, ], }; describe("calibration scoring", () => { it("scores an optimized article with the active GEO rubric", () => { const run = scoreOptimizedArticle({ jobId: "job_123", article, qaReport, }); expect(run.rubric_version_id).toBe(GEO_RUBRIC_V1.id); expect(run.dimension_scores.fact_integrity).toBe(4); expect(run.dimension_scores.readability).toBeGreaterThanOrEqual(4); expect(run.composite_score).toBeGreaterThan(6); expect(run.composite_score).toBeLessThanOrEqual(10); }); it("normalizes manual performance input through the adapter boundary", async () => { const adapter = createManualPerformanceAdapter(); const snapshot = await adapter.fetch({ publication: { id: "pub_123", job_id: "job_123", revision: 2, platform: "official_site", url: "https://example.com/article", published_at: "2026-06-24T12:00:00.000Z", status: "published", notes: "", created_at: "2026-06-24T12:00:00.000Z", updated_at: "2026-06-24T12:00:00.000Z", }, window_label: "T+7d", manualInput: { window_label: "T+7d", views: "1200", inquiries: "7", feedback_summary: "用户追问案例依据", }, }); expect(snapshot.source).toBe("manual"); expect(snapshot.metrics).toEqual({ views: 1200, inquiries: 7 }); }); it("creates a reviewable calibration event without changing the article", () => { const scoringRun = scoreOptimizedArticle({ jobId: "job_123", article, qaReport, }); const event = createCalibrationEvent({ scoringRun, qaReport, snapshot: { id: "perf_123", publication_id: "pub_123", source: "manual", window_label: "T+7d", metrics: { views: 1200, inquiries: 7 }, feedback_summary: "用户追问案例依据", snapshot_at: "2026-07-01T12:00:00.000Z", }, }); expect(event.direction).toBe("better_than_expected"); expect(event.observations.join(" ")).toContain("询盘"); expect(event.recommended_action).toContain("积累"); }); }); ``` - [ ] **Step 2: Run failing scoring tests** Run: ```bash npm test -- src/lib/calibration/__tests__/scoring.test.ts ``` Expected: FAIL because scoring/manual adapter files do not exist. - [ ] **Step 3: Implement scoring service** Create `src/lib/calibration/scoring.ts`: ```ts import { nanoid } from "nanoid"; import type { OptimizedArticle, QaReport } from "../domain/types"; import type { CalibrationContext, CalibrationDirection, CalibrationEvent, RubricVersion, ScoringRun, } from "./types"; export const GEO_RUBRIC_V1: RubricVersion = { id: "rubric_geo_v1", version: "v1", name: "GEO article performance rubric", formula: "weighted_average_0_to_10", is_active: true, created_at: "2026-06-24T00:00:00.000Z", dimensions: [ { id: "fact_integrity", label: "事实一致性", weight: 2, description: "事实、公司名、产品名和经验年限是否遵守事实卡。", }, { id: "platform_fit", label: "平台适配", weight: 1.5, description: "表达是否匹配目标发布平台。", }, { id: "search_intent_fit", label: "搜索意图匹配", weight: 1.5, description: "是否回答GEO/Search背后的用户问题。", }, { id: "answer_density", label: "答案密度", weight: 1.5, description: "是否提供具体信息而不是泛泛宣传。", }, { id: "trust_signal_quality", label: "信任信号质量", weight: 1.5, description: "可信依据是否具体、克制且可复核。", }, { id: "readability", label: "可读性", weight: 1, description: "标题、摘要、正文是否清晰易读。", }, ], }; interface ScoreOptimizedArticleInput { jobId: string; article: OptimizedArticle; qaReport: QaReport; } export function scoreOptimizedArticle({ jobId, article, qaReport, }: ScoreOptimizedArticleInput): ScoringRun { const combined = `${article.title}\n${article.summary}\n${article.body_markdown}`; const dimensionScores = { fact_integrity: scoreFactIntegrity(qaReport), platform_fit: scoreRuleGroup(qaReport, ["platform_fit", "voice_consistency"]), search_intent_fit: hasGeoIntent(combined) ? 4 : 2, answer_density: scoreAnswerDensity(combined), trust_signal_quality: scoreTrustSignals(combined, qaReport), readability: scoreReadability(article), }; const composite = weightedComposite(dimensionScores); return { id: `score_${nanoid(10)}`, job_id: jobId, revision: article.revision ?? 1, rubric_version_id: GEO_RUBRIC_V1.id, dimension_scores: dimensionScores, composite_score: composite, rationale: buildRationale(dimensionScores), created_at: new Date().toISOString(), }; } function scoreFactIntegrity(report: QaReport) { const hardRules = ["company_name_integrity", "claim_consistency", "hallucination_risk"]; const statuses = report.checks .filter((check) => hardRules.includes(check.rule_id)) .map((check) => check.status); if (statuses.includes("fail")) return 1; if (statuses.includes("warn")) return 4; return 5; } function scoreRuleGroup(report: QaReport, ruleIds: string[]) { const statuses = report.checks .filter((check) => ruleIds.includes(check.rule_id)) .map((check) => check.status); if (statuses.includes("fail")) return 2; if (statuses.includes("warn")) return 3; return 4; } function hasGeoIntent(text: string) { return /GEO|AI搜索|生成式引擎|搜索|可见性|问答|推荐/i.test(text); } function scoreAnswerDensity(text: string) { const headings = (text.match(/^##\s+/gm) ?? []).length; const concreteSignals = (text.match(/服务|流程|方案|能力|团队|行业|客户|案例/g) ?? []) .length; if (headings >= 2 && concreteSignals >= 8) return 5; if (headings >= 1 && concreteSignals >= 4) return 4; if (concreteSignals >= 2) return 3; return 2; } function scoreTrustSignals(text: string, report: QaReport) { const hallucination = report.checks.find( (check) => check.rule_id === "hallucination_risk", ); if (hallucination?.status === "fail") return 1; const trustSignals = (text.match(/依据|经验|资质|案例|事实卡|复核|客户/g) ?? []) .length; if (hallucination?.status === "warn") return trustSignals >= 2 ? 3 : 2; return trustSignals >= 2 ? 4 : 3; } function scoreReadability(article: OptimizedArticle) { const longSentence = `${article.summary}\n${article.body_markdown}` .split(/[。！？.!?]/) .some((sentence) => sentence.length > 180); if (article.title.length > 42 || longSentence) return 3; return 4; } function weightedComposite(scores: Record) { const totalWeight = GEO_RUBRIC_V1.dimensions.reduce( (sum, dimension) => sum + dimension.weight, 0, ); const weighted = GEO_RUBRIC_V1.dimensions.reduce( (sum, dimension) => sum + (scores[dimension.id] ?? 0) * dimension.weight, 0, ); return Math.round((weighted / totalWeight) * 2 * 10) / 10; } function buildRationale(scores: Record) { return `事实一致性 ${scores.fact_integrity}/5，平台适配 ${scores.platform_fit}/5，答案密度 ${scores.answer_density}/5，信任信号 ${scores.trust_signal_quality}/5。`; } export function createCalibrationEvent({ scoringRun, qaReport, snapshot, }: CalibrationContext): CalibrationEvent { const direction = inferDirection(scoringRun.composite_score, snapshot.metrics); const observations = buildObservations(direction, scoringRun, qaReport, snapshot.feedback_summary); return { id: `cal_${nanoid(10)}`, publication_id: snapshot.publication_id, scoring_run_id: scoringRun.id, performance_snapshot_id: snapshot.id, direction, observations, recommended_action: "先积累至少 5 篇同类样本，再评估是否调整 GEO rubric 权重。", created_at: new Date().toISOString(), }; } function inferDirection( composite: number, metrics: { views?: number; clicks?: number; inquiries?: number }, ): CalibrationDirection { if (!metrics.views && !metrics.clicks && !metrics.inquiries) { return "needs_more_data"; } if ((metrics.inquiries ?? 0) >= 3 || (metrics.clicks ?? 0) >= 50) { return composite >= 6 ? "better_than_expected" : "better_than_expected"; } if ((metrics.views ?? 0) < 100 && composite >= 7) { return "worse_than_expected"; } return "as_expected"; } function buildObservations( direction: CalibrationDirection, scoringRun: ScoringRun, qaReport: QaReport, feedbackSummary: string, ) { const observations = [ `综合评分 ${scoringRun.composite_score}/10，真实表现方向为 ${direction}。`, ]; if (qaReport.overall_status !== "pass") { observations.push(`QA 状态为 ${qaReport.overall_status}，需要和表现数据一起复盘。`); } if (feedbackSummary) { observations.push(`反馈摘要：${feedbackSummary}`); } if ((scoringRun.dimension_scores.trust_signal_quality ?? 0) <= 3) { observations.push("信任信号质量偏低，后续观察是否影响询盘。"); } return observations; } ``` - [ ] **Step 4: Implement manual adapter** Create `src/lib/calibration/manual-adapter.ts`: ```ts import { nanoid } from "nanoid"; import type { AdapterFetchInput, PerformanceAdapter, PerformanceSnapshot, } from "./types"; import { manualPerformanceInputSchema, performanceSnapshotSchema } from "./validation"; interface ManualAdapterFetchInput extends AdapterFetchInput { manualInput: unknown; } export function createManualPerformanceAdapter(): PerformanceAdapter & { fetch(input: ManualAdapterFetchInput): Promise; } { return { source: "manual", async fetch(input) { const parsed = manualPerformanceInputSchema.parse(input.manualInput); return performanceSnapshotSchema.parse({ id: `perf_${nanoid(10)}`, publication_id: input.publication.id, source: "manual", window_label: parsed.window_label, metrics: parsed.metrics, feedback_summary: parsed.feedback_summary, raw_reference: parsed.raw_reference, snapshot_at: new Date().toISOString(), }); }, }; } ``` - [ ] **Step 5: Run scoring tests** Run: ```bash npm test -- src/lib/calibration/__tests__/scoring.test.ts ``` Expected: PASS. - [ ] **Step 6: Commit Task 2** ```bash git add src/lib/calibration/scoring.ts src/lib/calibration/manual-adapter.ts src/lib/calibration/__tests__/scoring.test.ts git commit -m "新增发布表现评分服务" ``` ## Task 3: SQLite And D1 Schema **Files:** - Modify: `src/lib/db/schema.ts` - Create: `migrations/0002_publication_performance_calibration.sql` - [ ] **Step 1: Add local schema tables** In `src/lib/db/schema.ts`, append these tables inside the existing `db.exec(\`...\`)` block after `qa_reports`: ```sql create table if not exists rubric_versions ( id text primary key, version text not null, name text not null, dimensions text not null, formula text not null, is_active integer not null, created_at text not null ); create table if not exists scoring_runs ( id text primary key, job_id text not null, revision integer not null, rubric_version_id text not null, dimension_scores text not null, composite_score real not null, rationale text not null, created_at text not null, foreign key (job_id, revision) references optimized_articles(job_id, revision) on delete cascade, foreign key (rubric_version_id) references rubric_versions(id) ); create table if not exists publication_records ( id text primary key, job_id text not null, revision integer not null, platform text not null, url text not null, published_at text not null, status text not null, notes text not null, created_at text not null, updated_at text not null, foreign key (job_id, revision) references optimized_articles(job_id, revision) on delete cascade ); create table if not exists performance_snapshots ( id text primary key, publication_id text not null, source text not null, window_label text not null, metrics text not null, feedback_summary text not null, raw_reference text, snapshot_at text not null, foreign key (publication_id) references publication_records(id) on delete cascade ); create table if not exists calibration_events ( id text primary key, publication_id text not null, scoring_run_id text not null, performance_snapshot_id text not null, direction text not null, observations text not null, recommended_action text not null, created_at text not null, foreign key (publication_id) references publication_records(id) on delete cascade, foreign key (scoring_run_id) references scoring_runs(id) on delete cascade, foreign key (performance_snapshot_id) references performance_snapshots(id) on delete cascade ); create index if not exists idx_scoring_runs_job_revision on scoring_runs(job_id, revision); create index if not exists idx_publication_records_job_revision on publication_records(job_id, revision); create index if not exists idx_performance_snapshots_publication on performance_snapshots(publication_id); ``` - [ ] **Step 2: Add D1 migration** Create `migrations/0002_publication_performance_calibration.sql` with the same SQL in Cloudflare-compatible uppercase style: ```sql CREATE TABLE IF NOT EXISTS rubric_versions ( id TEXT PRIMARY KEY, version TEXT NOT NULL, name TEXT NOT NULL, dimensions TEXT NOT NULL, formula TEXT NOT NULL, is_active INTEGER NOT NULL, created_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS scoring_runs ( id TEXT PRIMARY KEY, job_id TEXT NOT NULL, revision INTEGER NOT NULL, rubric_version_id TEXT NOT NULL, dimension_scores TEXT NOT NULL, composite_score REAL NOT NULL, rationale TEXT NOT NULL, created_at TEXT NOT NULL, FOREIGN KEY (job_id, revision) REFERENCES optimized_articles(job_id, revision) ON DELETE CASCADE, FOREIGN KEY (rubric_version_id) REFERENCES rubric_versions(id) ); CREATE TABLE IF NOT EXISTS publication_records ( id TEXT PRIMARY KEY, job_id TEXT NOT NULL, revision INTEGER NOT NULL, platform TEXT NOT NULL, url TEXT NOT NULL, published_at TEXT NOT NULL, status TEXT NOT NULL, notes TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, FOREIGN KEY (job_id, revision) REFERENCES optimized_articles(job_id, revision) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS performance_snapshots ( id TEXT PRIMARY KEY, publication_id TEXT NOT NULL, source TEXT NOT NULL, window_label TEXT NOT NULL, metrics TEXT NOT NULL, feedback_summary TEXT NOT NULL, raw_reference TEXT, snapshot_at TEXT NOT NULL, FOREIGN KEY (publication_id) REFERENCES publication_records(id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS calibration_events ( id TEXT PRIMARY KEY, publication_id TEXT NOT NULL, scoring_run_id TEXT NOT NULL, performance_snapshot_id TEXT NOT NULL, direction TEXT NOT NULL, observations TEXT NOT NULL, recommended_action TEXT NOT NULL, created_at TEXT NOT NULL, FOREIGN KEY (publication_id) REFERENCES publication_records(id) ON DELETE CASCADE, FOREIGN KEY (scoring_run_id) REFERENCES scoring_runs(id) ON DELETE CASCADE, FOREIGN KEY (performance_snapshot_id) REFERENCES performance_snapshots(id) ON DELETE CASCADE ); CREATE INDEX IF NOT EXISTS idx_scoring_runs_job_revision ON scoring_runs(job_id, revision); CREATE INDEX IF NOT EXISTS idx_publication_records_job_revision ON publication_records(job_id, revision); CREATE INDEX IF NOT EXISTS idx_performance_snapshots_publication ON performance_snapshots(publication_id); ``` - [ ] **Step 3: Run schema syntax check** Run: ```bash node -e "const fs=require('fs'); const sql=fs.readFileSync('migrations/0002_publication_performance_calibration.sql','utf8'); console.log(sql.includes('performance_snapshots') ? 'migration ok' : 'missing table')" ``` Expected: prints `migration ok`. - [ ] **Step 4: Commit Task 3** ```bash git add src/lib/db/schema.ts migrations/0002_publication_performance_calibration.sql git commit -m "新增发布校准数据库结构" ``` ## Task 4: Repository Methods For Calibration **Files:** - Modify: `src/lib/db/repositories.ts` - Modify: `src/lib/db/repository.ts` - Modify: `src/lib/db/sqlite-repository.ts` - Modify: `src/lib/db/d1-repository.ts` - Modify: `src/lib/db/__tests__/repository.test.ts` - Modify: `src/lib/db/__tests__/d1-repository.test.ts` - [ ] **Step 1: Write failing SQLite repository test** Append to `src/lib/db/__tests__/repository.test.ts`: ```ts test("persists scoring, publication, performance, and calibration event", async () => { const repository = createSqliteRepository(dbPath); const job = await repository.createArticleJob({ source_title: "Title", source_body: "Body", image_inputs: [], publish_platform: "official_site", user_instructions: "", }); const article = await repository.saveOptimizedArticle(job.id, { title: "Optimized", summary: "Summary", body_markdown: "Body", image_suggestions: [], changed_sections: [], requires_user_confirmation: [], }); await repository.saveRubricVersion({ id: "rubric_geo_v1", version: "v1", name: "GEO rubric", dimensions: [], formula: "weighted_average_0_to_10", is_active: true, created_at: "2026-06-24T00:00:00.000Z", }); const scoringRun = await repository.saveScoringRun({ id: "score_1", job_id: job.id, revision: article.revision ?? 1, rubric_version_id: "rubric_geo_v1", dimension_scores: { readability: 4 }, composite_score: 8, rationale: "Readable", created_at: "2026-06-24T00:00:00.000Z", }); const publication = await repository.createPublicationRecord({ job_id: job.id, revision: article.revision ?? 1, platform: "official_site", url: "https://example.com/article", published_at: "2026-06-24T12:00:00.000Z", status: "published", notes: "官网首发", }); const snapshot = await repository.savePerformanceSnapshot({ id: "perf_1", publication_id: publication.id, source: "manual", window_label: "T+7d", metrics: { views: 1200 }, feedback_summary: "用户追问案例依据", snapshot_at: "2026-07-01T12:00:00.000Z", }); const event = await repository.saveCalibrationEvent({ id: "cal_1", publication_id: publication.id, scoring_run_id: scoringRun.id, performance_snapshot_id: snapshot.id, direction: "better_than_expected", observations: ["表现高于预期"], recommended_action: "继续积累样本", created_at: "2026-07-01T12:10:00.000Z", }); await expect(repository.listPublicationRecords(job.id)).resolves.toHaveLength(1); await expect(repository.getLatestScoringRun(job.id, article.revision ?? 1)) .resolves.toMatchObject({ id: scoringRun.id, composite_score: 8 }); await expect(repository.listPerformanceSnapshots(publication.id)) .resolves.toEqual([expect.objectContaining({ id: snapshot.id })]); expect(event.observations).toEqual(["表现高于预期"]); }); ``` - [ ] **Step 2: Run failing repository test** Run: ```bash npm test -- src/lib/db/__tests__/repository.test.ts -t "persists scoring" ``` Expected: FAIL because repository methods do not exist. - [ ] **Step 3: Extend repository interface** In `src/lib/db/repository.ts`, import calibration types and add methods to `AppRepository`: ```ts import type { CalibrationEvent, PerformanceSnapshot, PublicationRecord, RubricVersion, ScoringRun, } from "../calibration/types"; ``` Add these interface methods: ```ts saveRubricVersion(rubric: RubricVersion): Promise; saveScoringRun(run: ScoringRun): Promise; getLatestScoringRun(jobId: string, revision: number): Promise; createPublicationRecord( input: Omit, ): Promise; listPublicationRecords(jobId: string): Promise; getPublicationRecord(id: string): Promise; savePerformanceSnapshot(snapshot: PerformanceSnapshot): Promise; listPerformanceSnapshots(publicationId: string): Promise; saveCalibrationEvent(event: CalibrationEvent): Promise; ``` - [ ] **Step 4: Add SQLite helper types and functions** In `src/lib/db/repositories.ts`, import calibration types and add row interfaces: ```ts import type { CalibrationEvent, PerformanceSnapshot, PublicationRecord, RubricVersion, ScoringRun, } from "../calibration/types"; ``` Add row interfaces near existing row interfaces: ```ts interface RubricVersionRow { id: string; version: string; name: string; dimensions: string; formula: "weighted_average_0_to_10"; is_active: number; created_at: string; } interface ScoringRunRow { id: string; job_id: string; revision: number; rubric_version_id: string; dimension_scores: string; composite_score: number; rationale: string; created_at: string; } interface PublicationRecordRow { id: string; job_id: string; revision: number; platform: PublishPlatform; url: string; published_at: string; status: "draft" | "published" | "archived"; notes: string; created_at: string; updated_at: string; } interface PerformanceSnapshotRow { id: string; publication_id: string; source: "manual" | `adapter:${string}`; window_label: string; metrics: string; feedback_summary: string; raw_reference: string | null; snapshot_at: string; } interface CalibrationEventRow { id: string; publication_id: string; scoring_run_id: string; performance_snapshot_id: string; direction: CalibrationEvent["direction"]; observations: string; recommended_action: string; created_at: string; } ``` Add mapper helpers: ```ts function toRubricVersion(row: RubricVersionRow): RubricVersion { return { ...row, dimensions: parseJson(row.dimensions), is_active: Boolean(row.is_active), }; } function toScoringRun(row: ScoringRunRow): ScoringRun { return { ...row, dimension_scores: parseJson>(row.dimension_scores), }; } function toPerformanceSnapshot(row: PerformanceSnapshotRow): PerformanceSnapshot { return { ...row, raw_reference: row.raw_reference ?? undefined, metrics: parseJson(row.metrics), }; } function toCalibrationEvent(row: CalibrationEventRow): CalibrationEvent { return { ...row, observations: parseJson(row.observations), }; } ``` Add exported functions after `getLatestQaReport`: ```ts export function saveRubricVersion(dbPath: string | undefined, rubric: RubricVersion) { return withDb(dbPath, (db) => { db.prepare( `insert into rubric_versions ( id, version, name, dimensions, formula, is_active, created_at ) values (?, ?, ?, ?, ?, ?, ?) on conflict(id) do update set version = excluded.version, name = excluded.name, dimensions = excluded.dimensions, formula = excluded.formula, is_active = excluded.is_active`, ).run( rubric.id, rubric.version, rubric.name, serialize(rubric.dimensions), rubric.formula, rubric.is_active ? 1 : 0, rubric.created_at, ); return rubric; }); } export function saveScoringRun(dbPath: string | undefined, run: ScoringRun) { return withDb(dbPath, (db) => { db.prepare( `insert into scoring_runs ( id, job_id, revision, rubric_version_id, dimension_scores, composite_score, rationale, created_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ).run( run.id, run.job_id, run.revision, run.rubric_version_id, serialize(run.dimension_scores), run.composite_score, run.rationale, run.created_at, ); return run; }); } export function getLatestScoringRun( dbPath: string | undefined, jobId: string, revision: number, ) { return withDb(dbPath, (db) => { const row = db .prepare( `select * from scoring_runs where job_id = ? and revision = ? order by created_at desc limit 1`, ) .get(jobId, revision) as ScoringRunRow | undefined; return row ? toScoringRun(row) : null; }); } export function createPublicationRecord( dbPath: string | undefined, input: Omit, ) { return withDb(dbPath, (db) => { const timestamp = nowIso(); const record: PublicationRecord = { id: `pub_${nanoid(10)}`, ...input, created_at: timestamp, updated_at: timestamp, }; db.prepare( `insert into publication_records ( id, job_id, revision, platform, url, published_at, status, notes, created_at, updated_at ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, ).run( record.id, record.job_id, record.revision, record.platform, record.url, record.published_at, record.status, record.notes, record.created_at, record.updated_at, ); return record; }); } export function listPublicationRecords(dbPath: string | undefined, jobId: string) { return withDb(dbPath, (db) => db .prepare("select * from publication_records where job_id = ? order by published_at desc") .all(jobId) .map((row) => row as PublicationRecord), ); } export function getPublicationRecord(dbPath: string | undefined, id: string) { return withDb(dbPath, (db) => { const row = db .prepare("select * from publication_records where id = ?") .get(id) as PublicationRecordRow | undefined; return row ?? null; }); } export function savePerformanceSnapshot( dbPath: string | undefined, snapshot: PerformanceSnapshot, ) { return withDb(dbPath, (db) => { db.prepare( `insert into performance_snapshots ( id, publication_id, source, window_label, metrics, feedback_summary, raw_reference, snapshot_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ).run( snapshot.id, snapshot.publication_id, snapshot.source, snapshot.window_label, serialize(snapshot.metrics), snapshot.feedback_summary, snapshot.raw_reference ?? null, snapshot.snapshot_at, ); return snapshot; }); } export function listPerformanceSnapshots( dbPath: string | undefined, publicationId: string, ) { return withDb(dbPath, (db) => db .prepare( "select * from performance_snapshots where publication_id = ? order by snapshot_at desc", ) .all(publicationId) .map((row) => toPerformanceSnapshot(row as PerformanceSnapshotRow)), ); } export function saveCalibrationEvent( dbPath: string | undefined, event: CalibrationEvent, ) { return withDb(dbPath, (db) => { db.prepare( `insert into calibration_events ( id, publication_id, scoring_run_id, performance_snapshot_id, direction, observations, recommended_action, created_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ).run( event.id, event.publication_id, event.scoring_run_id, event.performance_snapshot_id, event.direction, serialize(event.observations), event.recommended_action, event.created_at, ); return event; }); } ``` - [ ] **Step 5: Expose SQLite methods** In `src/lib/db/sqlite-repository.ts`, add the imported helper names and methods: ```ts createPublicationRecord, getLatestScoringRun, getPublicationRecord, listPerformanceSnapshots, listPublicationRecords, saveCalibrationEvent, savePerformanceSnapshot, saveRubricVersion, saveScoringRun, ``` Add implementations in `createSqliteRepository`: ```ts saveRubricVersion(rubric) { return Promise.resolve(saveRubricVersion(dbPath, rubric)); }, saveScoringRun(run) { return Promise.resolve(saveScoringRun(dbPath, run)); }, getLatestScoringRun(jobId, revision) { return Promise.resolve(getLatestScoringRun(dbPath, jobId, revision)); }, createPublicationRecord(input) { return Promise.resolve(createPublicationRecord(dbPath, input)); }, listPublicationRecords(jobId) { return Promise.resolve(listPublicationRecords(dbPath, jobId)); }, getPublicationRecord(id) { return Promise.resolve(getPublicationRecord(dbPath, id)); }, savePerformanceSnapshot(snapshot) { return Promise.resolve(savePerformanceSnapshot(dbPath, snapshot)); }, listPerformanceSnapshots(publicationId) { return Promise.resolve(listPerformanceSnapshots(dbPath, publicationId)); }, saveCalibrationEvent(event) { return Promise.resolve(saveCalibrationEvent(dbPath, event)); }, ``` - [ ] **Step 6: Add D1 methods** In `src/lib/db/d1-repository.ts`, import calibration types: ```ts import type { CalibrationEvent, PerformanceSnapshot, PublicationRecord, RubricVersion, ScoringRun, } from "../calibration/types"; ``` Add row interfaces near the existing D1 row interfaces: ```ts interface RubricVersionRow { id: string; version: string; name: string; dimensions: string; formula: "weighted_average_0_to_10"; is_active: number; created_at: string; } interface ScoringRunRow { id: string; job_id: string; revision: number; rubric_version_id: string; dimension_scores: string; composite_score: number; rationale: string; created_at: string; } interface PublicationRecordRow { id: string; job_id: string; revision: number; platform: PublishPlatform; url: string; published_at: string; status: "draft" | "published" | "archived"; notes: string; created_at: string; updated_at: string; } interface PerformanceSnapshotRow { id: string; publication_id: string; source: "manual" | `adapter:${string}`; window_label: string; metrics: string; feedback_summary: string; raw_reference: string | null; snapshot_at: string; } interface CalibrationEventRow { id: string; publication_id: string; scoring_run_id: string; performance_snapshot_id: string; direction: CalibrationEvent["direction"]; observations: string; recommended_action: string; created_at: string; } ``` Add mapper helpers below `toArticleJob`: ```ts function toRubricVersion(row: RubricVersionRow): RubricVersion { return { ...row, dimensions: parseJson(row.dimensions), is_active: Boolean(row.is_active), }; } function toScoringRun(row: ScoringRunRow): ScoringRun { return { ...row, dimension_scores: parseJson>(row.dimension_scores), }; } function toPerformanceSnapshot(row: PerformanceSnapshotRow): PerformanceSnapshot { return { ...row, raw_reference: row.raw_reference ?? undefined, metrics: parseJson(row.metrics), }; } function toCalibrationEvent(row: CalibrationEventRow): CalibrationEvent { return { ...row, observations: parseJson(row.observations), }; } ``` Add these methods inside the object returned by `createD1Repository` after `getLatestQaReport`: ```ts async saveRubricVersion(rubric) { await db .prepare( `insert into rubric_versions ( id, version, name, dimensions, formula, is_active, created_at ) values (?, ?, ?, ?, ?, ?, ?) on conflict(id) do update set version = excluded.version, name = excluded.name, dimensions = excluded.dimensions, formula = excluded.formula, is_active = excluded.is_active`, ) .bind( rubric.id, rubric.version, rubric.name, serialize(rubric.dimensions), rubric.formula, rubric.is_active ? 1 : 0, rubric.created_at, ) .run(); return rubric; }, async saveScoringRun(run) { await db .prepare( `insert into scoring_runs ( id, job_id, revision, rubric_version_id, dimension_scores, composite_score, rationale, created_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ) .bind( run.id, run.job_id, run.revision, run.rubric_version_id, serialize(run.dimension_scores), run.composite_score, run.rationale, run.created_at, ) .run(); return run; }, async getLatestScoringRun(jobId, revision) { const row = await db .prepare( `select * from scoring_runs where job_id = ? and revision = ? order by created_at desc limit 1`, ) .bind(jobId, revision) .first(); return row ? toScoringRun(row) : null; }, async createPublicationRecord(input) { const timestamp = nowIso(); const record: PublicationRecord = { id: `pub_${nanoid(10)}`, ...input, created_at: timestamp, updated_at: timestamp, }; await db .prepare( `insert into publication_records ( id, job_id, revision, platform, url, published_at, status, notes, created_at, updated_at ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, ) .bind( record.id, record.job_id, record.revision, record.platform, record.url, record.published_at, record.status, record.notes, record.created_at, record.updated_at, ) .run(); return record; }, async listPublicationRecords(jobId) { const result = await db .prepare( "select * from publication_records where job_id = ? order by published_at desc", ) .bind(jobId) .all(); return result.results; }, async getPublicationRecord(id) { return db .prepare("select * from publication_records where id = ?") .bind(id) .first(); }, async savePerformanceSnapshot(snapshot) { await db .prepare( `insert into performance_snapshots ( id, publication_id, source, window_label, metrics, feedback_summary, raw_reference, snapshot_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ) .bind( snapshot.id, snapshot.publication_id, snapshot.source, snapshot.window_label, serialize(snapshot.metrics), snapshot.feedback_summary, snapshot.raw_reference ?? null, snapshot.snapshot_at, ) .run(); return snapshot; }, async listPerformanceSnapshots(publicationId) { const result = await db .prepare( "select * from performance_snapshots where publication_id = ? order by snapshot_at desc", ) .bind(publicationId) .all(); return result.results.map(toPerformanceSnapshot); }, async saveCalibrationEvent(event) { await db .prepare( `insert into calibration_events ( id, publication_id, scoring_run_id, performance_snapshot_id, direction, observations, recommended_action, created_at ) values (?, ?, ?, ?, ?, ?, ?, ?)`, ) .bind( event.id, event.publication_id, event.scoring_run_id, event.performance_snapshot_id, event.direction, serialize(event.observations), event.recommended_action, event.created_at, ) .run(); return event; }, ``` - [ ] **Step 7: Add D1 representative test** Append to `src/lib/db/__tests__/d1-repository.test.ts`: ```ts test("saves a manual performance snapshot using D1 prepare and bind", async () => { const run = vi.fn().mockResolvedValue({ success: true }); const bind = vi.fn().mockReturnValue({ run }); const prepare = vi.fn().mockReturnValue({ bind }); const db = { prepare } as unknown as D1Database; const repository = createD1Repository(db); await repository.savePerformanceSnapshot({ id: "perf_123", publication_id: "pub_123", source: "manual", window_label: "T+7d", metrics: { views: 1200 }, feedback_summary: "用户追问案例依据", snapshot_at: "2026-07-01T12:00:00.000Z", }); expect(prepare).toHaveBeenCalledWith( expect.stringContaining("insert into performance_snapshots"), ); expect(bind).toHaveBeenCalledWith( "perf_123", "pub_123", "manual", "T+7d", '{"views":1200}', "用户追问案例依据", null, "2026-07-01T12:00:00.000Z", ); }); ``` - [ ] **Step 8: Run repository tests** Run: ```bash npm test -- src/lib/db/__tests__/repository.test.ts src/lib/db/__tests__/d1-repository.test.ts ``` Expected: PASS. - [ ] **Step 9: Commit Task 4** ```bash git add src/lib/db/repositories.ts src/lib/db/repository.ts src/lib/db/sqlite-repository.ts src/lib/db/d1-repository.ts src/lib/db/__tests__/repository.test.ts src/lib/db/__tests__/d1-repository.test.ts git commit -m "接入发布校准仓储接口" ``` ## Task 5: Calibration API Routes **Files:** - Create: `src/app/api/jobs/[jobId]/calibration/score/route.ts` - Create: `src/app/api/jobs/[jobId]/publications/route.ts` - Create: `src/app/api/publications/[publicationId]/performance/route.ts` - Modify: `src/app/api/__tests__/jobs.test.ts` - [ ] **Step 1: Write route tests** In `src/app/api/__tests__/jobs.test.ts`, import the new routes: ```ts import { POST as scoreJob } from "../jobs/[jobId]/calibration/score/route"; import { GET as listPublications, POST as createPublication, } from "../jobs/[jobId]/publications/route"; import { POST as recordPerformance } from "../publications/[publicationId]/performance/route"; ``` Append this test inside `describe("job API routes", () => { ... })` after the optimize success tests: ```ts it("scores a revision, registers publication, and records manual performance", async () => { const { job } = await createJobFixture(); await confirmFactCard( request(validFactCard), params<{ jobId: string }>({ jobId: job.id }), ); llmMocks.generateValidatedJson .mockResolvedValueOnce({ title: "示例科技 GEO 内容优化方案", summary: "示例科技有限公司面向市场团队提供GEO内容优化服务。", body_markdown: "## 服务能力\n示例科技有限公司提供GEO内容优化服务。\n## 可信依据\n保留事实卡中的8年经验。", image_suggestions: [], changed_sections: ["title", "body"], requires_user_confirmation: [], }) .mockResolvedValueOnce({ checks: [] }); await optimizeJob(request({}), params<{ jobId: string }>({ jobId: job.id })); const scoreResponse = await scoreJob( request({}), params<{ jobId: string }>({ jobId: job.id }), ); const scoreBody = (await scoreResponse.json()) as { scoringRun: { id: string; composite_score: number }; }; expect(scoreResponse.status).toBe(201); expect(scoreBody.scoringRun.composite_score).toBeGreaterThan(0); const publicationResponse = await createPublication( request({ platform: "official_site", url: "https://example.com/article", published_at: "2026-06-24T12:00:00.000Z", notes: "官网首发", }), params<{ jobId: string }>({ jobId: job.id }), ); const publicationBody = (await publicationResponse.json()) as { publication: { id: string; notes: string }; }; expect(publicationResponse.status).toBe(201); expect(publicationBody.publication.notes).toBe("官网首发"); const listResponse = await listPublications( request({}), params<{ jobId: string }>({ jobId: job.id }), ); const listBody = (await listResponse.json()) as { publications: Array<{ id: string }>; }; expect(listResponse.status).toBe(200); expect(listBody.publications).toHaveLength(1); const performanceResponse = await recordPerformance( request({ window_label: "T+7d", views: "1200", inquiries: "7", feedback_summary: "用户追问案例依据", }), params<{ publicationId: string }>({ publicationId: publicationBody.publication.id, }), ); const performanceBody = (await performanceResponse.json()) as { snapshot: { metrics: { views: number } }; calibrationEvent: { observations: string[] }; }; expect(performanceResponse.status).toBe(201); expect(performanceBody.snapshot.metrics.views).toBe(1200); expect(performanceBody.calibrationEvent.observations.length).toBeGreaterThan(0); }); ``` - [ ] **Step 2: Run failing route test** Run: ```bash npm test -- src/app/api/__tests__/jobs.test.ts -t "scores a revision" ``` Expected: FAIL because route modules do not exist. - [ ] **Step 3: Add scoring route** Create `src/app/api/jobs/[jobId]/calibration/score/route.ts`: ```ts import { NextResponse } from "next/server"; import { requireApiAccess } from "../../../../../../lib/api/auth"; import { GEO_RUBRIC_V1, scoreOptimizedArticle } from "../../../../../../lib/calibration/scoring"; import { getRepositoryFromRuntime } from "../../../../../../lib/db/repository"; interface RouteContext { params: Promise<{ jobId: string }>; } export async function POST(request: Request, context: RouteContext) { const access = requireApiAccess(request); if (!access.ok) return access.response; const { jobId } = await context.params; const repository = getRepositoryFromRuntime(); const article = await repository.getLatestOptimizedArticle(jobId); const qaReport = await repository.getLatestQaReport(jobId); if (!article || !qaReport) { return NextResponse.json( { error: "Optimize the article before scoring calibration" }, { status: 409 }, ); } await repository.saveRubricVersion(GEO_RUBRIC_V1); const scoringRun = await repository.saveScoringRun( scoreOptimizedArticle({ jobId, article, qaReport }), ); return NextResponse.json({ scoringRun }, { status: 201 }); } ``` - [ ] **Step 4: Add publication route** Create `src/app/api/jobs/[jobId]/publications/route.ts`: ```ts import { NextResponse } from "next/server"; import { requireApiAccess } from "../../../../../lib/api/auth"; import { publicationInputSchema } from "../../../../../lib/calibration/validation"; import { getRepositoryFromRuntime } from "../../../../../lib/db/repository"; interface RouteContext { params: Promise<{ jobId: string }>; } export async function GET(request: Request, context: RouteContext) { const access = requireApiAccess(request); if (!access.ok) return access.response; const { jobId } = await context.params; const repository = getRepositoryFromRuntime(); return NextResponse.json({ publications: await repository.listPublicationRecords(jobId), }); } export async function POST(request: Request, context: RouteContext) { const access = requireApiAccess(request); if (!access.ok) return access.response; const { jobId } = await context.params; const repository = getRepositoryFromRuntime(); const article = await repository.getLatestOptimizedArticle(jobId); if (!article?.revision) { return NextResponse.json( { error: "Optimize the article before registering publication" }, { status: 409 }, ); } const input = publicationInputSchema.parse(await request.json()); const publication = await repository.createPublicationRecord({ job_id: jobId, revision: article.revision, platform: input.platform, url: input.url, published_at: input.published_at, status: "published", notes: input.notes, }); return NextResponse.json({ publication }, { status: 201 }); } ``` - [ ] **Step 5: Add performance route** Create `src/app/api/publications/[publicationId]/performance/route.ts`: ```ts import { NextResponse } from "next/server"; import { requireApiAccess } from "../../../../lib/api/auth"; import { createManualPerformanceAdapter } from "../../../../lib/calibration/manual-adapter"; import { createCalibrationEvent } from "../../../../lib/calibration/scoring"; import { getRepositoryFromRuntime } from "../../../../lib/db/repository"; interface RouteContext { params: Promise<{ publicationId: string }>; } export async function POST(request: Request, context: RouteContext) { const access = requireApiAccess(request); if (!access.ok) return access.response; const { publicationId } = await context.params; const repository = getRepositoryFromRuntime(); const publication = await repository.getPublicationRecord(publicationId); if (!publication) { return NextResponse.json({ error: "Publication not found" }, { status: 404 }); } const scoringRun = await repository.getLatestScoringRun( publication.job_id, publication.revision, ); const qaReport = await repository.getLatestQaReport(publication.job_id); if (!scoringRun || !qaReport) { return NextResponse.json( { error: "Score the optimized revision before recording performance" }, { status: 409 }, ); } const adapter = createManualPerformanceAdapter(); const snapshot = await repository.savePerformanceSnapshot( await adapter.fetch({ publication, window_label: "manual", manualInput: await request.json(), }), ); const calibrationEvent = await repository.saveCalibrationEvent( createCalibrationEvent({ scoringRun, qaReport, snapshot }), ); return NextResponse.json({ snapshot, calibrationEvent }, { status: 201 }); } ``` - [ ] **Step 6: Run route tests** Run: ```bash npm test -- src/app/api/__tests__/jobs.test.ts -t "scores a revision" ``` Expected: PASS. - [ ] **Step 7: Commit Task 5** ```bash git add 'src/app/api/jobs/[jobId]/calibration/score/route.ts' 'src/app/api/jobs/[jobId]/publications/route.ts' 'src/app/api/publications/[publicationId]/performance/route.ts' src/app/api/__tests__/jobs.test.ts git commit -m "新增发布校准接口" ``` ## Task 6: Frontend Calibration Panel **Files:** - Create: `src/components/performance-calibration-panel.tsx` - Modify: `src/app/page.tsx` - Modify: `src/app/globals.css` - [ ] **Step 1: Create panel component** Create `src/components/performance-calibration-panel.tsx`: ```tsx "use client"; import { useState } from "react"; import type { PublishPlatform } from "../lib/domain/types"; interface PerformanceCalibrationPanelProps { apiAccessKey: string; jobId: string | null; optimizedRevision: number | null; } interface ScoreResponse { scoringRun?: { id: string; composite_score: number; rationale: string }; error?: string; } interface PublicationResponse { publication?: { id: string; url: string }; error?: string; } interface PerformanceResponse { snapshot?: { metrics: Record }; calibrationEvent?: { observations: string[]; recommended_action: string }; error?: string; } export function PerformanceCalibrationPanel({ apiAccessKey, jobId, optimizedRevision, }: PerformanceCalibrationPanelProps) { const [platform, setPlatform] = useState("official_site"); const [url, setUrl] = useState(""); const [publishedAt, setPublishedAt] = useState(() => new Date().toISOString().slice(0, 16), ); const [publicationId, setPublicationId] = useState(null); const [views, setViews] = useState(""); const [clicks, setClicks] = useState(""); const [inquiries, setInquiries] = useState(""); const [feedbackSummary, setFeedbackSummary] = useState(""); const [message, setMessage] = useState(""); const [observations, setObservations] = useState([]); const disabled = !jobId || !optimizedRevision; async function scoreRevision() { if (!jobId) return; setMessage(""); const response = await fetch(`/api/jobs/${jobId}/calibration/score`, { method: "POST", headers: apiHeaders(apiAccessKey), }); const body = (await response.json()) as ScoreResponse; if (!response.ok || !body.scoringRun) { setMessage(body.error ?? "评分失败"); return; } setMessage( `校准评分 ${body.scoringRun.composite_score}/10：${body.scoringRun.rationale}`, ); } async function registerPublication() { if (!jobId) return; setMessage(""); const response = await fetch(`/api/jobs/${jobId}/publications`, { method: "POST", headers: apiHeaders(apiAccessKey), body: JSON.stringify({ platform, url, published_at: new Date(publishedAt).toISOString(), notes: "", }), }); const body = (await response.json()) as PublicationResponse; if (!response.ok || !body.publication) { setMessage(body.error ?? "发布记录保存失败"); return; } setPublicationId(body.publication.id); setMessage("发布记录已保存。"); } async function recordPerformance() { if (!publicationId) return; setMessage(""); const response = await fetch(`/api/publications/${publicationId}/performance`, { method: "POST", headers: apiHeaders(apiAccessKey), body: JSON.stringify({ window_label: "T+7d", views, clicks, inquiries, feedback_summary: feedbackSummary, }), }); const body = (await response.json()) as PerformanceResponse; if (!response.ok || !body.calibrationEvent) { setMessage(body.error ?? "表现数据保存失败"); return; } setObservations(body.calibrationEvent.observations); setMessage(body.calibrationEvent.recommended_action); } return (
发布表现校准