feat(qa-ops): 持久本地问答副本与安全答案预览
build / build (push) Successful in 1m11s

新增迁移50与每5分钟/手动持久同步,API只读本地;同步失败保留、权限阻断、租约与质量失效原子激活。
保留全量稳定分页/固定列,已存质量批量读取,元数据不反复解压长答案;详情安全Markdown与原文。

已运行整仓 make verify、源与副本隔离PG -race、真实只读源及隔离浏览器。
实际同步2525条;固定窗口640条本地中位1.46秒,对照直接源33.10秒。
停worker、缺源凭据、重启API后仍可查询;未更新8088,未修改生产原问答。
This commit is contained in:
姚章浩
2026-10-18 19:10:47 +08:00
parent 74ba737b1e
commit 3e7fcce0b1
49 changed files with 4038 additions and 59 deletions
+30
View File
@@ -0,0 +1,30 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, it, expect } from 'vitest'
import { QAAnswerMarkdown } from './QAAnswerMarkdown'
describe('AI answer Markdown preview', () => {
it('renders headings, tables, code, links and keeps original source', () => {
const answer =
'# 安装步骤\n\n- **先断电**\n- 检查接线\n\n| 参数 | 值 |\n| --- | --- |\n| 速度 | 50 |\n\n```python\nprint("ready")\n```\n\n[说明](https://example.invalid/guide)'
const html = renderToStaticMarkup(<QAAnswerMarkdown answer={answer} />)
expect(html).toContain('<h1>安装步骤</h1>')
expect(html).toContain('<strong>先断电</strong>')
expect(html).toContain('<table>')
expect(html).toContain('language-python')
expect(html).toContain('href="https://example.invalid/guide"')
expect(html).toContain('noopener noreferrer')
expect(html).toContain('查看 Markdown 原文')
})
it('never executes raw HTML, unsafe URL schemes or automatically loads external images', () => {
const answer =
'<script>globalThis.PWNED=true</script>\n\n<img src="x" onerror="alert(1)">\n\n[unsafe](javascript:alert%281%29)\n\n![图片](https://images.invalid/private.png)'
const html = renderToStaticMarkup(<QAAnswerMarkdown answer={answer} />)
expect(html).not.toContain('<script>')
expect(html).not.toContain('<img ')
expect(html).not.toContain('href="javascript:')
expect(html.split('<details')[0]).not.toContain('onerror=')
expect(html).toContain('查看图片')
})
it('does not confuse an empty answer with a positive assessment', () => {
expect(renderToStaticMarkup(<QAAnswerMarkdown answer="" />)).toContain('尚无答案;不默认判覆盖或正确')
})
})
+67
View File
@@ -0,0 +1,67 @@
import { useState } from 'react'
import Markdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import './qaAnswer.css'
export function safeAnswerURL(value: string): string {
if (!value || /[\u0000-\u0020\u007f\\]/.test(value) || value.startsWith('//')) return ''
if (!/^[a-z][a-z0-9+.-]*:/i.test(value)) return value
try {
const url = new URL(value)
return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password ? value : ''
} catch {
return ''
}
}
export function QAAnswerMarkdown({ answer }: { answer: string }) {
const [showImages, setShowImages] = useState(false)
if (!answer) return <p>尚无答案;不默认判覆盖或正确</p>
return (
<div className="qa-answer">
<div className="qa-answer-tools">
<span>Markdown 预览</span>
{/!\[/.test(answer) ? (
<button type="button" onClick={() => setShowImages(!showImages)} aria-pressed={showImages}>
{showImages ? '隐藏图片' : '显示答案图片'}
</button>
) : null}
</div>
<div className="qa-answer-markdown">
<Markdown
remarkPlugins={[remarkGfm]}
skipHtml
urlTransform={safeAnswerURL}
components={{
a: ({ href, children }) =>
href ? (
<a href={href} target="_blank" rel="noopener noreferrer" referrerPolicy="no-referrer">
{children}
</a>
) : (
<span>{children}</span>
),
img: ({ src, alt }) =>
src ? (
showImages ? (
<img src={src} alt={alt ?? ''} loading="lazy" referrerPolicy="no-referrer" />
) : (
<a href={src} target="_blank" rel="noopener noreferrer" referrerPolicy="no-referrer">
查看图片{alt ? `:${alt}` : ''}
</a>
)
) : (
<span>{alt || '图片地址不可用'}</span>
),
}}
>
{answer}
</Markdown>
</div>
<details className="qa-answer-source">
<summary>查看 Markdown 原文</summary>
<pre>{answer}</pre>
</details>
</div>
)
}
+55
View File
@@ -0,0 +1,55 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, it, expect, vi } from 'vitest'
import { QAMirrorSyncView } from './QAMirrorSync'
import type { QAMirrorStatus } from './qaMirror'
const base: QAMirrorStatus = {
mode: 'local',
ready: false,
blocked: false,
revision: 0,
records: 0,
source_observed_at: null,
last_success_at: null,
next_sync_at: null,
error_code: 'initial_sync_pending',
interval_seconds: 300,
worker_ready: true,
job: null,
}
describe('local Q&A synchronization strip', () => {
it('shows pending first import rather than a successfully empty dataset', () => {
const html = renderToStaticMarkup(<QAMirrorSyncView status={base} error="" submitting={false} onSync={vi.fn()} />)
expect(html).toContain('本地数据库')
expect(html).toContain('首次同步尚未完成')
expect(html).toContain('立即同步')
expect(html).toContain('每 5 分钟')
})
it('keeps the last-good dataset visibly stale after a failed sync', () => {
const status = {
...base,
ready: true,
revision: 1,
records: 639,
last_success_at: '2026-10-18T00:00:00Z',
source_observed_at: '2026-10-18T00:00:00Z',
next_sync_at: '2026-10-18T00:05:00Z',
error_code: 'mirror_source_unavailable',
}
const html = renderToStaticMarkup(<QAMirrorSyncView status={status} error="" submitting={false} onSync={vi.fn()} />)
expect(html).toContain('639')
expect(html).toContain('保留上次成功数据')
expect(html).toContain('最近成功同步')
})
it('distinguishes authorization blocking from an ordinary network failure', () => {
const html = renderToStaticMarkup(
<QAMirrorSyncView
status={{ ...base, blocked: true, error_code: 'mirror_source_authorization_failed' }}
error=""
submitting={false}
onSync={vi.fn()}
/>
)
expect(html).toContain('权限校验未通过')
expect(html).toContain('本地读取已阻断')
})
})
+124
View File
@@ -0,0 +1,124 @@
import { useEffect, useRef, useState } from 'react'
import { fetchQAMirrorStatus, mirrorSyncActive, mirrorStateChanged, startQAMirrorSync } from './qaMirror'
import type { QAMirrorStatus } from './qaMirror'
import { newOperationID } from './operationKey'
import './qaMirror.css'
interface ViewProps {
status: QAMirrorStatus | null
error: string
submitting: boolean
onSync: () => void
}
const stamp = (v: string) => new Date(v).toLocaleString('zh-CN', { hour12: false })
export function QAMirrorSyncView(p: ViewProps) {
const s = p.status
const active = mirrorSyncActive(s)
return (
<section className="qa-mirror-sync" aria-label="问答本地数据库与同步状态">
<div className="qa-mirror-sync-line">
<strong>本地数据库</strong>
<span>每 5 分钟后台同步 · 查询不请求远端</span>
{s?.ready ? <span>已同步 {s.records} 条</span> : null}
<button type="button" onClick={p.onSync} disabled={p.submitting || !s?.worker_ready || active}>
{p.submitting ? '正在入队…' : active ? '后台同步中…' : '立即同步'}
</button>
</div>
<div role="status" className="qa-ops-muted">
{!s
? '正在读取同步状态…'
: s.blocked
? '源端权限校验未通过,本地读取已阻断;修复授权后可重新同步。'
: !s.ready
? '首次同步尚未完成,暂不把未同步数据视为空结果。'
: `最近成功同步:${stamp(s.last_success_at!)};页面基于该本地副本,不承诺实时源快照。`}
{s?.job && active ? (
<span>
{' '}
{s.job.expected > 0
? `已检查 ${s.job.loaded} / ${s.job.expected} 条,取回变化 ${s.job.changed} 条。`
: '正在检查源端变化。'}
</span>
) : null}
{s?.error_code && s.error_code !== 'initial_sync_pending' && !s.blocked ? (
<span className="qa-ops-warning"> 最近同步失败,保留上次成功数据;请检查源端连接后重试。</span>
) : null}
{s && !s.worker_ready ? <span className="qa-ops-warning"> 同步执行器未在线。</span> : null}
</div>
{p.error ? (
<p className="error-banner" role="alert">
{p.error}
</p>
) : null}
</section>
)
}
export function QAMirrorSync({ onChanged }: { onChanged: () => void }) {
const [status, setStatus] = useState<QAMirrorStatus | null>(null),
[error, setError] = useState(''),
[submitting, setSubmitting] = useState(false)
const key = useRef('')
const acceptedJob = useRef('')
const changed = useRef(onChanged)
changed.current = onChanged
const observed = useRef<{ revision: number; blocked: boolean; ready: boolean } | undefined>(undefined)
const kick = useRef<() => void>(() => {})
useEffect(() => {
let disposed = false,
timer: ReturnType<typeof setTimeout> | undefined
const controller = new AbortController()
let inFlight = false
const read = async () => {
if (disposed || inFlight) return
inFlight = true
let next = 15000
try {
const fresh = await fetchQAMirrorStatus(controller.signal)
if (disposed) return
const previous = observed.current
observed.current = { revision: fresh.revision, blocked: fresh.blocked, ready: fresh.ready }
setStatus(fresh)
setError('')
if (mirrorStateChanged(previous, fresh)) changed.current()
if (!mirrorSyncActive(fresh) && fresh.job?.id === acceptedJob.current) {
key.current = ''
acceptedJob.current = ''
}
if (mirrorSyncActive(fresh) || !fresh.ready) next = 2500
} catch (e) {
if (!disposed) setError(e instanceof Error ? e.message : '本地同步状态读取失败')
} finally {
inFlight = false
if (!disposed) {
clearTimeout(timer)
timer = setTimeout(() => void read(), next)
}
}
}
kick.current = () => {
clearTimeout(timer)
void read()
}
void read()
return () => {
disposed = true
controller.abort()
clearTimeout(timer)
kick.current = () => {}
}
}, [])
const synchronize = async () => {
if (submitting || mirrorSyncActive(status)) return
setSubmitting(true)
setError('')
if (!key.current) key.current = newOperationID()
try {
acceptedJob.current = await startQAMirrorSync(key.current)
kick.current()
} catch (e) {
setError(e instanceof Error ? e.message : '同步请求未确认,请重试,已有本地数据不变')
} finally {
setSubmitting(false)
}
}
return <QAMirrorSyncView status={status} error={error} submitting={submitting} onSync={() => void synchronize()} />
}
+25 -3
View File
@@ -11,6 +11,8 @@ import { QAQualityEditor, QAQualityCounts } from './QAQuality'
import { qualityLabels } from './qaQuality'
import { usageLabels } from './qaUsage'
import { QAWeekPicker } from './QAWeekPicker'
import { QAAnswerMarkdown } from './QAAnswerMarkdown'
import { QAMirrorSync } from './QAMirrorSync'
import { currentQAWeek, qaDateTimeToISO, qaWeekQueryRange } from './qaWeeks'
interface ViewProps {
@@ -58,7 +60,7 @@ export function QAOperationsView(props: ViewProps) {
: '尚未读取问答'}
</span>
<span className="qa-ops-source">
DobotAI 2.0 / 钉钉 · 独立只读连接{props.status ? ` · ${stateLabels[props.status.state]}` : ''}
DobotAI 2.0 / 钉钉 · 本地问答副本{props.status ? ` · ${stateLabels[props.status.state]}` : ''}
</span>
</div>
{page?.organization ? (
@@ -240,7 +242,7 @@ export function QAOperationsView(props: ViewProps) {
<h4>原始问题</h4>
<div className="qa-ops-full-text">{detail.question || '无文本问题'}</div>
<h4>AI答案</h4>
<div className="qa-ops-full-text">{detail.answer || '尚无答案;不默认判覆盖或正确'}</div>
<QAAnswerMarkdown key={detail.id} answer={detail.answer} />
<h4>治理侧覆盖复检</h4>
<p>
{detail.coverage.verdict === 'uncovered'
@@ -309,6 +311,7 @@ export function QAOperations() {
const [loading, setLoading] = useState(false)
const [revision, setRevision] = useState(0)
const [qualityRevision, setQualityRevision] = useState(0)
const [mirrorChanged, setMirrorChanged] = useState(false)
const [detail, setDetail] = useState<QARecord | null>(null)
const [detailLoading, setDetailLoading] = useState(false)
const [detailError, setDetailError] = useState<string | null>(null)
@@ -400,6 +403,11 @@ export function QAOperations() {
}
}
const close = () => {
if (mirrorChanged) {
setMirrorChanged(false)
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}
detailRequest.current?.abort()
setDetail(null)
setDetailError(null)
@@ -412,7 +420,7 @@ export function QAOperations() {
<h2>
问答运营 <span>/ {view === 'regions' ? '区域归属' : view === 'usage' ? '使用统计' : '问答记录'}</span>
</h2>
<p>真实问答只读查询;原始记录、源端判断与治理复检分开保留。</p>
<p>本地问答查询;远端只读后台同步,原始记录与人工复核分开保留。</p>
</header>
{!canRead ? (
<p className="error-banner" role="alert">
@@ -420,6 +428,20 @@ export function QAOperations() {
</p>
) : (
<>
<QAMirrorSync
onChanged={() => {
if (detail || detailLoading) {
setMirrorChanged(true)
return
}
setQuery((q) => (q ? { ...q } : q))
setRevision((v) => v + 1)
setQualityRevision((v) => v + 1)
}}
/>
{mirrorChanged ? (
<p className="qa-ops-warning">本地副本已更新;当前详情和未保存复核不会被覆盖,关闭详情后刷新列表。</p>
) : null}
<nav className="qa-region-tabs" aria-label="问答运营视图">
<button type="button" aria-pressed={view === 'records'} onClick={() => setView('records')}>
问答记录
+92
View File
@@ -0,0 +1,92 @@
.qa-answer {
min-width: 0;
}
.qa-answer-tools {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-bottom: 12px;
color: var(--muted-foreground, #65758b);
font-size: 12px;
}
.qa-answer-markdown {
min-width: 0;
max-width: 100%;
overflow-x: auto;
overflow-wrap: anywhere;
line-height: 1.75;
}
.qa-answer-markdown > :first-child {
margin-top: 0;
}
.qa-answer-markdown h1 {
font-size: 1.45rem;
}
.qa-answer-markdown h2 {
font-size: 1.25rem;
}
.qa-answer-markdown h3 {
font-size: 1.1rem;
}
.qa-answer-markdown h1,
.qa-answer-markdown h2,
.qa-answer-markdown h3 {
line-height: 1.4;
margin: 1.1em 0 0.55em;
}
.qa-answer-markdown ul,
.qa-answer-markdown ol {
padding-left: 1.6em;
}
.qa-answer-markdown p {
margin: 0.7em 0;
}
.qa-answer-markdown table {
width: auto;
min-width: min(100%, 360px);
border-collapse: collapse;
margin: 12px 0;
}
.qa-answer-markdown th,
.qa-answer-markdown td {
white-space: normal;
padding: 8px 12px;
border: 1px solid var(--border, #dce4ef);
text-align: left;
}
.qa-answer-markdown blockquote {
border-left: 3px solid var(--accent, #2794dc);
padding-left: 14px;
margin-left: 0;
color: var(--muted-foreground, #65758b);
}
.qa-answer-markdown pre,
.qa-answer-source pre {
padding: 12px;
border: 1px solid var(--border, #dce4ef);
border-radius: 6px;
max-width: 100%;
overflow-x: auto;
white-space: pre;
font-size: 12px;
line-height: 1.6;
}
.qa-answer-markdown code {
font-family: ui-monospace, monospace;
}
.qa-answer-markdown img {
display: block;
max-width: 100%;
height: auto;
}
.qa-answer-source {
margin-top: 14px;
border-top: 1px solid var(--border, #dce4ef);
padding-top: 10px;
}
.qa-answer-source summary {
cursor: pointer;
font-size: 12px;
color: var(--muted-foreground, #65758b);
}
+29
View File
@@ -0,0 +1,29 @@
.qa-mirror-sync {
padding: 12px 0;
border-bottom: 1px solid var(--border, #dce4ef);
margin-bottom: 12px;
}
.qa-mirror-sync-line {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
margin-bottom: 7px;
font-size: 12px;
}
.qa-mirror-sync-line strong {
font-size: 13px;
color: #176940;
}
.qa-mirror-sync-line > button {
margin-left: auto;
}
.qa-mirror-sync .qa-ops-muted {
font-size: 12px;
line-height: 1.7;
}
@media (max-width: 600px) {
.qa-mirror-sync-line > button {
margin-left: 0;
}
}
+63
View File
@@ -0,0 +1,63 @@
import { afterEach, describe, it, expect, vi } from 'vitest'
import { parseQAMirrorStatus, mirrorStateChanged } from './qaMirror'
import { mergeQAPages, parseQARecordPage } from './qaOps'
const initial = {
mode: 'local',
ready: false,
blocked: false,
revision: 0,
records: 0,
source_observed_at: null,
last_success_at: null,
next_sync_at: null,
error_code: 'initial_sync_pending',
interval_seconds: 300,
worker_ready: true,
job: null,
}
afterEach(() => vi.unstubAllGlobals())
describe('local Q&A mirror contract', () => {
it('refreshes records on the first already-ready snapshot so an earlier initial 503 is not stranded', () => {
expect(mirrorStateChanged(undefined, { revision: 1, blocked: false, ready: true })).toBe(true)
expect(mirrorStateChanged(undefined, { revision: 0, blocked: false, ready: false })).toBe(false)
expect(
mirrorStateChanged({ revision: 1, blocked: false, ready: true }, { revision: 1, blocked: false, ready: true })
).toBe(false)
})
it('keeps unsynchronized and successfully empty data distinct', () => {
expect(parseQAMirrorStatus(initial).ready).toBe(false)
expect(
parseQAMirrorStatus({
...initial,
ready: true,
revision: 1,
error_code: '',
source_observed_at: '2026-10-18T00:00:00Z',
last_success_at: '2026-10-18T00:01:00Z',
next_sync_at: '2026-10-18T00:06:00Z',
}).records
).toBe(0)
})
it('rejects fake completeness, wrong cadence and malformed progress', () => {
expect(() => parseQAMirrorStatus({ ...initial, ready: true })).toThrow('响应无效')
expect(() => parseQAMirrorStatus({ ...initial, interval_seconds: 60 })).toThrow('响应无效')
expect(() =>
parseQAMirrorStatus({
...initial,
job: { id: 'j', state: 'running', loaded: 3, expected: 2, changed: 1, error_code: '' },
})
).toThrow('响应无效')
})
it('rejects equal-count pages from different local generations', () => {
const p = parseQARecordPage({
items: [],
columns: [],
total: 0,
has_more: false,
next_cursor: '',
as_of: '2026-10-18T00:00:00Z',
local_revision: 1,
})
expect(() => mergeQAPages(p, { ...p, local_revision: 2 })).toThrow('本地问答已更新')
})
})
+86
View File
@@ -0,0 +1,86 @@
import { getPayload } from './qaOps'
export interface QAMirrorStatus {
mode: 'local'
ready: boolean
blocked: boolean
revision: number
records: number
source_observed_at: string | null
last_success_at: string | null
next_sync_at: string | null
error_code: string
interval_seconds: 300
worker_ready: boolean
job: { id: string; state: string; loaded: number; expected: number; changed: number; error_code: string } | null
}
const invalid = (): never => {
throw new Error('本地问答同步响应无效,请检查接口契约')
}
const object = (v: unknown): Record<string, unknown> =>
v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : invalid()
const text = (v: unknown): string => (typeof v === 'string' ? v : invalid())
const count = (v: unknown): number => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : invalid())
const bool = (v: unknown): boolean => (typeof v === 'boolean' ? v : invalid())
const stamp = (v: unknown): string | null =>
v === null ? null : typeof v === 'string' && Number.isFinite(Date.parse(v)) ? v : invalid()
export function parseQAMirrorStatus(value: unknown): QAMirrorStatus {
const v = object(value)
if (v.mode !== 'local' || v.interval_seconds !== 300) return invalid()
let job: QAMirrorStatus['job'] = null
if (v.job !== null) {
const j = object(v.job)
const state = text(j.state)
if (!['pending', 'running', 'retry', 'completed', 'failed', 'cancelled'].includes(state)) return invalid()
job = {
id: text(j.id),
state,
loaded: count(j.loaded),
expected: count(j.expected),
changed: count(j.changed),
error_code: text(j.error_code),
}
if (!job.id || job.loaded > job.expected || job.changed > job.loaded) return invalid()
}
const out: QAMirrorStatus = {
mode: 'local',
ready: bool(v.ready),
blocked: bool(v.blocked),
revision: count(v.revision),
records: count(v.records),
source_observed_at: stamp(v.source_observed_at),
last_success_at: stamp(v.last_success_at),
next_sync_at: stamp(v.next_sync_at),
error_code: text(v.error_code),
interval_seconds: 300,
worker_ready: bool(v.worker_ready),
job,
}
if (out.ready && (!out.last_success_at || !out.source_observed_at || out.revision < 1)) return invalid()
if (!out.ready && (out.records !== 0 || out.revision !== 0 || out.last_success_at !== null)) return invalid()
return out
}
export async function fetchQAMirrorStatus(signal?: AbortSignal): Promise<QAMirrorStatus> {
return parseQAMirrorStatus(await getPayload('/api/v1/qa-ops/sync', signal))
}
export async function startQAMirrorSync(key: string, signal?: AbortSignal): Promise<string> {
const data = object(
await getPayload('/api/v1/qa-ops/sync', signal, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-records-sync', 'Idempotency-Key': key },
body: '{}',
})
)
const id = text(data.job_id)
if (!id || typeof data.deduplicated !== 'boolean') return invalid()
return id
}
export function mirrorStateChanged(
previous: { revision: number; blocked: boolean; ready: boolean } | undefined,
current: { revision: number; blocked: boolean; ready: boolean }
): boolean {
return previous
? previous.revision !== current.revision || previous.blocked !== current.blocked || previous.ready !== current.ready
: current.ready
}
export const mirrorSyncActive = (s: QAMirrorStatus | null) =>
Boolean(s?.job && ['pending', 'running', 'retry'].includes(s.job.state))
+4
View File
@@ -60,6 +60,8 @@ export function parseQAOrganizationVersion(value: unknown): QAOrganizationVersio
return result
}
export function mergeQAPages(current: QARecordPage, next: QARecordPage): QARecordPage {
if (current.local_revision !== next.local_revision)
throw new Error('本地问答已更新,请重新查询,不能混合不同同步版本的数据')
if (
current.organization?.directory_id !== next.organization?.directory_id ||
current.organization?.revision_id !== next.organization?.revision_id
@@ -96,6 +98,7 @@ export interface QARecord {
language?: string
}
export interface QARecordPage {
local_revision?: number
organization?: QAOrganizationVersion
items: QARecord[]
columns: QAColumn[]
@@ -232,6 +235,7 @@ export function parseQARecordPage(value: unknown): QARecordPage {
next_cursor: nextCursor,
as_of: instant(page.as_of),
...(page.organization === undefined ? {} : { organization: parseQAOrganizationVersion(page.organization) }),
...(page.local_revision === undefined ? {} : { local_revision: count(page.local_revision) }),
}
}