feat: 知识治理平台(含已验证发布/回滚契约)

全栈知识治理平台首次入库(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 干净
This commit is contained in:
2026-09-13 12:02:58 +08:00
committed by 姚章浩
parent ed48c4ceda
commit dcdc8d1ddd
410 changed files with 56661 additions and 1 deletions
+289
View File
@@ -0,0 +1,289 @@
# 知识治理平台状态机与术语契约
## 目的
本文件冻结治理平台的状态维度、存储枚举、API枚举、页面中文和终态含义。一个对象不得用单一`status`混合来源变化、人工审核、上传、解析、检索和发布状态。
原则:
```text
数据库/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:
```text
pending | running | retry | completed | failed | cancelled
```
| 值 | 页面中文 | 含义 | 是否终态 |
| --- | --- | --- | --- |
| `pending` | 等待执行 | 已创建,等待Worker领取 | 否 |
| `running` | 执行中 | 已被Worker持有有效租约 | 否 |
| `retry` | 等待重试 | 上次失败但仍可按退避重新执行 | 否 |
| `completed` | 已完成 | 本地Job处理器完成;不自动等于目标系统最终成功 | 是 |
| `failed` | 执行失败 | 达到最大尝试次数或遇到不可重试错误 | 是 |
| `cancelled` | 已取消 | 被明确取消,不得再被Worker领取 | 是 |
规则:
```text
Worker只领取pending、retry或过期running任务。
cancelled任务不可以被重新领取。
completed仅代表该Job完成;test.upload完成后仍必须由test.poll确认Processing终态。
```
### Scope policy
Current user-facing desired-policy vocabulary:
```text
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
```text
pending | approved | rejected | not_required
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `pending` | 待审核 | 必须等待文档工程师判断。 |
| `approved` | 已批准 | 可以进入后续封批条件判断,不代表生产已发布。 |
| `rejected` | 已驳回 | 不得自动重新入批。 |
| `not_required` | 无需审核 | 仅适用于明确规则允许的情形。 |
### Content
```text
unknown | downloading | verified | invalid | over_limit | failed
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `unknown` | 内容待获取 | 尚未取得可验证字节。 |
| `downloading` | 正在获取 | 正在受控下载/导出。 |
| `verified` | 内容已校验 | 大小、格式、内容SHA-256已验证。 |
| `invalid` | 内容无效 | 格式或文件魔数不符。 |
| `over_limit` | 超出限制 | 内容存在但超出当前导入策略。 |
| `failed` | 获取失败 | 内容获取或验证失败。 |
### Ingest
```text
pending | uploading | uploaded | failed
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `pending` | 等待上传 | 尚未提交目标。 |
| `uploading` | 上传中 | 已开始向测试目标提交。 |
| `uploaded` | 已上传 | 目标已接收对象;不代表解析完成。 |
| `failed` | 上传失败 | 上传步骤失败。 |
### Processing
```text
pending | processing | finalizing | completed | failed | stalled
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `pending` | 等待解析 | 目标尚未开始处理。 |
| `processing` | 解析中 | 正在解析、切片或向量化。 |
| `finalizing` | 索引与增强中 | 基础解析可能完成,索引/Wiki/图谱仍未完成。 |
| `completed` | 解析完成 | 远端最终处理完成;仍需独立Acceptance。 |
| `failed` | 解析失败 | 远端报告失败。 |
| `stalled` | 处理停滞 | 超过配置阈值未见进展。 |
### Retrieval
```text
unpublished | enabled | disabling | disabled | enabling | failed
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `unpublished` | 未发布 | 尚未允许检索。 |
| `enabled` | 已启用检索 | 已读回确认允许检索。 |
| `disabling` | 正在停用检索 | 请求已发出,尚未确认。 |
| `disabled` | 已停止检索 | 已读回确认停止检索,可恢复。 |
| `enabling` | 正在恢复检索 | 请求已发出,尚未确认。 |
| `failed` | 检索状态异常 | 停用/恢复失败或读回失败。 |
### Acceptance
```text
pending | passed | failed | manual_required
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `pending` | 等待验收 | 尚未检查。 |
| `passed` | 验收通过 | 指定检查通过。 |
| `failed` | 验收失败 | 指定检查失败。 |
| `manual_required` | 需人工确认 | 自动检查不足以得出结论。 |
### Release
当前批次状态:
```text
draft | sealed | cancelled
```
当前执行状态:
```text
pending | running | completed | failed
```
当前执行条目状态:
```text
pending | staged | activated | verified | failed | rolled_back
```
规则:
```text
sealed只表示发布清单冻结,不表示已发布。
ReleaseExecution.completed必须建立在逐项验证成功之上。
ReleaseExecution.failed不自动表示整体生产已恢复;需按R4回滚策略判断。
```
### Settings
```text
validated | active | retired | failed
```
| 值 | 页面中文 | 含义 |
| --- | --- | --- |
| `validated` | 已验证待启用 | 配置校验通过,尚未成为运行版本。 |
| `active` | 当前活动版本 | 运行时读取的唯一设置版本。 |
| `retired` | 已退役 | 被后续活动版本替代,保留审计。 |
| `failed` | 验证失败 | 配置未通过,不得启用。 |
## Transition rules
### Job transitions
```text
pending → running
running → completed | retry | failed | cancelled
retry → running | cancelled
pending → cancelled
```
`completed`、`failed`、`cancelled`均为终态。后续“重试”必须创建或重置受控Attempt,不能把已完成任务静默改回pending。
### Scope policy transitions
```text
unset → internal | external | blocked
internal | external | blocked → internal | external | blocked
both只能保留和读取,不由当前目录页新增。
```
Scope改变只更新期望状态;S7完成前不得把它视为立即上传或删除命令。
### Processing transitions
```text
pending → processing → finalizing → completed
pending | processing | finalizing → failed | stalled
stalled → processing(仅由确认重试后的远端进展恢复)
```
### Release transitions
当前实现只允许:
```text
pending → running → completed | failed
```
## Reserved future values
以下值已在产品术语中保留,但当前数据库、API和UI不得写入:
```text
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完成:
```text
分维度状态术语冻结
completed与页面“成功”含义统一
Job cancelled枚举、数据库约束和终态语义补齐
历史both策略的兼容边界明确
未来发布状态不提前持久化
```
C2不完成:
```text
取消Job的用户界面/API(后续按业务需求另立工作包)
SourceFile内容Hash、ChangeSet确认、生产快照和三级回滚
Scope策略的实际执行链(S7/P3)
Release rolling_back实际状态(R4)
```