生命周期模式篇

目标：让集成方掌握文档与容器的完整生命周期——发布 / 归档 / 回收站 / 彻底清除，以及批量操作、trash 保留期配置和各状态下的可见性投影，并理解容器与文档生命周期的级联关系。
不在本篇范围：文档版本链（见文档与版本模式篇）；容器层级建模、移动与断继承（见容器模型与层级模式篇）；ACL 权限位（见 ACL 与继承模式篇）；分享链路（见分享模式篇）；全文搜索中 trashed / archived 资源的可见性（见全文搜索模式篇）；错误码完整码表（见错误码参考）。

本篇是领域模型 §Document / Container 的生命周期纵深展开。Document 侧的生命周期状态与 Container 侧呈对称形态，本篇统一说明。

关键事实

文档状态机：ACTIVE / ARCHIVED / TRASHED / DELETED（DELETED 是 purge 后短暂过渡态，不可主动设置）。
容器状态机：ACTIVE / ARCHIVED / TRASHED（purge 后实体消失，不留 DELETED 投影）。
默认列表端点只返回 ACTIVE 资源；ARCHIVED 和 TRASHED 各自有独立的查询面。
delete 是软删除（移入回收站 TRASHED），purge 是不可逆的物理清除——两者语义截然不同，UI 必须区分。
容器 delete 把整棵子树（后代容器 + 所有子文档）一并移入 TRASHED；容器 purge 连带物理清除整棵子树。
⚠️ 容器侧 restore / purge / batchRestore / batchPurge 不在 /trash/ 子路径下——只有 trash/getPage 是 /v1/containers/trash/getPage，其它是 /v1/containers/restore / /purge 等同级路径；而文档侧则是 /v1/documents/trash/restore / /trash/purge 等。按下表实际路径调用，不要凭一方惯例拼另一方 URL。
purgeAt（自动彻底清除时间）= 进入 TRASHED 时间 + 租户级 trashRetentionDays；该配置可读（见 §六）。

一、发布与取消发布（文档专属）

发布是把某个版本显式钉为「已发布版」，与「当前版本」独立——两者可以不一致。集成方业务通常以「已发布版」为对外稳定版本（如签发直读 URL / 分享链接时只指向 publishedVersionId）。

发布（`GET /v1/documents/publish`）

bash

curl -X GET 'https://api.atkonbase.example.com/v1/documents/publish?docId=${docId}&versionId=${versionId}' \
  -H 'Authorization: Bearer ${accessToken}'

versionId 必须是该文档已存在的版本；不存在返 code=1。
发布不改 state，也不改 currentVersionId——只更新 publishedVersionId。

取消发布（`GET /v1/documents/unpublish`）

bash

curl -X GET 'https://api.atkonbase.example.com/v1/documents/unpublish?docId=${docId}' \
  -H 'Authorization: Bearer ${accessToken}'

清空 publishedVersionId，文档回到「无已发布版本」状态。发布版本 URL 此后不可签发；之前已签发的短时 URL 仍在有效期内可消费（到期自然失效）。

二、归档与取消归档

归档把资源置为「不活跃但保留」状态，不删字节，ACL 仍生效。

文档归档

端点	作用
`GET /v1/documents/archive?docId=...`	`state` → `ARCHIVED`
`GET /v1/documents/unarchive?docId=...`	`state` → `ACTIVE`

容器归档

端点	作用
`GET /v1/containers/archive?containerId=...`	`status` → `ARCHIVED`
`GET /v1/containers/unarchive?containerId=...`	`status` → `ACTIVE`

归档后行为：

资源对 getPage（无 state 过滤）不可见。
文档仍可读、仍可追加新版本、版本保留策略仍运行。
容器归档不级联归档子文档——子文档 state 不变；子文档通过 containerId 查询仍能找到。
容器归档后仍可在容器内创建新文档。

三、删除（移入回收站）

文档删除

bash

curl -X GET 'https://api.atkonbase.example.com/v1/documents/delete?docId=${docId}' \
  -H 'Authorization: Bearer ${accessToken}'

批量：

bash

curl -X POST 'https://api.atkonbase.example.com/v1/documents/batchDelete' \
  -H 'Authorization: Bearer ${accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{ "docIds": ["${d1}", "${d2}"] }'

单批 ≤ 100 条；响应 BatchResultDTO<String>，success / failed 各含原因。

容器删除

bash

curl -X GET 'https://api.atkonbase.example.com/v1/containers/delete?containerId=${containerId}' \
  -H 'Authorization: Bearer ${accessToken}'

批量：

bash

curl -X POST 'https://api.atkonbase.example.com/v1/containers/batchDelete' \
  -H 'Authorization: Bearer ${accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{ "containerIds": ["${c1}", "${c2}"] }'

⚠️ 容器删除是整棵子树操作——该容器的所有后代容器与文档全部进入 TRASHED。

四、回收站

回收站独立于活跃视图，资源在回收站期间可恢复，直到自动 purge 或手动 purge。

文档回收站端点

端点	用途
`POST /v1/documents/trash/getPage`	分页查已删除文档（含 `purgeAt`）
`GET /v1/documents/trash/restore?docId=...`	单条恢复（`TRASHED` → `ACTIVE`）
`POST /v1/documents/trash/batchRestore`	批量恢复，单批 ≤ 100
`GET /v1/documents/trash/purge?docId=...`	单条彻底清除（不可恢复）
`POST /v1/documents/trash/batchPurge`	批量彻底清除，单批 ≤ 100

容器回收站端点

端点	用途
`POST /v1/containers/trash/getPage`	分页查已删除容器（含 `purgeAt`）
`GET /v1/containers/restore?containerId=...`	单条恢复
`POST /v1/containers/batchRestore`	批量恢复，单批 ≤ 100
`GET /v1/containers/purge?containerId=...`	单条彻底清除（连同子树）
`POST /v1/containers/batchPurge`	批量彻底清除

curl 示例：查文档回收站

bash

curl -X POST 'https://api.atkonbase.example.com/v1/documents/trash/getPage' \
  -H 'Authorization: Bearer ${accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{ "pageSize": 20, "pageNumber": 1 }'

期望响应（关键字段）

json

{
  "code": 0,
  "data": {
    "total": 5,
    "rows": [
      {
        "docId": "D1000001",
        "title": "合同草稿",
        "state": "TRASHED",
        "purgeAt": "2026-08-01T10:00:00.000+08:00",
        "createTime": "2026-04-10T09:00:00.000+08:00"
      }
    ]
  }
}

purgeAt —— 自动彻底清除时间；= 进入 TRASHED 时间 + 当前租户 trashRetentionDays。调整 trashRetentionDays 后该字段下次查询即刷新（不锁定旧值）。
purgeAt=null 表示该租户配置了「永不自动 purge」（retentionDays=0）。

五、彻底清除（purge）

文档 purge

bash

curl -X GET 'https://api.atkonbase.example.com/v1/documents/trash/purge?docId=${docId}' \
  -H 'Authorization: Bearer ${accessToken}'

删除 Document 记录与所有版本记录；blob 物理清理由平台异步处理，集成方无感知。

容器 purge

bash

curl -X GET 'https://api.atkonbase.example.com/v1/containers/purge?containerId=${containerId}' \
  -H 'Authorization: Bearer ${accessToken}'

⚠️ 连同该容器整棵子树（后代容器 + 所有文档及全部版本）一并物理清除，不可恢复。UI 务必附双重确认；批量 purge 尤其谨慎。

六、trash 保留期配置（V1/System 小节）

集成方可读当前租户的 trash 保留天数配置，以便在 UI 上向用户展示「文档将在 N 天后永久删除」。

读取 trash 保留天数（`GET /v1/system/getTrashRetention`）

bash

curl -X GET 'https://api.atkonbase.example.com/v1/system/getTrashRetention' \
  -H 'Authorization: Bearer ${accessToken}'

所需 scope：client:storage:document:read。

期望响应（关键字段）

json

{
  "code": 0,
  "data": {
    "retentionDays": 30,
    "defaultDays": 30,
    "tenantOverrideDays": null
  }
}

字段	含义
`retentionDays`	当前租户实际生效天数（已应用租户级覆盖）；用于 UI 展示与 `purgeAt` 校对
`defaultDays`	平台全局默认天数（管理端未覆盖时的基准）
`tenantOverrideDays`	租户级覆盖天数；`null` 表示未设置覆盖、走全局默认

该配置由租户管理员在 Console 内设定，集成方只读。
值影响：进入 TRASHED 的资源在 retentionDays 天后被平台自动 purge；purgeAt 字段即由此计算。
retentionDays=0 表示永不自动 purge（需手动 purge）；此时回收站内资源 purgeAt=null。

⚠️ 该端点未来若 V1/System 有更多配置查询端点扩展，将单独立篇；本小节仅覆盖 trash 保留期这一端点。

七、生命周期与分享的关系

进入 TRASHED 状态的资源，其关联 ShareLink / ShareGrant 的可达性行为：

ShareLink（公开链接）：资源进入 TRASHED 后，访问该 token 的公开下载端点统一返回不可用响应。链接本身不自动撤销，资源恢复后链接重新可达。
ShareGrant（站内分享）：进入 TRASHED 的资源，关联 ShareGrant 仍在 status=ACTIVE，但被分享方读取该资源时受资源状态约束——资源在 TRASHED 状态下不可被普通 V1 资源端点读取。purge 后 ShareGrant 记录保留（历史存证），但资源已不可访问。

分享端点的完整行为见分享模式篇。

常见坑

⚠️ delete 与 purge 混淆：delete 可恢复、purge 不可恢复。UI 要用不同操作名称和不同确认文案严格区分。
⚠️ 容器 purge 低估影响范围：只想清除一个容器，不知道整棵子树都会被清除。规避：purge 前用 containers/stats 先看 totalDocumentCount / totalContainerCount，确认清除影响面。
⚠️ 容器侧 restore / purge 路径与文档侧不对称：文档是 /trash/restore / /trash/purge；容器是 /restore / /purge（非 /trash/ 子路径）。不要凭文档侧直觉拼容器侧 URL。
⚠️ purgeAt 当作绝对时间戳固化：以为设置后就不变。规避：租户管理员调整 trashRetentionDays 后，purgeAt 下次查询即刷新——不要本地缓存 purgeAt 字段值。
⚠️ 以为 archived 资源被分享时对外不可见：归档只影响默认列表，ACL 和分享逻辑不受归档状态影响。规避：若需隐藏归档资源，在分享链接创建前先撤销该资源的 ShareLink；或在业务层按状态过滤。
⚠️ 容器归档后子文档仍 ACTIVE：以为归档容器会同步归档下面的文档。规避：容器归档不级联，子文档仍可被查询到；按状态过滤要在文档列表时同时传 containerId + state。
⚠️ 批量端点传超 100 条：batchDelete / batchPurge / batchRestore 均为单批 ≤ 100，集成方自行切片。
⚠️ retentionDays=0 误解为「立即 purge」：0 表示永不自动 purge（保留到手动 purge），不是「进入 TRASHED 后立即物理清除」。

下一步

文档版本链、版本保留策略、publishedVersionId 细节 → 文档与版本模式篇
容器层级操作、移动、断继承 → 容器模型与层级模式篇
分享链接与站内分享完整行为 → 分享模式篇
全文搜索中 trashed / archived 资源的可见性 → 全文搜索模式篇
V1 端点契约 + Try-it → 接口参考

生命周期模式篇 ​

关键事实 ​

一、发布与取消发布（文档专属） ​

发布（GET /v1/documents/publish） ​

取消发布（GET /v1/documents/unpublish） ​

二、归档与取消归档 ​

文档归档 ​

容器归档 ​

三、删除（移入回收站） ​

文档删除 ​

容器删除 ​

四、回收站 ​

文档回收站端点 ​

容器回收站端点 ​

curl 示例：查文档回收站 ​

期望响应（关键字段） ​

五、彻底清除（purge） ​

文档 purge ​

容器 purge ​

六、trash 保留期配置（V1/System 小节） ​

读取 trash 保留天数（GET /v1/system/getTrashRetention） ​

期望响应（关键字段） ​

七、生命周期与分享的关系 ​

常见坑 ​

下一步 ​

生命周期模式篇

关键事实

一、发布与取消发布（文档专属）

发布（`GET /v1/documents/publish`）

取消发布（`GET /v1/documents/unpublish`）

二、归档与取消归档

文档归档

容器归档

三、删除（移入回收站）

文档删除

容器删除

四、回收站

文档回收站端点

容器回收站端点

curl 示例：查文档回收站

期望响应（关键字段）

五、彻底清除（purge）

文档 purge

容器 purge

六、trash 保留期配置（V1/System 小节）

读取 trash 保留天数（`GET /v1/system/getTrashRetention`）

期望响应（关键字段）

七、生命周期与分享的关系

常见坑

下一步