0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
62 lines
6.6 KiB
Markdown
62 lines
6.6 KiB
Markdown
<!-- 导航元信息: {"内容描述": "存储与对象关系", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# 存储与对象关系
|
||
|
||
## 存储职责
|
||
|
||
PostgreSQL 是服务端持久化业务与运行数据的权威。正文、规划、事实、候选、原始资料、结构定义、运行事件、证据、反馈和实验均保存于可核对版本的记录中。pgvector、关键词索引和查询视图是可重建派生物。
|
||
|
||
私人探索稿经受控文件接口原子保存，不进入正式设定或正文上下文。浏览器只保存交互状态和有基线版本的未提交编辑缓冲。上传、流式片段和导出中间文件属于有保留规则的暂存；暂存不能作为任务成功的唯一证据。
|
||
|
||
Git 保存代码、内置结构种子、Skill、角色提示、配置模板、迁移和文档，不保存作者正文、原始模型证据或凭据。
|
||
|
||
## 逻辑对象组
|
||
|
||
| 所属模块 | 逻辑对象 | 主要引用 |
|
||
|----------|----------|----------|
|
||
| B01 | work、volume、chapter、scene_plan、planning_version、planning_branch | 作品与目录稳定 ID；规划来源及结构版本 |
|
||
| B02 | entity、relation、event、fact_proposal、fact_version、foreshadowing | 作品、有效时点、实体身份、来源版本及结构版本 |
|
||
| B03 | source、source_version、source_locator、ranking_snapshot、analysis_version | 来源位置、原文哈希、采集时间、分析输入 |
|
||
| B04 | method、method_version、method_binding、method_usage | 固定方法版本、证据、反例和实际上下文 |
|
||
| B05 | document、document_version、paragraph、writing_candidate、document_branch | 章节、分支基线、段落身份、候选与审阅 |
|
||
| B06 | review_report、finding、voice_version、rule_version、revision_patch、quality_case | 正文和候选版本、上下文、规则、声音与检查覆盖 |
|
||
| B07 | preference_version、feedback_pair、observation、improvement、activation_receipt | 作者原话、适用范围、目标变更及实验 |
|
||
| B08 | delivery_manifest、export_artifact、release_record、serial_plan、reader_feedback | 固定章节版本、文件校验和、实际发布身份 |
|
||
| B09 | context_snapshot、context_source、source_dependency、search_chunk、embedding | 数据版本、结构版本、字段投影、允许用途和消费片段 |
|
||
| B10 | dataset_version、split_manifest、experiment、sample_run、blind_assignment、evaluation_result | 隔离用途、目标变更、固定条件及逐例证据 |
|
||
| S01 | change_set、author_review、command、commit_receipt、impact_reference | 请求哈希、类型化变更、被审版本和提交结果 |
|
||
| S02 | task、step、attempt、task_scope_lease、call、tool_event、checkpoint、budget_entry、raw_evidence、raw_lease、raw_archive、raw_cleanup_receipt | 流程、角色、模型、资源版本、步骤租约、作用域持有代次、原文授权/保留及来源 |
|
||
| S04 | type_registry、schema_version、work_extension、schema_binding、policy_version | 内置版本、扩展版本、有效结构与策略 |
|
||
|
||
这是逻辑模型，是否拆成独立表取决于查询、索引与事务需求。字段由所属模型及 Schema 约束，不建立一张可以任意更新任意业务的 JSON 总表。
|
||
|
||
## 关系与唯一性
|
||
|
||
- 展示章号与 chapter_id 分离。重排改顺序，不改身份；事件时点与计划位置分别表达。
|
||
- 故事事实区分叙事生效位置与系统确认版本或记录时间；历史回放固定当时可知的系统版本，不能把后来确认的知识倒灌旧运行。
|
||
- 当前指针指向不可变版本。正文、规划、结构、方法、声音和偏好各有自己的版本与生命周期。
|
||
- 候选元信息可共用身份、来源、状态和哈希；payload、保存及确认由所属模块解释。
|
||
- 命令键按作者与用途唯一，绑定规范化请求哈希。同键不同参数拒绝；同键同参数返回原回执。
|
||
- 业务事件与派生任务在正式提交事务内登记。任务尝试键包含步骤和尝试身份，完成写入核对租约及来源。
|
||
- 动态引用不能仅校验字符串形状。所属模块核对目标是否存在、类型是否允许、作品范围及有效版本，并维护可追查关系。
|
||
- 备份与数据归档包含结构和实例的引用关系。资料原文、raw、作者决策、旧版本和私人草稿不能只留下路径而丢失内容。
|
||
|
||
## 正式提交与派生
|
||
|
||
正文、来源归因、作者决策、提交回执以及必要派生任务同事务提交。明确批准的事实增量由 B02 作为同事务参与者执行；任一参与者验证或写入失败，整个提交回滚。
|
||
|
||
摘要、索引和自动事实提案提交后执行。事实提案仍须作者确认；派生失败不能把成功正文回滚成未保存。来源变更时的消费规则以[状态与来源有效性](状态与来源有效性.md)为准。
|
||
|
||
## 评测隔离与资料边界
|
||
|
||
生产、评测和维护使用独立数据库角色 `muse_app`、`muse_eval`、`muse_maint`。连接入口校验当前角色与用途一致；角色初始化由显式管理步骤执行，应用迁移不创建角色。`public` 保存业务对象，`evaluation` 保存评测对象，`oracle` 保存答案及匿名映射。生产角色只有业务数据权限；评测角色可维护评测数据并由评测编排读取 oracle，不能写业务表。迁移所有权与默认授权归维护角色，覆盖后续新增对象。生产连接无法读取 oracle 与匿名映射；评测候选不能通过生产确认入口。用于公开研究的合成夹具与作者真实语料分开保管。
|
||
|
||
参考书分析、本书事实与公共写作方法即使使用相同 Schema，也保持不同实例归属。资料转为本书设定、分析转为方法卡均形成带来源的候选并分别确认，不以复制 payload 自动转正。
|
||
|
||
旧混合表按[旧知识记录分流](旧知识记录分流.md)核对用途、type/型、确认和端点；原文及归档对象遵守[保留授权与恢复合同](../接口契约/原文证据生命周期.md)。迁移中的未知值保留在隔离记录，不以 JSONB 容纳为由直接启用。
|
||
|
||
## 私人文件与恢复
|
||
|
||
草稿接口只接受草稿身份，由服务端解析受控位置，保存内容哈希及版本。完整备份在受控一致性窗口记录数据库快照与草稿清单；恢复到隔离环境核对哈希、引用、版本和关键旅程。正式文稿导出不夹带私人笔记或凭据。
|
||
|
||
对象删除先检查引用和保留策略，再由各所属模块处理。停用、撤回和历史保留不同于物理删除；恢复所需的历史对象不因 UI 隐藏而被清理。
|