0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
78 lines
6.6 KiB
Markdown
78 lines
6.6 KiB
Markdown
<!-- 导航元信息: {"内容描述": "B02 故事世界", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# B02 故事世界
|
||
|
||
## 职责与对象
|
||
|
||
本书实体、关系、事实与时间语义；参考书分析仍归 B03。
|
||
|
||
实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。
|
||
|
||
## 公开接口
|
||
|
||
| 用例 | 输入责任 | 输出与后果 |
|
||
|------|----------|------------|
|
||
| query_state | 作品、叙事时点、知情主体、用途 | 有依据的当前可用事实与省略原因 |
|
||
| save_entity | 类型、结构绑定、实例变更和预期版本 | 实例候选或作者允许的正式编辑 |
|
||
| propose_facts | 固定正文版本、结构和抽取结果 | 带来源的增量提案 |
|
||
| prepare_approved_facts | 已审增量、范围与事务上下文 | 可加入同一正式提交的参与者 |
|
||
| revise_setting | 预期版本及作者变更 | 新设定版本和影响 |
|
||
| 读取实体轨迹于 | 同库同用途数据库工厂创建的受控连接、认证作者、作品与对象ID | 调用方事务内只读实体或关系对象的历史；校作品归属，不更改当前版本、不提交或回滚 |
|
||
|
||
所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。
|
||
|
||
## 内部职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| 接口.py | 故事世界公开用例和可导入合同 |
|
||
| 模型.py | 故事世界稳定对象、外壳及内部状态 |
|
||
| 存储.py | 故事世界所属记录的 SQL 与版本读写 |
|
||
| 世界设定.py | 地点、物品、组织、规则及代价 |
|
||
| 人物关系.py | 人物、关系、弧线、视角与说话特征 |
|
||
| 事实提案.py | 抽取增量、真实引用校验及确认参与者 |
|
||
| 时点查询.py | 叙事时点、读者和角色知情范围 |
|
||
| 连续性.py | 事件、动态状态、因果、伏笔与承诺 |
|
||
| 来源有效性.py | 当前证据有效性与复核需求 |
|
||
| 设定修订.py | 动态实例保存、版本与影响 |
|
||
| 提示词/抽取章节事实.md | 按有效结构抽取事实提案 |
|
||
|
||
完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-B02-故事世界.md)。
|
||
|
||
## 实现约束
|
||
|
||
提案的实例类型、内容字段及字段别名来自S04登记。业务外壳固定作品、对象、版本、实例族、叙事生效位置、知情范围及证据；不能以名称拼接代替稳定对象身份。关系端点使用已解析的本书对象，类型与引用约束仍按有效结构核对。旧六种增量只是迁移和回归场景，不作为新实体类型的封闭清单。
|
||
|
||
引文按固定正文格式中的段落与码点区间核对，保留原字符。协议JSON只解码一次；字面反斜杠加n不自动改成换行。机械挽回只能把实际出现的名称保留为“提及”候选，并明确移除无依据字段；不能把名称命中当成原抽取内容全部成立。
|
||
|
||
每条正文来源在事实请求中声明为一份独立充分依据，确认时核对其固定版本及引文；同文的多段证据放在该来源的引文列表。独立作者设定不依赖正文继续成立。已确认事实读取时按当前依据计算可用性，不修改其历史决定。
|
||
|
||
事实引用按该事实的叙事生效位置选择端点版本；已发生事实不能借用计划或猜测中的实体。角色知情使用`known_to`中的`actor_id`与`from_chapter_id`逐项表达获知位置，不以事件发生时间推定角色已经知情。历史内容按该版本保存的结构绑定解释，再应用当前字段用途策略；当前绑定升级不改写旧内容的字段含义。
|
||
|
||
事件生效位置、正文何时披露依据与系统确认版本分别保存和判断。后章回忆可以支持早期事件，不能因来源章节较晚而拒绝记录；截至早期章节的查询仍须省略尚未披露的正文依据。独立作者设定、角色猜测和未来规划明确标记，规划与猜测不混入已发生事实。作者总览、读者进度与指定角色知情范围分别查询；作者总览可以回查后文对早期事件的说明，早期读者视图仍不读取后文披露。预期章节窗口用稳定章节身份表达，只在作者视角显示。
|
||
|
||
- 实体类型从 S04 的已登记生命周期族读取，不能在抽取、验证、渲染和保存各自维护固定六型列表。
|
||
- 角色猜测、读者所知、未来规划和已发生事实分别表达；时间位置由稳定章节身份及叙事顺序解析。
|
||
- 引用字段在本模块验证真实目标、归属和时点，保留可追查关系。
|
||
- 来源唯一依据改变时退出当前事实消费；其他有效依据或独立作者设定按各自依据保留。
|
||
|
||
## 协作与失败
|
||
|
||
B09 经公开查询取事实；B05 可在原子包中加入已批准事实；S04 只负责字段结构，不能写实例。
|
||
|
||
引用不合法、证据缺失、时点超界、结构或版本变化返回失败；自动抽取始终停在提案。
|
||
|
||
## 验收行为
|
||
|
||
- 新增实体类型全链运行。
|
||
- 未来细纲不能冒充已发生事实。
|
||
- 已确认事实在正文改变后正确复核。
|
||
- 批准增量任一失败整包回滚。
|
||
|
||
验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。
|
||
|
||
## 作者实体表单与字段提案
|
||
|
||
世界类型清单的`schemas`只列出S04已发布的基础结构身份与版本，不混入候选或其他作品扩展，不假设结构ID与类型ID相同。`读取实体表单`核对作者、作品和对象，已有对象取实际保存绑定；新对象显式选择结构。返回当次uiVisible/userEditable投影、内容、结构/投影哈希、当前版本和真实事实语境；已发生、独立设定、计划与正文来源保持原含义。新表单读取不创建对象、不打开审阅或发起模型。
|
||
|
||
作者保存可用既有`提出事实`的字段请求分支：`事实字段提案请求`继承原事实外壳，`content`为空、`changes`使用S04逐字段set/remove合同。原content请求的结构与哈希形状保持不变；持久读取按有无changes选择确定类型，不将旧请求试作新字段请求。S04从服务端旧值计算规范内容，保护不可编辑字段并复检固定结构与投影；S01保存未决提案和完整请求。确认时再次重算相同变化、核对来源与预期版本，删除字段不会因省略键而变成无效操作。原请求和相同确认重放返回原回执，网页保存与打开审阅均不等于作者采纳。
|