Files
knowledge-governance/web/src/QAQuality.tsx
T
姚章浩 65653e5c01
build / build (push) Successful in 1m14s
fix(qa): 已覆盖正确性改为问题答案二元评估
已覆盖只允许正确或错误,未覆盖可待确认,缺引用不再阻止正确结论。
复用统一事务写入与不可变审计重评旧待确认,保留原问答和人工结论。
验证:全仓 make verify、真实隔离 PostgreSQL 全包与 race 回归通过。
2026-10-24 16:47:09 +08:00

518 lines
20 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { useEffect, useRef, useState } from 'react'
import type { FormEvent } from 'react'
import { getPayload, fetchQARecord, qaDatasetPrefix } from './qaOps'
import type { QAQuery, QARecord } from './qaOps'
import { newOperationID } from './operationKey'
import {
emptyQualityFields,
qualityLabels,
parseQAQuality,
parseQualityHistory,
parseQualitySnapshot,
parseQualitySummary,
} from './qaQuality'
import type { QAQuality, QualityFields, QualityHistory, QualitySnapshot, QualitySummary } from './qaQuality'
const stamp = (v: string) => new Date(v).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai', hour12: false })
const message = (e: unknown) => (e instanceof Error ? e.message : '质量操作失败,请重试')
interface EditorProps {
dataset?: 'master'
recordId: string
quality: QAQuality
onSaved: (record: QARecord) => void
onReload: () => void
}
export function QAQualityEditor({ recordId, quality, onSaved, onReload, dataset }: EditorProps) {
const apiPrefix = qaDatasetPrefix(dataset)
const initial = quality.state === 'reviewed' ? quality.effective : emptyQualityFields
const [fields, setFields] = useState<QualityFields>({ ...initial }),
[reason, setReason] = useState(quality.state === 'reviewed' ? quality.latest_review?.reason || '' : ''),
[loading, setLoading] = useState(false),
[error, setError] = useState(''),
[notice, setNotice] = useState('')
const [history, setHistory] = useState<QualityHistory | null>(null),
[snapshot, setSnapshot] = useState<QualitySnapshot | null>(null),
[historyError, setHistoryError] = useState(''),
[historyLoading, setHistoryLoading] = useState(false)
const saving = useRef<AbortController | null>(null),
reading = useRef<AbortController | null>(null),
snapshotReading = useRef<AbortController | null>(null),
nonce = useRef({ signature: '', value: '' })
useEffect(() => {
setFields({ ...(quality.state === 'reviewed' ? quality.effective : emptyQualityFields) })
setReason(quality.state === 'reviewed' ? quality.latest_review?.reason || '' : '')
setHistory(null)
setSnapshot(null)
}, [
recordId,
quality.input_hash,
quality.input_epoch,
quality.revision,
quality.state,
quality.effective,
quality.latest_review,
])
useEffect(
() => () => {
saving.current?.abort()
reading.current?.abort()
snapshotReading.current?.abort()
},
[]
)
const change = (key: keyof QualityFields, value: string) => {
setFields({
...fields,
[key]: value,
...(key === 'correctness' && value === 'correct' ? { root_cause: '' } : {}),
...(key === 'coverage' && value !== 'excluded' ? { exclusion_reason: '' } : {}),
})
setNotice('')
setError('')
}
const submit = async (event: FormEvent) => {
event.preventDefault()
if (loading) return
setLoading(true)
setError('')
setNotice('')
const controller = new AbortController()
saving.current = controller
const body = {
input_hash: quality.input_hash,
input_epoch: quality.input_epoch,
base_revision: quality.revision,
fields,
reason,
}
const signature = JSON.stringify(body)
try {
if (nonce.current.signature !== signature) nonce.current = { signature, value: newOperationID() }
const raw = await getPayload(`${apiPrefix}/records/${encodeURIComponent(recordId)}/reviews`, controller.signal, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-quality' },
body: JSON.stringify({ ...body, nonce: nonce.current.value }),
})
if (!raw || typeof raw !== 'object') throw Error('复核回执无效')
const receipt = raw as Record<string, unknown>
parseQAQuality(receipt.view)
if (!Number.isSafeInteger(receipt.saved_revision) || Number(receipt.saved_revision) < 1)
throw Error('复核回执缺少版本')
const savedRevision = Number(receipt.saved_revision)
const audit = parseQualityHistory(
await getPayload(
`${apiPrefix}/records/${encodeURIComponent(recordId)}/quality/history?review_before=${savedRevision + 1}`,
controller.signal
)
)
const saved = audit.reviews.find((r) => r.revision === savedRevision)
if (
!saved ||
saved.input_hash !== body.input_hash ||
saved.input_epoch !== body.input_epoch ||
saved.reason !== reason ||
Object.keys(fields).some(
(key) => saved.fields[key as keyof QualityFields] !== fields[key as keyof QualityFields]
)
)
throw Error('保存后的精确复核记录尚未读回,请用原表单重试,重复请求不会重复留档')
const fresh = await fetchQARecord(recordId, controller.signal, dataset)
if (!fresh.quality || fresh.quality.revision < savedRevision)
throw Error('复核已留档但当前问答尚未读回,请重新读取')
if (!controller.signal.aborted) {
setNotice(
`已保存并读回复核第 ${savedRevision} 版${fresh.quality.state === 'stale' ? ';原始输入又有变化,旧结论不再生效' : ''}`
)
onSaved(fresh)
}
} catch (e) {
if (!controller.signal.aborted) setError(message(e))
} finally {
if (!controller.signal.aborted) setLoading(false)
}
}
const loadHistory = async (kind: 'initial' | 'reviews' | 'checks' = 'initial') => {
reading.current?.abort()
const controller = new AbortController()
reading.current = controller
setHistoryError('')
setHistoryLoading(true)
const params = new URLSearchParams()
if (kind === 'reviews' && history?.next_review) params.set('review_before', String(history.next_review))
if (kind === 'checks' && history?.next_check) params.set('check_before', String(history.next_check))
try {
const next = parseQualityHistory(
await getPayload(
`${apiPrefix}/records/${encodeURIComponent(recordId)}/quality/history${params.size ? '?' + params : ''}`,
controller.signal
)
)
if (!controller.signal.aborted)
setHistory((old) =>
kind === 'initial' || !old
? next
: kind === 'reviews'
? { ...old, reviews: [...old.reviews, ...next.reviews], next_review: next.next_review }
: { ...old, checks: [...old.checks, ...next.checks], next_check: next.next_check }
)
} catch (e) {
if (!controller.signal.aborted) setHistoryError(message(e))
} finally {
if (!controller.signal.aborted) setHistoryLoading(false)
}
}
const loadInput = async (epoch: number) => {
snapshotReading.current?.abort()
const controller = new AbortController()
snapshotReading.current = controller
setHistoryError('')
setSnapshot(null)
try {
const next = parseQualitySnapshot(
await getPayload(
`${apiPrefix}/records/${encodeURIComponent(recordId)}/quality/inputs/${epoch}`,
controller.signal
)
)
if (next.payload.id !== recordId || next.input_epoch !== epoch) throw Error('历史输入版本不匹配')
if (!controller.signal.aborted) setSnapshot(next)
} catch (e) {
if (!controller.signal.aborted) setHistoryError(message(e))
}
}
return (
<section className="qa-quality-editor" aria-label="人工复核与留档">
<h4>
人工复核 <span>{qualityLabels[quality.state]}</span>
</h4>
{quality.state === 'stale' ? (
<p className="qa-ops-warning">
待重新核对:原始问答输入已变化,旧人工结论仅供查阅,不再用于当前有效结果。请核对完整问题、答案、引用与媒体。
</p>
) : null}
{quality.latest_review ? (
<p className="qa-ops-muted">
最近复核:{quality.latest_review.reviewer} · {stamp(quality.latest_review.created_at)} · 第{' '}
{quality.latest_review.revision} 版
</p>
) : null}
<p className="qa-ops-muted">
模型建议、自动规则、源端判断和人工结论独立保留;以下分类沿用正式标签,人工结论优先。复核人取登录身份。
</p>
{error ? (
<div role="alert" className="error-banner">
{error}{' '}
<button type="button" onClick={onReload} disabled={loading}>
重新读取问答
</button>
</div>
) : null}
{notice ? <p role="status">{notice}</p> : null}
<form onSubmit={(event) => void submit(event)} aria-label="人工复核表单" className="qa-quality-form">
<label>
覆盖结论
<select
required
disabled={loading}
value={fields.coverage}
onChange={(e) => change('coverage', e.target.value)}
>
<option value="">请选择</option>
{['covered', 'uncovered', 'partial', 'pending', 'excluded'].map((key) => (
<option key={key} value={key}>
{qualityLabels[key]}
</option>
))}
</select>
</label>
<label>
正确性
<select
required
disabled={loading}
value={fields.correctness}
onChange={(e) => change('correctness', e.target.value)}
>
<option value="">请选择</option>
{(fields.coverage === 'uncovered' ? ['correct', 'incorrect', 'pending'] : ['correct', 'incorrect']).map(
(key) => (
<option key={key} value={key}>
{qualityLabels[key]}
</option>
)
)}
</select>
</label>
<label>
产品分类(可留空)
<input
disabled={loading}
value={fields.product_category}
maxLength={128}
onChange={(e) => change('product_category', e.target.value)}
placeholder="沿用正式标签"
/>
</label>
<label>
问题类型(可留空)
<input
disabled={loading}
value={fields.problem_type}
maxLength={128}
onChange={(e) => change('problem_type', e.target.value)}
placeholder="沿用正式标签"
/>
</label>
<label className="qa-quality-full">
根因分析(有依据才填)
<textarea
disabled={loading || fields.correctness === 'correct'}
value={fields.root_cause}
maxLength={2000}
onChange={(e) => change('root_cause', e.target.value)}
/>
</label>
{fields.coverage === 'excluded' ? (
<label className="qa-quality-full">
不计入原因
<textarea
required
disabled={loading}
value={fields.exclusion_reason}
maxLength={2000}
onChange={(e) => change('exclusion_reason', e.target.value)}
/>
</label>
) : null}
<label className="qa-quality-full">
复核理由
<textarea
required
disabled={loading}
value={reason}
maxLength={4000}
onChange={(e) => {
setReason(e.target.value)
setNotice('')
}}
placeholder="说明核对依据;不确定时选择待确认"
/>
</label>
{quality.automatic.result.verdict === 'uncovered' && ['covered', 'partial'].includes(fields.coverage) ? (
<p className="qa-ops-warning qa-quality-full">
将采用有理由的人工结论;“暂无已发布”的自动命中记录仍保留,不伪装为未命中。
</p>
) : null}
<button
type="submit"
disabled={
loading ||
!fields.coverage ||
!fields.correctness ||
!reason.trim() ||
(fields.coverage === 'excluded' && !fields.exclusion_reason.trim())
}
>
{loading ? '正在保存并核对…' : '保存并读回'}
</button>
</form>
<p className="qa-ops-muted qa-ops-organization">
当前输入第 {quality.input_epoch} 次观察 · 复核版本 {quality.revision} · 自动复检已留档于{' '}
{stamp(quality.automatic.created_at)}。当前输入指纹:{quality.input_hash}
</p>
<button type="button" disabled={historyLoading} onClick={() => void loadHistory()}>
读取复核/复检历史
</button>
{historyError ? (
<p role="alert" className="error-banner">
{historyError}
</p>
) : null}
{history ? (
<div className="qa-quality-history">
<h4>人工修改历史</h4>
{history.reviews.length ? (
history.reviews.map((r) => (
<article key={r.revision}>
<strong>
复核 #{r.revision} · {r.reviewer} · {stamp(r.created_at)}
</strong>
<p>
{qualityLabels[r.fields.coverage]} / {qualityLabels[r.fields.correctness]} ·{' '}
{r.fields.product_category || '产品未填'} / {r.fields.problem_type || '类型未填'}
</p>
<p>{r.reason}</p>
{r.fields.root_cause ? <p>根因:{r.fields.root_cause}</p> : null}
{r.fields.exclusion_reason ? <p>不计入原因:{r.fields.exclusion_reason}</p> : null}
<button type="button" onClick={() => void loadInput(r.input_epoch)}>
查看第 {r.input_epoch} 次输入
</button>
</article>
))
) : (
<p>尚无人工修改记录。</p>
)}
{history.next_review ? (
<button disabled={historyLoading} type="button" onClick={() => void loadHistory('reviews')}>
更多人工历史
</button>
) : null}
<h4>自动复检历史(不是 AI 评估)</h4>
{history.checks.map((c) => (
<article key={c.id}>
<p>
输入 #{c.input_epoch} · {c.result.rule_version} · {stamp(c.created_at)}
</p>
<p>
{c.result.verdict === 'uncovered' ? '命中“暂无已发布”:未覆盖' : '未命中:仍待评估,不默认覆盖'}
;当次源判断:{c.source.verdict || '未记录'}
</p>
<button type="button" disabled={!c.input_available} onClick={() => void loadInput(c.input_epoch)}>
{c.input_available ? `查看第 ${c.input_epoch} 次输入` : '此版本仅留存指纹/命中元数据'}
</button>
</article>
))}
{history.next_check ? (
<button disabled={historyLoading} type="button" onClick={() => void loadHistory('checks')}>
更多复检历史
</button>
) : null}
</div>
) : null}
{snapshot ? (
<section aria-label="历史评估输入">
<h4>历史输入 #{snapshot.input_epoch}</h4>
<p>{stamp(snapshot.created_at)} · 仅此历史版本,不代表当前答案</p>
<h5>原始问题</h5>
<pre>{snapshot.payload.question}</pre>
<h5>当时答案</h5>
<pre>{snapshot.payload.answer}</pre>
<details>
<summary>当时引用与媒体</summary>
<pre>
{JSON.stringify({ references: snapshot.payload.references, media: snapshot.payload.media }, null, 2)}
</pre>
</details>
</section>
) : null}
</section>
)
}
interface SummaryProps {
data: QualitySummary | null
loading: boolean
error: string
onRefresh: () => void
}
export function QAQualitySummaryView({ data, loading, error, onRefresh }: SummaryProps) {
return (
<section className="qa-quality-summary" aria-label="质量数量">
<button type="button" disabled={loading} onClick={onRefresh}>
{loading ? '正在统计…' : '质量统计'}
</button>
{error ? (
<p role="alert" className="error-banner">
{error}
</p>
) : null}
{data && !error && !loading ? (
<>
<p>
完整筛选范围 {data.summary.total} 条 · 已复核 {data.summary.reviewed} · 未复核 {data.summary.unreviewed} ·
待重新核对 {data.summary.stale} · 人工待确认 {data.summary.pending_confirmation} · 规则命中未覆盖{' '}
{data.summary.rule_uncovered}
</p>
<div className="qa-quality-rates" aria-label="质量比例">
{(
[
['知识覆盖率', data.summary.rates.coverage],
['回答正确率', data.summary.rates.correctness],
] as const
).map(([label, rate]) => (
<div key={label}>
<strong>
{label}:{rate.percent === null ? '暂无可计算数据' : `${rate.percent.toFixed(1)}%`}
</strong>
<p>
分子 {rate.numerator} / 分母 {rate.denominator};排除 {data.summary.total - rate.denominator} 条
</p>
</div>
))}
</div>
<details className="qa-ops-organization">
<summary>查看比例口径和分母构成</summary>
<p>
覆盖分母:已覆盖 {data.summary.rates.breakdown.covered} + 未覆盖 {data.summary.rates.breakdown.uncovered}{' '}
+ 部分覆盖 {data.summary.rates.breakdown.partial};部分覆盖不计完全覆盖。
</p>
<p>
覆盖分母排除:待确认 {data.summary.rates.breakdown.pending}、未评估{' '}
{data.summary.rates.breakdown.unassessed}、不计入 {data.summary.rates.breakdown.excluded}、待重新核对{' '}
{data.summary.rates.breakdown.stale}。
</p>
<p>
正确性分母仅含已覆盖且判断明确:正确 {data.summary.rates.breakdown.covered_correct} + 错误{' '}
{data.summary.rates.breakdown.covered_incorrect};已覆盖中的待确认{' '}
{data.summary.rates.breakdown.covered_pending}、未评估 {data.summary.rates.breakdown.covered_unassessed}{' '}
不计入,其余未覆盖/部分覆盖等记录也不计入。
</p>
<p>
当前有效人工结论优先;精确规则命中的未覆盖可进入覆盖分母,但不证明回答错误。失效记录暂不参与两项比例,原始问答运行成功也不代表答案正确。
</p>
<p className="qa-ops-muted">统计规则:{data.summary.rates.policy_version}</p>
</details>
</>
) : null}
</section>
)
}
export function QAQualityCounts({ query, revision }: { query: QAQuery | null; revision: number }) {
const [data, setData] = useState<QualitySummary | null>(null),
[loading, setLoading] = useState(false),
[error, setError] = useState(''),
[requested, setRequested] = useState(false),
[refresh, setRefresh] = useState(0)
useEffect(() => {
if (!query || !requested) {
setData(null)
return
}
const controller = new AbortController()
setData(null)
setError('')
setLoading(true)
getPayload('/api/v1/qa-ops/quality/query', controller.signal, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-quality' },
body: JSON.stringify({ start: query.start, end: query.end, keyword: query.keyword }),
})
.then((raw) => {
const next = parseQualitySummary(raw)
if (
(next.start !== query.start && Date.parse(next.start) !== Date.parse(query.start)) ||
Date.parse(next.end) !== Date.parse(query.end) ||
next.keyword !== query.keyword
)
throw Error('质量数量与当前查询范围不一致')
if (!controller.signal.aborted) setData(next)
})
.catch((e) => {
if (!controller.signal.aborted) setError(message(e))
})
.finally(() => {
if (!controller.signal.aborted) setLoading(false)
})
return () => controller.abort()
}, [query, revision, requested, refresh])
return (
<QAQualitySummaryView
data={data}
loading={loading}
error={error}
onRefresh={() => {
setRequested(true)
setRefresh((v) => v + 1)
}}
/>
)
}