Files
knowledge-governance/web/src/sourceConnections.ts
T
姚章浩 2c7265efc4
build / build (push) Successful in 58s
feat(sources): 数据源配置收敛成 dws 导入 + PP 导入;「去掉来源」= 归档下架(不删数据)
主人要求:去掉入口,统一成 dws 导入与 PP 导入;其他来源连数据一起下架,之后用 dws 重新获取。

界面(web):
- 「数据源配置」只剩两块:**dws 导入(钉钉)**(按当前钉钉账号列出可访问的知识库与钉盘空间)
  与 **PP 导入**(PP 资料下载中心)。上一步加的「显示 AList/钉钉知识库来源」折叠开关删除。
- 来源卡片新增管理员可见的「去掉来源」(带确认弹窗,说明是归档下架、数据保留可恢复)。
- 侧栏文案改成"只留两个入口";发现面板标题改为「dws 导入(钉钉)」。

后端(归档语义,可逆):
- 迁移 000047:source_connections 增 archived_at / archived_by + 只覆盖未归档行的部分索引。
- store:ArchiveSourceConnection / RestoreSourceConnection(幂等;归档同时停用并清空
  next_refresh_at,避免被手工改回后立刻带着旧调度跑)。列表、目录、计划刷新(claimDue)、
  手动扫描(triggerBlock/inspect)四类查询一律排除归档行。
- 注册路径(dws 重新获取):RegisterDingtalkSpace 的 ON CONFLICT 清掉归档标记 ——
  重新登记同一个空间**原地复活同一行**,不产生重复,历史快照仍属于同一行。
- HTTP:POST /api/v1/source-connections/{id}/archive|restore(管理员专属,写意图头
  source-archive / source-restore + Idempotency-Key;404 区分"不存在"与"已是目标状态");
  openapi 同步两条契约。

验证:
- 集成测试(真 postgres):归档从列表消失但 source_items 一行不少、重复归档不漂移归档时间与人、
  未知 ID 报 ErrSourceConnectionNotFound、归档来源不能再被扫描、恢复后回到列表但保持停用;
  dws 重新登记同一空间复活同一行。
- httpapi:写意图/幂等键门禁、200/403/404/500、错误体不回显内部细节、classifyRole 管理员专属。
- 迁移护栏:000047 结构 + 四类 SQL 必须含 archived_at is null(漏一条就是入口没去掉)。
- make verify 15/15。
2026-10-14 12:36:32 +08:00

538 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 { newOperationID } from './operationKey'
export type SourceConnectionType = 'pp' | 'alist' | 'dingtalk' | 'manual'
export type SourceHealthStatus = 'unknown' | 'healthy' | 'degraded' | 'unhealthy'
export type SourceScanState = 'pending' | 'running' | 'completed' | 'failed'
export interface SourceScanSummary {
id: string
state: SourceScanState
observed_items: number
unchanged_items: number
added_items: number
updated_items: number
over_limit_items: number
missing_items: number
planned_uploads: number
error_code: string
created_at: string
completed_at: string | null
}
export interface TriggeredSourceScan {
id: string
source_connection_id: string
source_type: SourceConnectionType
state: SourceScanState
created_at: string
}
export type SourceScanChangeType = 'added' | 'updated' | 'unavailable'
export interface SourceScanChangeView {
id: string
source_item_id: string | null
change_type: SourceScanChangeType
observed_size_bytes: number | null
created_at: string
}
export interface SourceScanDetail extends SourceScanSummary {
changes: SourceScanChangeView[]
}
export interface SourceScanPage {
items: SourceScanSummary[]
total: number
limit: number
offset: number
}
export interface SourceConnectionView {
id: string
source_type: SourceConnectionType
name: string
enabled: boolean
schedule_configured: boolean
health_status: SourceHealthStatus
item_count: number
updated_at: string
last_scan?: SourceScanSummary | null
}
export interface SourceConnectionSummary {
total: number
enabled: number
disabled: number
healthy: number
degraded: number
unhealthy: number
unknown: number
}
export interface SourceConnectionPage {
items: SourceConnectionView[]
summary: SourceConnectionSummary
}
const sourceTypes = new Set<SourceConnectionType>(['pp', 'alist', 'dingtalk', 'manual'])
const healthStatuses = new Set<SourceHealthStatus>(['unknown', 'healthy', 'degraded', 'unhealthy'])
const scanStates = new Set<SourceScanState>(['pending', 'running', 'completed', 'failed'])
const scanChangeTypes = new Set<SourceScanChangeType>(['added', 'updated', 'unavailable'])
const summaryKeys: ReadonlyArray<keyof SourceConnectionSummary> = [
'total',
'enabled',
'disabled',
'healthy',
'degraded',
'unhealthy',
'unknown',
]
export function parseSourceConnectionsResponse(value: unknown): SourceConnectionPage {
if (!isRecord(value) || !Array.isArray(value.data) || !isRecord(value.summary)) {
throw new Error('invalid source connections response')
}
const items = value.data.map((raw): SourceConnectionView => {
if (
!isRecord(raw) ||
typeof raw.id !== 'string' ||
typeof raw.source_type !== 'string' ||
!sourceTypes.has(raw.source_type as SourceConnectionType) ||
typeof raw.name !== 'string' ||
typeof raw.enabled !== 'boolean' ||
typeof raw.schedule_configured !== 'boolean' ||
typeof raw.health_status !== 'string' ||
!healthStatuses.has(raw.health_status as SourceHealthStatus) ||
!isCount(raw.item_count) ||
typeof raw.updated_at !== 'string'
) {
throw new Error('invalid source connection item')
}
const lastScan = parseSourceScanSummary(raw.last_scan)
return {
id: raw.id,
source_type: raw.source_type as SourceConnectionType,
name: raw.name,
enabled: raw.enabled,
schedule_configured: raw.schedule_configured,
health_status: raw.health_status as SourceHealthStatus,
item_count: raw.item_count,
updated_at: raw.updated_at,
last_scan: lastScan,
}
})
const summary = {} as SourceConnectionSummary
for (const key of summaryKeys) {
const count = value.summary[key]
if (!isCount(count)) throw new Error('invalid source connection summary')
summary[key] = count
}
return { items, summary }
}
export interface SourceConnectionListItem {
id: string
source_type: SourceConnectionType
name: string
enabled: boolean
schedule_configured: boolean
health_status: string
item_count: number
updated_at: string
next_refresh_at: string | null
}
function parseConnectionList(raw: unknown): SourceConnectionListItem[] {
if (!Array.isArray(raw)) throw new Error('invalid source connections list')
return raw.map((item): SourceConnectionListItem => {
if (
!isRecord(item) ||
typeof item.id !== 'string' ||
typeof item.source_type !== 'string' ||
typeof item.name !== 'string' ||
typeof item.enabled !== 'boolean' ||
typeof item.schedule_configured !== 'boolean' ||
typeof item.item_count !== 'number' ||
typeof item.updated_at !== 'string' ||
(item.next_refresh_at !== null && typeof item.next_refresh_at !== 'string')
) {
throw new Error('invalid source connection item')
}
return {
id: item.id,
source_type: item.source_type as SourceConnectionType,
name: item.name,
enabled: item.enabled,
schedule_configured: item.schedule_configured,
health_status: typeof item.health_status === 'string' ? item.health_status : '',
item_count: item.item_count,
updated_at: item.updated_at,
next_refresh_at: (item.next_refresh_at as string | null) ?? null,
}
})
}
export async function fetchSourceConnectionList(signal?: AbortSignal): Promise<SourceConnectionListItem[]> {
const response = await fetch('/api/v1/source-connections', { headers: { Accept: 'application/json' }, signal })
if (!response.ok) throw new Error(`加载来源连接失败(HTTP ${response.status})`)
const value = (await response.json()) as unknown
if (!isRecord(value) || !Array.isArray(value.data)) throw new Error('invalid source connections response')
return parseConnectionList(value.data)
}
export async function fetchSourceConnections(signal?: AbortSignal): Promise<SourceConnectionPage> {
const response = await fetch('/api/v1/source-connections', {
headers: { Accept: 'application/json' },
signal,
})
if (!response.ok) {
throw new Error(`加载来源连接失败(HTTP ${response.status})`)
}
return parseSourceConnectionsResponse(await response.json())
}
export async function triggerSourceScan(connectionID: string): Promise<TriggeredSourceScan> {
const response = await fetch(`/api/v1/source-connections/${encodeURIComponent(connectionID)}/scan`, {
method: 'POST',
headers: { Accept: 'application/json', 'Idempotency-Key': newOperationID() },
})
if (!response.ok) {
throw new Error(response.status === 409 ? '该来源已有扫描正在运行' : `触发来源扫描失败(HTTP ${response.status})`)
}
const raw = (await response.json()) as unknown
if (
!isRecord(raw) ||
typeof raw.id !== 'string' ||
typeof raw.source_connection_id !== 'string' ||
typeof raw.source_type !== 'string' ||
!sourceTypes.has(raw.source_type as SourceConnectionType) ||
typeof raw.state !== 'string' ||
!scanStates.has(raw.state as SourceScanState) ||
typeof raw.created_at !== 'string'
) {
throw new Error('invalid triggered source scan response')
}
return {
id: raw.id,
source_connection_id: raw.source_connection_id,
source_type: raw.source_type as SourceConnectionType,
state: raw.state as SourceScanState,
created_at: raw.created_at,
}
}
export function parseSourceScansResponse(value: unknown): SourceScanPage {
if (
!isRecord(value) ||
!Array.isArray(value.data) ||
!isCount(value.total) ||
!isCount(value.limit) ||
value.limit < 1 ||
!isCount(value.offset)
) {
throw new Error('invalid source scans response')
}
return {
items: value.data.map((item) => {
const parsed = parseSourceScanSummary(item)
if (!parsed) throw new Error('invalid source scan summary')
return parsed
}),
total: value.total,
limit: value.limit,
offset: value.offset,
}
}
export function parseSourceScanDetailResponse(value: unknown): SourceScanDetail {
if (!isRecord(value) || !isRecord(value.data) || !Array.isArray(value.data.changes)) {
throw new Error('invalid source scan detail response')
}
const summary = parseSourceScanSummary(value.data)
if (!summary) throw new Error('invalid source scan detail response')
const changes = value.data.changes.map((raw): SourceScanChangeView => {
if (
!isRecord(raw) ||
typeof raw.id !== 'string' ||
(raw.source_item_id !== null && typeof raw.source_item_id !== 'string') ||
typeof raw.change_type !== 'string' ||
!scanChangeTypes.has(raw.change_type as SourceScanChangeType) ||
(raw.observed_size_bytes !== null && !isCount(raw.observed_size_bytes)) ||
typeof raw.created_at !== 'string'
) {
throw new Error('invalid source scan change')
}
return {
id: raw.id,
source_item_id: raw.source_item_id as string | null,
change_type: raw.change_type as SourceScanChangeType,
observed_size_bytes: raw.observed_size_bytes as number | null,
created_at: raw.created_at,
}
})
return { ...summary, changes }
}
export async function fetchSourceScans(
connectionID: string,
limit = 20,
offset = 0,
signal?: AbortSignal
): Promise<SourceScanPage> {
const params = new URLSearchParams({ limit: String(limit), offset: String(offset) })
const response = await fetch(`/api/v1/source-connections/${encodeURIComponent(connectionID)}/scans?${params}`, {
headers: { Accept: 'application/json' },
signal,
})
if (!response.ok) throw new Error(`加载扫描历史失败(HTTP ${response.status})`)
return parseSourceScansResponse(await response.json())
}
export async function fetchSourceScanDetail(
connectionID: string,
scanID: string,
signal?: AbortSignal
): Promise<SourceScanDetail> {
const response = await fetch(
`/api/v1/source-connections/${encodeURIComponent(connectionID)}/scans/${encodeURIComponent(scanID)}`,
{
headers: { Accept: 'application/json' },
signal,
}
)
if (!response.ok) throw new Error(`加载扫描详情失败(HTTP ${response.status})`)
return parseSourceScanDetailResponse(await response.json())
}
function parseSourceScanSummary(raw: unknown): SourceScanSummary | null {
if (raw === null || raw === undefined) return null
if (
!isRecord(raw) ||
typeof raw.id !== 'string' ||
typeof raw.state !== 'string' ||
!scanStates.has(raw.state as SourceScanState) ||
typeof raw.error_code !== 'string' ||
typeof raw.created_at !== 'string' ||
(raw.completed_at !== null && typeof raw.completed_at !== 'string')
) {
throw new Error('invalid source scan summary')
}
const countKeys = [
'observed_items',
'unchanged_items',
'added_items',
'updated_items',
'over_limit_items',
'missing_items',
'planned_uploads',
] as const
for (const key of countKeys) {
if (!isCount(raw[key])) throw new Error('invalid source scan summary')
}
return {
id: raw.id,
state: raw.state as SourceScanState,
observed_items: raw.observed_items as number,
unchanged_items: raw.unchanged_items as number,
added_items: raw.added_items as number,
updated_items: raw.updated_items as number,
over_limit_items: raw.over_limit_items as number,
missing_items: raw.missing_items as number,
planned_uploads: raw.planned_uploads as number,
error_code: raw.error_code,
created_at: raw.created_at,
completed_at: raw.completed_at as string | null,
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null
}
function isCount(value: unknown): value is number {
return typeof value === 'number' && Number.isInteger(value) && value >= 0
}
// V1 source settings revisions -------------------------------------------------
export type SourceSettingsRevisionState = 'validated' | 'active' | 'retired' | 'failed'
export interface SourceSettingsRevision {
id: string
revision_number: number
state: SourceSettingsRevisionState
name: string
endpoint: string
credential_ref: string
enabled: boolean
refresh_interval_seconds: string
created_by: string
created_at: string
validated_at: string | null
activated_at: string | null
retired_at: string | null
}
export interface SourceSettingsDraftRequest {
source_type: SourceConnectionType
name: string
endpoint: string
credential_ref: string
enabled: boolean
schedule: { refresh_interval_seconds?: number | null }
}
const revisionStates = new Set<SourceSettingsRevisionState>(['validated', 'active', 'retired', 'failed'])
function parseSettingsRevision(raw: unknown): SourceSettingsRevision {
if (
!isRecord(raw) ||
typeof raw.id !== 'string' ||
typeof raw.revision_number !== 'number' ||
typeof raw.state !== 'string' ||
!revisionStates.has(raw.state as SourceSettingsRevisionState) ||
typeof raw.name !== 'string' ||
typeof raw.endpoint !== 'string' ||
typeof raw.credential_ref !== 'string' ||
typeof raw.enabled !== 'boolean' ||
typeof raw.refresh_interval_seconds !== 'string' ||
typeof raw.created_by !== 'string' ||
typeof raw.created_at !== 'string' ||
(raw.validated_at !== null && typeof raw.validated_at !== 'string') ||
(raw.activated_at !== null && typeof raw.activated_at !== 'string') ||
(raw.retired_at !== null && typeof raw.retired_at !== 'string')
) {
throw new Error('invalid source settings revision')
}
return {
id: raw.id,
revision_number: raw.revision_number,
state: raw.state as SourceSettingsRevisionState,
name: raw.name,
endpoint: raw.endpoint,
credential_ref: raw.credential_ref,
enabled: raw.enabled,
refresh_interval_seconds: raw.refresh_interval_seconds,
created_by: raw.created_by,
created_at: raw.created_at,
validated_at: (raw.validated_at as string | null) ?? null,
activated_at: (raw.activated_at as string | null) ?? null,
retired_at: (raw.retired_at as string | null) ?? null,
}
}
export async function fetchSourceSettingsRevisions(
connectionID: string,
signal?: AbortSignal
): Promise<SourceSettingsRevision[]> {
const response = await fetch(`/api/v1/source-connections/${encodeURIComponent(connectionID)}/settings/revisions`, {
headers: { Accept: 'application/json' },
signal,
})
if (!response.ok) throw new Error(`加载来源设置历史失败(HTTP ${response.status})`)
const value = (await response.json()) as unknown
if (!isRecord(value) || !Array.isArray(value.data)) throw new Error('invalid source settings revisions response')
return value.data.map(parseSettingsRevision)
}
async function postSourceSettings(
path: string,
body: string,
errorMessage: string
): Promise<{ operation: string; id: string | null }> {
const response = await fetch(path, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Governance-Action': 'source-settings',
'Idempotency-Key': newOperationID(),
},
body,
})
if (!response.ok) {
let detail = ''
try {
const parsed = (await response.json()) as unknown
if (isRecord(parsed) && typeof parsed.error === 'string') detail = parsed.error
} catch {
/* keep status-only message */
}
throw new Error(detail ? `${errorMessage}:${detail}` : `${errorMessage}(HTTP ${response.status})`)
}
const value = (await response.json()) as unknown
if (!isRecord(value) || (value.operation !== 'created' && value.operation !== 'replayed') || !isRecord(value.data))
throw new Error('invalid source settings response')
const id = typeof value.data.id === 'string' ? value.data.id : null
return { operation: value.operation, id }
}
export async function createSourceSettingsRevision(
connectionID: string,
draft: SourceSettingsDraftRequest
): Promise<{ operation: string; id: string }> {
const result = await postSourceSettings(
`/api/v1/source-connections/${encodeURIComponent(connectionID)}/settings/revisions`,
JSON.stringify(draft),
'保存来源设置草稿失败'
)
if (!result.id) throw new Error('创建来源设置草稿未返回修订号')
return result as { operation: string; id: string }
}
export async function activateSourceSettingsRevision(
connectionID: string,
revisionID: string
): Promise<{ operation: string }> {
return postSourceSettings(
`/api/v1/source-connections/${encodeURIComponent(connectionID)}/settings/revisions/${encodeURIComponent(revisionID)}/activate`,
'{}',
'启用来源设置修订失败'
)
}
/**
* 「去掉来源」:归档下架(**不是物理删除**)。
* 来源会从数据源配置、来源与目录、计划刷新与手动扫描里消失;目录快照、发布记录与
* 审计数据原样保留 —— 再用 dws 重新登记同一个来源就会原地复活。幂等,仅管理员可用。
*/
export async function archiveSourceConnection(connectionID: string): Promise<void> {
await postSourceArchive(
`/api/v1/source-connections/${encodeURIComponent(connectionID)}/archive`,
'source-archive',
'去掉来源失败'
)
}
/** 撤销归档:来源重新出现,但保持停用(调度不会自动恢复)。 */
export async function restoreSourceConnection(connectionID: string): Promise<void> {
await postSourceArchive(
`/api/v1/source-connections/${encodeURIComponent(connectionID)}/restore`,
'source-restore',
'恢复来源失败'
)
}
async function postSourceArchive(path: string, intent: string, errorMessage: string): Promise<void> {
const response = await fetch(path, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Governance-Action': intent,
'Idempotency-Key': newOperationID(),
},
body: '{}',
})
if (!response.ok) {
let detail = ''
try {
const parsed = (await response.json()) as unknown
if (isRecord(parsed) && typeof parsed.error === 'string') detail = parsed.error
} catch {
/* keep status-only message */
}
throw new Error(detail ? `${errorMessage}:${detail}` : `${errorMessage}(HTTP ${response.status})`)
}
}