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
+60 -5
View File
@@ -21,6 +21,14 @@ import (
// begin only after an admin sets an interval — same posture as the existing
// imported DingTalk sources.
// 登记失败的可行动分类(处理器据此返回不同错误码,前端才能说清"该怎么办"):
// - 同名来源**仍在使用**(未归档):不能悄悄改名,也不能出现两个同名来源;
// - 同一个登记键已指向另一个 root,而那个来源仍在使用。
var (
ErrDingtalkSpaceNameTaken = errors.New("dingtalk space name is already used by a live connection")
ErrDingtalkSpaceIdentityConflict = errors.New("dingtalk space registration: live connection already serves another root")
)
// RegisterDingtalkSpaceInput describes one space resolved by the sidecar.
type RegisterDingtalkSpaceInput struct {
RootKey string // sidecar inventory key, e.g. "atom" or "space-1f2e3d4c5b"
@@ -56,17 +64,42 @@ func (s *Store) RegisterDingtalkSpace(ctx context.Context, in RegisterDingtalkSp
}
connectionID := in.ConnectionID()
var existingName, existingRoot string
err := s.db.QueryRow(ctx, `SELECT name, base_url FROM source_connections WHERE id = $1`, connectionID).Scan(&existingName, &existingRoot)
var existingArchived bool
err := s.db.QueryRow(ctx, `SELECT name, base_url, archived_at IS NOT NULL FROM source_connections WHERE id = $1`, connectionID).
Scan(&existingName, &existingRoot, &existingArchived)
switch {
case errors.Is(err, pgx.ErrNoRows):
// fresh registration below
case err != nil:
return "", fmt.Errorf("load dingtalk connection: %w", err)
default:
// A different space resolved under the same key must not silently
// rewrite the existing connection.
if !strings.HasPrefix(existingRoot, "spaces/"+in.RootID+"?") {
return "", fmt.Errorf("dingtalk space registration: connection %s already serves another root", connectionID)
// 同一个键解析到了另一个 root:**在用中**的行不能悄悄改写(可能是两个不同空间
// 撞了同一个键);已经归档的行可以就地改写 —— 这正是"去掉来源之后再用 dws
// 重新获取"的语义。
if !strings.HasPrefix(existingRoot, "spaces/"+in.RootID+"?") && !existingArchived {
return "", ErrDingtalkSpaceIdentityConflict
}
}
// 名字有 UNIQUE 约束,而**旧路径登记**的来源(例如早期直接建的钉钉知识库连接,
// base_url 为空、id 与 dws 现在推导出的确定性 id 不同)会一直占着这个名字。
// 归档行已经不显示在任何页面,就把它改名腾出位置(数据与审计一行不动);
// 仍在使用的同名来源则直接报可行动错误,绝不悄悄改名。
var nameHolderID string
var nameHolderArchived bool
err = s.db.QueryRow(ctx, `SELECT id, archived_at IS NOT NULL FROM source_connections WHERE name = $1 AND id <> $2`, in.Name, connectionID).
Scan(&nameHolderID, &nameHolderArchived)
switch {
case errors.Is(err, pgx.ErrNoRows):
case err != nil:
return "", fmt.Errorf("lookup dingtalk connection name: %w", err)
default:
if !nameHolderArchived {
return "", ErrDingtalkSpaceNameTaken
}
if _, err := s.db.Exec(ctx, `
UPDATE source_connections SET name = $2, updated_at = $3, updated_by = $4 WHERE id = $1`,
nameHolderID, archivedConnectionName(in.Name, nameHolderID), in.Now.UTC(), "dingtalk-registration"); err != nil {
return "", fmt.Errorf("free archived dingtalk name: %w", err)
}
}
// base_url stores a stable, non-secret locator (the root dentry uuid plus
@@ -93,3 +126,25 @@ SET name = EXCLUDED.name, base_url = EXCLUDED.base_url,
}
return connectionID, nil
}
// archivedConnectionName 给"已归档但名字仍占着唯一槽位"的行一个确定性新名字:
// 内建短 ID 后缀保证唯一,并按 name 列(255)截断原名。
func archivedConnectionName(name, connectionID string) string {
suffix := "(已下架 · " + shortConnectionIDSuffix(connectionID) + ")"
runes := []rune(name)
if limit := 255 - len([]rune(suffix)); len(runes) > limit && limit > 0 {
runes = runes[:limit]
}
return string(runes) + suffix
}
func shortConnectionIDSuffix(connectionID string) string {
trimmed := strings.TrimPrefix(connectionID, "sc-")
if len(trimmed) > 8 {
trimmed = trimmed[:8]
}
if trimmed == "" {
trimmed = "unknown"
}
return trimmed
}
@@ -4,6 +4,7 @@ import (
"context"
"errors"
"os"
"strings"
"testing"
"time"
@@ -221,3 +222,111 @@ func TestRegisterDingtalkSpaceRevivesArchivedConnection(t *testing.T) {
t.Fatalf("复活状态 = rows:%d archived:%v by:%q", rows, archivedAt, archivedBy)
}
}
// 场景复刻(2026-10-14 线上 409 事故):早期路径登记的同名来源被归档后仍占着
// UNIQUE(name) 槽位,而它的 id 与 dws 现在推导出的确定性 id 不同 ⇒ 重新登记撞唯一约束。
// 期望:归档行被改名腾位(数据与审计不动),新来源按新 id 正常登记。
func TestRegisterDingtalkSpaceFreesNameHeldByArchivedLegacyConnection(t *testing.T) {
databaseURL := isolatedIntegrationDatabaseURL(t, os.Getenv("TEST_DATABASE_URL"))
if databaseURL == "" {
t.Skip("TEST_DATABASE_URL is not set")
}
ctx := context.Background()
pool, err := pgxpool.New(ctx, databaseURL)
if err != nil {
t.Fatal(err)
}
defer pool.Close()
if err := ApplyMigrations(ctx, pool); err != nil {
t.Fatalf("ApplyMigrations() error = %v", err)
}
store := NewStore(pool)
now := time.Date(2026, 10, 14, 5, 0, 0, 0, time.UTC)
// 旧路径登记的来源:id 与 dws 推导不同、base_url 为空、已归档、名字仍占槽位。
if _, err := pool.Exec(ctx, `
INSERT INTO source_connections (id, source_type, name, base_url, enabled, archived_at, archived_by, created_at, updated_at)
VALUES ('sc-18d10ca094c6071d44a32e531359e3b2', 'dingtalk', '公司级技术支持知识库', '', FALSE, $1, 'yaozhanghao', $1, $1)`, now); err != nil {
t.Fatal(err)
}
if _, err := pool.Exec(ctx, `
INSERT INTO source_items (id, source_connection_id, stable_external_id, canonical_uri_hash,
title, item_type, visibility, visibility_origin, source_change, created_at, updated_at)
VALUES ('item-legacy', 'sc-18d10ca094c6071d44a32e531359e3b2', 'ext-legacy', repeat('b', 64), '旧行留下的文档',
'file', 'internal', 'configured_scope', 'unchanged', $1, $1)`, now); err != nil {
t.Fatal(err)
}
input := RegisterDingtalkSpaceInput{
RootKey: "support-kb", Name: "公司级技术支持知识库", SpaceID: "space-support", RootID: "root-support", Now: now,
}
connectionID, err := store.RegisterDingtalkSpace(ctx, input)
if err != nil {
t.Fatalf("登记被旧归档行挡住:%v", err)
}
if connectionID == "sc-18d10ca094c6071d44a32e531359e3b2" {
t.Fatalf("不该复用没有身份证据的旧行:%s", connectionID)
}
page, err := store.ListSourceConnections(ctx)
if err != nil {
t.Fatal(err)
}
if len(page.Items) != 1 || page.Items[0].ID != connectionID || page.Items[0].Name != "公司级技术支持知识库" {
t.Fatalf("列表 = %#v", page.Items)
}
// 旧行:改名腾位、保持归档、内容一行不丢。
var legacyName string
var legacyArchivedAt *time.Time
var legacyItems int
if err := pool.QueryRow(ctx, `SELECT name, archived_at, (SELECT COUNT(*)::int FROM source_items WHERE source_connection_id = 'sc-18d10ca094c6071d44a32e531359e3b2') FROM source_connections WHERE id = 'sc-18d10ca094c6071d44a32e531359e3b2'`).
Scan(&legacyName, &legacyArchivedAt, &legacyItems); err != nil {
t.Fatal(err)
}
if legacyName == "公司级技术支持知识库" || !strings.Contains(legacyName, "(已下架 · 18d10ca0)") {
t.Fatalf("旧归档行没有被改名腾位:%q", legacyName)
}
if legacyArchivedAt == nil || legacyItems != 1 {
t.Fatalf("旧归档行被破坏:archived=%v items=%d", legacyArchivedAt, legacyItems)
}
// 同名来源仍在使用(未归档)时:拒绝并给出可行动错误,且不写任何东西。
if _, err := pool.Exec(ctx, `
INSERT INTO source_connections (id, source_type, name, enabled, created_at, updated_at)
VALUES ('sc-live-other', 'dingtalk', '在用中的同名来源', TRUE, $1, $1)`, now); err != nil {
t.Fatal(err)
}
_, err = store.RegisterDingtalkSpace(ctx, RegisterDingtalkSpaceInput{
RootKey: "other-key", Name: "在用中的同名来源", SpaceID: "space-other", RootID: "root-other", Now: now,
})
if !errors.Is(err, ErrDingtalkSpaceNameTaken) {
t.Fatalf("同名在用来源 = %v, want ErrDingtalkSpaceNameTaken", err)
}
// 同一个登记键解析到另一个 root:在用中 ⇒ 拒绝;已归档 ⇒ 就地改写。
held := RegisterDingtalkSpaceInput{RootKey: "held-key", Name: "同键来源", SpaceID: "space-a", RootID: "root-a", Now: now}
heldID, err := store.RegisterDingtalkSpace(ctx, held)
if err != nil {
t.Fatal(err)
}
_, err = store.RegisterDingtalkSpace(ctx, RegisterDingtalkSpaceInput{
RootKey: "held-key", Name: "同键来源", SpaceID: "space-b", RootID: "root-b", Now: now,
})
if !errors.Is(err, ErrDingtalkSpaceIdentityConflict) {
t.Fatalf("同键换 root(在用)= %v, want ErrDingtalkSpaceIdentityConflict", err)
}
if err := store.ArchiveSourceConnection(ctx, heldID, "yaozhanghao", now); err != nil {
t.Fatal(err)
}
if _, err := store.RegisterDingtalkSpace(ctx, RegisterDingtalkSpaceInput{
RootKey: "held-key", Name: "同键来源", SpaceID: "space-b", RootID: "root-b", Now: now,
}); err != nil {
t.Fatalf("归档后同键换 root 应就地改写:%v", err)
}
var rootAfter string
if err := pool.QueryRow(ctx, `SELECT base_url FROM source_connections WHERE id = $1`, heldID).Scan(&rootAfter); err != nil {
t.Fatal(err)
}
if !strings.HasPrefix(rootAfter, "spaces/root-b?") {
t.Fatalf("归档行没有被就地改写:%q", rootAfter)
}
}