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 干净
290 lines
9.2 KiB
Markdown
290 lines
9.2 KiB
Markdown
# 知识治理平台状态机与术语契约
|
||
|
||
## 目的
|
||
|
||
本文件冻结治理平台的状态维度、存储枚举、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）
|
||
```
|