create-zleap-app 0.10.4 → 0.10.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/index.js +3 -0
  2. package/package.json +3 -3
  3. package/skills/zleap-cloud-app/SKILL.md +3 -3
  4. package/skills/zleap-cloud-app/references/app-runtime.md +3 -3
  5. package/skills/zleap-cloud-app/references/cloud-functions.md +25 -18
  6. package/skills/zleap-cloud-app/references/console-members.md +8 -16
  7. package/skills/zleap-cloud-app/references/limits.md +27 -36
  8. package/skills/zleap-cloud-app/references/manifest.md +26 -58
  9. package/skills/zleap-cloud-app/references/permissions.md +21 -21
  10. package/skills/zleap-cloud-app/references/sdk-database-files.md +12 -10
  11. package/skills/zleap-cloud-app/references/status-codes.md +117 -136
  12. package/skills/zleap-cloud-app/references/triggers.md +4 -4
  13. package/skills/zleap-cloud-app-release/SKILL.md +39 -82
  14. package/skills/zleap-cloud-app-release/references/app-center-install.md +22 -23
  15. package/skills/zleap-cloud-app-release/references/app-center-publish.md +56 -142
  16. package/skills/zleap-cloud-app-release/references/console-functions.md +12 -28
  17. package/skills/zleap-cloud-app-release/references/console-members.md +8 -16
  18. package/skills/zleap-cloud-app-release/references/console-release.md +18 -24
  19. package/skills/zleap-cloud-app-release/references/console-workspace.md +23 -90
  20. package/skills/zleap-cloud-app-release/references/dev-to-production.md +79 -349
  21. package/skills/zleap-cloud-app-release/references/permissions.md +21 -21
  22. package/skills/zleap-cloud-app-release/references/status-codes.md +117 -136
  23. package/templates/react-ts/scripts/zleap.mjs +14 -0
  24. package/templates/react-ts/src/cloud/client.ts +3 -3
  25. package/skills/zleap-cloud-app-release/references/console-legacy-release.md +0 -411
package/skills/zleap-cloud-app/references/sdk-database-files.md CHANGED
@@ -79,7 +79,7 @@ const db = zl.cloud.database();
79
79
 
80
80
  > **为什么用 `DYNAMIC_CURRENT_ENV`**（提示）
81
81
  >
82
- > 数据域（dev / prod）是「部署 + 当前用户 + 应用有没有生产环境」决定的：开发数据域默认只对开发团队（`appid` 应用成员 / 旧应用上传者）开放；
82
+ > 数据域（dev / prod）是「部署 + 当前用户 + 应用有没有生产环境」决定的：开发数据域默认只对开发团队（应用成员）开放；
83
83
  > 部署开放生产后其他使用者都用 prod，发布者本人在应用有了生产环境后也用 prod。
84
84
  > 应用自己判断不了，所以传哨兵 `DYNAMIC_CURRENT_ENV`，由宿主在握手时替你解析成具体值。
85
85
  > 写死 `'dev'` 或 `'prod'` 时，如果那不是当前对你开放的数据域，打开会话会被拒绝。
@@ -113,12 +113,12 @@ const caps = await zl.cloud.os.ready();
113
113
  数据库 / 文件相关的 profile 或操作符缺失抛 `UNSUPPORTED_OPERATION`；后台执行（`app-execution/1`）缺失抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 才是 `UNSUPPORTED_OPERATION`）。
114
114
  服务端只在条件满足时下发 profile（`zleap-service/internal/services/cloudauthority/runtime_session.go`）：
115
115
 
116
- | Profile | 解锁的 API | 服务端下发条件 |
117
- | ------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
118
- | `document-core/1` | `get` / `count` / `add` / `set` / `update` / `remove` / `operations.get` | 数据库已就绪、Manifest 的 `data.collections` 非空、已授予 `cloud.database.read` 或 `write`（`data.schemas` 可选，不写就是灵活集合） |
119
- | `watch-snapshot/1` | `watch()` | 在上一条基础上，声明并授予了 `cloud.database.read` |
120
- | `storage-object/1` | `uploadFile` / `downloadFile` / `deleteFile` / `os.files.*` | 部署启用了对象存储、授予了 `cloud.storage.read` 或 `write`；生产数据域还要求当前安装绑定了已就绪的签名发布 |
121
- | `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` | 当前安装有已启用的后台能力授权（在应用窗口「权限」里勾选了后台能力；`appid` 应用的发布绑定由平台自动完成，旧 `app_key` 应用还需「激活开发」）；缺失时抛 `BACKGROUND_CAPABILITY_UNAVAILABLE` |
116
+ | Profile | 解锁的 API | 服务端下发条件 |
117
+ | ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
118
+ | `document-core/1` | `get` / `count` / `add` / `set` / `update` / `remove` / `operations.get` | 数据库已就绪、Manifest 的 `data.collections` 非空、已授予 `cloud.database.read` 或 `write`（`data.schemas` 可选，不写就是灵活集合） |
119
+ | `watch-snapshot/1` | `watch()` | 在上一条基础上，声明并授予了 `cloud.database.read` |
120
+ | `storage-object/1` | `uploadFile` / `downloadFile` / `deleteFile` / `os.files.*` | 部署启用了对象存储、授予了 `cloud.storage.read` 或 `write`；生产数据域还要求当前安装绑定了已就绪的签名发布 |
121
+ | `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` | 当前安装有已启用的后台能力授权（在应用窗口「权限」里勾选了后台能力；发布绑定由平台自动完成）；缺失时抛 `BACKGROUND_CAPABILITY_UNAVAILABLE` |
122
122
 
123
123
  ```js
124
124
  const { profiles } = await zl.cloud.os.ready();
@@ -386,7 +386,9 @@ off(); // 取消订阅
386
386
  - 回调**只带变更坐标，不带文档内容**——收到后用 `get` / `watch` 重读；
387
387
  - 只会收到**本集合**的变更（一个订阅覆盖应用所有集合，SDK 按 `collection_key` 过滤）；
388
388
  - 推送是**协商可选**的：宿主没有推送能力、或还没 `init` 时返回一个空的取消函数，回调永远不会触发。
389
- 所以**保留一个低频的 `watch` / `get` 兜底是安全的**，不要假设一定有实时通知。
389
+ 所以**保留一个低频的 `watch` / `get` 兜底是安全的**，不要假设一定有实时通知；
390
+ - 时延：写入确认后平台立即转发，通常 1 秒内到达；平台繁忙时退回定时转发，可能延迟到几十秒。
391
+ 自己写入后要马上看到结果的，直接用写入返回值或重读，不要等 `onChange`。
390
392
 
391
393
  ### 不支持的方法
392
394
 
@@ -612,9 +614,9 @@ async function saveTodo(data) {
612
614
  }
613
615
  ```
614
616
 
615
- > **激活新发布后的会话失效**（提示）
617
+ > **绑定新发布后的会话失效**（提示）
616
618
  >
617
- > 开发者「激活」新的发布候选后，旧会话会收到 `RELEASE_UNAVAILABLE`。宿主会自动重开会话并**重试一次**，
619
+ > 安装切换到另一个版本并绑定新的发布后，旧会话会收到 `RELEASE_UNAVAILABLE`。宿主会自动重开会话并**重试一次**，
618
620
  > 多数情况下应用无感。若仍失败，请用户重新打开应用。
619
621
 
620
622
  ## 后台执行与能力调用
package/skills/zleap-cloud-app/references/status-codes.md CHANGED
@@ -39,7 +39,7 @@
39
39
  | 字段 | 含义 |
40
40
  | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
41
  | `code` | 业务码，按段位归类：401xx 认证、403xx 拒绝、404xx 不存在、409xx 冲突、422xx 参数、429xx 超限、503xx 未就绪/暂不可用、50000 内部错误 |
42
- | `message` | **给人看的中文说明**。数据服务、发布激活等错误会说清具体原因，容量类会带上数字（如「本应用文档总数：已用 9800，上限 10000」） |
42
+ | `message` | **给人看的中文说明**。数据服务、发布等错误会说清具体原因，容量类会带上数字（如「本应用文档总数：已用 9800，上限 10000」） |
43
43
  | `data.reason` | **稳定的原因码**，程序据此分流（本页各表格里的码） |
44
44
  | `data.next_action` | **下一步做什么**（2026-10 新增），只有能由使用者自己处理的错误才带 |
45
45
  | `data` 其他字段 | 定位信息：`operation`、`operation_id`、`layer`，容量类的 `quota` / `used` / `limit`，查询类的 `scan_limit` / `suggested_index`，限流的 `app_concurrency_limit` |
@@ -112,36 +112,36 @@
112
112
 
113
113
  ### 通道与调用
114
114
 
115
- | 错误码 | 含义 | 可重试 | 处理 |
116
- | ----------------------------------- | --------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
117
- | `COMMIT_UNKNOWN` | **写操作结果未知**（写请求 30 秒未返回等） | ✅ | **用原 `operationId` 查回执**，确认前不要换编号重新写 |
118
- | `CALL_TIMEOUT` | 读请求 30 秒未返回 / 握手 15 秒未完成 / 作业等待超时 | ✅ | 可重试；带 `jobId` 时用 `jobs.wait` 继续等 |
119
- | `RUNTIME_UNAVAILABLE` | 通道已关闭或服务暂不可用 | ✅ | 稍后重试；页面卸载后通道不可再用 |
120
- | `APP_RATE_LIMITED` | 本应用此刻并发请求过多（单应用并发槽被占满） | ❌\* | 稍后重试；不要立刻循环重试 |
121
- | `RESOURCE_EXHAUSTED` | 超出限制（并发 >8、分页/排序/大小上限、配额） | — | 对照 [限制](limits.md) 调整；配额类需清理数据 |
122
- | `REQUEST_TOO_LARGE` | 请求体超过协商上限（默认 256 KiB） | ❌ | 拆分请求 |
123
- | `IDEMPOTENCY_CONFLICT` | 同一请求编号被重复使用，或同一操作编号用于不同内容 | ❌ | 新请求用新编号；重试同一写入时内容必须完全相同 |
124
- | `OPERATION_EXPIRED` | 操作编号超出首次使用窗口（300 秒）或回执已过期 | ❌ | 重新读取最新状态后，用新编号发起 |
125
- | `PROTOCOL_MISMATCH` | SDK 与宿主协议不一致，或响应结构异常 | ❌ | 使用与当前 OS 匹配的 SDK 版本 |
126
- | `BACKGROUND_CAPABILITY_UNAVAILABLE` | 宿主没有协商到 `app-execution/1`，`callFunction` / `capabilities.invoke` 无法执行 | ❌ | 先让使用者在应用窗口「权限」里勾选后台能力并保存；确认版本已签发并激活、部署开放后台执行。旧 SDK 报的是 `UNSUPPORTED_OPERATION`，升级 SDK |
127
- | `UNSUPPORTED_OPERATION` | 平台未实现或未协商的操作 | ❌ | 改实现，见 [未实现的 SDK 功能](limits.md#未实现的-sdk-功能) |
115
+ | 错误码 | 含义 | 可重试 | 处理 |
116
+ | ----------------------------------- | --------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `COMMIT_UNKNOWN` | **写操作结果未知**（写请求 30 秒未返回等） | ✅ | **用原 `operationId` 查回执**，确认前不要换编号重新写 |
118
+ | `CALL_TIMEOUT` | 读请求 30 秒未返回 / 握手 15 秒未完成 / 作业等待超时 | ✅ | 可重试；带 `jobId` 时用 `jobs.wait` 继续等 |
119
+ | `RUNTIME_UNAVAILABLE` | 通道已关闭或服务暂不可用 | ✅ | 稍后重试；页面卸载后通道不可再用 |
120
+ | `APP_RATE_LIMITED` | 本应用此刻并发请求过多（单应用并发槽被占满） | ❌\* | 稍后重试；不要立刻循环重试 |
121
+ | `RESOURCE_EXHAUSTED` | 超出限制（并发 >8、分页/排序/大小上限、配额） | — | 对照 [限制](limits.md) 调整；配额类需清理数据 |
122
+ | `REQUEST_TOO_LARGE` | 请求体超过协商上限（默认 256 KiB） | ❌ | 拆分请求 |
123
+ | `IDEMPOTENCY_CONFLICT` | 同一请求编号被重复使用，或同一操作编号用于不同内容 | ❌ | 新请求用新编号；重试同一写入时内容必须完全相同 |
124
+ | `OPERATION_EXPIRED` | 操作编号超出首次使用窗口（300 秒）或回执已过期 | ❌ | 重新读取最新状态后，用新编号发起 |
125
+ | `PROTOCOL_MISMATCH` | SDK 与宿主协议不一致，或响应结构异常 | ❌ | 使用与当前 OS 匹配的 SDK 版本 |
126
+ | `BACKGROUND_CAPABILITY_UNAVAILABLE` | 宿主没有协商到 `app-execution/1`，`callFunction` / `capabilities.invoke` 无法执行 | ❌ | 先让使用者在应用窗口「权限」里勾选后台能力并保存；确认安装已绑定就绪发布、部署开放后台执行。旧 SDK 报的是 `UNSUPPORTED_OPERATION`，升级 SDK |
127
+ | `UNSUPPORTED_OPERATION` | 平台未实现或未协商的操作 | ❌ | 改实现，见 [未实现的 SDK 功能](limits.md#未实现的-sdk-功能) |
128
128
 
129
129
  \* `retryable` 为 `false`，但稍等后重试通常能成功；持续出现说明有长任务占满了并发。
130
130
 
131
131
  ### 初始化与授权
132
132
 
133
- | 错误码 | 含义 | 处理 |
134
- | ---------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
135
- | `INIT_REQUIRED` | 调用 `ready()` 前没有 `zl.cloud.init()` | 先初始化 |
136
- | `INIT_CONFLICT` | 同一页面用不同环境再次初始化 | 一个页面只绑定一个环境 |
137
- | `ENV_MISMATCH` | `env` 取值非法 | 只能是 `dev` / `prod`（或 `DYNAMIC_CURRENT_ENV`） |
138
- | `AUTH_REQUIRED` | 登录态或运行会话失效 | 重新打开应用 |
139
- | `SCOPE_FORBIDDEN` | 权限范围不允许（含未授权数据访问、生产文件存储未开放） | 见本页末尾「排查：`SCOPE_FORBIDDEN`」 |
140
- | `ENV_FORBIDDEN` | 应用要用的环境不存在或已停用 | 见下方「打开应用时的错误」 |
141
- | `PUBLISHER_REQUIRED` | 开发数据域只对开发团队开放（`appid` 应用成员 / 旧应用该版本上传者） | 请管理员在控制台「成员」里把你加为开发者；给其他人用需要发布为线上版本 |
142
- | `STALE_GENERATION` | 授权或数据绑定已换代（如重新授权、恢复备份） | 重新打开应用，建立新会话 |
143
- | `RULE_DENIED` | 集合记录规则拒绝了本次读/写 | 检查 `data.policies` 的 `read`/`write` 表达式与文档内容 |
144
- | `QUERY_NOT_AUTHORIZED` | 查询不在授权范围内（宿主白名单中的码，服务端来源**未验证**） | 检查查询条件与授权 |
133
+ | 错误码 | 含义 | 处理 |
134
+ | ---------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
135
+ | `INIT_REQUIRED` | 调用 `ready()` 前没有 `zl.cloud.init()` | 先初始化 |
136
+ | `INIT_CONFLICT` | 同一页面用不同环境再次初始化 | 一个页面只绑定一个环境 |
137
+ | `ENV_MISMATCH` | `env` 取值非法 | 只能是 `dev` / `prod`（或 `DYNAMIC_CURRENT_ENV`） |
138
+ | `AUTH_REQUIRED` | 登录态或运行会话失效 | 重新打开应用 |
139
+ | `SCOPE_FORBIDDEN` | 权限范围不允许（含未授权数据访问、生产文件存储未开放） | 见本页末尾「排查：`SCOPE_FORBIDDEN`」 |
140
+ | `ENV_FORBIDDEN` | 应用要用的环境不存在或已停用 | 见下方「打开应用时的错误」 |
141
+ | `PUBLISHER_REQUIRED` | 开发数据域只对应用成员开放 | 请管理员在控制台「成员」里把你加为开发者；给其他人用需要发布为线上版本 |
142
+ | `STALE_GENERATION` | 授权或数据绑定已换代（如重新授权、恢复备份） | 重新打开应用，建立新会话 |
143
+ | `RULE_DENIED` | 集合记录规则拒绝了本次读/写 | 检查 `data.policies` 的 `read`/`write` 表达式与文档内容 |
144
+ | `QUERY_NOT_AUTHORIZED` | 查询不在授权范围内（宿主白名单中的码，服务端来源**未验证**） | 检查查询条件与授权 |
145
145
 
146
146
  ### 数据
147
147
 
@@ -151,6 +151,7 @@
151
151
  | `VERSION_CONFLICT` | 乐观锁冲突，或键已存在等 409 类错误 | 重新读取最新版本再改 |
152
152
  | `DOCUMENT_NOT_FOUND` | 文档不存在（或 404 类错误） | 检查文档键；读取时可用 `throwOnNotFound: false` |
153
153
  | `COLLECTION_NOT_FOUND` | 集合不存在 | 在 Manifest `data.collections` 声明；生产环境要单独开通集合 |
154
+ | `SCOPE_FORBIDDEN` | 读写了 manifest **没声明**的集合（或没授权） | 先在 `data.collections` 声明再部署；已声明还报这个，看「权限」里是否勾了数据读写 |
154
155
  | `INDEX_REQUIRED` | 查询需要扫描的行数超过单次上限 | 给筛选字段建索引；已有索引仍超限时缩小筛选范围 |
155
156
  | `RESOURCE_NOT_READY` | 云数据库正在开通，或数据服务还没加载本应用 | 通常一分钟内自动就绪，稍后刷新重试 |
156
157
 
@@ -164,17 +165,17 @@
164
165
 
165
166
  ### 发布与后台调用
166
167
 
167
- | 错误码 | 含义 | 处理 |
168
- | ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
169
- | `FUNCTION_RELEASE_REQUIRED` | 当前安装还没有绑定就绪的签名发布 | `appid` 应用：正常不会出现；在应用窗口「权限」里重新保存一次，或在控制台「版本管理」切换一次版本，平台自动补签并绑定；仍出现说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传。旧 `app_key` 应用：到「版本与激活」完成「验证并签发」和「激活开发」 |
170
- | `RELEASE_UNAVAILABLE` | 发布代数已变化（激活了新版本），旧会话作废 | 宿主会自动重开会话并重试一次；仍失败时重新打开应用 |
171
- | `RELEASE_NOT_READY` | 发布候选尚未就绪 | 先完成签发 |
172
- | `RELEASE_DISABLED` | 发布候选已撤回 | 使用其他就绪候选 |
173
- | `RELEASE_ACTIVATION_UNAVAILABLE` | 目标环境不存在且无法自动创建 | 见 [发布与激活](#发布与激活) |
174
- | `RELEASE_ACTIVATION_TARGET_MISSING` | 激活目标与校验后的 Manifest 不一致（少见） | 见 [发布与激活](#发布与激活) |
175
- | `NODE_LOST` | 执行节点失联，**结果未确认**（作业状态 `unknown`） | 不要重复提交；用 `jobId` / `invocationId` 核对 |
176
- | `NODE_LOST_EXPIRED` | 节点失联且超过对账期限 | 到控制台运行记录核对是否已产生写入，再决定是否重新提交 |
177
- | `EXECUTION_FAILED` | `callFunction` 作业失败且没有更具体的错误码 | 到控制台运行记录或日志查看失败原因 |
168
+ | 错误码 | 含义 | 处理 |
169
+ | ----------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
+ | `FUNCTION_RELEASE_REQUIRED` | 当前安装还没有绑定就绪的签名发布 | 在应用窗口「权限」里允许后台运行（重新保存一次），或在控制台「版本管理」切换一次版本，平台自动补签并绑定；仍出现说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传 |
171
+ | `RELEASE_UNAVAILABLE` | 发布代数已变化（安装绑定了新版本），旧会话作废 | 宿主会自动重开会话并重试一次；仍失败时重新打开应用 |
172
+ | `RELEASE_NOT_READY` | 发布候选尚未就绪 | 重新发布，平台会重新签发 |
173
+ | `RELEASE_DISABLED` | 发布候选已撤回 | 重新上传并发布 |
174
+ | `RELEASE_ACTIVATION_UNAVAILABLE` | 目标环境不存在且无法自动创建 | 通常是部署未开放对应环境；请联系平台管理员 |
175
+ | `RELEASE_ACTIVATION_TARGET_MISSING` | 激活目标与校验后的 Manifest 不一致（少见） | 重新上传并安装该版本 |
176
+ | `NODE_LOST` | 执行节点失联，**结果未确认**（作业状态 `unknown`） | 不要重复提交；用 `jobId` / `invocationId` 核对 |
177
+ | `NODE_LOST_EXPIRED` | 节点失联且超过对账期限 | 到控制台运行记录核对是否已产生写入，再决定是否重新提交 |
178
+ | `EXECUTION_FAILED` | `callFunction` 作业失败且没有更具体的错误码 | 到控制台运行记录或日志查看失败原因 |
178
179
 
179
180
  `callFunction` 失败时，`errCode` 优先使用作业结果里的 `errorCode`；作业状态为 `unknown` 时抛 `COMMIT_UNKNOWN`，
180
181
  仍在排队/执行时抛 `CALL_TIMEOUT`（都带 `jobId`，可用 `jobs.wait` 继续等）。`capabilities.invoke` 不抛错，
@@ -205,10 +206,10 @@
205
206
 
206
207
  | 原因码 | message | next_action / 处理 |
207
208
  | --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
208
- | `ENV_FORBIDDEN`（环境不存在） | 环境不可访问 | 「该应用还没有开通生产环境：先在应用页把版本激活到生产，再用生产数据」 |
209
+ | `ENV_FORBIDDEN`（环境不存在） | 环境不可访问 | 「该应用还没有开通生产环境：发布为线上版本时会自动准备生产环境，稍后重试」 |
209
210
  | `ENV_FORBIDDEN`（环境已停用） | 环境不可访问 | 「该环境的记录已被停用，请回应用页重新加载，或在「数据权限」里重新保存一次授权」 |
210
211
  | `ENV_FORBIDDEN`（部署未开放生产） | 生产 Cloud 运行能力尚未开放 / 本部署未开放生产环境 | 部署未开放生产时只能用开发环境 |
211
- | `PUBLISHER_REQUIRED` | 环境不可访问 | 非发布者打开只有开发环境的应用；上线到生产后才能给其他人用 |
212
+ | `PUBLISHER_REQUIRED` | 环境不可访问 | 非应用成员打开只有开发环境的应用；发布为线上版本后才能给其他人用 |
212
213
  | `CONSENT_REQUIRED` | 请先由宿主用户明确授权数据访问 | 在应用窗口「权限」里勾选后保存（应用里表现为 `SCOPE_FORBIDDEN`） |
213
214
  | `STORAGE_PROD_UNAVAILABLE` | 生产文件存储尚未开放 | 部署未开放生产文件存储（应用里表现为 `SCOPE_FORBIDDEN`） |
214
215
  | `RESOURCE_NOT_READY` | 基础服务未就绪 | 环境的云资源还没接上，稍后重新打开 |
@@ -289,39 +290,30 @@
289
290
 
290
291
  上传同一路径的文件时，没有 `overwrite` + `expectedETag` 就会得到 `VERSION_CONFLICT`。
291
292
 
292
- ## 发布与激活
293
-
294
- 激活冲突统一为 40900「发布激活未完成」，`data` 里同时带 `reason` 和 `next_action`：
295
-
296
- | 原因码 | next_action |
297
- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
298
- | `RELEASE_NOT_READY` | 这个发布版本还没就绪：先签发并等校验完成 |
299
- | `RELEASE_PROOF_UNAVAILABLE` | 这个发布版本缺少可验证的签名证明：重新签发它 |
300
- | `RELEASE_POLICY_STALE` | 发布版本记录的是旧策略：重新签发让它绑定当前策略 |
301
- | `RELEASE_TRUST_UNAVAILABLE` | 这个发布版本的签名与当前信任策略对不上：重新签发它，或让管理员按当前策略重新审批 |
302
- | `RELEASE_APPROVAL_EXPIRED_OR_MISSING` | 这个发布版本没有有效的生产审批：让管理员在发布审核里批准后再激活到生产 |
303
- | `PRODUCTION_RELEASE_UNAVAILABLE` | 本部署没有可用的生产签发方：先配好生产签发密钥，或改用开发环境 |
304
- | `RELEASE_VERSION_SWITCH_UNAVAILABLE` | 安装的版本与这个发布版本不一致：先把安装升级到该版本再激活 |
305
- | `ACTIVATION_EPOCH_STALE` | 安装的授权状态已经变化：刷新页面后重新点激活 |
306
- | `ACTIVATION_EPOCH_REQUIRED` | 该安装已绑定过发布版本：带上当前授权代数再激活（刷新页面会自动带上） |
307
- | `ACTIVATION_REQUEST_REQUIRED` | 缺少 request_id：重新点一次激活会生成新的 request_id |
308
- | `RELEASE_STATE_CHANGED` | 发布状态在激活过程中变了：刷新页面后重试 |
309
- | `ROLLBACK_TARGET_UNAVAILABLE` | 当前并没有绑定到要回滚的版本：刷新页面后重试 |
310
- | `IDEMPOTENCY_CONFLICT` | 这个 request_id 已经用于另一次请求：重试会生成新的 request_id |
311
- | `RELEASE_ACTIVATION_UNAVAILABLE` | 该应用还没有这个环境：先在「数据权限」里选择这个环境再激活 |
312
- | `RELEASE_ACTIVATION_TARGET_MISSING` | （见下方说明） |
313
- | `RELEASE_DISABLED`、`RELEASE_ACTIVATION_SCOPE_REQUIRED`、`RELEASE_ARTIFACT_MISMATCH`、`FUNCTION_RUNTIME_SNAPSHOT_REQUIRED` | 无（按原因码处理） |
293
+ ## 发布与生产门禁
294
+
295
+ 第一次发布带云资源的版本时，平台自动完成**应用级**生产准备：生产环境 → 签发生产发布（归属上传者）→ 生产门禁 → 生产库与生产集合，
296
+ 不依赖任何人的安装。生产门禁不通过时统一返回 40900，`data` 里同时带 `reason` 和 `next_action`：
297
+
298
+ | 原因码 | next_action |
299
+ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
300
+ | `RELEASE_NOT_READY` | 这个发布版本还没就绪：重新发布，平台会重新签发 |
301
+ | `RELEASE_PROOF_UNAVAILABLE` | 这个发布版本缺少可验证的签名证明：重新发布会重新签发 |
302
+ | `RELEASE_POLICY_STALE` | 发布版本记录的是旧策略：重新发布会按当前策略重新签发 |
303
+ | `RELEASE_TRUST_UNAVAILABLE` | 签名与当前信任策略对不上：重新发布，或让管理员检查发布信任配置 |
304
+ | `RELEASE_APPROVAL_EXPIRED_OR_MISSING` | 这个发布版本没有有效的生产审批：重新发布会重新签发 |
305
+ | `PRODUCTION_RELEASE_UNAVAILABLE` | 本部署没有可用的生产签发方：先配好生产签发密钥，或改用开发环境 |
306
+ | `RELEASE_DISABLED`、`RELEASE_ARTIFACT_MISMATCH`、`FUNCTION_RUNTIME_SNAPSHOT_REQUIRED` | 无（按原因码处理）；重新上传或重新发布 |
314
307
 
315
308
  需要知道的变化：
316
309
 
317
- - **激活不再要求先允许后台能力**；**目标环境不存在时激活会自动创建它**（含数据库开通请求）。
318
- 所以 `RELEASE_ACTIVATION_UNAVAILABLE` 只在自动创建也失败时出现；生产环境未开放时自动创建返回 40300「本部署未开放生产环境」。
319
- - `RELEASE_ACTIVATION_TARGET_MISSING` 现在只在「已缓存的 Manifest 判定为纯前端、校验后的 Manifest 却不是」这种少见情况出现。
320
- 它的提示文字仍写着「先勾选后台能力」，这句已过时：遇到时重新上传并安装该版本即可。
321
- - 安装从未绑定过发布时，首次激活可以不带 `expected_activation_epoch`。
322
- - 生产不可用有两种返回：激活接口的 40300（`message` 为 `PRODUCTION_RELEASE_UNAVAILABLE`，`reason` 为
310
+ - 生产门禁由平台自动检查（签名证明、审批窗口、策略版本、信任根、函数运行快照、生产签发方），
311
+ 所有步骤自动完成；不通过时按上表给出原因，**重新发布会重新签发**。
312
+ - 已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布，不会重新跑一遍生产准备。
313
+ - 生产不可用有两种返回：发布接口的 40300（`message` 为 `PRODUCTION_RELEASE_UNAVAILABLE`，`reason` 为
323
314
  `DEPLOYMENT_NOT_PRODUCTION` / `PRODUCTION_RELEASE_UNAVAILABLE` / `RELEASE_TRUST_UNAVAILABLE`，不带 `next_action`），
324
315
  以及生产门禁的 40900（带上表的 `next_action`）。前者是部署没开放生产，不是你写错了。
316
+ - 发布本身的其他失败（生产库未就绪、上传者账号已停用）见 [发布为线上版本](#发布为线上版本)。
325
317
 
326
318
  ## 后台调用与云函数
327
319
 
@@ -406,25 +398,23 @@
406
398
 
407
399
  `zleap-app prepare` 的特殊结果：
408
400
 
409
- - **平台 `appid` 应用**通常不需要 `prepare`（上传自动签名、安装 / 切换版本时自动绑定），只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用。
401
+ - 通常不需要 `prepare`（上传时自动签名、安装 / 切换版本时自动绑定），只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用。
410
402
  它只准备开发环境：只声明数据的应用在开发权限阶段后结束，`status` 为 **`ready`**，响应里 `"environment": "dev"`；
411
- Manifest 声明了 headless 后台能力时，还会创建发布候选、签名并激活到开发。
412
- - **旧 `app_key` 应用**没有声明云资源（无 `cloud.*` 权限、无后台能力、无集合）时直接返回 `status` 为 **`not_required`**，
413
- `next` 提示「应用未声明云资源或后台执行，安装后即可运行」。
403
+ Manifest 声明了 headless 后台能力时，还会创建发布候选、签名并绑定到开发环境。
414
404
  - 某个阶段失败时，`data` 里带 `stage`（失败的阶段）、`completed_stages`（已完成的阶段）、`cause.reason`（原因码）、
415
405
  `next`（「用app_diagnose核对当前状态；不自动重试准备写操作」），内层错误有 `next_action` 时也一并带上。
416
406
  用**同一个** `--request-id` 重试会从失败的阶段继续。
417
407
  - 其他失败：42200「version_id和32位小写十六进制request_id必填」、40900「请先安装指定版本」、
418
- 40300「只能准备本人private应用」（旧应用）、40300「只能准备本人上传的版本」（`appid` 应用传了别人上传的 `version_id`）、
408
+ 40300「只能准备本人上传的版本」（传了别人上传的 `version_id`）、
419
409
  42200「应用执行或共享调度未启用，需要平台管理员完成部署」、40900「准备结果未确认，请先诊断」。不传 `--request-id` 时命令行会自动生成。
420
410
 
421
411
  > **`prepare` 支持哪些版本**（说明）
422
412
  >
423
413
  >
424
- > - **平台 `appid` 应用**：接受**本人上传**的版本（可见性 `private` 或 `members`），只准备开发环境
425
- > （开发环境 → 数据库 → 开发数据域权限，声明了 headless 时再加签名并激活到开发），不会碰生产；
426
- > 生产由**首次 `release`（发布为线上版本）**自动准备。appid 应用通常不需要它，只在 `diagnose` 提示 `next_action: app_prepare` 时兜底使用。
427
- > - **旧 `app_key` 应用**：只接受**本人 private、且已安装**的包，一路准备到生产。
414
+ > 只接受**本人上传**的版本（可见性 `members`），只准备开发环境
415
+ > （开发环境 → 数据库 → 开发数据域权限，声明了 headless 时再加签名并绑定到开发环境），不会碰生产；
416
+ > 生产由**首次发布为线上版本**自动准备。因为自动签名与绑定，通常不需要它，只在 `diagnose` 提示 `next_action: app_prepare` 时兜底使用。
417
+ >
428
418
 
429
419
  `zleap-app publish` 等写操作网络结果不明时返回 `COMMIT_UNKNOWN`，**不会自动重传**：
430
420
  用 `zleap-app operation --request-id <原操作号>` 或 `zleap-app status` 查询原结果。
@@ -433,28 +423,24 @@
433
423
 
434
424
  上传、`zleap-app check` 或安装时，Manifest 相关失败通过 `detail.reason` 返回：
435
425
 
436
- | 原因 | 含义 | 处理 |
437
- | ----------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
438
- | `MANIFEST_UNSUPPORTED` | `schema` 不是 `zleap.app/2`、结构/引用/执行形态无效，或 `appid` 与 `app_key` 不一致 | 对照 [Manifest](manifest.md) 逐字段核对 |
439
- | `SCHEMA_INVALID` | 集合 Schema 不符合数据面契约（`detail.collection` 指出集合） | 只用集合 Schema 子集 |
440
- | `RULE_DENIED` | 集合记录规则表达式无效 | 修正表达式 |
441
- | `RULE_FIELD_UNDECLARED` | 记录规则引用了 Schema 未声明的字段 | 在 Schema 顶层声明该字段 |
442
- | `RUNTIME_UNAVAILABLE` | 运行环境未开放（`builtin` UI、纯后台带函数等） | 见 [不可安装的配置](limits.md#已知会导致「应用不可安装」的配置) |
443
- | `FEATURE_UNAVAILABLE` | 声明了未开放的能力或写法 | 同上 |
426
+ | 原因 | 含义 | 处理 |
427
+ | ----------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
428
+ | `MANIFEST_UNSUPPORTED` | `schema` 不是 `zleap.app/2`、结构/引用/执行形态无效 | 对照 [Manifest](manifest.md) 逐字段核对 |
429
+ | `SCHEMA_INVALID` | 集合 Schema 不符合数据面契约（`detail.collection` 指出集合） | 只用集合 Schema 子集 |
430
+ | `RULE_DENIED` | 集合记录规则表达式无效 | 修正表达式 |
431
+ | `RULE_FIELD_UNDECLARED` | 记录规则引用了 Schema 未声明的字段 | 在 Schema 顶层声明该字段 |
432
+ | `RUNTIME_UNAVAILABLE` | 运行环境未开放（`builtin` UI、纯后台带函数等） | 见 [不可安装的配置](limits.md#已知会导致「应用不可安装」的配置) |
433
+ | `FEATURE_UNAVAILABLE` | 声明了未开放的能力或写法 | 同上 |
444
434
 
445
435
  常见的上传失败文案（没有原因码，直接看提示）：
446
436
 
447
- | 提示 | 原因 |
448
- | ----------------------------------------------------- | ----------------------------------------------------------------- |
449
- | 应用包根目录必须包含非空 LICENSE 文件 | 缺少 `LICENSE` 或内容为空 |
450
- | manifest entry 必须指向存在的包内 HTML 文件 | `entry` 不是包内 `.html`/`.htm`，或文件不存在 |
451
- | manifest 的 appid 与 app_key 不一致 | 同时写了 `appid` 和 `app_key` 且两者不同（42200），只保留 `appid` |
452
- | manifest app_key 必须使用包含发布者前缀的小写命名空间 | 应用标识既不是平台 `appid`，也不符合旧 `app_key` 命名空间规则 |
453
- | 发布者声明不属于当前登录用户 | 仅旧 `app_key` 应用：`publisher.publisher_id` 不是上传者本人 |
454
- | 不能覆盖其他发布者的应用标识 | 仅旧 `app_key` 应用：`app_key` 已被别人使用 |
455
- | 该版本已经存在，请更换版本号 | 同版本号、内容不同 |
456
- | 云函数制品入口缺失 | 函数 `entry` 在包里不存在 |
457
- | 应用包不在开发会话授权范围 | 包里的 `appid` 与 `zleap-app auth login` 时不一致 |
437
+ | 提示 | 原因 |
438
+ | ------------------------------------------- | ------------------------------------------------- |
439
+ | 应用包根目录必须包含非空 LICENSE 文件 | 缺少 `LICENSE` 或内容为空 |
440
+ | manifest entry 必须指向存在的包内 HTML 文件 | `entry` 不是包内 `.html`/`.htm`，或文件不存在 |
441
+ | 该版本已经存在，请更换版本号 | 同版本号、内容不同 |
442
+ | 云函数制品入口缺失 | 函数 `entry` 在包里不存在 |
443
+ | 应用包不在开发会话授权范围 | 包里的 `appid` 与 `zleap-app auth login` 时不一致 |
458
444
 
459
445
  ### 应用与成员
460
446
 
@@ -469,26 +455,21 @@
469
455
 
470
456
  成员管理见 [成员管理](console-members.md)。
471
457
 
472
- ### 发布为线上版本与目录可见性
458
+ ### 发布为线上版本
473
459
 
474
- 控制台「版本管理」发布 / 回退（`POST /api/v1/app-cloud/apps/{app_id}/publish`），以及应用中心「发布到企业目录 / 撤回企业目录」：
460
+ 控制台「版本管理」发布 / 回退（`POST /api/v1/app-cloud/apps/{app_id}/publish`）：
475
461
 
476
- | 业务码 | message | `detail.reason` | 处理（`next_action`） |
477
- | ------ | -------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
478
- | 40900 | 生产数据库还没就绪，暂时不能发布 | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪，稍后在版本管理里重新发布；持续失败请在控制台「数据库」查看状态 |
479
- | 40900 | 这个版本的上传者账号已停用，无法发布 | `UPLOADER_INACTIVE` | 请其他成员重新上传这个版本（npm run deploy）后再发布 |
480
- | 40900 | 这个应用请在云开发控制台「版本管理」里发布或回退 | `USE_VERSION_MANAGEMENT` | 应用中心不能改平台 `appid` 应用的线上版本；到控制台「发布 → 版本管理」点「发布为线上版本」或「回退到此版本」 |
481
- | 40900 | 该应用使用旧的命名空间标识，请在「版本与激活」里管理版本 | `LEGACY_APP` | 旧 `app_key` 应用走「版本与激活」 |
482
- | 40400 | 版本不存在或已删除 / 该版本没有可用制品 | — | 刷新版本列表后重试 |
483
- | 42200 | 发布说明最多 500 字 | — | 缩短发布说明 |
484
- | 40400 | 应用不存在，或你不是这个应用的成员 | — | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
485
-
486
- `USE_VERSION_MANAGEMENT` 来自应用中心的「发布到企业目录 / 撤回企业目录」接口，不是版本管理接口本身的错误；
487
- 它表示**这个应用不该在应用中心改线上状态**。平台 `appid` 应用请改用控制台「版本管理」。
462
+ | 业务码 | message | `detail.reason` | 处理（`next_action`） |
463
+ | ------ | --------------------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
464
+ | 40900 | 生产数据库还没就绪，暂时不能发布 | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪，稍后在版本管理里重新发布；持续失败请在控制台「数据库」查看状态 |
465
+ | 40900 | 这个版本的上传者账号已停用，无法发布 | `UPLOADER_INACTIVE` | 请其他成员重新上传这个版本（npm run deploy）后再发布 |
466
+ | 40400 | 版本不存在或已删除 / 该版本没有可用制品 | — | 刷新版本列表后重试 |
467
+ | 42200 | 发布说明最多 500 字 | — | 缩短发布说明 |
468
+ | 40400 | 应用不存在，或你不是这个应用的成员 | — | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
488
469
 
489
470
  任一成员都可以发布任一版本，不要求上传者正在使用这个版本。带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本**第一次**发布时，
490
471
  平台自动完成应用级生产准备（生产环境 → 签发生产发布 → 生产门禁 → 生产库与生产集合），`PROD_DATABASE_NOT_READY`、`UPLOADER_INACTIVE` 只在这一步出现；
491
- 生产门禁不通过时返回与激活相同的原因码（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`，见 [发布与激活](#发布与激活)），重新发布即会重新签发。
472
+ 生产门禁不通过时返回 [发布与生产门禁](#发布与生产门禁) 表中的原因码（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`），重新发布即会重新签发。
492
473
  已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。见 版本管理 · 带云资源的版本（文档站 /console/release#带云资源的版本）。
493
474
 
494
475
  ## 版本更新与回滚
@@ -497,12 +478,12 @@
497
478
 
498
479
  这些码来自安装版本切换接口（`appversion/read.go`、`official.go`、`apply.go`）：
499
480
 
500
- | 业务码 | message | `detail.reason` | 处理 |
501
- | ------ | -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
502
- | 42200 | 应用没有可切换的版本 | `VERSION_LIST_EMPTY` | 该应用还没有任何有效版本，或你的账号看不到任何版本；先在控制台的版本页确认已有上传（`appid`：版本管理；旧应用：版本与激活），再刷新 |
503
- | 42200 | 官方版本切换必须指定当前安装版本 | `EXPECTED_VERSION_REQUIRED` | 请求里带上当前安装的版本 ID（CLI 用 `--expected-version-id`），不要省略 |
504
- | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_STALE` | 你带来的「当前版本」与安装记录不一致；重新读取安装状态后，用最新的版本 ID 再操作 |
505
- | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_CHANGED` | 提交期间安装被其他操作改掉了；刷新后重新读取，再决定是否重试 |
481
+ | 业务码 | message | `detail.reason` | 处理 |
482
+ | ------ | -------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
483
+ | 42200 | 应用没有可切换的版本 | `VERSION_LIST_EMPTY` | 该应用还没有任何有效版本，或你的账号看不到任何版本；先在控制台「版本管理」确认已有上传，再刷新 |
484
+ | 42200 | 官方版本切换必须指定当前安装版本 | `EXPECTED_VERSION_REQUIRED` | 请求里带上当前安装的版本 ID（CLI 用 `--expected-version-id`），不要省略 |
485
+ | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_STALE` | 你带来的「当前版本」与安装记录不一致；重新读取安装状态后，用最新的版本 ID 再操作 |
486
+ | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_CHANGED` | 提交期间安装被其他操作改掉了；刷新后重新读取，再决定是否重试 |
506
487
 
507
488
  `INSTALLATION_VERSION_STALE` 在写入前检查就失败；`INSTALLATION_VERSION_CHANGED` 是写入时的并发校验失败（CAS 没命中）。
508
489
  两者都**不要用旧的版本 ID 盲目重试**，先 `zleap-app diagnose` 或在控制台刷新安装状态。
@@ -538,26 +519,26 @@
538
519
  >
539
520
  > 这个码由 CLI/MCP 的版本切换接口返回。应用中心的「更新」走上面的预检流程，Schema 变化只是提醒，分区变化才阻断。
540
521
 
541
- ## 签名证明验证
522
+ ## 发布签名
542
523
 
543
- 在控制台版本页（`appid` 应用是「版本管理」，旧 `app_key` 应用是「版本与激活」）验证签名证明时，失败按原因码归类显示：
524
+ 平台在上传带后台能力的版本时自动签发开发发布，首次发布为线上版本时自动签发生产发布。
525
+ 签发或验签失败时按原因码归类返回：
544
526
 
545
- | 服务端原因码 | 界面文案 |
546
- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
547
- | `RELEASE_PROOF_TOO_LARGE`（或本地检查文件 > 2 MiB） | 证明文件超过 2 MiB 限制。 |
548
- | `RELEASE_PROOF_INVALID` | 证明 JSON 或签名信封无效。 |
549
- | `RELEASE_IDENTITY_MISMATCH`、`RELEASE_DIGEST_MISMATCH`、`RELEASE_SOURCE_MISMATCH` | 证明与当前应用、发布、包、来源、摘要或策略不匹配。 |
550
- | `RELEASE_SIGNATURE_INVALID` | 无法验证发布签名。 |
551
- | `RELEASE_ARTIFACT_MISMATCH`、`RELEASE_MANIFEST_MISMATCH` | 签名 Manifest 或包制品清单不匹配。 |
552
- | `RELEASE_POLICY_STALE` | 策略审核已过期或不再当前。 |
553
- | `RELEASE_POLICY_UNAVAILABLE` | 尚未配置发布策略，无法验证。 |
554
- | `RELEASE_TRUST_UNAVAILABLE` | 发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期。请由管理员检查配置后重试。 |
555
- | `RELEASE_DISABLED` | 此发布候选已撤回。 |
556
- | 其他 | 签名证明验证请求被拒绝。 |
557
- | 网络结果不明 | 结果未确认，已保留原发布与签名证明。请查询原结果，确认前不会重复提交。 |
527
+ | 服务端原因码 | 含义 |
528
+ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
529
+ | `RELEASE_PROOF_TOO_LARGE` | 证明文件超过 2 MiB 限制 |
530
+ | `RELEASE_PROOF_INVALID` | 证明 JSON 或签名信封无效 |
531
+ | `RELEASE_IDENTITY_MISMATCH`、`RELEASE_DIGEST_MISMATCH`、`RELEASE_SOURCE_MISMATCH` | 证明与当前应用、发布、包、来源、摘要或策略不匹配 |
532
+ | `RELEASE_SIGNATURE_INVALID` | 无法验证发布签名 |
533
+ | `RELEASE_ARTIFACT_MISMATCH`、`RELEASE_MANIFEST_MISMATCH` | 签名 Manifest 或包制品清单不匹配 |
534
+ | `RELEASE_POLICY_STALE` | 策略审核已过期或不是当前策略 |
535
+ | `RELEASE_POLICY_UNAVAILABLE` | 尚未配置发布策略，无法验证 |
536
+ | `RELEASE_TRUST_UNAVAILABLE` | 发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期；由管理员检查 |
537
+ | `RELEASE_DISABLED` | 发布候选已撤回 |
538
+ | 其他 | 签名验证请求被拒绝 |
558
539
 
559
- 验证签名时的 `RELEASE_POLICY_UNAVAILABLE`、`RELEASE_TRUST_UNAVAILABLE` 属于**部署未配置**；
560
- 激活到生产时的 `RELEASE_TRUST_UNAVAILABLE` 则表示这个发布的签名与当前信任策略对不上，重新签发即可（见 [发布与激活](#发布与激活)）。
540
+ 签发时的 `RELEASE_POLICY_UNAVAILABLE`、`RELEASE_TRUST_UNAVAILABLE` 属于**部署未配置**；
541
+ 发布生产版本时的 `RELEASE_TRUST_UNAVAILABLE` 则表示这个发布的签名与当前信任策略对不上，重新发布即可（见 [发布与生产门禁](#发布与生产门禁)）。
561
542
 
562
543
  ## 触发器与事件
563
544
 
@@ -603,8 +584,6 @@
603
584
  | 日志库未开通导致云函数执行失败（`LOG_UNAVAILABLE` / `TELEMETRY_ALLOCATION_UNAVAILABLE`） | 云函数照常执行，只是暂时查不到日志 |
604
585
  | 写入时偶发 `DATA_SERVICE_UNAVAILABLE`（数据绑定缺少身份记录） | 平台自动补建，不再报错 |
605
586
  | 数据库已存在但数据服务尚未加载时 `RESOURCE_NOT_READY` | 按专属库是否存在判定，已开通的库直接可用 |
606
- | 激活要求「至少允许一项后台能力」（`RELEASE_ACTIVATION_TARGET_MISSING`） | 激活不再要求后台能力 |
607
- | 激活到不存在的环境（`RELEASE_ACTIVATION_UNAVAILABLE`） | 激活时自动创建环境 |
608
587
 
609
588
  ## 状态值
610
589
 
@@ -623,6 +602,8 @@
623
602
 
624
603
  ### 发布候选
625
604
 
605
+ 发布候选由平台自动创建和签名，不需要手动操作。
606
+
626
607
  | 状态 | 控制台文案 |
627
608
  | ------------ | ---------- |
628
609
  | `draft` | 草稿 |
@@ -630,7 +611,7 @@
630
611
  | `ready` | 已就绪 |
631
612
  | `disabled` | 已撤回 |
632
613
 
633
- 只有「已就绪」的候选可以激活。生产门禁评估结论：`eligible`「等待 Provider 复核」、
614
+ 只有「已就绪」的候选可以用于发布。生产门禁评估结论：`eligible`「等待 Provider 复核」、
634
615
  `blocked`「已阻断」、`invalid`「不可用」。
635
616
 
636
617
  ### 后台作业
package/skills/zleap-cloud-app/references/triggers.md CHANGED
@@ -116,7 +116,7 @@
116
116
  1. 触发器指向的**后台能力已启用**：在应用窗口「权限」的「后台能力（定时任务 / 云函数）」里勾选，
117
117
  或在 后台能力面板（文档站 /console/functions#后台能力） 点「允许后台运行」（安装时后台能力一律是停用）；
118
118
  2. 如果该能力的 provider 是云函数（`managed_function`），当前安装还要绑定**就绪**的签名发布，否则执行时报 `FUNCTION_RELEASE_REQUIRED`。
119
- appid 应用由平台在上传时自动签名、安装 / 切换版本 / 授权时自动绑定，不需要手动操作；旧 `app_key` 应用要在版本与激活（文档站 /console/legacy-release#激活开发）完成「激活开发」；
119
+ 平台在上传时自动签名、安装 / 切换版本 / 授权时自动绑定，不需要手动操作；
120
120
  3. Manifest 里**确实声明了**这个触发器；
121
121
  4. `background.modes` 包含对应模式。
122
122
 
@@ -378,7 +378,7 @@
378
378
 
379
379
  ### 报 `TRIGGER_MODE_NOT_DECLARED`
380
380
 
381
- `background.modes` 里没有 `"scheduled"`（或 `"events"`）。补上后上传新版本、把安装更新到该版本（appid 应用切换时平台自动绑定新版本的就绪发布；旧 `app_key` 应用云函数类能力还要重新「激活开发」）。
381
+ `background.modes` 里没有 `"scheduled"`（或 `"events"`）。补上后上传新版本、把安装更新到该版本（切换时平台自动绑定新版本的就绪发布）。
382
382
 
383
383
  ### 报 `TRIGGER_NOT_DECLARED`
384
384
 
@@ -387,7 +387,7 @@ Manifest 里找不到这个触发器 ID、ID 重复，或它的 `capability` 指
387
387
  ### 报 `TRIGGER_SCHEDULE_MISMATCH`
388
388
 
389
389
  提交的 cron 和 Manifest 里写的**不完全一致**。控制台的 cron 直接取自声明，正常情况下不会出现；
390
- 如果出现，确认当前安装的就是你修改并签名后的那个版本。
390
+ 如果出现，确认当前安装的就是你修改后上传的那个版本。
391
391
 
392
392
  ### 报 `TRIGGER_TIMEZONE_MISMATCH`
393
393
 
@@ -400,7 +400,7 @@ Manifest 里找不到这个触发器 ID、ID 重复，或它的 `capability` 指
400
400
 
401
401
  1. 后台能力是「已允许后台运行」吗？显示「授权给的是之前安装的版本」时触发器会暂停，需要重新授权。
402
402
  切换版本后：应用中心「更新」只会让**权限变宽**的能力需要重新确认；CLI `zleap-app update` / `rollback` 会**停用全部**后台能力；
403
- 2. 云函数类能力：当前安装绑定了就绪发布吗？运行记录里出现 `FUNCTION_RELEASE_REQUIRED` 时，appid 应用在应用窗口「权限」里重新保存一次或在「版本管理」切换一次版本（平台自动补签并绑定），旧 `app_key` 应用到「版本与激活」完成「激活开发」；
403
+ 2. 云函数类能力：当前安装绑定了就绪发布吗？运行记录里出现 `FUNCTION_RELEASE_REQUIRED` 时，在应用窗口「权限」里允许后台运行（重新保存一次），或在「版本管理」切换一次版本，平台自动补签并绑定；
404
404
  3. 「接下来」的时间是不是还没到？
405
405
  4. 数据库是否正在冻结（备份/恢复中）？
406
406
  5. 看卡片的「最近投递」，再到 日志（文档站 /console/logs） 按调用编号查有没有执行记录。