knowledge-governance/docs/DOMAIN_MODEL.md

知识治理平台领域对象契约

目的

本文件是知识治理平台当前实现的唯一领域对象映射。它将产品术语映射到现有Go模型、PostgreSQL表和外部边界；后续模块不得另造一套身份、时间或状态语义。

本文件不把“代码存在”“容器健康”写成已完成能力。尚未存在的对象或关联明确列在 Current implementation gaps。

统一主链

SourceConnection → SourceItem → SourceItemVersion → ContentObject
SourceConnection → SourceCatalogSnapshot → SourceCatalogNode
SourceCatalogChangeSet → SourceCatalogChangeItem
SourceItemVersion → TestPublication → AcceptanceResult
ReleaseBatch → ReleaseExecution → ReleaseItemExecution

完整目标主链将在后续工作包补齐为：

SourceConnection
→ SourceItem / SourceItemVersion / ContentObject
→ SourceCatalogSnapshot
→ SourceCatalogChangeSet
→ ProcessingExecution / Job
→ TestPublication / AcceptanceResult
→ ReleaseChangeSet
→ ProductionSnapshot
→ ReleaseBatch / ReleaseExecution

全局身份与时间规则

规则	契约
ID	所有主对象使用服务端生成的不透明ID；页面和Job Payload只能传递ID，不能传递受保护来源URL、Token或Cookie。
时间	created_at表示治理对象创建；updated_at表示本对象最后治理状态变化；来源侧时间必须单独使用updated_at_source或source_updated_at。
内容Hash	只有content_objects.sha256是文件内容SHA-256。canonical_uri_hash、source_locator_hash和snapshot_sha256绝不能作为内容Hash展示或用于内容去重。
删除	来源不可用不等于来源删除。只有权威来源删除事件或经人工确认的删除ChangeSet才可进入目标移除流程。
目标写入	普通治理层不直接写WeKnora数据库；测试写入通过官方API/受控适配器；生产发布由独立Release Worker和门禁处理。

Source

**产品含义：**一个独立配置、独立健康状态、独立刷新策略的资料来源。

当前实现：

项目	当前映射
Go模型	governance.SourceConnection
数据表	source_connections
主键	source_connections.id
类型	source_type：当前为pp、alist、dingtalk；manual是Go层支持的扩展类型。
时间	created_at、updated_at
可变配置	enabled、schedule、last_health
敏感字段	base_url、secret_ref；不得返回前端或日志。

不可变/关系约束：

一个SourceConnection可以有多个SourceItem。
一个SourceConnection可以有多个SourceCatalogSnapshot。
SourceItem、Snapshot、ChangeSet不得跨SourceConnection关联。

SourceFile

**产品含义：**来源中的一份可治理资料，以及该资料的每个来源版本和内容对象。

SourceFile不是一个单表对象，当前由三个对象组成：

逻辑层	Go模型	数据表	稳定身份
文件身份	governance.SourceItem	source_items	(source_connection_id, stable_external_id)
文件版本	governance.SourceItemVersion	source_item_versions	(source_item_id, revision)
内容对象	governance.ContentObject	content_objects	全局sha256

关键字段：

SourceItem:
- source_connection_id
- stable_external_id
- canonical_uri_hash
- normalized_path
- revision
- updated_at_source
- source_change

SourceItemVersion:
- source_item_id
- revision
- content_object_id（内容尚未下载或验证前允许为空）
- content_state
- source_updated_at

ContentObject:
- sha256
- size_bytes
- mime
- validated_format
- local_spool_ref
- content_state

关系规则：

路径变化不必然产生新SourceItem。
内容Hash变化产生新的SourceItemVersion或新的内容关联。
同一内容Hash可以被多个SourceItemVersion复用，但每个版本仍保留自己的来源身份和来源时间。
TestPublication必须引用一个SourceItemVersion，不能直接引用路径或ContentObject。

Snapshot

**产品含义：**一次来源目录扫描获得的不可变目录事实；它记录当时看到的文件/目录，而不是文件正文副本。

当前实现：

项目	当前映射
快照表	source_catalog_snapshots
节点表	source_catalog_nodes
当前指针	source_catalog_heads
快照主键	source_catalog_snapshots.id
来源约束	(source_connection_id, snapshot_sha256)唯一
时间	observed_at、created_at；Head使用activated_at
目录节点	node_type=folder
文件节点	node_type=file

Snapshot规则：

SourceConnection → SourceCatalogSnapshot → SourceCatalogNode
Head只指向一个当前快照；切换Head不得修改旧快照。
节点的source_locator_hash是来源定位摘要，不是内容Hash。
节点可选关联source_item_id；未关联节点仍可作为目录事实展示。

操作记录补充：source_scans和source_scan_changes是旧扫描运行记录，不能替代当前不可变目录快照。

ChangeSet

**产品含义：**两个不可变来源Snapshot之间的可审查差异计划。

当前实现：

项目	当前映射
主表	source_catalog_change_sets
条目表	source_catalog_change_items
Go投影	governance.CatalogChangeSet、CatalogChangeItem
主键	source_catalog_change_sets.id
快照关系	from_snapshot_id、to_snapshot_id
动作	add、update、move_scope、delete、no_change
时间	created_at、confirmed_at、applied_at
当前状态字段	planned、confirmed、applied、cancelled

ChangeSet规则：

一个ChangeSet只能属于一个SourceConnection。
from_snapshot_id和to_snapshot_id必须属于同一SourceConnection。
to_snapshot_id当前唯一，因此一份激活快照最多对应一份目录ChangeSet。
ChangeItem当前使用(change_set_id, source_locator_hash)唯一。
ChangeSet只表达比较结果；它本身不等于已经上传、解析或删除。

**后续目标：**S8/P3/P5会补充SourceItemVersion、内容Hash、旧新范围、确认执行和Job关联。

Job

**产品含义：**可租约、可重试、可恢复的异步工作项；Job只保存安全业务ID和进度，不保存敏感连接数据。

当前实现：

项目	当前映射
Go模型	jobs.Job（internal/jobs）
数据表	jobs
主键	jobs.id
幂等	idempotency_key唯一
调度	priority、available_at
租约	lease_owner、lease_until
尝试	attempt、max_attempts
时间	created_at、updated_at、started_at、completed_at

当前Job类型示例：

source.catalog.refresh
test.upload
test.poll
test.validate
test.remove
release.publish
release.rollback

Job规则：

Job完成只表示本地处理器完成；对于WeKnora解析，必须继续由test.poll确认远端终态。
Job payload不允许保存Token、Cookie、签名URL、原始文件内容或生产凭据。
ReleaseExecution通过job_id外键绑定发布Job。

Release

**产品含义：**把经过测试验收的知识，以可追溯、可验证、可回滚方式发布到生产。

当前Release由批次、执行和执行项组成：

逻辑层	Go模型	数据表	主键
发布批次	governance.ReleaseBatch	release_batches	id
批次条目	ReleaseBatchItemView投影	release_batch_items	(release_batch_id, publication_id)
发布执行	governance.ReleaseExecution	release_executions	id
执行条目	ReleaseItemExecutionView投影	release_item_executions	id

Release关系：

ReleaseBatch → ReleaseExecution → ReleaseItemExecution
ReleaseExecution → Job（通过job_id）
ReleaseItemExecution → TestPublication（通过publication_id）
Rollback ReleaseExecution → prior publish ReleaseExecution

Release规则：

ReleaseBatch sealed后内容不可变。
一个批次最多有一个publish execution。
一个publish execution最多有一个rollback execution。
ReleaseItemExecution记录生产前后revision和安全错误码。
只有独立生产门禁、备份恢复验证和Release Worker均满足时才可以请求生产执行。

TestPublication和验收（辅助对象）

TestPublication不是原始SourceFile，也不是生产Release；它表示某个SourceItemVersion在指定测试知识库中的处理实例。

SourceItemVersion → TestPublication → AcceptanceResult

项目	当前映射
测试发布	governance.Publication / API投影TestPublication / 表test_publications
验收结果	governance.AcceptanceResult / 表acceptance_results
身份	(source_item_version_id, test_kb_id)唯一
处理维度	ingest_state、processing_state、retrieval_state
版本维度	parser_generation、index_generation

当前实现缺口

Current implementation gaps

以下缺口是已知事实，不能在任何页面、报告或测试中标为“已完成”：

1. SourceCatalogNode尚不能为所有来源绑定SourceItem和SourceItemVersion。
2. 目录Snapshot节点尚未持久保存文件内容SHA-256；snapshot_sha256不是文件内容Hash。
3. SourceCatalogChangeItem尚未保存旧新内容Hash、旧新范围和SourceItemVersion关联。
4. ChangeSet确认尚未直接创建Processing Job；当前Processing Confirmation仅绑定TestPublication。
5. Job尚未通过统一外键绑定ChangeSet、文件版本、目标和动作；该工作属于P3/P5。
6. ReleaseChangeSet和ProductionSnapshot尚未实现；当前Release Plan是实时计算，不能冒充不可变发布ChangeSet。
7. 当前ReleaseExecution没有来源Snapshot、来源ChangeSet、发布ChangeSet和生产Snapshot的完整外键链；该工作属于R1、R2、R6。
8. Source配置、SourceFile身份和内容Hash的运行时证据仍需后续S2、P1、P2补齐。

C1验收边界

C1只完成以下内容：

冻结当前对象术语和真实映射
明确身份、时间和关系规则
标出当前不存在的对象和关联
用测试防止领域契约文档丢失关键对象

C1不完成：

统一状态机（C2）
OpenAPI（C3）
写操作幂等（C4）
内容Hash闭环（P1）
ChangeSet执行（P3）
发布ChangeSet或Production Snapshot（R1/R2）