feat(monitor): 需下架车道可逐条移除测试库知识 —— 补齐最后一个没有页面入口的流程

背景:来源侧被判「禁止导入」后,已建好的测试库知识不会自动消失;此前只有变更集
删除路径会入队 test.remove,页面既列不出条目也没有按钮,运维无法闭环(车道只有按
库计数)。

新增:
- GET /api/v1/test-publications?removal=required:条目级列表,判据与车道计数同源
  (superseded_at IS NULL / 有 knowledge_id / completed / retrieval_state NOT IN
  (disabling,disabled) / policy_state='blocked'),过滤是叠加而不是替换。
- POST /api/v1/test-publications/{id}/removal:engineer 级写路由,要求 Idempotency-Key,
  按条目幂等(operator-remove:<id>);置 disabling 并交既有 test.remove 工作流去删除
  远端知识并读回校验。错误映射 404/409(已移除)/409(不可移除)/501(未接线)。
- 界面:需下架车道逐条显示条目 + 「下架(从测试库移除)」,页内二次确认,成功提示,
  完成后计数归零。

修掉过程中踩到的两个真问题:
1. 二次确认的确认态原先经容器 props 传给视图,一次容器改动把三个 props 丢了 ——
   视图永远渲染原按钮、确认步骤静默消失,而所有静态单元测试仍然通过。改为把确认态
   放在视图内部;并把「取消」放在原按钮位置(真实指针连点两下只会落到取消)。
2. jobs 上有部分唯一索引 UNIQUE (business_change_set_id, business_version_id,
   business_target_kb_id, business_action) WHERE business_change_set_id IS NOT NULL。
   本路径给这三列写空串(非 NULL),('','','','remove') 对所有条目是同一个键 ——
   第一条之后每次 INSERT 都撞唯一索引、被 ON CONFLICT DO NOTHING 静默吞掉,留下
   「状态已 disabling、没有任务」的永久卡死条目,而车道恰好隐藏 disabling,运维也
   看不到。改为写 NULL(语义:无变更集身份)+ 冲突目标收敛到 idempotency_key +
   校验 RowsAffected()(0 行回查既有任务;查不到就报错,不提交无任务的 disabling)。
   卡死状态在重试时可自愈。

测试:internal/platform/postgres/test_publication_removal_integration_test.go(两条发布
各自入队、business_* 为 NULL、卡死自愈;把修复退回旧写法该测试即 FAIL,已实测)、
internal/httpapi/test_publication_removal_test.go(权限/幂等键/错误映射/未接线 501/列表
过滤)、前端 testPublications.test.ts + WeKnoraMonitor.test.tsx。

验收(纯界面,两条都走完):解析监控 → 需下架(2)→ 逐条「下架」+ 二次确认 →
retrieval_state=disabled(PDF 03:57:03Z、md 04:08:55Z),jobs completed(attempt 2,
首次 test_remove_pending=远端仍在处理,重试通过;工作流以 GetKnowledge 读回 404 判
成功)→ 车道需下架(0)。核验「确认前不执行」:首次点击后仍 unpublished、移除任务数仍 1。
This commit is contained in:
姚章浩
2026-10-10 12:10:46 +08:00
parent e9a643cc33
commit a1b46d2b7c
14 changed files with 4488 additions and 3684 deletions
+7
View File
@@ -34,6 +34,13 @@ describe('WeKnoraMonitorView',()=>{
const removal=renderToStaticMarkup(<WeKnoraMonitorView {...baseProps} lane="removal" />)
expect(removal).toContain('需下架(3)')
expect(removal).toContain('3 份仍在检索中')
const withItems = renderToStaticMarkup(<WeKnoraMonitorView {...baseProps} lane="removal" removalItems={[{ id: 'tp-live', title: '相机线束固定孔位尺寸图.pdf', target_scope: 'internal', processing_state: 'completed', ingest_state: 'uploaded', retrieval_state: 'unpublished', source_item_id: 'si-1', source_item_version_id: 'siv-1', knowledge_id: 'knowledge-1', updated_at: '2026-10-10T03:00:00Z', created_at: '2026-10-10T02:00:00Z' } as never]} /> as never)
expect(withItems).toContain('相机线束固定孔位尺寸图.pdf')
expect(withItems).toContain('下架(从测试库移除)')
// 确认态在视图内部(不依赖容器传参):初始渲染必须是普通按钮,且不得出现确认/取消,
// 避免"点一下就直接执行"的降级。
expect(withItems).toContain('下架(从测试库移除)')
expect(withItems).not.toContain('确认下架(从测试库移除)')
})
it('shows inbox lanes for the knowledge-base diff view',()=>{
const attention=renderToStaticMarkup(<WeKnoraMonitorView {...baseProps} lane='attention' />)
+39 -6
View File
@@ -3,7 +3,7 @@ import { useContext, useEffect, useMemo, useState } from 'react'
import { fetchMonitorFiles, fetchMonitorOverview, fetchRunMetrics } from './monitor'
import type { RunMetrics } from './monitor'
import type { KnowledgeProgress, MonitorFilePage, MonitorOverview, MonitorStatus } from './monitor'
import { fetchJobFailures, fetchTestPublications, retryPublication, retryPublicationsBatch, cancelPublicationsBatch, requeueJobFailure, startTestPublications } from './testPublications'
import { fetchJobFailures, fetchTestPublications, retryPublication, retryPublicationsBatch, cancelPublicationsBatch, requeueJobFailure, startTestPublications, fetchRemovalRequiredPublications, startPublicationRemoval } from './testPublications'
import type { JobFailure, ProcessingState, TestPublication, TestPublicationPage } from './testPublications'
import { fetchActiveUISettings, settingsRefreshDelays } from './uiSettings'
import { WorkspaceContextTabsSetter } from './workspaceContext'
@@ -107,6 +107,11 @@ interface ViewProps {
onStart?: (ids: string[]) => void
onLoadMore?: () => void
onRefresh: () => void
/** 需下架车道的条目列表(被禁止导入但仍存活在测试库),以及移除动作。 */
removalItems?: TestPublication[]
removalBusyIDs?: string[]
removalMessage?: string
onStartRemoval?: (id: string) => void
}
export function WeKnoraMonitorView({
@@ -143,9 +148,15 @@ export function WeKnoraMonitorView({
onStart = () => undefined,
onLoadMore = () => undefined,
onRefresh,
removalItems = [],
removalBusyIDs = [],
removalMessage = '',
onStartRemoval = () => undefined,
}: ViewProps) {
const [selectedStartIDs, setSelectedStartIDs] = useState<string[]>([])
const [selectedRetryIDs, setSelectedRetryIDs] = useState<string[]>([])
// 破坏性动作的二次确认状态放在视图内部:容器漏传参也不会把"确认"这一步静默降级掉。
const [confirmRemovalID, setConfirmRemovalID] = useState('')
const toggleStartSelection = (id: string) => setSelectedStartIDs((current) => current.includes(id) ? current.filter((value) => value !== id) : [...current, id])
const toggleRetrySelection = (id: string) => setSelectedRetryIDs((current) => current.includes(id) ? current.filter((value) => value !== id) : [...current, id])
const stages: Array<[MonitorStatus, number]> = selectedKB ? [
@@ -217,8 +228,10 @@ export function WeKnoraMonitorView({
</section> : null}
{lane === 'removal' ? <section className="inbox-section" aria-label="需下架">
<div className="section-head"><h2>需下架({laneCounts.removal})</h2><span className="tiny">来源目录里被改为“禁止导入”或撤销标注、但仍在知识库中可检索的文件</span></div>
{(overview?.knowledge_bases || []).some((kb) => kb.needs_removal > 0) ? <ul className="dlq-list">{(overview?.knowledge_bases || []).filter((kb) => kb.needs_removal > 0).map((kb) => <li key={kb.id}><span className="monitor-status failed">需下架</span><b>{kb.name}</b><small>{kb.needs_removal} 份仍在检索中</small></li>)}</ul> : emptyLane('没有标注为禁止但仍留在知识库里的文件。')}
<p className="tiny">这里只负责把差异暴露出来:来源项被判“禁止导入”后,仍存活在测试库里的知识必须移除。移除动作走 <code>test.remove</code> 工作流(会删除测试库里的知识条目,重新标注后可再次入库);该入口当前由变更集删除路径触发,页面尚未提供独立按钮。</p>
{removalMessage ? <p className="tiny" role="status">{removalMessage}</p> : null}
{removalItems.length ? <ul className="dlq-list">{removalItems.map((item) => <li key={item.id}><span className="monitor-status failed">需下架</span><b>「{item.title}」</b><small>{scope(item.target_scope)} · 知识仍在测试库中可检索</small>{confirmRemovalID === item.id ? <><button onClick={() => setConfirmRemovalID('')}>取消</button><button disabled={removalBusyIDs.includes(item.id)} onClick={() => { setConfirmRemovalID(''); onStartRemoval(item.id) }}>{removalBusyIDs.includes(item.id) ? '下架中…' : '确认下架(从测试库移除)'}</button></> : <button disabled={removalBusyIDs.includes(item.id)} onClick={() => setConfirmRemovalID(item.id)}>下架(从测试库移除)</button>}</li>)}</ul> : null}
{(overview?.knowledge_bases || []).some((kb) => kb.needs_removal > 0) ? <ul className="dlq-list">{(overview?.knowledge_bases || []).filter((kb) => kb.needs_removal > 0).map((kb) => <li key={kb.id}><span className="monitor-status failed">需下架</span><b>{kb.name}</b><small>{kb.needs_removal} 份仍在检索中</small></li>)}</ul> : removalItems.length ? null : emptyLane('没有标注为禁止但仍留在知识库里的文件。')}
<p className="tiny">这里只负责把差异暴露出来:来源项被判“禁止导入”后,仍存活在测试库里的知识必须移除。逐条点“下架(从测试库移除)”并二次确认后,走 <code>test.remove</code> 工作流删除测试库里的知识条目(会读回校验;重新标注后可再次入库,不影响生产知识库)。</p>
</section> : null}
{lane === 'inflight' ? <section className="inbox-section" aria-label="处理中">
<div className="section-head"><h2>处理中({inflightItems.length})</h2><span className="tiny">无需操作,仅供查看</span></div>
@@ -276,6 +289,9 @@ export function WeKnoraMonitor() {
const [batchMessage, setBatchMessage] = useState('')
const [failures, setFailures] = useState<JobFailure[]>([])
const [attention, setAttention] = useState<TestPublication[] | null>(null)
const [removalItems, setRemovalItems] = useState<TestPublication[]>([])
const [removalBusyIDs, setRemovalBusyIDs] = useState<string[]>([])
const [removalMessage, setRemovalMessage] = useState('')
const [loadingMore, setLoadingMore] = useState(false)
const [metrics, setMetrics] = useState<RunMetrics | null>(null)
const setContextTabs = useContext(WorkspaceContextTabsSetter)
@@ -306,8 +322,9 @@ export function WeKnoraMonitor() {
fetchTestPublications({ processing_state: queueStatus, target_scope: queueScope, limit: 50, offset: 0 }, controller.signal),
fetchTestPublications({ processing_state: 'planned', limit: 100, offset: 0 }, controller.signal),
fetchTestPublications({ processing_state: ['failed', 'stalled'], limit: 100, offset: 0 }, controller.signal),
]).then(([queuePage, planPage, attentionPage]) => {
if (!controller.signal.aborted) { setQueue(queuePage); setPlans(planPage.items); setAttention(attentionPage.items); setError(null) }
fetchRemovalRequiredPublications(controller.signal),
]).then(([queuePage, planPage, attentionPage, removalPage]) => {
if (!controller.signal.aborted) { setQueue(queuePage); setPlans(planPage.items); setAttention(attentionPage.items); setRemovalItems(removalPage.items); setError(null) }
}).catch((cause) => { if (!controller.signal.aborted) setError(cause instanceof Error ? cause.message : '加载解析队列失败') }).finally(() => { if (!controller.signal.aborted) setLoading(false) })
return () => controller.abort()
}, [queueStatus, queueScope, documentRevision])
@@ -379,6 +396,22 @@ export function WeKnoraMonitor() {
}
}
// 需下架 → 移除:把被禁止导入、但仍存活在测试库的知识交给既有的 test.remove 工作流。
const startRemoval = async (id: string) => {
if (removalBusyIDs.includes(id)) return
setRemovalBusyIDs((current: string[]) => [...current, id])
setRemovalMessage('')
try {
await startPublicationRemoval(id)
setRemovalMessage('已受理下架:正在移除测试库中的知识条目,完成后本条会从「需下架」消失。')
setDocumentRevision((value) => value + 1)
} catch (cause) {
setRemovalMessage(cause instanceof Error ? cause.message : '触发下架失败')
} finally {
setRemovalBusyIDs((current: string[]) => current.filter((value) => value !== id))
}
}
const loadMoreQueue = async () => {
if (loadingMore) return
setLoadingMore(true)
@@ -441,5 +474,5 @@ export function WeKnoraMonitor() {
setStarting(false)
}
}
return <WeKnoraMonitorView overview={overview} files={files} queue={queue} plans={plans} selectedKB={selected} status={status} queueStatus={queueStatus} queueScope={queueScope} loading={loading} error={error} retryingIDs={retryingIDs} requeueingIDs={requeueingIDs} cancellingIDs={cancellingIDs} starting={starting} startMessage={startMessage} batchMessage={batchMessage} failures={failures} metrics={metrics} onSelectKB={(kb) => { setSelected(kb); setStatus(''); setFiles(null) }} onStatus={(value) => { setStatus(value); setFiles(null) }} onQueueStatus={setQueueStatus} onQueueScope={setQueueScope} lane={lane} onLaneChange={(value) => setLane(value as typeof lane)} onRetry={(id) => void retryOne(id)} onBatchRetry={(ids) => void retryBatch(ids)} onBatchCancel={(ids) => void cancelBatch(ids)} onRequeueFailure={(id) => void requeueFailure(id)} onStart={(ids) => void startPlans(ids)} attention={attention ?? undefined} loadingMore={loadingMore} onLoadMore={() => void loadMoreQueue()} onRefresh={() => { setDocumentRevision((value) => value + 1); setResourceRevision((value) => value + 1) }} />
return <WeKnoraMonitorView overview={overview} files={files} queue={queue} plans={plans} selectedKB={selected} status={status} queueStatus={queueStatus} queueScope={queueScope} loading={loading} error={error} retryingIDs={retryingIDs} requeueingIDs={requeueingIDs} cancellingIDs={cancellingIDs} starting={starting} startMessage={startMessage} batchMessage={batchMessage} failures={failures} metrics={metrics} onSelectKB={(kb) => { setSelected(kb); setStatus(''); setFiles(null) }} onStatus={(value) => { setStatus(value); setFiles(null) }} onQueueStatus={setQueueStatus} onQueueScope={setQueueScope} lane={lane} onLaneChange={(value) => setLane(value as typeof lane)} onRetry={(id) => void retryOne(id)} onBatchRetry={(ids) => void retryBatch(ids)} onBatchCancel={(ids) => void cancelBatch(ids)} onRequeueFailure={(id) => void requeueFailure(id)} onStart={(ids) => void startPlans(ids)} attention={attention ?? undefined} loadingMore={loadingMore} onLoadMore={() => void loadMoreQueue()} onRefresh={() => { setDocumentRevision((value) => value + 1); setResourceRevision((value) => value + 1) }} removalItems={removalItems} removalBusyIDs={removalBusyIDs} removalMessage={removalMessage} onStartRemoval={(id) => void startRemoval(id)} />
}
+32 -1
View File
@@ -1,6 +1,6 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { fetchAcceptanceResults, fetchTestPublications, parseTestPublicationsResponse, retryPublication, retryPublicationsBatch, startTestPublications, fetchJobFailures } from './testPublications'
import { fetchAcceptanceResults, fetchTestPublications, parseTestPublicationsResponse, retryPublication, retryPublicationsBatch, startTestPublications, fetchJobFailures, fetchRemovalRequiredPublications, startPublicationRemoval } from './testPublications'
afterEach(() => vi.unstubAllGlobals())
@@ -89,6 +89,37 @@ describe('retryPublication', () => {
})
})
describe('需下架条目的移除入口', () => {
it('只取被禁止但仍存活在测试库的条目', async () => {
const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ data: [], total: 0, limit: 50, offset: 0 }) })
vi.stubGlobal('fetch', fetchMock)
await fetchRemovalRequiredPublications()
const url = String(fetchMock.mock.calls[0][0])
expect(url).toContain('/api/v1/test-publications?')
expect(url).toContain('removal=required')
})
it('带幂等键触发下架并回传任务号', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ publication_id: 'tp-1', job_id: 'job-remove-1', state: 'disabling' }), { status: 202 }))
vi.stubGlobal('fetch', fetchMock)
await expect(startPublicationRemoval('tp-1')).resolves.toEqual({ job_id: 'job-remove-1' })
const [url, init] = fetchMock.mock.calls[0]
expect(url).toBe('/api/v1/test-publications/tp-1/removal')
expect(init.method).toBe('POST')
expect(String(init.headers['Idempotency-Key'])).not.toHaveLength(0)
})
it('把服务端拒绝原因原样抛给界面', async () => {
const fetchMock = vi.fn().mockResolvedValue({ status: 409, json: async () => ({ error: '该知识的检索已经移除,无需重复下架' }) })
vi.stubGlobal('fetch', fetchMock)
await expect(startPublicationRemoval('tp-1')).rejects.toThrow('该知识的检索已经移除,无需重复下架')
})
})
describe('startTestPublications', () => {
it('starts only the explicitly confirmed processing plans', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: { selected: 2, started: 1, already_started: 1, unavailable: 0 } }), { status: 202 }))
+29
View File
@@ -34,6 +34,8 @@ export interface AcceptanceRecord {
}
export interface TestPublicationQuery {
/** removal: 'required' 只取「被禁止导入但仍存活在测试库」的条目(解析监控 → 需下架)。 */
removal?: 'required'
// A single state, or several at once (joined into a comma list server-side).
processing_state: ProcessingState | '' | ProcessingState[]
target_scope?: 'internal' | 'external' | ''
@@ -96,6 +98,7 @@ export async function fetchTestPublications(query: TestPublicationQuery, signal?
const parameters = new URLSearchParams()
if (query.processing_state) parameters.set('processing_state', Array.isArray(query.processing_state) ? query.processing_state.join(',') : query.processing_state)
if (query.target_scope) parameters.set('target_scope', query.target_scope)
if (query.removal) parameters.set('removal', query.removal)
parameters.set('limit', String(query.limit))
parameters.set('offset', String(query.offset))
const response = await fetch(`/api/v1/test-publications?${parameters.toString()}`, { headers: { Accept: 'application/json' }, signal })
@@ -103,6 +106,32 @@ export async function fetchTestPublications(query: TestPublicationQuery, signal?
return parseTestPublicationsResponse(await response.json())
}
/**
* 需下架车道用:列出「来源侧被判禁止导入、但知识仍存活在测试库里」的具体条目。
* 此前车道只有按库计数,运维看不到条目、也没有处置入口。
*/
export async function fetchRemovalRequiredPublications(signal?: AbortSignal): Promise<TestPublicationPage> {
return fetchTestPublications({ processing_state: '', removal: 'required', limit: 50, offset: 0 }, signal)
}
/**
* 触发移除:把该条目置为下架中,交服务端既有的 test.remove 工作流去删远端知识并读回校验。
* 服务端按条目幂等(重复点击不会重复入队),因此这里每次生成新的幂等键是安全的。
*/
export async function startPublicationRemoval(publicationId: string): Promise<{ job_id: string }> {
const response = await fetch(`/api/v1/test-publications/${encodeURIComponent(publicationId)}/removal`, {
method: 'POST',
headers: { Accept: 'application/json', 'Idempotency-Key': newOperationID() },
})
if (response.status !== 202) {
const body = (await response.json().catch(() => null)) as { error?: string } | null
throw new Error(body?.error ?? `触发下架失败(HTTP ${response.status})`)
}
const value = await response.json() as unknown
if (!isRecord(value) || typeof value.job_id !== 'string') throw new Error('下架响应无效')
return { job_id: value.job_id }
}
export async function fetchAcceptanceResults(publicationId: string, signal?: AbortSignal): Promise<AcceptanceRecord[]> {
const response = await fetch(`/api/v1/test-publications/${encodeURIComponent(publicationId)}/acceptance`, { headers: { Accept: 'application/json' }, signal })
if (!response.ok) throw new Error(`加载验收结果失败(HTTP ${response.status})`)