feat(sources): 数据源配置收敛成 dws 导入 + PP 导入;「去掉来源」= 归档下架(不删数据)
build / build (push) Successful in 58s

主人要求:去掉入口,统一成 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。
This commit is contained in:
姚章浩
2026-10-14 12:36:32 +08:00
parent 64b32c2da6
commit 2c7265efc4
20 changed files with 1426 additions and 281 deletions
+218 -58
View File
@@ -79,7 +79,13 @@ const healthStatuses = new Set<SourceHealthStatus>(['unknown', 'healthy', 'degra
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',
'total',
'enabled',
'disabled',
'healthy',
'degraded',
'unhealthy',
'unknown',
]
export function parseSourceConnectionsResponse(value: unknown): SourceConnectionPage {
@@ -87,11 +93,19 @@ export function parseSourceConnectionsResponse(value: unknown): SourceConnection
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') {
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)
@@ -131,18 +145,28 @@ export interface SourceConnectionListItem {
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')) {
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,
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,
item_count: item.item_count,
updated_at: item.updated_at,
next_refresh_at: (item.next_refresh_at as string | null) ?? null,
}
})
@@ -151,7 +175,7 @@ function parseConnectionList(raw: unknown): SourceConnectionListItem[] {
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
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)
}
@@ -175,10 +199,17 @@ export async function triggerSourceScan(connectionID: string): Promise<Triggered
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') {
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 {
@@ -191,8 +222,14 @@ export async function triggerSourceScan(connectionID: string): Promise<Triggered
}
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)) {
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 {
@@ -214,10 +251,15 @@ export function parseSourceScanDetailResponse(value: unknown): SourceScanDetail
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') {
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 {
@@ -231,31 +273,59 @@ export function parseSourceScanDetailResponse(value: unknown): SourceScanDetail
return { ...summary, changes }
}
export async function fetchSourceScans(connectionID: string, limit = 20, offset = 0, signal?: AbortSignal): Promise<SourceScanPage> {
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,
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,
})
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')) {
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
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')
}
@@ -315,63 +385,153 @@ export interface SourceSettingsDraftRequest {
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')) {
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,
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[]> {
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
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 }> {
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() },
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
const parsed = (await response.json()) as unknown
if (isRecord(parsed) && typeof parsed.error === 'string') detail = parsed.error
} catch { /* keep status-only message */ }
} 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 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), '保存来源设置草稿失败')
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`, '{}', '启用来源设置修订失败')
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})`)
}
}