Files
knowledge-governance/web/src/qaQuality.ts
T
姚章浩 09b2c1dce5
build / build (push) Successful in 1m17s
fix(qa): 表头筛选并统一未覆盖正确性待确认
修正筛选入口位置:五项条件在表头就地选择,保持完整集筛选与无感续载。
统一固定规则:未覆盖一律待确认,原问答/人工模型证据不改写,已覆盖仍保留点踩优先。
验证:行为红绿、前端/Go全套及隔离PostgreSQL全mirror竞态通过;完整本地门禁与原生备份真实恢复通过。
2026-10-25 13:58:08 +08:00

387 lines
12 KiB
TypeScript

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<string, string> = {
covered: '已覆盖',
uncovered: '未覆盖',
partial: '部分覆盖',
pending: '待确认',
excluded: '不计入',
correct: '正确',
incorrect: '错误',
unreviewed: '未复核',
reviewed: '已复核',
stale: '待重新核对',
}
const bad = (): never => {
throw new Error('质量留档响应无效,未展示可能失真的结论')
}
const obj = (v: unknown): Record<string, unknown> =>
v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : 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,
},
}
}