create-zleap-app 0.10.2 → 0.10.4

package/skills/zleap-cloud-app-release/references/permissions.md

@@ -196,7 +196,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
 > 授权后，本应用可在关窗后按你勾选的能力运行（如定时巡检），只作用于你本人的数据，其他使用者看不到。
 
 - 授权限定在**这个安装 + 这个版本 + 这个环境**；每一步执行前都会重新检查；
-- `managed_function`（云函数）还要求绑定**就绪并已激活**的发布，否则提示「该版本尚未激活发布版本，暂时无法执行。请到「发布版本」页完成「激活开发」。」，调用返回 `FUNCTION_RELEASE_REQUIRED`。appid 应用到控制台「版本管理」页下方的「开发环境：云函数激活」完成这一步；
+- `managed_function`（云函数）还要求绑定**就绪**的签名发布，否则该项下方提示「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签；旧应用请到云开发控制台「版本与激活」完成「激活开发」。」，调用返回 `FUNCTION_RELEASE_REQUIRED`。appid 应用由平台在上传时自动签名、在这里保存（或允许 / 撤销后台运行）时自动绑定，缺签时当场补签，正常不会看到这条提示；旧 `app_key` 应用到控制台「版本与激活」完成「验证并签发」和「激活开发」；
 - `logic_unit` / `builtin` provider 不需要发布；
 - `os.agent.complete` 等内置动作同样是一项后台能力，要在这里启用后才能调用。
 
@@ -340,7 +340,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
 | 云函数访问不到字段                                   | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？                            |
 | 用户之间看不到彼此数据                               | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"`               |
 | 前端调用后台能力 `BACKGROUND_CAPABILITY_UNAVAILABLE` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载（旧 SDK 报 `UNSUPPORTED_OPERATION`）                 |
-| 云函数 `FUNCTION_RELEASE_REQUIRED`                   | 到「版本管理」页下方「开发环境：云函数激活」（或概览的「去签名」）完成签发与「激活开发」                          |
+| 云函数 `FUNCTION_RELEASE_REQUIRED`                   | appid 应用：在应用窗口「权限」里重新保存一次，或在「版本管理」切换一次版本，平台自动补签并绑定；仍出现请联系平台管理员检查签名密钥 / 信任配置，或重新上传。旧应用：到「版本与激活」完成「验证并签发」与「激活开发」 |
 | 更新版本后后台任务不跑了                             | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力                                           |
 | 跨应用调用失败                                       | 普通 SDK 不支持跨应用调用                                                                                         |
 

package/skills/zleap-cloud-app-release/references/status-codes.md

@@ -12,7 +12,7 @@
 | **权限类**     | `SCOPE_FORBIDDEN`、`RULE_DENIED`、`ENV_FORBIDDEN`      | 去授权或改规则，不要盲目重试         |
 | **数据类**     | `SCHEMA_INVALID`、`VERSION_CONFLICT`、`INDEX_REQUIRED` | 改代码、改数据或建索引               |
 | **结果未知**   | `COMMIT_UNKNOWN`、`NODE_LOST`                          | **用原操作编号查询**，不要换编号重试 |
-| **未就绪**     | `RESOURCE_NOT_READY`、`FUNCTION_RELEASE_REQUIRED`      | 等开通完成 / 签发并激活后再试        |
+| **未就绪**     | `RESOURCE_NOT_READY`、`FUNCTION_RELEASE_REQUIRED`      | 等开通完成 / 发布就绪并绑定后再试    |
 | **繁忙或超限** | `APP_RATE_LIMITED`、`RESOURCE_EXHAUSTED`               | 稍后重试，或按提示清理数据、调整用法 |
 | **临时故障**   | `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE`                  | 可以重试                             |
 | **平台未开放** | `UNSUPPORTED_OPERATION`、`FEATURE_UNAVAILABLE`         | 改实现，重试无用                     |
@@ -166,7 +166,7 @@
 
 | 错误码                              | 含义                                               | 处理                                                                      |
 | ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
-| `FUNCTION_RELEASE_REQUIRED`         | 当前安装还没有绑定已签发并激活的发布               | 在控制台版本页签发并激活（`appid` 应用：版本管理 → 开发环境：云函数激活） |
+| `FUNCTION_RELEASE_REQUIRED`         | 当前安装还没有绑定就绪的签名发布                   | `appid` 应用：正常不会出现；在应用窗口「权限」里重新保存一次，或在控制台「版本管理」切换一次版本，平台自动补签并绑定；仍出现说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传。旧 `app_key` 应用：到「版本与激活」完成「验证并签发」和「激活开发」 |
 | `RELEASE_UNAVAILABLE`               | 发布代数已变化（激活了新版本），旧会话作废         | 宿主会自动重开会话并重试一次；仍失败时重新打开应用                        |
 | `RELEASE_NOT_READY`                 | 发布候选尚未就绪                                   | 先完成签发                                                                |
 | `RELEASE_DISABLED`                  | 发布候选已撤回                                     | 使用其他就绪候选                                                          |
@@ -331,7 +331,7 @@
 | ------------------------------------ | --------------------------------------- | ---------------------------------------- |
 | 50390                                | 应用执行worker尚未启用                  | 部署未开放后台执行，联系管理员           |
 | 50390 `FUNCTION_RUNTIME_UNAVAILABLE` | 应用执行需要共享调度服务                | 同上                                     |
-| 40300 `FUNCTION_RELEASE_REQUIRED`    | 云函数必须绑定已验证发布                | 签发并激活                               |
+| 40300 `FUNCTION_RELEASE_REQUIRED`    | 云函数必须绑定已验证发布                | 见 [发布与后台调用](#发布与后台调用)     |
 | 40900（无原因码）                    | 同一操作编号的输入不同                  | 新调用用新的操作编号                     |
 | 40900（无原因码）                    | 首次受理操作已过期                      | 用新的操作编号重新提交                   |
 | 42900                                | 调用历史容量已满 / 本人后台调用队列已满 | 等在途作业结束后再提交（每人最多 16 个） |
@@ -406,7 +406,8 @@
 
 `zleap-app prepare` 的特殊结果：
 
-- **平台 `appid` 应用**只准备开发环境：只声明数据的应用在开发权限阶段后结束，`status` 为 **`ready`**，响应里 `"environment": "dev"`；
+- **平台 `appid` 应用**通常不需要 `prepare`（上传自动签名、安装 / 切换版本时自动绑定），只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用。
+  它只准备开发环境：只声明数据的应用在开发权限阶段后结束，`status` 为 **`ready`**，响应里 `"environment": "dev"`；
   Manifest 声明了 headless 后台能力时，还会创建发布候选、签名并激活到开发。
 - **旧 `app_key` 应用**没有声明云资源（无 `cloud.*` 权限、无后台能力、无集合）时直接返回 `status` 为 **`not_required`**，
   `next` 提示「应用未声明云资源或后台执行，安装后即可运行」。
@@ -422,7 +423,7 @@
 >
 > - **平台 `appid` 应用**：接受**本人上传**的版本（可见性 `private` 或 `members`），只准备开发环境
 >   （开发环境 → 数据库 → 开发数据域权限，声明了 headless 时再加签名并激活到开发），不会碰生产；
->   生产由**首次 `release`（发布为线上版本）**自动准备。声明了 headless 时，它等同于控制台「版本管理」下方「**开发环境：云函数激活**」。
+>   生产由**首次 `release`（发布为线上版本）**自动准备。appid 应用通常不需要它，只在 `diagnose` 提示 `next_action: app_prepare` 时兜底使用。
 > - **旧 `app_key` 应用**：只接受**本人 private、且已安装**的包，一路准备到生产。
 
 `zleap-app publish` 等写操作网络结果不明时返回 `COMMIT_UNKNOWN`，**不会自动重传**：
@@ -474,7 +475,8 @@
 
 | 业务码 | message                                                  | `detail.reason`           | 处理（`next_action`）                                                                                        |
 | ------ | -------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| 40900  | 发布带云资源的版本前，上传者需要正在使用这个版本         | `UPLOADER_NOT_ON_VERSION` | 请上传者打开应用并切换到这个版本（npm run deploy 会自动切换），再发布                                        |
+| 40900  | 生产数据库还没就绪，暂时不能发布                         | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪，稍后在版本管理里重新发布；持续失败请在控制台「数据库」查看状态                            |
+| 40900  | 这个版本的上传者账号已停用，无法发布                     | `UPLOADER_INACTIVE`       | 请其他成员重新上传这个版本（npm run deploy）后再发布                                                         |
 | 40900  | 这个应用请在云开发控制台「版本管理」里发布或回退         | `USE_VERSION_MANAGEMENT`  | 应用中心不能改平台 `appid` 应用的线上版本；到控制台「发布 → 版本管理」点「发布为线上版本」或「回退到此版本」 |
 | 40900  | 该应用使用旧的命名空间标识，请在「版本与激活」里管理版本 | `LEGACY_APP`              | 旧 `app_key` 应用走「版本与激活」                                                                            |
 | 40400  | 版本不存在或已删除 / 该版本没有可用制品                  | —                         | 刷新版本列表后重试                                                                                           |
@@ -484,11 +486,14 @@
 `USE_VERSION_MANAGEMENT` 来自应用中心的「发布到企业目录 / 撤回企业目录」接口，不是版本管理接口本身的错误；
 它表示**这个应用不该在应用中心改线上状态**。平台 `appid` 应用请改用控制台「版本管理」。
 
-`UPLOADER_NOT_ON_VERSION` 只出现在带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本上，且只在**第一次发布**时要求；已经发布过的版本再次发布会复用生产准备。见 [版本管理 · 带云资源的版本](console-release.md#带云资源的版本)。
+任一成员都可以发布任一版本，不要求上传者正在使用这个版本。带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本**第一次**发布时，
+平台自动完成应用级生产准备（生产环境 → 签发生产发布 → 生产门禁 → 生产库与生产集合），`PROD_DATABASE_NOT_READY`、`UPLOADER_INACTIVE` 只在这一步出现；
+生产门禁不通过时返回与激活相同的原因码（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`，见 [发布与激活](#发布与激活)），重新发布即会重新签发。
+已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。见 [版本管理 · 带云资源的版本](console-release.md#带云资源的版本)。
 
 ## 版本更新与回滚
 
-### 版本切换（控制台「我也用这个」/ CLI `update`、`rollback`）
+### 版本切换（控制台「切换到此版本」/ CLI `update`、`rollback`）
 
 这些码来自安装版本切换接口（`appversion/read.go`、`official.go`、`apply.go`）：
 

package/templates/react-ts/scripts/zleap.mjs

@@ -267,7 +267,7 @@ function finish(appId, installed, diagnosis = null) {
   if (installed) steps.push('从 zleapOS 启动台打开应用（已打开的窗口点「重新加载应用」）。');
   if (hasBackgroundCapabilities(readJSON(manifestFile, {})) && diagnosis?.resource_preparation_required) {
     steps.push(
-      `有云函数 / 后台能力：npx zleap-app prepare ${appId} --version-id ${readJSON(stateFile, {}).versionId ?? '<version_id>'} 签名并激活到开发环境（或在「云开发控制台」→ 版本管理下方「开发环境：云函数激活」操作），再在应用窗口「权限」里允许后台能力。`,
+      `有云函数 / 后台能力：npx zleap-app prepare ${appId} --version-id ${readJSON(stateFile, {}).versionId ?? '<version_id>'} 补做开发环境准备（平台上传时通常已自动签名并绑定，只有自动签名失败时才会走到这一步），再在应用窗口「权限」里允许后台能力。`,
     );
   }
   if (!cloud || !cloud.dev || !cloud.databaseReady) {
@@ -342,8 +342,16 @@ async function release() {
   const result = cli(args);
   if (result.code !== 0) {
     if (needLogin(result.stderr)) throw new StepError(`${result.stderr}\n先运行 npm run login`);
-    if (/UPLOADER_NOT_ON_VERSION/.test(result.stderr + result.stdout)) {
-      throw new StepError('带云资源的版本第一次发布前，上传者需要正在使用这个版本：上传者先 npm run deploy（会自动切换），再发布。');
+    const output = result.stderr + result.stdout;
+    if (/PROD_DATABASE_NOT_READY/.test(output)) {
+      throw new StepError('生产数据库还没就绪，暂时不能发布：通常 1 分钟内就绪，稍后再 npm run release；持续失败请在云开发控制台「数据库」查看状态。');
+    }
+    if (/UPLOADER_INACTIVE/.test(output)) {
+      throw new StepError('这个版本的上传者账号已停用，无法发布：重新 npm run deploy 上传一个版本，再发布。');
+    }
+    if (/UPLOADER_NOT_ON_VERSION/.test(output)) {
+      // 旧版平台才会返回：新平台任一成员都能发布任一版本
+      throw new StepError('当前平台版本要求上传者正在使用这个版本：上传者先 npm run deploy（会自动切换），再发布。');
     }
     throw new StepError(`发布失败：${result.stderr || result.stdout}`);
   }