Files
knowledge-governance/web/src/QAOperations.tsx
T
姚章浩 87f97a2f9b
build / build (push) Successful in 1m7s
feat(qaops): 完成详情下拉与每周自动保存草稿
详情使用共享主表字典,稀疏修改所选字段并保留原始问答及旧复核审计。
月周统计提供文本和下拉双入口;每租户每周一份持久草稿,按技能六节双语模板真实预填。
加入幂等自动保存、冲突保留、未知响应重试、切周及离开保护和schema58非破坏降级保护。

验证:完整make verify、隔离PostgreSQL全mirror竞态回归、真实恢复库浏览器验收通过。
浏览器实测字段精确读回、月周双输入、模板预填、MD/CSV、自动保存、冲突、失败重试与API重启恢复。
未连接或改写DobotAI生产源库,未运行付费模型;提交时尚未部署。
2026-10-20 05:44:02 +08:00

641 lines
24 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 { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
import type { FormEvent } from 'react'
import { useOptionalAuth } from './auth'
import { fetchQARecord, fetchAllQARecords, fetchQAStatus, qaCellValue, qaColumns } from './qaOps'
import type { QAQuery, QARecord, QARecordPage, QAStatus } from './qaOps'
import './qaOps.css'
import { ledgerWindow, ledgerCellPreview } from './qaLedgerRendering'
import { QARegionalStatistics } from './QADepartmentStatistics'
import { QADashboard } from './QADashboard'
import { QAWeekly } from './QAWeekly'
import { QAInlineFields } from './QAInlineFields'
import { qaFieldColors, qaTagColumns } from './qaFieldColors'
import { qualityLabels } from './qaQuality'
import { QAWeekPicker } from './QAWeekPicker'
import { QAAnswerMarkdown } from './QAAnswerMarkdown'
import { QAMirrorSync } from './QAMirrorSync'
import { QAAIWorkbench, QAAIRecordEvidence, QAAITaskBadges } from './QAAI'
import type { AIStatus, AIWorkState } from './qaAITypes'
import { currentQAWeek, qaDateTimeToISO, qaWeekQueryRange } from './qaWeeks'
export type QAOpsView = 'records' | 'dashboard' | 'regions' | 'weekly'
export function QAOperationsTabs({ view, onChange }: { view: QAOpsView; onChange: (view: QAOpsView) => void }) {
return (
<nav className="qa-region-tabs" aria-label="问答运营视图">
{(
[
['records', '问题流水表'],
['dashboard', '问题统计看板'],
['regions', '区域统计'],
['weekly', '周报生成'],
] as const
).map(([id, label]) => (
<button key={id} type="button" aria-pressed={view === id} onClick={() => onChange(id)}>
{label}
</button>
))}
</nav>
)
}
interface ViewProps {
taskUpdates?: AIWorkState[]
onQualitySaved?: (record: QARecord) => void
onReloadDetail?: () => void
page: QARecordPage | null
status: QAStatus | null
loading: boolean
error: string | null
detail: QARecord | null
detailLoading: boolean
detailError: string | null
onSelect: (id: string) => void
onCloseDetail: () => void
progress?: { loaded: number; total: number }
onRetry: () => void
}
const warningLabels: Record<string, string> = {
database_temp_enabled: '数据库仍允许临时对象:未视为完全只读验收通过',
database_transport_unencrypted: '数据库连接未启用 TLS:上线前须完成传输安全审核',
}
const stamp = (value: string) => new Date(value).toLocaleString('zh-CN', { hour12: false })
const sourceCoverageLabels: Record<string, string> = { covered: '已覆盖', uncovered: '未覆盖' }
function tasksFor(item: QARecord, updates: AIWorkState[] | undefined) {
const byKind = new Map((item.background_tasks ?? []).map((task) => [task.kind, task]))
for (const task of updates ?? []) {
const previous = byKind.get(task.kind)
if (!previous || previous.id === task.id || Date.parse(task.updated_at) > Date.parse(previous.updated_at))
byKind.set(task.kind, task)
}
return [...byKind.values()].sort((a, b) => a.kind.localeCompare(b.kind))
}
const QARow = memo(
function QARow({
item,
rowIndex,
tasks,
onSelect,
}: {
item: QARecord
rowIndex: number
tasks: AIWorkState[]
signature: string
onSelect: (id: string) => void
}) {
return (
<tr
className="qa-ops-record-row"
data-qa-row={item.id}
aria-rowindex={rowIndex}
onDoubleClick={(event) => {
if (!(event.target as HTMLElement).closest('button,a,input,select,textarea,summary')) onSelect(item.id)
}}
>
{qaColumns.map(({ key }) => (
<td
key={key}
className={
key === 'answer' || key === 'question' || key === 'question_chinese' || key === 'department'
? 'qa-ops-text-cell'
: ''
}
>
<span
className={qaTagColumns.has(key) ? 'qa-field-tag' : key === 'trigger_person' ? 'qa-person-name' : ''}
style={qaTagColumns.has(key) ? qaFieldColors(key, qaCellValue(item, key) ?? '—') : undefined}
>
{['answer', 'question', 'question_chinese', 'department'].includes(key)
? ledgerCellPreview(qaCellValue(item, key) ?? '—')
: (qaCellValue(item, key) ?? '—')}
</span>
</td>
))}
<td>
<div className="qa-ledger-actions">
<button type="button" onClick={() => onSelect(item.id)} aria-label={`查看问答 ${item.id} 的详情`}>
详情
</button>
{item.quality ? <small className="qa-quality-state">{qualityLabels[item.quality.state]}</small> : null}
<QAAITaskBadges tasks={tasks} />
</div>
</td>
</tr>
)
},
(before, after) =>
before.item === after.item &&
before.rowIndex === after.rowIndex &&
before.signature === after.signature &&
before.onSelect === after.onSelect
)
const ledgerColumnWidth = (key: string) =>
['answer', 'question', 'question_chinese'].includes(key)
? 320
: key === 'asked_at'
? 185
: key === 'department'
? 240
: key === 'root_cause'
? 155
: 125
export function QAOperationsView(props: ViewProps) {
const page = props.page
const scrollRef = useRef<HTMLDivElement>(null)
const [viewport, setViewport] = useState({ top: 0, height: 600 })
const visible = ledgerWindow(page?.items.length ?? 0, viewport.top, viewport.height)
useEffect(() => {
const element = scrollRef.current
if (!element) return
const observer = new ResizeObserver(() =>
setViewport({ top: Math.max(0, element.scrollTop - 40), height: element.clientHeight })
)
observer.observe(element)
return () => observer.disconnect()
}, [Boolean(page?.items.length)])
const columns = qaColumns
const updates = useMemo(() => {
const map = new Map<string, AIWorkState[]>()
for (const task of props.taskUpdates ?? []) {
const list = map.get(task.record_id) ?? []
if (!list.some((previous) => previous.kind === task.kind)) list.push(task)
map.set(task.record_id, list)
}
return map
}, [props.taskUpdates])
const detail = props.detail
const showDrawer = Boolean(detail || props.detailLoading || props.detailError)
return (
<section className="qa-ops-results" aria-label="问答记录">
<div className="qa-ops-result-bar">
<span>
{props.loading
? `正在读取全部问答…${props.progress ? `(${props.progress.loaded} / ${props.progress.total})` : ''}`
: page
? `共 ${page.total} 条 · 已载入 ${page.items.length} 条`
: '尚未读取问答'}
</span>
<small className="qa-ops-muted">双击行查看详情</small>
</div>
{props.status?.warnings
.filter((warning) => !['database_temp_enabled', 'database_transport_unencrypted'].includes(warning))
.map((warning) => (
<p className="qa-ops-warning" key={warning}>
{warningLabels[warning] ?? '数据源有待审核的安全告警'}
</p>
))}
{props.error ? (
<div className="error-banner" role="alert">
{props.error}{' '}
<button type="button" onClick={props.onRetry} disabled={props.loading}>
重试读取
</button>
</div>
) : null}
{page && page.items.length > 0 ? (
<div
ref={scrollRef}
className="qa-ops-table-scroll"
aria-label="问答表格滚动区"
tabIndex={0}
onScroll={(event) => {
const element = event.currentTarget
setViewport({ top: Math.max(0, element.scrollTop - 40), height: element.clientHeight })
}}
>
<table
className="qa-ops-table"
aria-rowcount={page.items.length + 1}
style={{ width: qaColumns.reduce((sum, c) => sum + ledgerColumnWidth(c.key), 160) }}
>
<colgroup>
{qaColumns.map((c) => (
<col key={c.key} style={{ width: ledgerColumnWidth(c.key) }} />
))}
<col style={{ width: 160 }} />
</colgroup>
<thead>
<tr>
{columns.map(({ key, label }) => (
<th key={key}>{label}</th>
))}
<th>操作</th>
</tr>
</thead>
<tbody>
{visible.padTop > 0 ? (
<tr aria-hidden="true" className="qa-ledger-spacer">
<td colSpan={columns.length + 1} style={{ height: visible.padTop }} />
</tr>
) : null}
{page.items.slice(visible.start, visible.end).map((item, index) => {
const tasks = tasksFor(item, updates.get(item.id))
return (
<QARow
key={item.id}
item={item}
rowIndex={visible.start + index + 2}
tasks={tasks}
signature={JSON.stringify(tasks)}
onSelect={props.onSelect}
/>
)
})}
{visible.padBottom > 0 ? (
<tr aria-hidden="true" className="qa-ledger-spacer">
<td colSpan={columns.length + 1} style={{ height: visible.padBottom }} />
</tr>
) : null}
</tbody>
</table>
</div>
) : page && !props.loading && !props.error ? (
<p className="qa-ops-empty">没有符合条件的问答,请调整时间范围或关键词。</p>
) : null}
{showDrawer ? (
<>
<aside
className="qa-ops-drawer"
role="dialog"
aria-modal="false"
aria-label="问答详情"
onKeyDown={(event) => {
if (event.key === 'Escape') props.onCloseDetail()
}}
>
<header>
<h3>问答详情</h3>
<button type="button" autoFocus onClick={props.onCloseDetail}>
关闭详情
</button>
</header>
{detail ? (
<QAInlineFields
key={detail.id}
record={detail}
onSaved={props.onQualitySaved ?? (() => {})}
onReload={props.onReloadDetail ?? (() => {})}
/>
) : null}
{props.detailLoading ? <p role="status">正在读取完整问答…</p> : null}
{props.detailError ? (
<p className="error-banner" role="alert">
{props.detailError}
</p>
) : null}
{detail ? (
<div className="qa-ops-detail-content">
<dl className="qa-ops-detail-meta">
<dt>提问时间</dt>
<dd>
{stamp(detail.asked_at)}
{detail.time_source === 'turn.created_at' ? '(问答时间回退,入站消息缺失)' : ''}
</dd>
<dt>提问人</dt>
<dd>{detail.asker || '未关联'}</dd>
<dt>部门</dt>
<dd>
{detail.department || '未匹配'}
{detail.organization?.department_origin === 'current_directory' ? '(当前通讯录补全)' : ''}
</dd>
</dl>
<h4>原始问题</h4>
<div className="qa-ops-full-text">{detail.question || '无文本问题'}</div>
<h4>AI答案</h4>
<QAAnswerMarkdown key={detail.id} answer={detail.answer} />
<h4>治理侧覆盖复检</h4>
<p>
{detail.coverage.verdict === 'uncovered'
? '未覆盖:答案包含“暂无已发布”,引用不能抵消这一结果。'
: detail.coverage.verdict === 'covered'
? '已覆盖:成功读取且非空答案未包含“暂无已发布”。'
: detail.coverage.rule_version === 'master-answer-substring-v2'
? '待判定:答案为空或读取未完成,未据未命中标记判定已覆盖。'
: '旧版规则只检测未覆盖标记,尚无已覆盖结论。'}
</p>
<p className="qa-ops-muted">规则:{detail.coverage.rule_version}</p>
<h4>源端覆盖(仅对照)</h4>
<p>
{sourceCoverageLabels[detail.source_coverage.verdict] ?? '未记录'} ·{' '}
{detail.source_coverage.evaluator_version || '无版本'}
</p>
<p className="qa-ops-muted">{detail.source_coverage.reason_code || '未记录判定原因'}</p>
<QAAIRecordEvidence
key={detail.id + ':ai'}
recordID={detail.id}
revision={updates
.get(detail.id)
?.map((task) => task.updated_at)
.join(':')}
/>
<h4>引用知识</h4>
<pre>{JSON.stringify(detail.references, null, 2)}</pre>
<details>
<summary>问题媒体记录</summary>
<pre>{JSON.stringify(detail.media, null, 2)}</pre>
</details>
</div>
) : null}
</aside>
</>
) : null}
</section>
)
}
function initialDraft() {
const current = currentQAWeek()
const { year, week, start, end } = qaWeekQueryRange(current.year, current.week)
return { year, week: week as number | null, start, end, keyword: '' }
}
export function QAOperations() {
const [view, setView] = useState<QAOpsView>('records')
const weeklyBeforeLeave = useRef<(() => Promise<boolean>) | null>(null)
const registerWeeklyLeave = useCallback((guard: (() => Promise<boolean>) | null) => {
weeklyBeforeLeave.current = guard
}, [])
const auth = useOptionalAuth()
const canRead = auth?.identity?.role === 'admin'
const [draft, setDraft] = useState(initialDraft)
const [query, setQuery] = useState<QAQuery | null>(null)
const [page, setPage] = useState<QARecordPage | null>(null)
const [status, setStatus] = useState<QAStatus | null>(null)
const [error, setError] = useState<string | null>(null)
const [loading, setLoading] = useState(false)
const [revision, setRevision] = useState(0)
const [qualityRevision, setQualityRevision] = useState(0)
const [aiStatus, setAIStatus] = useState<AIStatus | null>(null)
const generation = useRef(0)
const freshAI = useRef(new Map<string, QARecord>())
const viewRef = useRef(view)
viewRef.current = view
const [mirrorChanged, setMirrorChanged] = useState(false)
const [detail, setDetail] = useState<QARecord | null>(null)
const [detailLoading, setDetailLoading] = useState(false)
const [detailError, setDetailError] = useState<string | null>(null)
const [progress, setProgress] = useState<{ loaded: number; total: number } | undefined>()
const detailRequest = useRef<AbortController | null>(null)
const returnFocus = useRef<HTMLElement | null>(null)
useEffect(() => {
if (!canRead || query) return
setQuery({
start: qaDateTimeToISO(draft.start),
end: qaDateTimeToISO(draft.end),
keyword: draft.keyword,
cursor: '',
})
}, [canRead, draft, query])
useEffect(() => {
if (!query || !canRead) return
if (view !== 'records') {
setLoading(false)
setError(null)
detailRequest.current?.abort()
setDetail(null)
return
}
const controller = new AbortController()
generation.current += 1
freshAI.current.clear()
detailRequest.current?.abort()
setLoading(true)
setError(null)
setPage(null)
setProgress(undefined)
setDetail(null)
setDetailError(null)
setDetailLoading(false)
void fetchQAStatus(controller.signal)
.then(setStatus)
.catch(() => {
if (!controller.signal.aborted) setStatus(null)
})
void fetchAllQARecords({ ...query, dataset: 'master' }, controller.signal, (loaded, total) => {
if (!controller.signal.aborted) setProgress({ loaded, total })
})
.then((result) => {
if (!controller.signal.aborted)
setPage({ ...result, items: result.items.map((item) => freshAI.current.get(item.id) ?? item) })
})
.catch((reason: unknown) => {
if (!controller.signal.aborted) setError(reason instanceof Error ? reason.message : '问答读取失败')
})
.finally(() => {
if (!controller.signal.aborted) setLoading(false)
})
return () => controller.abort()
}, [query, canRead, revision, view])
useEffect(
() => () => {
detailRequest.current?.abort()
},
[]
)
const submit = (event: FormEvent) => {
event.preventDefault()
try {
const start = qaDateTimeToISO(draft.start),
end = qaDateTimeToISO(draft.end)
if (!(Date.parse(start) < Date.parse(end))) throw new Error('开始时间必须早于结束时间')
if (Date.parse(start) >= Date.now()) throw new Error('所选周或时间尚未开始,请选择已开始的时间范围')
setQuery({ start, end, keyword: draft.keyword, cursor: '' })
} catch (reason) {
setError(reason instanceof Error ? reason.message : '时间格式无效')
}
}
const select = useCallback(async (id: string) => {
detailRequest.current?.abort()
returnFocus.current = document.activeElement as HTMLElement | null
const controller = new AbortController()
detailRequest.current = controller
setDetail(null)
setDetailError(null)
setDetailLoading(true)
try {
const result = await fetchQARecord(id, controller.signal, 'master')
if (!controller.signal.aborted) setDetail(result)
} catch (reason) {
if (!controller.signal.aborted) setDetailError(reason instanceof Error ? reason.message : '详情读取失败')
} finally {
if (!controller.signal.aborted) setDetailLoading(false)
}
}, [])
const refreshAIRecord = useCallback((id: string) => {
if (viewRef.current === 'dashboard') {
setQualityRevision((value) => value + 1)
return
}
const version = generation.current
void fetchQARecord(id, undefined, 'master')
.then((fresh) => {
if (version !== generation.current) return
freshAI.current.set(id, fresh)
setPage((old) => (old ? { ...old, items: old.items.map((item) => (item.id === id ? fresh : item)) } : old))
setDetail((old) => (old?.id === id ? fresh : old))
})
.catch(() => {})
}, [])
const close = () => {
if (mirrorChanged) {
setMirrorChanged(false)
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}
detailRequest.current?.abort()
setDetail(null)
setDetailError(null)
setDetailLoading(false)
returnFocus.current?.focus()
}
const queryView = view === 'records' || view === 'dashboard'
return (
<section className="qa-ops" aria-label="问答运营">
<header className="qa-ops-header">
<h2>问答运营</h2>
</header>
{!canRead ? (
<p className="error-banner" role="alert">
尚未配置员工问答可见范围,当前仅管理员可访问。
</p>
) : (
<>
<QAOperationsTabs
view={view}
onChange={(next) => {
if (view === 'weekly' && next !== 'weekly' && weeklyBeforeLeave.current)
void weeklyBeforeLeave.current().then((ok) => {
if (ok) setView(next)
})
else setView(next)
}}
/>
{queryView ? (
<>
{mirrorChanged ? <p className="qa-ops-warning">数据已更新,关闭详情后刷新。</p> : null}
<form className="qa-ops-query" onSubmit={submit}>
<QAWeekPicker
year={draft.year}
week={draft.week}
onCurrentWeek={() => {
const current = initialDraft()
setDraft({ ...current, keyword: draft.keyword })
setQuery({
start: qaDateTimeToISO(current.start),
end: qaDateTimeToISO(current.end),
keyword: draft.keyword,
cursor: '',
})
}}
onChange={(year, week) =>
setDraft((old) =>
week === null ? { ...old, year, week } : { ...old, ...qaWeekQueryRange(year, week) }
)
}
/>
<label>
开始时间(北京时间)
<input
type="datetime-local"
required
value={draft.start}
onChange={(e) => setDraft({ ...draft, start: e.target.value, week: null })}
/>
</label>
<label>
结束时间(北京时间,不含)
<input
type="datetime-local"
required
value={draft.end}
onChange={(e) => setDraft({ ...draft, end: e.target.value, week: null })}
/>
</label>
<label className="qa-ops-keyword">
关键词
<input
type="search"
maxLength={200}
placeholder="检索原始/中文问题"
value={draft.keyword}
onChange={(e) => setDraft({ ...draft, keyword: e.target.value })}
/>
</label>
<button className="qa-query-action" type="submit" disabled={loading}>
查询
</button>
<QAMirrorSync
onChanged={() => {
if (detail || detailLoading) {
setMirrorChanged(true)
return
}
setQuery((q) => (q ? { ...q } : q))
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}}
/>
</form>
<div hidden={view !== 'records'}>
<QAAIWorkbench query={query} onStatus={setAIStatus} onRecordChanged={refreshAIRecord} />
</div>
</>
) : null}
{view === 'regions' ? (
<QARegionalStatistics
onSaved={() => {
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}}
/>
) : view === 'weekly' ? (
<QAWeekly onBeforeLeave={registerWeeklyLeave} />
) : view === 'dashboard' ? (
<QADashboard
query={query}
error={error}
revision={qualityRevision}
onRetry={() => {
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}}
/>
) : (
<QAOperationsView
page={page}
status={status}
taskUpdates={aiStatus?.recent_tasks}
error={error}
loading={loading}
detail={detail}
detailLoading={detailLoading}
detailError={detailError}
onReloadDetail={() => {
if (detail) void select(detail.id)
}}
onQualitySaved={(fresh) => {
if (fresh.id !== detail?.id) return
setDetail(fresh)
setPage((old) =>
old ? { ...old, items: old.items.map((item) => (item.id === fresh.id ? fresh : item)) } : old
)
setQualityRevision((v) => v + 1)
}}
onSelect={select}
onCloseDetail={close}
progress={progress}
onRetry={() => setRevision((v) => v + 1)}
/>
)}
</>
)}
</section>
)
}