Weegloo Docs - 系统属性 (sys)

WEEGLOO 中所有资源的响应都分为两部分。一部分是该资源的主体数据，例如 fields；另一部分是由系统管理的元数据。这些元数据全部存放在 sys 对象中。

sys 中包含资源的标识符 (id)、种类 (type)、创建与修改时间、版本，以及与其他资源的关系。本页将所有资源共有的 sys 结构，以及不同资源种类之间的差异集中整理在一处。各资源的单独参考文档只另行说明该资源特有的 sys 键，共有部分则引用本页。

公共字段

几乎所有资源的 sys 都具有以下字段。createdBy、updatedBy 和 space 以指向其他资源的 Refer 结构 ({ "sys": { "id", "type": "Refer", "targetType" } }) 形式存在。详细结构在下方的 Refer 结构中说明。

属性	类型	说明
`id`	string	资源的唯一标识符。用于单条查询、修改、删除路径中的 `{...Id}` 位置。
`type`	string	资源种类。其值为该资源的种类名称（例如 `"Content"`、`"Media"`、`"Tag"`）。
`createdBy`	Refer<User>	创建该资源的用户。
`updatedBy`	Refer<User>	最后一次修改该资源的用户。
`createdAt`	string (date-time)	创建时间。
`updatedAt`	string (date-time)	最后修改时间。
`version`	integer (≥1)	当前版本。每次修改资源时递增 1。
`space`	Refer<Space>	该资源所属的 Space。仅 Space 下属资源具有此字段。

version 还用于防止并发修改冲突。在修改、发布等变更类请求中，必须将当前的 version 值放入 X-Weegloo-Version 请求头中发送。详细规则请参阅约定。

Organization 不属于 Space 下属资源，因此没有 space。它改为具有指向所属套餐的 plan(Refer<Plan>) 和表示是否为官方的 isOfficial(boolean)。Space 具有指向上级 Organization 的 organization(Refer<Organization>) 和 plan。

Refer 结构

sys 中指向其他资源的引用始终采用相同的结构。type 固定为 "Refer"，targetType 则指明所指向资源的种类。

{
  "sys": {
    "id": "HnQ32YiH",
    "type": "Refer",
    "targetType": "Space"
  }
}

targetType 中存放所指向资源的种类名称。例如 space 的 targetType 为 "Space"，createdBy、updatedBy 为 "User"，Content 的 contentType 为 "ContentType"。也就是说，标记为 Refer<User>、Refer<Space> 的类型都采用此结构，只是 targetType 不同。

不同资源种类的差异

在公共字段之上，会根据资源种类附加额外属性。大致分为三类。

发布生命周期资源 (Content、Media)

Content 和 Media 具有编写、发布、归档这样的生命周期。因此在 sys 中会增加表示发布状态的属性。

属性	类型	说明
`status`	string (enum)	发布状态。为 `Draft`、`Changed`、`Published`、`Archived` 之一。
`publish`	object	发布状态指针。参见下方的键说明。
`archive`	object	归档信息。仅在归档时存在，否则没有该键。

status 为以下 4 种之一。

`status`	含义
`Draft`	正在编写、尚未发布的状态。
`Changed`	曾经发布过，但此后被修改、存在尚未发布的变更的状态。
`Published`	已发布且没有未发布变更的状态。
`Archived`	已归档的状态。

publish 对象是指向发布状态的指针。处于已发布状态时，它具有以下全部键。

键	类型	说明
`version`	integer	发布时刻的 `sys.version`。
`at`	string (date-time)	最后一次发布时间。
`firstAt`	string (date-time)	首次发布时间。即使取消发布也会保留。
`counter`	integer	累计发布次数。
`by`	Refer<User>	最后一次执行发布的用户。

取消发布后，publish 中会移除 version、at、by，仅保留 firstAt、counter。如果从未发布过，则 publish 为 { "counter": 0 }。

archive 对象仅在归档时存在，具有归档时刻的 version、归档时间 at，以及执行归档的用户 by。若不处于归档状态，则没有 archive 键本身。

这里的 sys.version 是工作中版本（每次变更，如创建、修改、发布等都会递增），而 publish.version 是最后一次发布的版本。两者可能不同。

下面是处于已发布状态的 Content 的 sys 示例。

{
  "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
  "type": "Content",
  "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
  "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
  "publish": {
    "version": 1,
    "at": "2026-06-18T09:51:44.128Z",
    "firstAt": "2026-06-18T09:51:44.128Z",
    "counter": 1,
    "by": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }
  },
  "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
  "createdAt": "2026-06-18T09:51:14.597Z",
  "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
  "updatedAt": "2026-06-18T09:51:44.128Z",
  "version": 2,
  "status": "Published"
}

发布生命周期的状态转换顺序及各阶段的响应，在 Content 和 Media 中说明。

配置资源 (Tag、Locale、Organization、Space 等)

Tag、Locale、Organization、Space、SpaceRole、ServiceUserRole、Webhook、ServiceLogin 这类资源没有发布的概念。创建后即时生效，没有发布以将其上线到传递通道的步骤。

因此它们的 sys 中没有 status、publish、archive，只在公共字段之外具有 version。version 每次修改时递增 1，在变更请求时放入 X-Weegloo-Version 请求头。

SpaceRole 在此之外还具有 isLocked(boolean)。若为 true，则表示这是 WEEGLOO 默认提供的角色。

特殊资源 (ServiceUser、WebHosting)

部分资源的 sys 不符合上述两类。

ServiceUser 是通过产品的会员注册而产生的资源。它不是由人在内容工作室中创建和修改的资源，因此 sys 中没有 createdBy、updatedBy、version。它改为具有登录方式 provider(string) 和 email(string)。由于没有 version，修改 ServiceUser 时不需要 X-Weegloo-Version 请求头。

WebHosting 是托管部署物的资源。它具有公共字段和 version，并在此基础上增加了部署处理状态 state(enum)。这并非发布状态，而是处理已上传部署物的进度状态。

`state`	含义
`PENDING`	等待处理中。
`PROCESSING`	处理中。
`COMPLETED`	处理完成。
`FAILED`	处理失败。

CMA 与 CDA 的差异：version vs revision

即使是同一个 Content、Media，从哪个 API 获取也会导致 sys 的结构不同。

从 CMA（管理）获取的 Content、Media 是工作中的资源。因此它会一并包含 version、status、publish（以及归档时的 archive），同时告知当前工作状态和发布状态。

CDA（传递）只传递已发布的快照。由于不存在工作中状态的概念，sys 中不包含 version、status、publish、archive。它改为使用指向已发布快照编号的单个 revision(integer)。每次发布时，revision 都会存入该时刻的版本。

{
  "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
  "type": "Content",
  "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
  "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
  "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
  "createdAt": "2026-06-18T09:51:14.597Z",
  "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
  "updatedAt": "2026-06-18T09:51:44.128Z",
  "revision": 3
}

发布传递模型（只传递已发布的内容、发布快照、revision）在 CDA 概述中详细说明。

公共查询参数：列表查询、分页。
约定：媒体类型、JSON Patch、并发 (X-Weegloo-Version)。
错误：错误响应格式与公共代码。
CDA 概述：发布快照 (revision) 传递模型。