knowledge-governance/scripts/test-scope.json

{
  "_doc": [
    "测试范围声明：**哪些跳过是允许的**。judge 在 scripts/ci_checks.py 里读这个文件。",
    "极性是『默认必需』：没在这里声明的测试，一旦被 SKIP / PENDING ⇒ 门禁红（必需项不能报通过）。",
    "只有『确实需要外部环境、本仓拿不到』的集成/外部依赖用例才写进来，每条必须写清理由。",
    "package 级条目 = 该包里所有 skip 都算『可选未运行』（例如整个包都依赖 TEST_DATABASE_URL）。",
    "test 级条目 = 只豁免那一个用例（包里其它用例仍是必需的）。",
    "报告里会把这些『可选未运行』的条数与原因如实列出 —— 记录，不等于通过。",
    "⚠️ 文件缺失或解析不了 ⇒ 门禁红：范围声明不出来时，不许默认放行。"
  ],
  "optional": [
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibrarySourceReadOnlyDiagnostic",
      "reason": "仅明确只读测试源授权及进程内凭据下运行；真实 PG、ES、OSS 不冻结，属于诊断而非一致性或生产放行；默认 CI 不注入测试源凭据，实际失败必须另行保留而非算通过"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryCaptureIsolatedStack",
      "reason": "显式隔离 PG、随机 ES 索引和无网络 Docker 夹具的联合捕获验收；默认 CI 不连接这些服务，本地另行运行并做索引覆盖变异反向验证；不代表真实 WeKnora 写入隔离或 Wiki 语义验收"
    },
    {
      "package": "knowledge-governance/internal/libraryfreeze",
      "test": "TestFreezeIsolatedDocker",
      "reason": "只在显式 KG_FREEZE_DOCKER_ISOLATED=1 下使用本地 Docker 与已缓存 busybox 创建随机标签、无网络/无挂载夹具，验证真实暂停恢复和进程中断；默认 CI 不连接 Docker 或运行中的服务，本地另行实跑"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "test": "TestAILiveBailianPersistsAssessmentAndTranslation",
      "reason": "真实百炼付费调用仅在明确用户授权、独立注入凭据、精确opt-in及一次性隔离库下执行；普通CI不携带服务密钥或消耗配额，本批另行真实后台与浏览器验收"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "reason": "本包所有集成用例只在显式一次性 loopback kg_qaops_mirror_test_ 库运行；默认 CI 不连共享或生产库；隔离 PG -race 另行实跑"
    },
    {
      "package": "knowledge-governance/internal/qaopsquality",
      "test": "TestQualityStoreImmutableHistoryReplayConcurrencyAndStaleness",
      "reason": "仅在显式一次性 loopback kg_qaops_quality_test_ 库执行；默认 CI 不连接共享/生产库，隔离 PG 另行实跑"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestQARecordInternalIdentityAndWholeFilterKeys",
      "reason": "必须显式一次性隔离PG；验证真实只读SQL身份关联/计数及隐私，不连接生产；默认无库时明确跳过，另行本地补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestQAUsageGroupsCountEventsOnceOverTheFullFilter",
      "reason": "必须显式一次性隔离PG；验证真实只读SQL身份关联/计数及隐私，不连接生产；默认无库时明确跳过，另行本地补验"
    },
    {
      "package": "knowledge-governance/internal/qaopsorg",
      "test": "TestDirectorySyncQueueDurableReplayAndLeaseFencing",
      "reason": "仅显式一次性隔离PG库验证持久化入队、并发重放、进程接管与租约栅栏；不调用真实钉钉源、不连接共享或生产库；默认CI无库则明确跳过"
    },
    {
      "package": "knowledge-governance/internal/qaopsorg",
      "test": "TestOrganizationStoreRoundTripAndOptimisticConflict",
      "reason": "仅在显式KG_QAOPS_ORG_TEST_ISOLATED=1且127.0.0.1上的一次性kg_qaops_org_test_库运行；写入治理侧快照与配置，禁止使用共享或生产库；本批已在隔离PG补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestSSHDialerTransportsRealTraffic",
      "reason": "需要已批准 SSH 路径和只读版本接口；CI 不带生产 SSH 凭据，缺环境时显式跳过"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestSSHTunnelCloseReapsChild",
      "reason": "需要已批准 SSH 目标来验证子进程回收；无路径的 CI 不应尝试建立生产连接"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestReadOnlyRepositoryAgainstFixtureDatabase",
      "reason": "需显式 KG_DOBOTAI_TEST_ISOLATED=1 且 TEST_DATABASE_URL 通过隔离库护栏，CI 不建生产测试表；本批已在一次性测试库补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestBuildRefusesUnsafeAccountsAndTargets",
      "reason": "只在显式一次性测试库创建危险权限夹具，不在生产库验证写入；本批已在隔离库补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestSourceRechecksEffectivePrivilegesBeforeEveryQuery",
      "reason": "在一次性测试库模拟额外表写权限，测试前须通过隔离护栏；本批已实际补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestQARecordSearchPreservesSourceAndDoesNotMultiplyFeedback",
      "reason": "完整查询/反馈/游标/空列验证需要显式一次性测试库；本批已在隔离库补验"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestProductionReadOnlyCombinedVerification",
      "reason": "需独立批准的生产只读账号文件与 SSH 路径并显式 KG_DOBOTAI_PROD_VERIFY=1；CI 永不自动读取生产库"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestProductionQAQueryReadOnlyVerification",
      "reason": "真实源查询端到端验证仅在显式 KG_DOBOTAI_PROD_VERIFY=1、批准的凭据文件与 SSH 路径下执行；CI 不访问生产，测试不写源库"
    },
    {
      "package": "knowledge-governance/internal/platform/postgres",
      "reason": "整个包的集成用例都要 TEST_DATABASE_URL 指向可销毁测试库；本仓不连生产库，CI 无库 ⇒ 跳过（补验路径：起一次性 PG 后设 TEST_DATABASE_URL）"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "reason": "v0.7.1 源/目标库与 MinIO 集成环境；无环境即跳过"
    },
    {
      "package": "knowledge-governance/cmd/pp-ledger-import",
      "reason": "导入器集成用例需要 TEST_DATABASE_URL"
    },
    {
      "package": "knowledge-governance/cmd/release-worker",
      "reason": "release runtime 集成用例需要受限文件与运行时环境变量"
    },
    {
      "package": "knowledge-governance/internal/monitoring",
      "reason": "真实服务健康矩阵 / 指标窗口用例需要外部服务可达"
    },
    {
      "package": "knowledge-governance/internal/httpapi",
      "test": "TestUISettingsWriteReadBackIntegration",
      "reason": "系统设置写回读用例需要一个运行中的实例"
    },
    {
      "package": "knowledge-governance/internal/httpapi",
      "test": "TestUISettingsWriteReadBackWithLiveVerification",
      "reason": "同上（带实时校验的那条）"
    },
    {
      "package": "knowledge-governance/internal/version",
      "test": "TestNumberMatchesChangelog",
      "reason": "未注入版本号时按设计 SKIP（本地跑全量测试不该被迫先构建）；**它的强制点在 contracts 项**：那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
    },
    {
      "package": "knowledge-governance/internal/version",
      "test": "TestDevBuildDoesNotClaimRelease",
      "reason": "构建身份未注入时按设计 SKIP（本地跑全量测试不该被迫先构建）；**它的强制点在 contracts 项**：那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
    },
    {
      "package": "knowledge-governance/internal/version",
      "test": "TestReleaseBuildRequiresEvidence",
      "reason": "构建身份未注入时按设计 SKIP（本地跑全量测试不该被迫先构建）；**它的强制点在 contracts 项**：那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
    },
    {
      "package": "knowledge-governance/internal/versionhistory",
      "test": "TestLiveSyncAgainstRealRepository",
      "reason": "真实仓库的只读同步用例需要内部可达的 Gitea（**匿名**，不读凭据）；无环境即跳过（补验路径：设 VERSION_HISTORY_LIVE_BASE_URL 后单跑这条）"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "test": "TestLocalMirrorQueriesNeverRequireSource",
      "reason": "仅显式一次性隔离PG验证本地副本/持久同步或专门只读源夹具；默认CI不连接共享与生产库，另行实际执行隔离验收"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "test": "TestLocalMirrorDurableQueueCoalescesAndAudits",
      "reason": "仅显式一次性隔离PG验证本地副本/持久同步或专门只读源夹具；默认CI不连接共享与生产库，另行实际执行隔离验收"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "test": "TestLocalMirrorSyncActivatesAndCheckpoints",
      "reason": "仅显式一次性隔离PG验证本地副本/持久同步或专门只读源夹具；默认CI不连接共享与生产库，另行实际执行隔离验收"
    },
    {
      "package": "knowledge-governance/internal/qaopsmirror",
      "test": "TestLocalMirrorPeriodicSyncIsDurableAndDueOnly",
      "reason": "仅显式一次性隔离PG验证本地副本/持久同步或专门只读源夹具；默认CI不连接共享与生产库，另行实际执行隔离验收"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryReleaseRunIsolated",
      "reason": "完整编排（授权→预备份→四类写入→校验）跑真实一次性隔离 PG 与随机 ES 索引；默认 CI 无这些服务，本机 WeKnora 测试栈已实跑通过"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryProductionTargetIsolated",
      "reason": "需要一次性隔离库 kg_library_test_* 与随机 ES 索引（KG_LIBRARY_TEST_DATABASE_URL / KG_LIBRARY_TEST_ELASTIC_URL / KG_LIBRARY_TEST_ISOLATED=1）；默认 CI 不提供，本机 WeKnora 测试栈已真实跑通导入/撤销/预备份/故障恢复，CI 中跳过不等于验证"
    },
    {
      "package": "knowledge-governance/internal/dobotaiops",
      "test": "TestMirrorSourceManifestDetectsUpdatesWithoutVolatileTimes",
      "reason": "仅显式一次性隔离PG验证本地副本/持久同步或专门只读源夹具；默认CI不连接共享与生产库，另行实际执行隔离验收"
    },
    {
      "package": "knowledge-governance/internal/qawemail",
      "test": "TestScheduledSendRequiresConfirmationAndSendsExactlyOnce",
      "reason": "需要一个一次性 PostgreSQL 与测试主密钥（KG_WEEKLY_MAIL_TEST_DSN/KG_WEEKLY_MAIL_TEST_KEY），CI 不提供；本批已在隔离库真实跑通并通过"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryRollbackKeepsPreExistingTargetDataIsolated",
      "reason": "需要一次性隔离库 kg_library_test_*、随机 ES 索引与真实对象存储（KG_LIBRARY_TEST_S3_*）；验证目标非空/同租户其它知识库/共享资源/历史孤儿/跨租户数据在失败恢复后逐行字节不变，默认 CI 无这些服务，本机已实跑通过"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryRestoreRefusesWithoutWriteSetRecordIsolated",
      "reason": "同上环境；验证缺少持久化写集合时恢复必须失败且不动目标，默认 CI 跳过不算验证"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryPreflightRejectsCrossScopeIDConflictIsolated",
      "reason": "同上环境；验证跨范围同 ID 资源冲突在任何写入之前被拒绝，默认 CI 跳过不算验证"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryWikiStageHalfWriteRollbackIsolated",
      "reason": "同上环境；验证 wiki 阶段半写（database/resources 已提交）后回滚不留残渣，默认 CI 跳过不算验证"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryWriteSetRecordTamperRefusesRestoreIsolated",
      "reason": "同上环境；验证写集合记录被篡改/删除后取回与恢复都失败，默认 CI 跳过不算验证"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestLibraryKillWorkerThenResumeRecoversWriteSetIsolated",
      "reason": "同上环境并用 SIGKILL 杀掉子进程模拟 worker 被杀，验证重启后只按持久写集合恢复且目标原有数据不变；需要本地真实 PG/ES/MinIO，默认 CI 跳过不算验证"
    },
    {
      "package": "knowledge-governance/internal/releaseadapter/v071",
      "test": "TestWriteSetKillHelper",
      "reason": "上面 SIGKILL 用例的子进程 fixture，单独运行没有意义；默认 CI 跳过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestLibraryRunAnchorsWriteSetAndKeepsLookingItUpBeyondHistoryWindow",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：要证明的正是 Store 的『版本列表 1..100 上限』与按身份精确查询的差别，假版本库不实现该上限（本轮缺陷就是这样一路绿的）；默认 CI 无库 ⇒ 跳过，本机一次性 PG 已实跑：原码红（library version limit out of range）、只改 200→100 仍红（超出窗口找不到）、修后绿"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestTakeoverClassificationUsesExactCurrentVersionBeyondHistoryWindow",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：要证明的是『当前生效版本』不能按最近 N 条找——先灌 250 条历史把窗口挤满，再断言接管判定仍是 pending_final / superseded；假 store 不实现窗口语义，默认 CI 无库 ⇒ 跳过（补验路径：起一次性 PG 后设 TEST_DATABASE_URL 单跑这条）"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestTakeoverRefusesSameSnapshotRegisteredByAnotherJob",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：要证明的是『同一个快照由别的作业登记成生效版本』不能当成本作业的完成证据——版本行 id 由 (kind, scope, 快照) 决定且写入是 upsert（会改写 source_job_id），这个形状只有存储层能造；默认 CI 无库 ⇒ 跳过，本机一次性库已实跑（含负例：撤掉身份判定后判成 pending_final）"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestFailLibraryTakeoverKeepsMaintenanceAndNamesBackup",
      "reason": "必须在真实 PostgreSQL 上跑：断言『拒绝接管』的三处落库效果（作业 failed + 留预备份基线 + 维护 released_at 仍为 NULL/state=needs_restore），假 store 只能证明调用了函数；默认 CI 无库 ⇒ 跳过，本机一次性库已实跑（负例：把恢复指引改成\"无需恢复\"即红）"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestPrebackupVersionKeepsFirstRegistrationTimeOnReuse",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：要证明的是 RecordLibraryVersion 的 upsert 语义——预备份版本行只记首次登记时刻（崩溃接管复用时不许把'什么时候拍的备份'洗成现在），而生效版本行仍按最近一次激活写当前时刻。假 store 造不出这个差别。默认 CI 无库 ⇒ 跳过；本机一次性库 kg_takeover_reuse_test 已实跑，两条负例（撤掉保留规则 / 规则漏到所有 kind）均红"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestTakeoverHistoricalRestoreOnRealLedger",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：要证明的是『被顶替的生效版本行属于别的作业』不等于本作业过期——正例要求新恢复授权+本作业独占维护窗口+未变预备份基线时判 fresh；负例逐项撤掉授权/实例占用/基线归属/清单字节都必须回到 superseded。这些形状（版本行 upsert 改写 source_job_id、实例锁行、授权有效期）假 store 造不全；默认 CI 无库 ⇒ 跳过，本机一次性库已实跑正负例"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestFailLibraryJobOrTakeoverKeepsRiskWhenResumed",
      "reason": "必须在真实 PostgreSQL 上跑：断言续作早退（授权过期）时作业仍失败但 recovery 必须点名预备份、维护保持未释放且 state=needs_restore，不能出现『无需恢复』；假 store 无法证明三张表的落库效果；默认 CI 无库 ⇒ 跳过，本机一次性库已实跑"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestTakeoverKeepsWriteSetEvidenceAcrossRepeatedInterruptions",
      "reason": "必须在真实 PostgreSQL（TEST_DATABASE_URL 指向可销毁测试库）上跑：丢证据的机制是 RecordLibraryVersion 的 evidence=EXCLUDED.evidence 整份覆盖，只有存储层能造出这个形状；用例走两轮中断+接管+最终恢复，断言 writeset_digest/backup_bytes/job/backup_snapshot 全部存活且 created_at 不变。默认 CI 无库 ⇒ 跳过；本机一次性库已实跑：修前红（第 1 次接管后写集合丢失）、修后绿，去掉合并逻辑再跑仍红"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestTakeoverLedgerRefusesForeignOrMissingBackupEvidence",
      "reason": "必须在真实 PostgreSQL 上跑：复用未登记的预备份、字节数不一致、写集合被篡改/换作业/换预备份这些负例都依赖版本行身份与 upsert 语义（假 store 造不全）；默认 CI 无库 ⇒ 跳过，本机一次性库已实跑（修前红：复用未登记预备份竟然成功）"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestHandoffChainGatesReleaseJobOnVerifiedTransfer",
      "reason": "需要隔离的 fixture PostgreSQL（KG_TEST_DSN）与真实 libraryctl 二进制（KG_TEST_LIBRARYCTL）；CI 不注入测试库。本机已用独立测试库容器实跑通过，未运行不等于通过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestSnapshotCandidatesPaginateBeyondFiftyAndIncludeRecoveryBackups",
      "reason": "需要隔离的 fixture PostgreSQL（KG_TEST_DSN）才能验证 >50 条分页与失败作业预备份的枚举；CI 不注入测试库。本机已用独立测试库容器实跑通过（go test ./cmd/worker -run 'TestHandoff|TestSnapshotCandidates' → ok），未运行不等于通过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestHandoffReplayDoesNotOverwriteTerminalStateOrDuplicateReleaseJob",
      "reason": "需要隔离的 fixture PostgreSQL 与真实 libraryctl 二进制，验证幂等重放不重复投递、迟到失败不改写终态；CI 不注入测试库。本机已实跑通过，未运行不等于通过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestHandoffFromAPIBindingHandsOverToRelease",
      "reason": "需要隔离 fixture PostgreSQL：从 API 真实前驱（handoff 队列作业已关联）验证交接、错误前驱拒绝、交接后重放。CI 无测试库；本机已实跑（go test ./cmd/worker -count=1 → ok）"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestLateHandoffFailureLeavesHandedOverJobUntouched",
      "reason": "需要隔离 fixture PostgreSQL：用测试屏障确定性复现“失败出口时所有权已切给 release”，验证 running/succeeded 零修改。本机已实跑通过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestSnapshotOriginOnlyFromCaptureEvents",
      "reason": "需要隔离 fixture PostgreSQL：验证 test_sealed 与 production_effective 共存（正常成功链）仍按源绑定识别，以及真冲突/无捕获事件被拒。本机已实跑通过"
    },
    {
      "package": "knowledge-governance/cmd/worker",
      "test": "TestUnownedHandoffCreatesNoStageRow",
      "reason": "需要隔离 fixture PostgreSQL：验证未被持有的 handoff 不建阶段行、不改作业，且用真实 handoff ID 重放时幂等且零写入。CI 无测试库；本机已实跑（go test ./cmd/worker -count=1 → ok）"
    }
  ]
}