zheromiku
dcdc8d1ddd
全栈知识治理平台首次入库（P1-P10 + 发布链路模拟验证闭环）： - 治理核心：源目录/变更集/人工审核/发布批次/发布执行（fail-closed 闸口） - 测试通道：WeKnora 测试 KB 上传/轮询/验收；poll 完成时写入 parser_generation/index_generation，修复 manual/seed 路径发布闸口永久拦截 - 发布适配器 v071（本地 source=测试角色 / 云端 target=生产角色 模拟验证通过）： * ES 导出/导入 mapping 自适应（.keyword 子字段、可选 tenant_id） * OSS locator 支持嵌套 scheme；chunks.seq_id 由目标序列分配 * bundle 归档同身份重试原子替换；verifier 按 bundle chunk_type 计数 * 回滚 job payload 支持 prior_execution_id（strict 解码） - 三通道发布+回滚演练实测：publish 4/4 verified，检索命中， rollback 4/4 rolled_back，目标端 PG is_enabled=false、ES is_enabled=false - 前端 A·Data-console 风格全站统一，120 用例通过 - 门禁：go vet / go test 全包通过，gofmt 干净
9.2 KiB
9.2 KiB
知识治理平台状态机与术语契约
目的
本文件冻结治理平台的状态维度、存储枚举、API枚举、页面中文和终态含义。一个对象不得用单一status混合来源变化、人工审核、上传、解析、检索和发布状态。
原则：
数据库/API使用稳定英文枚举。
页面使用中文业务文案。
completed是当前统一的“成功完成”内部终态；页面可显示“成功”或“已完成”。
unknown、空字符串、未配置不能伪装成healthy或completed。
未来状态先写在“保留值”，未对应迁移和实现前不得持久化。
State dimensions
| 维度 | 负责回答的问题 | 当前主要对象 |
|---|---|---|
| Scope policy | 资料希望进入哪里？ | 目录规则、文件覆盖规则 |
| Source change | 来源事实发生了什么？ | SourceItem、CatalogChangeItem |
| Review | 人工是否批准？ | PublicationReview |
| Content | 原始内容是否取得和验证？ | ContentObject、SourceItemVersion |
| Job | 后台执行器是否仍在处理？ | jobs |
| Ingest | 是否已提交到测试目标？ | TestPublication |
| Processing | WeKnora解析/索引是否完成？ | TestPublication |
| Retrieval | 是否允许被检索？ | TestPublication/目标系统 |
| Acceptance | 测试结果是否通过？ | AcceptanceResult |
| Release | 生产发布批次/执行进行到哪里？ | ReleaseBatch、ReleaseExecution |
| Settings | 设置版本能否使用？ | UISettingsRevision |
Job
Current storage/API values:
pending | running | retry | completed | failed | cancelled
| 值 | 页面中文 | 含义 | 是否终态 |
|---|---|---|---|
pending |
等待执行 | 已创建，等待Worker领取 | 否 |
running |
执行中 | 已被Worker持有有效租约 | 否 |
retry |
等待重试 | 上次失败但仍可按退避重新执行 | 否 |
completed |
已完成 | 本地Job处理器完成；不自动等于目标系统最终成功 | 是 |
failed |
执行失败 | 达到最大尝试次数或遇到不可重试错误 | 是 |
cancelled |
已取消 | 被明确取消，不得再被Worker领取 | 是 |
规则：
Worker只领取pending、retry或过期running任务。
cancelled任务不可以被重新领取。
completed仅代表该Job完成；test.upload完成后仍必须由test.poll确认Processing终态。
Scope policy
Current user-facing desired-policy vocabulary:
unset | internal | external | blocked
| 值 | 页面中文 | 当前持久化解释 |
|---|---|---|
unset |
未设置 | 没有显式目录/文件覆盖规则；当前有效范围由来源默认或历史数据决定。它不是可写的Visibility数据库值。 |
internal |
对内 | 期望进入对内测试知识库。 |
external |
对外 | 期望进入对外测试知识库，后续仍需人工审核。 |
blocked |
禁止导入 | 期望不再导入；不得因此自动删除生产知识。 |
historical compatibility value: both
both是历史兼容持久化值，页面只读显示“对内 + 对外”。目录页顶部不提供新增both操作。mixed和unknown是目录汇总显示值，不是文件期望策略。
Source change
| 存储/API值 | 页面中文 | 含义 |
|---|---|---|
unchanged |
无变化 | 与基线相比无来源差异。 |
added |
新增 | 来源新发现。 |
updated |
已更新 | 现有来源身份出现新修订或新内容证据。 |
deleted |
已删除 | 仅限权威来源明确删除。 |
unavailable |
来源不可用 | 权限、接口或扫描失败；绝不是删除信号。 |
Catalog ChangeSet使用不同的动作值：add、update、move_scope、delete、no_change。它是比较计划动作，不直接等同于SourceItem.source_change。
Review
pending | approved | rejected | not_required
| 值 | 页面中文 | 含义 |
|---|---|---|
pending |
待审核 | 必须等待文档工程师判断。 |
approved |
已批准 | 可以进入后续封批条件判断，不代表生产已发布。 |
rejected |
已驳回 | 不得自动重新入批。 |
not_required |
无需审核 | 仅适用于明确规则允许的情形。 |
Content
unknown | downloading | verified | invalid | over_limit | failed
| 值 | 页面中文 | 含义 |
|---|---|---|
unknown |
内容待获取 | 尚未取得可验证字节。 |
downloading |
正在获取 | 正在受控下载/导出。 |
verified |
内容已校验 | 大小、格式、内容SHA-256已验证。 |
invalid |
内容无效 | 格式或文件魔数不符。 |
over_limit |
超出限制 | 内容存在但超出当前导入策略。 |
failed |
获取失败 | 内容获取或验证失败。 |
Ingest
pending | uploading | uploaded | failed
| 值 | 页面中文 | 含义 |
|---|---|---|
pending |
等待上传 | 尚未提交目标。 |
uploading |
上传中 | 已开始向测试目标提交。 |
uploaded |
已上传 | 目标已接收对象；不代表解析完成。 |
failed |
上传失败 | 上传步骤失败。 |
Processing
pending | processing | finalizing | completed | failed | stalled
| 值 | 页面中文 | 含义 |
|---|---|---|
pending |
等待解析 | 目标尚未开始处理。 |
processing |
解析中 | 正在解析、切片或向量化。 |
finalizing |
索引与增强中 | 基础解析可能完成，索引/Wiki/图谱仍未完成。 |
completed |
解析完成 | 远端最终处理完成；仍需独立Acceptance。 |
failed |
解析失败 | 远端报告失败。 |
stalled |
处理停滞 | 超过配置阈值未见进展。 |
Retrieval
unpublished | enabled | disabling | disabled | enabling | failed
| 值 | 页面中文 | 含义 |
|---|---|---|
unpublished |
未发布 | 尚未允许检索。 |
enabled |
已启用检索 | 已读回确认允许检索。 |
disabling |
正在停用检索 | 请求已发出，尚未确认。 |
disabled |
已停止检索 | 已读回确认停止检索，可恢复。 |
enabling |
正在恢复检索 | 请求已发出，尚未确认。 |
failed |
检索状态异常 | 停用/恢复失败或读回失败。 |
Acceptance
pending | passed | failed | manual_required
| 值 | 页面中文 | 含义 |
|---|---|---|
pending |
等待验收 | 尚未检查。 |
passed |
验收通过 | 指定检查通过。 |
failed |
验收失败 | 指定检查失败。 |
manual_required |
需人工确认 | 自动检查不足以得出结论。 |
Release
当前批次状态：
draft | sealed | cancelled
当前执行状态：
pending | running | completed | failed
当前执行条目状态：
pending | staged | activated | verified | failed | rolled_back
规则：
sealed只表示发布清单冻结，不表示已发布。
ReleaseExecution.completed必须建立在逐项验证成功之上。
ReleaseExecution.failed不自动表示整体生产已恢复；需按R4回滚策略判断。
Settings
validated | active | retired | failed
| 值 | 页面中文 | 含义 |
|---|---|---|
validated |
已验证待启用 | 配置校验通过，尚未成为运行版本。 |
active |
当前活动版本 | 运行时读取的唯一设置版本。 |
retired |
已退役 | 被后续活动版本替代，保留审计。 |
failed |
验证失败 | 配置未通过，不得启用。 |
Transition rules
Job transitions
pending → running
running → completed | retry | failed | cancelled
retry → running | cancelled
pending → cancelled
completed、failed、cancelled均为终态。后续“重试”必须创建或重置受控Attempt，不能把已完成任务静默改回pending。
Scope policy transitions
unset → internal | external | blocked
internal | external | blocked → internal | external | blocked
both只能保留和读取，不由当前目录页新增。
Scope改变只更新期望状态；S7完成前不得把它视为立即上传或删除命令。
Processing transitions
pending → processing → finalizing → completed
pending | processing | finalizing → failed | stalled
stalled → processing（仅由确认重试后的远端进展恢复）
Release transitions
当前实现只允许：
pending → running → completed | failed
Reserved future values
以下值已在产品术语中保留，但当前数据库、API和UI不得写入：
rolling_back
rolled_back
rollback_failed
snapshotting
verifying
applying
rolling_back must not be persisted before R4。
R1、R2、R4完成后，Release状态机会扩展这些值，并新增Production Snapshot与Release ChangeSet关联。
C2验收边界
C2完成：
分维度状态术语冻结
completed与页面“成功”含义统一
Job cancelled枚举、数据库约束和终态语义补齐
历史both策略的兼容边界明确
未来发布状态不提前持久化
C2不完成：
取消Job的用户界面/API（后续按业务需求另立工作包）
SourceFile内容Hash、ChangeSet确认、生产快照和三级回滚
Scope策略的实际执行链（S7/P3）
Release rolling_back实际状态（R4）