# 数据权威与可视化领域 SoT

> 本领域定义“数据以谁为准、输入产出如何落库、raw 如何进库、只读看板怎么工作、库如何恢复”。“一切输入产出必须落库可见”这条全系统硬纪律的 owner 在[领域索引 §3](_index.md)，本领域只定义它的**存储与可恢复侧**：哪些东西进哪类表、写入顺序、可恢复要求。原则不在此重复。

## 1. 唯一职责

本领域拥有：

- 数据权威层级：PostgreSQL 是正式内容权威，Git 退回代码与文档的家。
- 输入产出落库的机制侧：哪些输入产出必须进哪类表，以及落库的可恢复要求。
- raw（完整原文、完整问答、标准答案、供应商响应）进库与访问控制。
- 只读可视化看板的合同：它对库只读、绝不写。
- 可恢复性：库如何从备份加上 Git 里的代码与 DDL 重建。

本领域**不拥有**作品、实体、范式的业务语义（那些在各内容领域），也**不决定**候选质量或用户接受结果（那些在质量与复利领域、创作流程领域）。本领域只回答“数据放在哪、谁能看、能不能恢复”。

## 2. 权威层级

```text
PostgreSQL（muse-example 库） = 正式内容权威（SoT）
Git                           = 代码 / Skill / Agent 提示词 / meta（schema 与 chains）/ 文档 / DDL 的权威
                                + 这些东西的版本历史与备份
库内向量索引（pgvector）       = 数据库一侧的检索加速，不是独立权威，可从库重建
仓外 vault                    = 可选备份，不是合同要求
```

- 正式内容都在库里：作品、章、正文、实体、范式、用户决策、运行回执，以及 raw。判断“系统里有没有这个东西”，以库里能不能查到为准。
- Git 不是正式内容权威。它保存让系统能跑起来、能重建的代码和 DDL 及其变更历史；也可以对作品相关信息和作品文本留痕（历史、备份）。但留痕只是痕迹，不是权威——正式内容以库为准，看板只读库，两者冲突时以库为准。
- 向量索引只是加速检索（快速找出相关实体和知识）的手段，删掉或损坏不影响正式内容，能从库里的正文和知识重建。
- 旧主张“Git 文件是正式内容 SoT、数据库是可删除投影、删库零丢失”已作废，全部反过来。

## 3. 一切输入产出落库（机制侧）

落库原则（每个输入、每个产出都要落库，没落库等于不存在）见[领域索引 §3](_index.md)，那里是唯一 owner。本节把它落成**存储合同**：每类输入产出进哪类表。落库动作由各业务管线与 Skill 负责执行，本领域负责“必须落库的清单”和“可恢复”两件事。

| 输入产出 | 落库去向 |
|---|---|
| 作品、章、正文（正式） | 内容表（作品 / 章 / 正文 block） |
| 实体、关系、叙事状态、世界规则 | 实体与知识表 |
| 范式（写法、适用条件、证据、生命周期） | 范式表 |
| 用户意图、规划、细纲、冻结的上下文、范式选择 | 规划与上下文冻结表 |
| AI 待审候选正文（未接受） | 候选表（raw 访问控制，见 §5） |
| 检测、评分、审核、实验结果 | 质量结果表 + 运行回执（见 §7） |
| 用户的接受 / 合并 / 丢弃决策 | 用户决策记录 |
| 每次运行的回执 | 运行回执表（见 §7） |
| 补证、重写记录 | 对应的候选 / 回执记录 |
| 模型调用的提示词与执行配置 | 模型调用记录表（raw 访问控制，见 §5） |
| 完整原文、完整问答、标准答案、供应商响应 | raw 表（见 §5） |

硬要求：

- 上表每一类都必须有库内记录；只读看板看不到的，就是没落库。
- 每条记录要能回答“它是谁产生的、针对哪个作品/章/候选、什么时候”。
- 落库写入必须走 `db` skill 这一条数据库通道，不裸连、不散写一次性脚本（见 §9 与 [07-Agent与Skill领域](07-Agent与Skill领域.md)）。

## 4. 写入顺序

```text
校验输入
  -> 写库（正式内容权威）
  -> 记录安全事件 / 变更
  -> 异步刷新库内检索加速（向量索引）
```

- 向量刷新失败**不回滚**已经成功的库写入。向量索引只是加速，可从库重建（见 §8）。
- 检索加速失败只影响速度，不改变内容语义、不跳过审核。
- 模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。
- 任何外部系统、缓存或投影都不得反过来改写库里的正式内容。

## 5. raw 进库与访问控制

raw 指不适合直接当正文、但需要留存可查的完整材料：完整 Prompt/Response、未接受的候选正文、标准答案、原书全文、供应商原始响应。

- raw **进库**，放在单独的表里并加访问控制；只读看板可以看全文。
- 旧主张“raw 必须留仓外、仓外 vault 是合同要求”已作废：仓外 vault 降级为可选备份，不再是合同要求。
- 内容表（作品 / 章 / 正文 / 实体）里只放正式内容与安全摘要，不直接塞完整 Prompt/Response。
- 密钥、token 和外部连接凭据**仍不得**写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。

访问控制的最小要求：

- raw 表默认不进入普通检索结果；要看全文须显式指定。
- 看板展示 raw 全文时，不展示密钥 / token / 凭据字段。

## 6. 只读可视化模块

一个本地 web 看板，把库里的状态随时渲染给人看。核心不变量：纯标准库实现、只对库做只读查询并渲染、**绝不触发任何写**（接受、丢弃等写操作仍由 `confirm` skill 与主会话走，看板只展示结果）；看板看到的等于库里的，因此它倒逼 §3 一切落库——看板上空白的地方，就是落库的缺口。

完整合同（只读硬约束、技术形态、视图清单、raw 访问控制、验收）见 [可视化模块合同](../可视化模块合同.md)，那里是本模块的唯一 SoT，本节不复制。

## 7. 运行回执库表合同

每次生成、检测、审核或接受运行，都在库内留下一条回执。旧版“作品内 `runs/` 文件合同”改为库表合同：回执存在库里，不再靠 Git 文件读出。

一条回执至少包含：

- `run_id`、`attempt`：哪一次运行、第几次尝试。
- `candidate_version`、`candidate_sha256`：针对哪个候选版本、正文哈希是多少。
- `context_sha256`：用的是哪一份冻结上下文。
- 检测与质量结果的安全摘要：结论和失败类别（完整 Prompt/Response 不落这里，落 raw 表）。
- 用户决策：接受、合并或丢弃。
- raw 归档指针：完整内容在库内 raw 表的哪条记录。

硬要求：

- 回执写入后**不改写**；新的尝试产生新的记录（不可变账本）。
- 回执字段合同由本领域拥有；作品领域只提供一个在作品下的归档关系，质量领域只消费其中的结果摘要。
- 现有实现里 `runtime` 的不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）即属此合同的落地。

## 8. 可恢复性

数据库是权威，所以可恢复性围绕数据库建立：

- **库结构与数据**：靠数据库备份、快照或 dump 恢复。
- **从零重建**：用 Git 里的代码与 DDL（`db/ddl/` 审计文件）重建库结构，再恢复数据。
- **向量索引**：可从库里的正文与知识重建，不单独备份也不算丢。
- **代码与文档**：靠 Git 历史恢复。

不再承诺“删掉数据库零丢失”。删库后可恢复的前提是有可用的备份或 dump，加上 Git 里的代码与 DDL。DB 备份与重建脚本属待建项（见 §10）。

## 9. Git 角色

- Git 保存代码、Skill、Agent 提示词、`meta/`（schema 与 chains）、文档、DDL 的版本历史，提供差异审查、回滚依据和备份。
- Git 不是正式内容权威，也不是实时消息总线。它可以对作品信息与作品文本留痕（历史、备份），但留痕不等于权威；正式内容以库为准，看板只读库，冲突时以库为准。
- 一次 `git commit` **不等于**用户接受。接受语义由创作流程和库内状态决定，见 [05-创作流程领域](05-创作流程领域.md)。
- 数据库写入、DDL 应用走 `db` skill 单一通道；DDL 先落 `db/ddl/` 审计文件再应用，不绕过。

可承认的现有实现（引用即可，细节以各自载体为准）：

- `db` skill：单一数据库通道。
- `runtime`：不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）。
- 额度账本：`db/ddl/95-example额度账本.sql`。
- 清洗日志：`db/ddl/92-example清洗日志.sql`。
- 参考作品授权快照：`db/ddl/96-example参考作品授权快照.sql`（**决定不启用**，领域索引 §9；DDL 留存不 apply）。
- `import` skill：参考书 / 旧稿导入落库。

## 10. 待建（目标合同）

以下为当前尚未满足、但属于本领域目标合同的缺口：

- 一切输入产出落库：运行注册 / 回执 / 质量评判 / 模型调用明细表已建（97/98），写路径未接通；候选正文、用户决策、补证记录、规划与冻结（99/100）尚未建。
- 只读可视化看板：首版已建（总览/作品/知识库/运行记录四空间）；运行详情下钻、智能体空间、工作区标签待建。
- raw 全文进库的表与访问控制（101）。
- DB 备份与重建脚本。

## 11. 验收条件

1. 删库后，能用数据库备份 / dump 加上 Git 里的代码与 DDL 重建出库结构和数据。
2. raw 全文（完整原文、完整问答、标准答案、供应商响应）能从库里读到，且受访问控制。
3. 只读看板对库零写：它发起的所有数据库操作都是只读查询。
4. §3 表中的每一类输入产出，在库里都查得到对应记录；看板看不到的即判为缺口。
5. 向量索引被删除或损坏后，正式内容不丢，且能从库重建索引。
6. 运行回执写入后不可改写，新尝试产生新记录。
7. 内容表与运行报告里查不到密钥 / token / 外部凭据。
8. 检索加速或模型运行失败时，库里已有的正式内容不被损坏、审核终态不被跳过。

## 12. 关联 SoT

- 横切合同 owner（一切输入产出落库）：[领域索引 §3](_index.md)
- 内容权威的业务语义：[01-作品领域](01-作品领域.md)、[02-实体领域](02-实体领域.md)、[03-范式领域](03-范式领域.md)
- 上下文冻结与取数：[04-上下文领域](04-上下文领域.md)
- 候选、用户决策与接受语义：[05-创作流程领域](05-创作流程领域.md)
- 检测 / 审核 / 实验结果消费回执：[06-质量与复利领域](06-质量与复利领域.md)
- 数据库通道与 Skill 边界：[07-Agent与Skill领域](07-Agent与Skill领域.md)
- 外部交互上级合同：[专题-05](../../../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)