export interface QualityFields { coverage: string correctness: string product_category: string problem_type: string root_cause: string exclusion_reason: string } export interface QualityCheck { input_available: boolean id: number input_epoch: number input_hash: string result: { state: string; verdict?: string; rule_version: string; matched_text?: string } source: { verdict: string; reason_code: string; evaluator_version: string } created_at: string } export interface QualityReview { revision: number input_epoch: number input_hash: string fields: QualityFields reason: string reviewer: string created_at: string } export interface QAQuality { effective_source?: 'master-effective-fields-v1' feedback_rule?: 'downvote-is-incorrect-v1' correctness_rule?: 'coverage-correctness-v1' input_hash: string input_epoch: number revision: number state: 'unreviewed' | 'reviewed' | 'stale' automatic: QualityCheck latest_review: QualityReview | null effective: QualityFields } export interface QualityHistory { reviews: QualityReview[] checks: QualityCheck[] next_review: number next_check: number } export interface QualitySnapshot { input_epoch: number input_hash: string created_at: string payload: { id: string; question: string; answer: string; status: string; references: unknown; media: unknown } } export interface QualityRate { numerator: number denominator: number percent: number | null } export interface QualityRates { policy_version: 'quality-rates-human-first-v1' coverage: QualityRate correctness: QualityRate breakdown: { covered: number uncovered: number partial: number pending: number unassessed: number excluded: number stale: number covered_correct: number covered_incorrect: number covered_pending: number covered_unassessed: number } } export interface QualitySummary { summary: { total: number reviewed: number unreviewed: number stale: number pending_confirmation: number rule_uncovered: number rates: QualityRates } start: string end: string keyword: string as_of: string scope: 'whole_filter' ai_state: 'not_configured' } export const emptyQualityFields: QualityFields = { coverage: '', correctness: '', product_category: '', problem_type: '', root_cause: '', exclusion_reason: '', } export const qualityLabels: Record = { covered: '已覆盖', uncovered: '未覆盖', partial: '部分覆盖', pending: '待确认', excluded: '不计入', correct: '正确', incorrect: '错误', unreviewed: '未复核', reviewed: '已复核', stale: '待重新核对', } const bad = (): never => { throw new Error('质量留档响应无效,未展示可能失真的结论') } const obj = (v: unknown): Record => v && typeof v === 'object' && !Array.isArray(v) ? (v as Record) : bad() const text = (v: unknown): string => (typeof v === 'string' ? v : bad()) const num = (v: unknown): number => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : bad()) const positive = (v: unknown): number => { const n = num(v) return n > 0 ? n : bad() } const hash = (v: unknown): string => { const t = text(v) return /^[a-f0-9]{64}$/.test(t) ? t : bad() } const stamp = (v: unknown): string => { const t = text(v) return Number.isFinite(Date.parse(t)) ? t : bad() } function fields(v: unknown, complete = false): QualityFields { const r = obj(v) const f = { coverage: text(r.coverage), correctness: text(r.correctness), product_category: text(r.product_category), problem_type: text(r.problem_type), root_cause: text(r.root_cause), exclusion_reason: text(r.exclusion_reason), } if ( !['', 'covered', 'uncovered', 'partial', 'pending', 'excluded'].includes(f.coverage) || !['', 'correct', 'incorrect', 'pending'].includes(f.correctness) || (complete && (!f.coverage || !f.correctness)) || (f.correctness === 'correct' && f.root_cause !== '') || (f.coverage === 'excluded' && !f.exclusion_reason.trim()) || (f.coverage !== 'excluded' && f.exclusion_reason !== '') ) return bad() return f } function check(value: unknown): QualityCheck { const v = obj(value), r = obj(v.result), s = obj(v.source) const state = text(r.state), rule_version = text(r.rule_version) if ( !rule_version || (state !== 'pending' && state !== 'checked') || (state === 'checked' && (r.verdict !== 'uncovered' || r.matched_text !== '暂无已发布')) || (state === 'pending' && r.verdict !== undefined) ) return bad() return { input_available: typeof v.input_available === 'boolean' ? v.input_available : bad(), id: positive(v.id), input_epoch: positive(v.input_epoch), input_hash: hash(v.input_hash), result: { state, rule_version, ...(r.verdict === undefined ? {} : { verdict: text(r.verdict), matched_text: text(r.matched_text) }), }, source: { verdict: text(s.verdict), reason_code: text(s.reason_code), evaluator_version: text(s.evaluator_version), }, created_at: stamp(v.created_at), } } function review(value: unknown): QualityReview { const v = obj(value), reason = text(v.reason), reviewer = text(v.reviewer) if (!reason.trim() || !reviewer) return bad() return { revision: positive(v.revision), input_epoch: positive(v.input_epoch), input_hash: hash(v.input_hash), fields: fields(v.fields, true), reason, reviewer, created_at: stamp(v.created_at), } } export function parseQAQuality(value: unknown, allowMasterProjection = false, hasDownvote = false): QAQuality { const v = obj(value), state = text(v.state) if (!['unreviewed', 'reviewed', 'stale'].includes(state)) return bad() const automatic = check(v.automatic), latest_review = v.latest_review === null ? null : review(v.latest_review), input_hash = hash(v.input_hash), input_epoch = positive(v.input_epoch), revision = num(v.revision), effective = fields(v.effective) if ( automatic.input_hash !== input_hash || automatic.input_epoch !== input_epoch || (latest_review && latest_review.revision !== revision) || (!latest_review && revision !== 0) ) return bad() const actual = latest_review ? latest_review.input_hash === input_hash && latest_review.input_epoch === input_epoch ? 'reviewed' : 'stale' : 'unreviewed' if (state !== actual) return bad() const expected = state === 'reviewed' ? latest_review!.fields : { ...emptyQualityFields, coverage: automatic.result.verdict || '' } const master = v.effective_source === 'master-effective-fields-v1' if (v.effective_source !== undefined && (!master || !allowMasterProjection)) return bad() const coverageRule = v.correctness_rule === 'coverage-correctness-v1' if ( v.correctness_rule !== undefined && (!coverageRule || !master || !allowMasterProjection || (effective.coverage === 'uncovered' ? effective.correctness !== 'pending' : effective.correctness !== '')) ) return bad() const downvoteRule = v.feedback_rule === 'downvote-is-incorrect-v1' if ( v.feedback_rule !== undefined && (!downvoteRule || !master || !allowMasterProjection || !hasDownvote || effective.correctness !== 'incorrect') ) return bad() for (const key of Object.keys(expected) as (keyof QualityFields)[]) { // Explicit fixed rules may replace effective correctness, never the historical review. if (master) { if ( state === 'reviewed' && !( (downvoteRule || (coverageRule && (effective.coverage === 'uncovered' || expected.correctness === 'pending'))) && key === 'correctness' ) && (expected[key] !== '' || (key === 'root_cause' && expected.correctness === 'correct')) && expected[key] !== effective[key] ) return bad() } else if (expected[key] !== effective[key]) return bad() } return { input_hash, input_epoch, revision, state: state as QAQuality['state'], automatic, latest_review, effective, ...(master ? { effective_source: 'master-effective-fields-v1' as const } : {}), ...(downvoteRule ? { feedback_rule: 'downvote-is-incorrect-v1' as const } : {}), ...(coverageRule ? { correctness_rule: 'coverage-correctness-v1' as const } : {}), } } function qualityRate(value: unknown): QualityRate { const v = obj(value), numerator = num(v.numerator), denominator = num(v.denominator) if (numerator > denominator) return bad() if (denominator === 0) { if (v.percent !== null) return bad() return { numerator, denominator, percent: null } } if ( typeof v.percent !== 'number' || !Number.isFinite(v.percent) || v.percent < 0 || v.percent > 100 || Math.abs(v.percent - (100 * numerator) / denominator) > 1e-8 ) return bad() return { numerator, denominator, percent: v.percent } } export { qualityRate as parseQualityRate } function qualityRates(value: unknown, total: number, stale: number): QualityRates { const v = obj(value), r = obj(v.breakdown) const b = { covered: num(r.covered), uncovered: num(r.uncovered), partial: num(r.partial), pending: num(r.pending), unassessed: num(r.unassessed), excluded: num(r.excluded), stale: num(r.stale), covered_correct: num(r.covered_correct), covered_incorrect: num(r.covered_incorrect), covered_pending: num(r.covered_pending), covered_unassessed: num(r.covered_unassessed), } const coverage = qualityRate(v.coverage), correctness = qualityRate(v.correctness) if ( v.policy_version !== 'quality-rates-human-first-v1' || b.stale !== stale || num(b.covered + b.uncovered + b.partial + b.pending + b.unassessed + b.excluded + b.stale) !== total || num(b.covered_correct + b.covered_incorrect + b.covered_pending + b.covered_unassessed) !== b.covered || coverage.numerator !== b.covered || coverage.denominator !== b.covered + b.uncovered + b.partial || correctness.numerator !== b.covered_correct || correctness.denominator !== b.covered_correct + b.covered_incorrect ) return bad() return { policy_version: 'quality-rates-human-first-v1', coverage, correctness, breakdown: b } } export function parseQualitySummary(value: unknown): QualitySummary { const v = obj(value), s = obj(v.summary), summary = { total: num(s.total), reviewed: num(s.reviewed), unreviewed: num(s.unreviewed), stale: num(s.stale), pending_confirmation: num(s.pending_confirmation), rule_uncovered: num(s.rule_uncovered), rates: qualityRates(s.rates, num(s.total), num(s.stale)), } const start = stamp(v.start), end = stamp(v.end) if ( v.scope !== 'whole_filter' || v.ai_state !== 'not_configured' || summary.total !== summary.reviewed + summary.unreviewed + summary.stale || summary.pending_confirmation > summary.reviewed || summary.rule_uncovered > summary.total || Date.parse(start) >= Date.parse(end) ) return bad() return { summary, start, end, keyword: text(v.keyword), as_of: stamp(v.as_of), scope: 'whole_filter', ai_state: 'not_configured', } } export function parseQualityHistory(value: unknown): QualityHistory { const v = obj(value) if (!Array.isArray(v.reviews) || !Array.isArray(v.checks)) return bad() const reviews = v.reviews.map(review), checks = v.checks.map(check), next_review = num(v.next_review), next_check = num(v.next_check) if ( reviews.length > 20 || checks.length > 20 || reviews.some((r, i) => i > 0 && r.revision >= reviews[i - 1].revision) || checks.some((c, i) => i > 0 && c.id >= checks[i - 1].id) || (next_review && next_review !== reviews.at(-1)?.revision) || (next_check && next_check !== checks.at(-1)?.id) ) return bad() return { reviews, checks, next_review, next_check } } export function parseQualitySnapshot(value: unknown): QualitySnapshot { const v = obj(value), p = obj(v.payload) return { input_epoch: positive(v.input_epoch), input_hash: hash(v.input_hash), created_at: stamp(v.created_at), payload: { id: text(p.id), question: text(p.question), answer: text(p.answer), status: text(p.status), references: p.references, media: p.media, }, } }