Files
knowledge-governance/web/src/QAQuality.tsx
T
姚章浩 4b3aaff321 feat(qa-ops): 完成复检留档与人工复核闭环
治理侧保存输入观测版本、自动复检及人工复核历史,输入变化失效、版本冲突和幂等重放不覆盖人工记录。批量质量数量使用完整筛选元数据,未采集原文不伪造快照,延迟旧扫描不回退新输入。

验证:全仓 make verify 退出码0,Go656及前端253通过;五包竞态、源/组织/质量隔离PG、真实只读源和隔离网页读回复核通过。默认91个可选集成跳过不计通过。未接AI模型,不写DobotAI源库,未推送、未合并、未部署。
2026-10-17 22:37:26 +08:00

484 lines
18 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 } 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 {
recordId: string
quality: QAQuality
onSaved: (record: QARecord) => void
onReload: () => void
}
export function QAQualityEditor({ recordId, quality, onSaved, onReload }: EditorProps) {
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(
`/api/v1/qa-ops/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(
`/api/v1/qa-ops/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)
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(
`/api/v1/qa-ops/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(
`/api/v1/qa-ops/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">
AI 评估未接入。自动规则、源端判断和人工结论独立保留;以下分类沿用正式标签,不自动猜测。复核人取登录身份。
</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>
{['correct', 'incorrect', 'pending'].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>
<p className="qa-ops-muted">
AI 评估未接入;人工待确认是已复核中的子集,规则命中可与人工结论不同。不计算比例。读取:{stamp(data.as_of)}
</p>
</>
) : !error && !loading ? (
<span className="qa-ops-muted">按当前完整时间/关键词范围留档,不按当前页估算。</span>
) : 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)
}}
/>
)
}