fix(dingtalk): 登记钉钉知识库 409 space_registration_conflict —— 归档行占名 + 错误被吞
build / build (push) Successful in 57s

现象:点「公司级技术支持知识库」登记,返回 HTTP 409:space_registration_conflict。

根因(真数据取证):
- source_connections.name 有唯一约束。这 3 个钉钉来源是**早期路径**登记的
  (base_url 为空,id 与 dws 现在推导的确定性 id 不同):
  sc-18d10ca0… 公司级技术支持知识库 / sc-eaef0ec1… ATOM知识库 / sc-dc7cea1c… 技术诊断部知识沉淀。
- 上一步「去掉来源」只是归档下架,**名字仍占着唯一槽位** ⇒ 重新登记时 INSERT 撞
  UNIQUE(name)。
- 处理器把**所有**存储层错误都翻译成同一个 409 space_registration_conflict(真实原因被吞)。

修复:
- store:同名的另一行若**已归档** ⇒ 改名腾位(`…(已下架 · <短ID>)`,归档行不显示,
  数据与审计一行不动);若**仍在使用** ⇒ ErrDingtalkSpaceNameTaken(绝不悄悄改名)。
  同一个登记键解析到别的 root 时:在用中的行报 ErrDingtalkSpaceIdentityConflict;
  归档过的行允许就地改写("去掉后再用 dws 重新获取"的语义)。
- httpapi:分类映射 —— space_name_conflict / space_identity_conflict(409 + 可行动 hint),
  其余内部故障改回 500 space_registration_failed,不再伪装成冲突。
- web:读一次响应体同时取 error 与 hint,**hint 优先**;补两个新码的中文说明。

验证:真 postgres 集成测试复刻线上形态(旧行占名 + 归档 ⇒ 登记成功、旧行改名保持归档、
内容不丢;同名在用 ⇒ 拒绝;同键换 root 在用 ⇒ 拒绝、归档 ⇒ 就地改写);handler 分类测试
(409/409/500,且不回显内部细节);前端 hint 优先用例;make verify 15/15。
This commit is contained in:
姚章浩
2026-10-14 12:59:52 +08:00
parent 2c7265efc4
commit 9a8a3e7795
7 changed files with 363 additions and 31 deletions
+54 -9
View File
@@ -6,9 +6,17 @@ afterEach(() => vi.unstubAllGlobals())
describe('DingTalk session client', () => {
it('returns the starting state immediately while the QR is being generated', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({
id: 'session-1', state: 'starting', created_at: 1, expires_at: 2,
}), { status: 201 }))
const fetchMock = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: 'session-1',
state: 'starting',
created_at: 1,
expires_at: 2,
}),
{ status: 201 }
)
)
vi.stubGlobal('fetch', fetchMock)
const target = 'https://alidocs.dingtalk.com/i/spaces/9JOGOQneRgkneX4Q/overview'
@@ -18,14 +26,51 @@ describe('DingTalk session client', () => {
})
it('preserves login_required as a machine-readable error for automatic QR fallback', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(
JSON.stringify({ error: 'login_required' }),
{ status: 409, headers: { 'Content-Type': 'application/json' } },
)))
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue(
new Response(JSON.stringify({ error: 'login_required' }), {
status: 409,
headers: { 'Content-Type': 'application/json' },
})
)
)
const error = await registerDingtalkSpace('https://alidocs.dingtalk.com/i/spaces/9JOGOQneRgkneX4Q/overview')
.then(() => null, (cause: unknown) => cause)
const error = await registerDingtalkSpace('https://alidocs.dingtalk.com/i/spaces/9JOGOQneRgkneX4Q/overview').then(
() => null,
(cause: unknown) => cause
)
expect(error).toBeInstanceOf(DingtalkRequestError)
expect(error).toMatchObject({ code: 'login_required', status: 409 })
})
})
describe('钉钉知识库登记的失败说明', () => {
it('后端 hint 优先,其次本地文案;错误码始终带出', async () => {
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue(
new Response(JSON.stringify({ error: 'space_name_conflict', hint: '已有同名来源仍在使用:先「去掉来源」' }), {
status: 409,
})
)
)
await expect(registerDingtalkSpace('https://alidocs.dingtalk.com/i/spaces/x')).rejects.toThrow(
'已有同名来源仍在使用:先「去掉来源」'
)
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue(new Response(JSON.stringify({ error: 'space_identity_conflict' }), { status: 409 }))
)
await expect(registerDingtalkSpace('https://alidocs.dingtalk.com/i/spaces/x')).rejects.toThrow(
'这个登记键已指向另一个知识库空间'
)
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue(new Response(JSON.stringify({ error: 'space_registration_failed' }), { status: 500 }))
)
await expect(registerDingtalkSpace('https://alidocs.dingtalk.com/i/spaces/x')).rejects.toThrow(
'登记失败(服务端内部错误)'
)
})
})
+59 -15
View File
@@ -4,7 +4,8 @@ import { newOperationID } from './operationKey'
// The API proxies to the dingtalk-login sidecar; this module never sees the
// token itself — only the base64 QR image and a terminal state.
export type DingtalkSessionState = 'starting' | 'qr' | 'scanned' | 'reusing' | 'success' | 'expired' | 'failed' | 'closed'
export type DingtalkSessionState =
'starting' | 'qr' | 'scanned' | 'reusing' | 'success' | 'expired' | 'failed' | 'closed'
export interface DingtalkSessionView {
id: string
@@ -15,7 +16,16 @@ export interface DingtalkSessionView {
error?: string
}
const sessionStates = new Set<string>(['starting', 'qr', 'scanned', 'reusing', 'success', 'expired', 'failed', 'closed'])
const sessionStates = new Set<string>([
'starting',
'qr',
'scanned',
'reusing',
'success',
'expired',
'failed',
'closed',
])
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -24,7 +34,12 @@ function isRecord(value: unknown): value is Record<string, unknown> {
export async function startDingtalkSession(space?: string): Promise<DingtalkSessionView> {
const response = await fetch('/api/v1/dingtalk-session', {
method: 'POST',
headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-Governance-Action': 'dingtalk-session', 'Idempotency-Key': newOperationID() },
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Governance-Action': 'dingtalk-session',
'Idempotency-Key': newOperationID(),
},
body: JSON.stringify(space ? { space } : {}),
})
if (!response.ok) throw new Error(`发起钉钉扫码会话失败(HTTP ${response.status})`)
@@ -32,13 +47,19 @@ export async function startDingtalkSession(space?: string): Promise<DingtalkSess
}
export async function fetchDingtalkSession(id: string, signal?: AbortSignal): Promise<DingtalkSessionView> {
const response = await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, { headers: { Accept: 'application/json' }, signal })
const response = await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, {
headers: { Accept: 'application/json' },
signal,
})
if (!response.ok) throw new Error(`读取钉钉扫码会话失败(HTTP ${response.status})`)
return parseSession(await response.json())
}
export async function cancelDingtalkSession(id: string): Promise<void> {
await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, { method: 'DELETE', headers: { Accept: 'application/json' } }).catch(() => undefined)
await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, {
method: 'DELETE',
headers: { Accept: 'application/json' },
}).catch(() => undefined)
}
export interface RegisteredDingtalkSpace {
@@ -50,7 +71,7 @@ export class DingtalkRequestError extends Error {
constructor(
message: string,
public readonly code: string,
public readonly status: number,
public readonly status: number
) {
super(message)
this.name = 'DingtalkRequestError'
@@ -63,36 +84,59 @@ export class DingtalkRequestError extends Error {
export async function registerDingtalkSpace(url: string): Promise<RegisteredDingtalkSpace> {
const response = await fetch('/api/v1/dingtalk-spaces', {
method: 'POST',
headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-Governance-Action': 'dingtalk-space', 'Idempotency-Key': newOperationID() },
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Governance-Action': 'dingtalk-space',
'Idempotency-Key': newOperationID(),
},
body: JSON.stringify({ url }),
})
if (!response.ok) {
// 响应体只能读一次:错误码与后端 hint 一起取出(hint 优先,它比本地文案更具体)。
let code = ''
let hint = ''
try {
const parsed = await response.json() as unknown
if (isRecord(parsed) && typeof parsed.error === 'string') code = parsed.error
} catch { /* status-only */ }
const parsed = (await response.json()) as unknown
if (isRecord(parsed)) {
if (typeof parsed.error === 'string') code = parsed.error
if (typeof parsed.hint === 'string') hint = parsed.hint
}
} catch {
/* status-only */
}
const friendly: Record<string, string> = {
login_required: '钉钉扫码会话无效或已过期,请先在钉钉来源卡片上「扫码刷新会话」',
space_not_found: '未找到该知识库空间:请确认空间链接正确且当前账号有阅读权限',
name_conflict: '该空间与已登记的来源同名',
// 登记冲突分两种:同名来源还在用 vs 同一个登记键指向了别的空间。原因要说清,
// 否则用户只能看到一个无细节的 409(2026-10-14 线上就是这样卡住的)。
space_name_conflict: '已有同名来源仍在使用(未下架):先在该来源卡片上「去掉来源」,或确认选的是同一个知识库空间',
space_identity_conflict: '这个登记键已指向另一个知识库空间:刷新列表后重试;仍失败就把该来源「去掉来源」再登记',
space_registration_failed: '登记失败(服务端内部错误):已记录,请稍后重试或让管理员看服务日志',
invalid_space_url: '链接不是有效的钉钉知识库空间地址(应形如 alidocs.dingtalk.com/i/spaces/…)',
}
throw new DingtalkRequestError(
friendly[code] || `登记钉钉知识库失败(HTTP ${response.status}${code ? ':' + code : ''})`,
hint || friendly[code] || `登记钉钉知识库失败(HTTP ${response.status}${code ? ':' + code : ''})`,
code,
response.status,
response.status
)
}
const value = await response.json() as unknown
const value = (await response.json()) as unknown
if (!isRecord(value) || !isRecord(value.data)) throw new Error('invalid dingtalk space response')
const data = value.data
if (typeof data.connection_id !== 'string' || typeof data.name !== 'string') throw new Error('invalid dingtalk space response')
if (typeof data.connection_id !== 'string' || typeof data.name !== 'string')
throw new Error('invalid dingtalk space response')
return { connection_id: data.connection_id, name: data.name }
}
function parseSession(value: unknown): DingtalkSessionView {
if (!isRecord(value) || typeof value.id !== 'string' || typeof value.state !== 'string' || !sessionStates.has(value.state)) {
if (
!isRecord(value) ||
typeof value.id !== 'string' ||
typeof value.state !== 'string' ||
!sessionStates.has(value.state)
) {
throw new Error('invalid dingtalk session response')
}
return {