# 知识治理平台状态机与术语契约

## 目的

本文件冻结治理平台的状态维度、存储枚举、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）
```