数据导出

目标：说清 ATKONBASE 完整数据导出包的结构与约定——包里有什么、按什么布局组织、二进制本体怎么带走、manifest 如何自描述，以及异地重建前必须自行处理的环节。
适用场景：你需要把一个实例（或其中某个租户）的内容数据完整迁出——做反锁定留存、灾备归档或迁移到其它系统。读完本篇即可独立解读一个导出包，无需额外上下文。
不在本篇范围：导出的发起与下载属于平台运维操作，由部署方的平台管理员触发；本篇只描述产物格式，不涉及操作端点。

一、导出包是什么

导出包是一个 ZIP 归档，包含一个实例（或单个租户）在某一时间点的完整内容数据真值：

模型（schema）：内容类型、字段定义、词表、模板等「内容长什么样」的定义。
结构化数据（data）：容器层级、文档、文档版本链、元数据值、ACL 条目。
二进制本体清单（blobs）：每个被版本引用的文件本体的存储引用、大小、内容校验值与时效下载链接——本体不打进包内，凭清单按需取走。
manifest：包的自描述索引，含各实体计数、快照时间点、版本号与可移植性声明。

导出是单向的：它把数据完整交到你手里，异地如何重建由接收方自行决定。

二、包目录布局

布局取决于导出范围：

单租户——数据直接落在包根目录：

manifest.json
schema.json
data/
  containers.json
  documents.json
  document_versions.json
  metadata.json
  acl.json
  blobs.json

全实例（所有租户）——按租户编码分目录，租户间数据互不混入：

manifest.json
tenants/
  acme/
    schema.json
    data/ ...
  globex/
    schema.json
    data/ ...

manifest.json 始终在包根。每个租户区段在 manifest 的 tenants 列表里都有对应条目，其 directory 字段就是该租户数据在包内的目录前缀（单租户为空串）——据此即可在包内导航定位。

三、各数据文件

每个 data/*.json 都是一个 JSON 数组，元素自描述、可独立解读：

文件	内容
`containers.json`	容器层级：每个容器的业务 ID、父容器、类型、名称、排序、状态与继承开关
`documents.json`	文档：业务 ID、所属容器、标题、类型、当前/已发布版本指针、状态
`document_versions.json`	文档版本链（含全部历史版本）：版本号承载顺序，附本体指针 `blobId`、内容校验值、大小、MIME、原始文件名
`metadata.json`	元数据值：按「资源类型 + 资源」聚合为一条记录，字段以业务键标识、附类型化取值，多值字段保持原有顺序
`acl.json`	ACL 条目：携带授权主体引用（用户/角色/部门标识）与权限信息，足以重建有效权限矩阵
`blobs.json`	二进制本体清单（见下节）

元数据字段值按其类型编码（字符串 / 整数 / 布尔 / 日期 / 多值数组等），解析规则见字段值编码契约。

四、二进制本体清单与下载

文件本体可达 GB~TB 级，不打进导出包。blobs.json 是一份清单，每个被版本链引用的本体一条（按本体去重，多个版本引用同一本体时只出现一次）：

字段	含义
`blobId`	本体业务主键，`document_versions.json` 经此字段引用
`storageBackend`	存储后端类型（`local` / `s3`）
`bucket` / `objectKey`	存储引用
`sizeBytes`	文件大小（字节）
`contentHash`	内容校验值（SHA-256），见下方完整性校验说明；可能为空
`downloadUrl`	时效预签名下载 URL：在有效期内可直接 GET 取走本体

预签名 URL 有效期：URL 自导出包生成起算有一段固定有效期，manifest.json 的 presignedUrlTtlSeconds 字段标注具体秒数。请在有效期内取走本体；过期后需重新发起导出。

downloadUrl 为空时：当前存储后端不支持预签名直链（如本地存储部署）。此时需由部署方按其存储访问方式自行取用本体；导出包仍给出存储引用（bucket / objectKey）供定位。

contentHash 的可信度因本体来源而异：经标准上传 / 分片合并写入的本体，contentHash 是服务端实算的 SHA-256，下载后可凭此比对校验字节完整；经预签名直传写入的本体，contentHash 是上传方声明、服务端未重算校验的值，仅供参考；个别本体该值可能为空。请按此预期使用，不要假设所有 contentHash 都已被平台核验。

五、manifest 自描述

manifest.json 是核验与导航的入口：

字段	含义
`formatVersion`	导出包格式版本（包结构与文件布局的版本）
`schemaVersion`	内容模型 schema 版本（`schema.json` 结构的版本）
`scope`	导出范围：`ALL_TENANTS` / `SINGLE_TENANT`
`snapshotAt`	近似快照时间点——包内仅含该时间点及之前的数据
`generatedAt`	导出包生成时间
`presignedUrlTtlSeconds`	二进制清单预签名 URL 有效期（秒）
`portability`	可移植性声明（见下节）
`tenants`	按租户列出的区段：含 `tenantId` / `tenantCode` / `directory` 目录导航，以及容器、文档、版本、元数据记录、ACL 资源、本体的各项计数

逐租户计数可用于核对：把包内各 data/*.json 的元素数与 manifest 计数比对，即可验证导出包是否完整、有无截断。

快照语义：导出取近似时间点快照，以 snapshotAt 为统一截止线纳入数据。版本链是 append-only 的（历史版本不可变），因此版本数据天然一致；跨全实例时各租户区段同样以 snapshotAt 为界对齐。

六、可移植性声明

导出对可移植性保持透明：manifest.json 的 portability 段显式标注异地重建前须自行处理的环节：

ACL 主体需映射（aclSubjectMappingRequired）：acl.json 携带的授权主体标识（用户/角色/部门）是源实例内的标识。异地重建有效权限矩阵前，须把这些标识映射到目标系统中对应的主体。
本体下载方式：本体不在包内，凭 blobs.json 的预签名 URL 或经存储层鉴权下载。

七、导源不导派生

导出遵循导源不导派生：只导出能重建一切的源数据——模型、结构化数据与二进制本体清单。可由源数据重算的派生物交给异地重新生成，从而保持包体精简、架构清晰。这类在异地由模型 + 本体重算的派生物包括：

渲染产物（预览图、缩略图、格式转换产物）
抽取文本 / 检索分块 / 向量嵌入等检索增强派生物

manifest.json 的 portability.excludedDerivatives 列出这些派生物类型，供你按需在异地重建。

下一步

理解包内对象之间的关系 → 领域模型
解析 metadata.json 里的字段值 → 字段值编码契约

数据导出 ​

一、导出包是什么 ​

二、包目录布局 ​

三、各数据文件 ​

四、二进制本体清单与下载 ​

五、manifest 自描述 ​

六、可移植性声明 ​

七、导源不导派生 ​

下一步 ​