create-zleap-app 0.10.0 → 0.10.2

package/skills/zleap-cloud-app-release/references/dev-to-production.md

@@ -7,47 +7,259 @@
 
 如果你只想先在自己桌面上跑通一个读写数据库的应用，先看 快速开始（文档站 /guide/quickstart）。
 
-## 用 appid 的应用：上传后在版本管理里发布
+## 先分清两种应用
 
-在云开发控制台「创建应用」得到平台 `appid`（`zl…`）的应用，上线流程简化为两步：
+平台现在**推荐、并且新建的都是 `appid` 应用**：在云开发控制台「创建应用」得到 `zl` + 16 位十六进制的应用标识。
+早期还有一批用 `app_key` 命名空间（如 `com.example.todo`）创建的旧应用，它们仍能使用，但上线方式不同。
 
-1. **上传开发版本**：`npm run deploy`（构建 → 检查 → 上传 → 切换本人安装）。每个成员的每次上传都是一个开发版本，只有成员能用。
-2. **发布为线上版本**：控制台侧栏「发布」→「**版本管理**」，在要上线的版本上点「**发布为线上版本**」（可选填发布说明）；
-   或在项目里 `npm run release -- --notes "本次更新说明"`（发布最近一次 deploy 的版本，见[用命令行发布](console-release.md#用命令行发布)）。
-   发布后**全企业可见**：应用出现在应用中心，新安装装的是线上版本，不需要再「发布到企业目录」。
+| 对比项       | 平台 `appid` 应用（推荐）                                  | 旧 `app_key` 应用                                     |
+| ------------ | ---------------------------------------------------------- | ----------------------------------------------------- |
+| Manifest     | 写 `"appid": "zl…"`                                        | 写 `"app_key": "com.example.todo"`                    |
+| 每次上传     | **开发版本**，可见性 `members`（只有应用成员能看到、安装） | **private**（只有上传者本人）                         |
+| 上线方式     | 控制台「版本管理」→「发布为线上版本」                      | 应用中心「发布到企业目录」/ `market-publish`          |
+| 生产环境     | 首次「发布为线上版本」时**自动准备**                       | 手动「激活到生产」，或 `prepare`（仅本人 private 包） |
+| 生产准备命令 | 不需要：首次「发布为线上版本」自动准备；`prepare` 只准备开发环境 | `zleap-app prepare`                                   |
+| 读哪一节     | 下面的[推荐路线](#推荐路线-appid-应用从开发到上线)         | 后半部分[旧应用的完整流程](#legacy-flow)              |
 
-| 应用                                                                                 | 发布时平台做什么                                                                                                       |
-| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| **只用宿主能力**（没有集合、`cloud.*` 能力、`runtime.backend`、headless 能力）       | 直接发布。**不需要签名、激活**，也不需要开发 / 生产环境                                                                |
-| **带云资源**（声明了上面任何一项）                                                   | 以上传者身份一并准备生产：环境、生产授权、签名、激活到生产、生产集合。要求上传者**正在使用这个版本**，否则 `UPLOADER_NOT_ON_VERSION` |
+> **先确认你的应用是哪种**（提示）
+>
+> 打开项目的 `manifest.json`：有 `appid` 字段（或值是 `zl` 开头）就是平台应用；有 `app_key` 字段（值带点，如 `com.example.todo`）就是旧应用。
+> 不确定时，在控制台应用切换器里能看到这个应用，并且「发布」组里是「版本管理」，就是 `appid` 应用。
+
+## 推荐路线：appid 应用从开发到上线
+
+```
+创建应用（拿 appid）
+        ↓
+脚手架新建项目 / 已有项目接入
+        ↓
+npm run login → npm run deploy（构建 → 检查 → 上传开发版本 → 装到自己桌面）
+        ↓                         ↘ 声明了集合的应用：安装时自动开通开发环境、数据库、集合
+打开应用调试（运行体检、控制台日志、npm run logs）
+        ↓
+有云函数？→ 控制台「版本管理」下方「开发环境：云函数激活」签名并激活
+            → 应用窗口「权限」里允许后台能力
+        ↓
+发布为线上版本（首次带云资源时自动准备生产）
+        ↓
+同事在应用中心安装；下次打开自动更新，非成员 24 小时后强制更新
+        ↓
+迭代：deploy → release；回退：把旧版本再 release 一次
+        ↓
+一起开发：控制台「成员」里添加开发者
+```
+
+### 第 1 步：创建应用，拿到 `appid`
+
+**做什么**：在云开发控制台新建一个应用，拿到平台生成的 `appid`（应用标识，`zl` + 16 位小写十六进制）。
+
+**在哪做**：打开启动台 →「更多工具」→「云开发控制台」（也可以在启动台直接搜索「云开发」）。
+云开发控制台是**系统内置应用**，不需要去应用中心安装。在左上角应用切换器里点「**创建应用**」，填应用名称（说明可选），点「创建」。
+
+**做完的标志**：控制台概览显示这个应用的 `appid`，并提示「应用已创建，还没有上传过代码。按下面三步把第一个版本传上来。」
+你自动成为应用**管理员**；要加同事一起开发，去「成员」页（见第 9 步）。
+
+（截图：新建应用、还没上传时的控制台概览，见文档站）
+
+### 第 2 步：生成项目，或接入已有项目
+
+**做什么**：准备一个能部署到 zleapOS 的项目，并让 `manifest.json` 指向第 1 步的 `appid`。
+
+**在哪做**：
+
+- **新项目**：用脚手架生成 React + TypeScript + Vite 项目：
+
+  ```bash
+  npm create zleap-app@latest my-app -- --appid <appid> --name "我的应用"
+  ```
+
+  生成的项目自带 Cloud SDK、`zleap-app` CLI、部署脚本和 AI 编程工具 skills。详细选项见 npm 包与工具链（文档站 /guide/npm-packages#脚手架-create-zleap-app）。
+  需要 Node.js 20.19.x 或 22.12+，安装步骤见 环境准备与安装（文档站 /guide/install）。
+
+- **已有项目**：把 `appid` 写进 `manifest.json` 的 `appid` 字段（新应用不再需要 `app_key` 和 `publisher`），
+  并参考 已有项目接入云开发（文档站 /guide/integrate） 配置 SDK、构建和部署脚本。
+
+**做完的标志**：`manifest.json` 里有正确的 `"appid": "zl…"`；本地 `npm run dev` 能打开页面。
+
+### 第 3 步：登录并部署到自己的桌面
+
+**做什么**：登录开发会话，构建、检查、上传一个开发版本，并把它安装 / 切换到自己桌面。
+
+**在哪做**：项目目录里执行：
+
+```bash
+npm run login -- --target https://os.example.com
+# 浏览器打开后，核对页面与终端里的确认码一致，再点「允许开发工具」
+
+npm run deploy
+# 构建 → 检查 → 上传开发版本 → 安装 / 切换本人安装
+```
+
+- 登录后的**访问凭据 30 分钟有效，CLI 会自动续期**；授权从首次登录起最长 30 天。
+- `npm run deploy` 上传的是**开发版本**，只有应用成员能看到和安装，还不是线上版本。
+- 声明了 `data.collections` 的应用，安装时平台会**自动创建开发环境、开通数据库、按 Manifest 建集合**，通常 1 分钟内完成。
+
+**做完的标志**：终端输出 `app_id`、`version_id`，并提示「本人安装已是 v…」；控制台概览的「开通进度」到 **3/5**
+（创建开发环境、开通数据库、创建集合已完成）。后两步「签名版本」「升级安装并激活」只在有云函数时才需要。
+
+（截图：安装后的概览：前 3 步完成，开通进度 3/5，见文档站）
+
+> **版本号会自动递增**（提示）
+>
+> `npm run deploy` 发现同一个 `version` 已经上传过不同内容时，会自动把补丁号加一。你也可以手动改 `manifest.json` 的 `version`。
+
+### 第 4 步：打开应用，调试
+
+**做什么**：从启动台打开应用，确认它连上了 OS、能读写数据，并学会看运行状态和日志。
+
+**在哪做**：
+
+- 启动台打开刚安装的应用。应用窗口顶部有「**权限**」和「**重新加载应用**」；左下应显示「**● OS 已连接**」。
+- 控制台「概览」里的「**运行体检**」会逐层检查安装、授权、数据和后台能力，失败时给出具体层。
+- 控制台「日志」页查页面错误和云函数日志；在项目里运行 `npm run logs` 查看最近 24 小时本人页面上报的错误和本人云函数日志
+  （默认自动选 `dev` / `prod`，也可 `npm run logs -- --environment dev`）。
+- `npm run status` 等价于 `zleap-app diagnose <app_id>`，查看安装版本、权限和开通状态。
+
+**做完的标志**：应用窗口能正常读写；运行体检显示各层通过；日志里没有持续报错。
+
+（截图：部署后的应用窗口：OS 已连接，能读写待办，见文档站）
+
+> **开发环境只对应用成员开放**（说明）
+>
+> `appid` 应用的开发数据域对**全部应用成员**（管理员 / 开发者）开放：在「成员」里加为开发者的同事装上开发版本，就能和你一起读写开发数据。
+> 非成员访问会被拒绝（`PUBLISHER_REQUIRED`，「开发环境仅发布者本人可访问」）——要给他们用，请发布为线上版本（第 6 步）。
+
+### 第 5 步：有云函数 / 后台能力时，签名并激活开发
+
+**做什么**：让云函数和后台能力在开发环境里真正跑起来。只有 Manifest 声明了云函数、`runtime.backend` 或 `execution: "headless"` 的后台能力时才需要；
+只用宿主能力的应用直接跳到第 6 步。
+
+**在哪做**：
+
+1. 控制台侧栏「发布」→「**版本管理**」，页面下方是「**开发环境：云函数激活**」。
+   按「新建候选 → 签名验证 → 激活开发」三步操作；这里只列出**你本人上传**的版本。
+   也可以在项目里运行 `npx zleap-app prepare <app_id> --version-id <id>`，等价完成开发环境准备（不碰生产）。
+2. 打开应用窗口，点「**权限**」，在「**应用权限**」对话框里勾选「**后台能力（定时任务 / 云函数）**」下要用的能力，
+   点「**保存并重新加载**」。
+
+两步没有先后要求，但**都做完**后台能力才会执行：只激活不允许，函数不会跑；只允许不激活，调用报 `FUNCTION_RELEASE_REQUIRED`。
+
+**做完的标志**：控制台概览第 5 步显示「**已激活到开发环境**」；「云函数」页对应函数状态为「**可调用**」；
+应用窗口「权限」里不再出现「该版本尚未激活发布版本，暂时无法执行。……」的提示。
+
+（截图：版本管理页：上方发布线上版本，下方「开发环境：云函数激活」，见文档站）
+
+### 第 6 步：发布为线上版本
+
+**做什么**：把某个开发版本设为线上版本，让全企业用户可以用到。
 
-之后的迭代：再 `npm run deploy` 上传新版本 → 在「版本管理」发布它。回退就是在旧版本上点「回退到此版本」。
-已经开着应用的人不会被打断；其他使用者下次打开时**自动跟随**到线上版本，应用里也可以用 `zl.app.getUpdateManager()` 提示立即更新。
-详见 [版本管理](console-release.md#版本管理) 和 版本更新与授权登录（文档站 /reference/app-runtime）。
+**在哪做**：控制台侧栏「发布」→「**版本管理**」，在要上线的版本行点「**发布为线上版本**」（可填「发布说明（可选）」）。
+也可以在项目里发布最近一次 `npm run deploy` 上传的版本：
 
-> **下文的 ①–⑩ 与 appid 应用的对应关系**（说明）
+```bash
+npm run release -- --notes "本次更新说明"
+# 交互环境会二次确认；CI 等非交互环境加 --yes
+# 等价于 zleap-app release <app_id> --version-id <version_id> --notes "…"
+```
+
+发布后**全企业可见**：应用出现在应用中心，新安装装的是线上版本，不需要再「发布到企业目录」。
+
+| 应用类型                                               | 发布时平台做什么                                                                                                                                     |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **只用宿主能力**（没有集合、`cloud.*` 能力、后台能力） | 直接发布。不需要签名、激活，也不需要开发 / 生产环境                                                                                                  |
+| **带云资源**（声明了集合、`cloud.*` 能力或后台能力）   | 第一次发布时以上传者身份自动准备生产：生产环境、生产授权、签名、激活到生产、生产集合。要求上传者**正在使用这个版本**，否则 `UPLOADER_NOT_ON_VERSION` |
+
+已经发布过的版本再次发布（包括回退）会复用当时的发布，**不再要求上传者安装着这个版本**。
+
+> **部署没开放生产时**（说明）
 >
-> 下文是完整流程，最初为旧 `app_key` 命名空间应用写成。对 appid 应用：
+> 带云资源的版本第一次发布会卡在准备生产（生产环境建不出来）。这是**部署未开放生产**，由运维决定，不是你的应用写错了；
+> 只用宿主能力的应用不受影响。判断方式见[旧应用一节的两个问题](#先回答两个问题)。
+
+**做完的标志**：「线上版本」卡片显示这个版本；应用中心能搜索到应用；同事可以安装。
+
+> **应用中心「我的发布」里的 appid 版本**（提示）
+>
+> `appid` 应用的版本行显示「**仅成员可见**」，卡片统计是「企业 n / 开发版本 n」。成员版本上没有「发布到企业目录」，
+> 而是「**去版本管理发布**」主按钮，点它打开云开发控制台「版本管理」；已发布的版本保持「**云开发**」按钮。上线统一在「版本管理」里点「发布为线上版本」。
+
+> **第一次发布被 UPLOADER_NOT_ON_VERSION 拦下**（提示）
+>
+> 带云资源的版本第一次发布要求**上传者本人**当前安装的就是这个版本。让上传者在项目里再跑一次 `npm run deploy`
+> （它会自动切换安装），然后再发布；也可以让上传者在「版本管理」里点「我也用这个」。
+
+### 第 7 步：同事安装，之后自动更新
+
+**做什么**：让同事在应用中心安装，并理解后续更新行为。
+
+**在哪做**：同事打开「应用中心」→「发现」，找到应用并点「安装」。安装时会一次性授予该版本 Manifest 声明的数据 / 文件权限；
+**后台能力仍需同事本人在应用窗口「权限」里勾选**。
+
+**做完的标志**：同事能打开应用并读写**生产数据域**。开发环境里的数据不会带过去。
+
+更新行为：
+
+- 发布新线上版本后，没开着应用的使用者**下次打开自动更新**；
+- 正开着旧版本的窗口会收到更新提示；
+- **非成员**的旧窗口在新版本发布 **24 小时后会被强制切换**，提示「这个版本已超过 24 小时的使用期限，正在更新到最新版本…」；
+- 应用里也可以用 `zl.app.getUpdateManager()` 主动提示立即更新。
+
+详见 [版本管理](console-release.md) 和 版本更新与授权登录（文档站 /reference/app-runtime）。
+
+### 第 8 步：迭代与回退
+
+**做什么**：持续发新版本；出问题时回到旧版本。
+
+**在哪做**：
+
+- **迭代**：改代码 → `npm run deploy` 上传新开发版本 → 在「版本管理」或 `npm run release` 发布它。
+- **自己先换到某个版本**：在「版本管理」里点「我也用这个」，或
+  `zleap-app update <app_id> --expected-version-id <当前> --version-id <新>`。
+- **回退**：在旧版本行点「**回退到此版本**」，或 `zleap-app release <app_id> --version-id <旧版本 ID>`。
+
+> **回退应用版本不等于回退业务数据**（危险）
 >
-> - ①② 写代码、检查打包相同；③④ 上传和安装给自己用 `npm run deploy` 一步完成；
-> - 只用宿主能力的应用跳过 ⑤⑥⑧，没有开发环境要开通，也不用签名和激活；
-> - 带云资源的应用在开发阶段照旧按 ⑤–⑦ 开通开发环境、调试；
-> - ⑧ 上生产、⑨ 发布到企业目录、⑩ 让同事升级，都由「版本管理」里的「发布为线上版本」代替。
+> 「回退到此版本」只改线上版本，**不会回退数据库里的数据**。目标版本的 `data` / `storage` 声明与当前版本不同时，
+> `update` / `rollback` 会返回 `DATA_MIGRATION_REQUIRED` 并保持原版本；平台不会替你做数据迁移。
 
-## 全景
+> **集合结构不会随新版本更新**（注意）
+>
+> 集合在开发环境数据库就绪后按 Manifest 自动创建；之后**新版本改 Schema 不会更新已有集合**。
+> 需要调整结构时，新建一个集合并自行迁移数据。
+
+### 第 9 步：一起开发
+
+**做什么**：让同事能上传、调试和管理这个应用。
+
+**在哪做**：控制台侧栏「团队」→「**成员**」→ 输入对方的登录名、手机号或邮箱，角色选「**开发者**」，点「添加」。
+角色说明：**管理员**「管理成员与应用」；**开发者**「上传、调试与管理」。只有管理员能增删成员。
+
+**做完的标志**：成员列表出现同事；同事用同一 `appid` 登录后，可以 `npm run deploy`，他上传的版本也会出现在「版本管理」里，
+任何成员都可以把合适的版本发布为线上版本。
+
+> **成员共享开发数据**（提示）
+>
+> 成员装上开发版本后使用的是同一个开发数据域，彼此能看到对方在共享集合里写的数据（私有集合按账号隔离）。
+
+## 旧 `app_key` 应用的完整流程（手动签名、激活、企业目录） {#legacy-flow}
+
+> **这一节只给旧应用**（说明）
+>
+> 下面 ①–⑩ 是早期 `app_key` 命名空间应用的完整流程：上传默认 private、手动签名并激活、手动激活生产、发布到企业目录。
+> **新应用请用上面的推荐路线**，不要照这一节操作；`prepare` 对 `appid` 应用只准备开发环境，生产仍由首次「发布为线上版本」自动准备。
 
 ```
- 开发            上传与安装              开发环境                  上线                 分享
-──────────    ──────────────────    ─────────────────────    ───────────────────    ─────────────
-① 写代码   →  ③ 上传（private）  →  ⑤ 开通清单 1–3 步     →  ⑧ 生产环境 + 门禁   →  ⑨ 发布到企业目录
-② 检查打包 →  ④ 安装给自己       →  ⑥ 签名并激活开发*     →     激活到生产**        同事安装使用
-                                    ⑦ 调试与验收                                    ⑩ 迭代新版本
+ 开发            上传与安装              开发环境                  调试          上线                    分享
+──────────    ──────────────────    ─────────────────────    ─────────    ───────────────────    ─────────────
+① 写代码   →  ③ 上传（private）  →  ⑤ 开通清单 1–3 步     →  ⑦ 验收   →  ⑧ 生产环境 + 门禁   →  ⑨ 发布到企业目录
+② 检查打包 →  ④ 安装给自己       →  ⑥ 签名并激活开发*     →             →     激活到生产**        同事安装使用
+                                                                                              ⑩ 迭代新版本
 
   *  只有声明了云函数 / 后台能力的应用需要
   ** 只有部署开放了生产环境时才有
 ```
 
-## 先回答两个问题
+### 先回答两个问题
 
 整条流程有两个分叉，开始之前先确定：
 
@@ -63,28 +275,15 @@
 
 由此得到四种路线：
 
-| 部署 \ 应用    | 只有前端（只读写数据 / 文件）     | 有后台能力 / 云函数       |
-| -------------- | --------------------------------- | ------------------------- |
-| **生产未开放** | ①–⑤ → ⑦ → ⑨                       | ①–⑦ → ⑨                   |
-| **生产已开放** | ①–⑤ → ⑦ → ⑧ → ⑨（或用 `prepare`） | ①–⑧ → ⑨（或用 `prepare`） |
+| 部署 \ 应用    | 只有前端（只读写数据 / 文件） | 有后台能力 / 云函数         |
+| -------------- | ----------------------------- | --------------------------- |
+| **生产未开放** | ①–⑤ → ⑦ → ⑨                   | ①–⑦ → ⑨                     |
+| **生产已开放** | ①–⑤ → ⑦ → ⑧ → ⑨               | ①–⑦ → ⑧ → ⑨（或 `prepare`） |
 
-## ① 写代码
+### ① 写代码
 
-先在**云开发控制台**侧栏顶部的应用切换下拉里点「**创建应用**」，填名称，拿到平台生成的 `appid`
-（如 `zl3f9a2c7e1b0d4a68`），你成为应用管理员。团队一起开发时，在控制台「成员」里把同事加为开发者，见 [成员管理](console-members.md)。
-
-推荐用脚手架起步（React + TypeScript + Vite，自带 Cloud SDK、`zleap-app` CLI、部署脚本和 AI 编程工具 skills）：
-
-```bash
-npm create zleap-app@latest my-app -- --appid zl3f9a2c7e1b0d4a68 --name "我的应用"
-```
-
-之后 ② ~ ④ 可以合并成一条 `npm run deploy`（构建 → 检查 → 上传 private → 安装/切换本人安装），首次先 `npm run login`。
-也可以用原生模板（纯 HTML/JS，零构建）：
-
-```bash
-zleap-app init hosted-package ./my-app --app-key zl3f9a2c7e1b0d4a68   # --app-key 填 appid
-```
+旧应用是在平台早期用 `app_key` 命名空间（如 `com.example.todo`）创建的应用。代码、Manifest、SDK 的写法和新应用相同，
+区别是 Manifest 里写 `app_key` 而不是 `appid`，以及后面的上传、签名、上架流程不同。
 
 要做的事：
 
@@ -103,39 +302,42 @@ zleap-app init hosted-package ./my-app --app-key zl3f9a2c7e1b0d4a68   # --app-ke
 参考：Manifest v2 配置（文档站 /reference/manifest）、云数据库 API（文档站 /reference/database-api）、
 云函数开发（文档站 /reference/cloud-function）、触发器（文档站 /reference/triggers）、[权限与授权](permissions.md)。
 
-## ② 检查与打包
+### ② 检查与打包
 
 ```bash
 zleap-app check ./my-app
 zleap-app pack ./my-app --output ./out/my-app.zip
 ```
 
-- `pack` 产出确定性 ZIP，自动排除 `.env*`、`*.log`、`*.pem`、`node_modules`、`.git`、`out` 等；仍请自己确认业务文件里没有内嵌密钥。
-- 登录后（见下一步）可加 `--target https://os.example.com` 用目标部署的规则在线再校验一次。
+- `pack` 必须给 `--output`。它产出确定性 ZIP，自动排除 `.env*`、`*.log`、`*.pem`、`node_modules`、`.git`、`out` 等；
+  仍请自己确认业务文件里没有内嵌密钥。
+- 登录后可加 `--target https://os.example.com` 用目标部署的规则在线再校验一次；**带 `--target` 需要先登录**。
 - **`check` 通过只代表静态规则通过**（`runtime_test=not_checked`），不代表应用能用。
 
 带 `cloudfunctions/` 的包同样可以用 `zleap-app check / pack / publish`，校验规则与应用中心上传一致。
 
-## ③ 上传
+### ③ 上传
 
 两种入口，任选其一：
 
-| 入口         | 做法                                                                                                | 结果                                                                                               |
-| ------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **命令行**   | `zleap-app auth login --target <OS> --app-key <appid>`（浏览器核对确认码）→ `zleap-app publish <zip>` | 永远是 **private（仅自己可见）**；回执里有 `app_id`、`version_id`、`package_id`                    |
-| **应用中心** | 「我的发布」→「自建应用」→「应用包」→「**上传应用包**」                                             | 提示「应用包已上传，可继续发布到企业目录。」；若该应用已有企业可见版本，新版本**自动继承企业可见** |
+| 入口         | 做法                                                                                                    | 结果                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **命令行**   | `zleap-app auth login --target <OS> --app-key <app_key>`（浏览器核对确认码）→ `zleap-app publish <zip>` | **private（仅自己可见）**；回执里有 `app_id`、`version_id`、`package_id`                           |
+| **应用中心** | 「我的发布」→「自建应用」→「应用包」→「**上传应用包**」                                                 | 提示「应用包已上传，可继续发布到企业目录。」；若该应用已有企业可见版本，新版本**自动继承企业可见** |
 
 两点约定：
 
 - **每次上传都要提高 `version`**。同一版本号换了内容会被拒绝。
-- 上传结果不明（`COMMIT_UNKNOWN`）时**不要直接重传**，先 `zleap-app status` 或刷新「我的发布」核对。
-- `appid` 必须已在控制台创建（否则 40400「appid 不存在」），上传者必须是应用成员（否则 40300「你不是这个应用的开发者」，请管理员在「成员」里把你加为开发者）。
+- 上传结果不明（`COMMIT_UNKNOWN`）时**不要直接重传**，先 `zleap-app status`（只列本人上传的包）或刷新「我的发布」核对。
+  上传回执在 `~/.config/zleap-app/operations/`，用 `zleap-app operation --request-id publish-…` 查询。
+- 应用必须已经在平台存在（否则 40400）；上传者必须是应用成员（否则 40300「你不是这个应用的开发者」，
+  请管理员在「成员」里把你加为开发者）。
 
 部署配置了发布信任根时，上传会**自动生成一条草稿发布候选**，⑥ 里直接签它即可。
 
 参考：[上传与发布应用](app-center-publish.md)。
 
-## ④ 安装给自己
+### ④ 安装给自己
 
 `zleap-app install <app_id>`，或在应用详情页点「**安装**」。
 
@@ -147,9 +349,9 @@ zleap-app pack ./my-app --output ./out/my-app.zip
 
 参考：[安装与卸载](app-center-install.md)、[权限与授权](permissions.md)。
 
-## ⑤ 开通开发环境
+### ⑤ 开通开发环境
 
-打开**云开发控制台**（第一次先在应用中心安装它），侧栏选中你的应用，「概览」里是 5 步开通清单。
+打开**云开发控制台**（系统内置，启动台「更多工具」里或搜索「云开发」直接打开），侧栏选中你的应用，「概览」里是 5 步开通清单。
 前 3 步是「数据」组：
 
 | 步骤            | 你要做的                                                                         | 完成标志            |
@@ -158,20 +360,20 @@ zleap-app pack ./my-app --output ./out/my-app.zip
 | 2. 开通数据库   | 自动开始，页面每 3 秒刷新；失败时点「查看并重试」                                | 「已就绪」          |
 | 3. 创建集合     | 一般自动建好；缺了就点「**同步集合**」→「同步 Manifest 中的集合」                | 「已有 {n} 个集合」 |
 
-**只有前端的应用到这里就能用了**——打开应用即可读写开发数据域。进度停在 3/5 是正常的。
+**只有前端的应用到这里就能用了**——打开应用即可读写开发数据域。进度停在 3/5 是正常的；后两步只服务云函数。
 
-开发环境默认**只有发布者本人**能访问（其他人会得到 `PUBLISHER_REQUIRED`）。
+开发环境默认**只有该版本的上传者本人**能访问（旧应用没有成员概念；其他人会得到 `PUBLISHER_REQUIRED`）。
 
 参考：[工作区概览](console-workspace.md)、数据库（文档站 /console/database）。
 
-## ⑥ 签名并激活开发（有后台部分时）
+### ⑥ 签名并激活开发（有后台部分时）
 
 云函数和后台能力**只运行签名并激活的版本**。开通清单的后 2 步（「运行」组，「使用云函数或后台任务时需要」）就是这件事。
 推荐顺序：
 
 1. **签名**：控制台「**版本与激活**」页，在这个版本的草稿候选上点「**验证并签发**」
    （确认框「为该候选签发发布证明？」，服务端用部署私钥签名，私钥不离开服务器）→ 候选变为「**已就绪**」。
-   没有草稿候选时先点「新建发布候选」选中这个应用包。
+   没有草稿候选时先点「**新建发布候选**」选中这个应用包。
 2. **允许后台运行**：点应用窗口顶部的「**权限**」，在「应用权限」对话框里勾选「**后台能力（定时任务 / 云函数）**」下要用的能力，
    点「**保存并重新加载**」。当前安装版本已有「已就绪」发布时，这一步保存会**自动把该发布绑定到安装**。
 3. **核对或补做激活**：回概览看第 5 步。显示「**已激活到开发环境**」就完成了；否则到「版本与激活」点「**激活开发**」
@@ -195,7 +397,7 @@ zleap-app pack ./my-app --output ./out/my-app.zip
 
 参考：[版本与激活（旧应用）](console-legacy-release.md)、[云函数与后台能力](console-functions.md)。
 
-## ⑦ 调试与验收
+### ⑦ 调试与验收
 
 调试工具：
 
@@ -213,15 +415,16 @@ zleap-app pack ./my-app --output ./out/my-app.zip
 
 - 运行机预先装好 Node.js 22.12+、Puppeteer Core 25+ 和 Chrome，准备一个仅属主可读写（0600）、放在仓库外的运行配置；
 - 验收计划（JSON）固定 `app_key`、`version_id` 和 `steps`，**必须**包含读取断言、写操作、独立数据探针和刷新后断言；
+- 命令是 `zleap-app test <plan.json> --runner-config <运行器配置>`，第一个参数是**计划文件**，不是应用目录；
 - 报告用 `zleap-app logs <report_id>` 查看。只用专用测试账号和测试数据。
 
 参考：日志（文档站 /console/logs）、[状态与错误码](status-codes.md)。
 
-## ⑧ 上线到生产（部署已开放生产时）
+### ⑧ 上线到生产（部署已开放生产时）
 
 生产数据域面向全体使用者，与开发数据域**完全隔离**：开发环境里的数据和授权都不会带过去。
 
-### 手动路线（控制台）
+#### 手动路线（控制台）
 
 1. **生产环境与集合**：「激活到生产」会自动创建生产环境（也可以在控制台侧栏切到「生产环境」后在概览创建），
    但**不会建集合**。环境一建好，应用窗口就会切到生产数据域，没有集合时报 `COLLECTION_NOT_FOUND`。
@@ -239,49 +442,53 @@ zleap-app pack ./my-app --output ./out/my-app.zip
 > 「验证并签发」得到的证明，审批有效期最长为签发后 7 天。过期后这条候选进不了生产，且**已就绪的候选不能重新签发**——
 > 需要为同一个应用包新建候选再签一次。所以签名之后尽快完成生产激活。
 
-### 一键准备 `prepare`
+#### 一键准备 `prepare`
 
-对**本人 private、且已安装**的版本，`prepare` 一条命令按顺序完成整条链路：
+下面讲旧 `app_key` 应用的 `prepare`：一路准备到生产。平台 `appid` 应用也可以用 `prepare`，但它**只准备开发环境**
+（开发环境 → 数据库 → 开发数据域权限 → 声明了 headless 时签名并激活到开发），不会碰生产，声明了 headless 时等同于控制台「版本管理」下方的
+「开发环境：云函数激活」；`appid` 应用的生产由首次「发布为线上版本」自动准备。`prepare` 只接受你本人上传的版本，
+传别人的 `version_id` 会得到 403「只能准备本人上传的版本」；旧应用则必须是本人 private 包，否则 403「只能准备本人private应用」。
 
 ```bash
 zleap-app prepare <app_id> --version-id <version_id> --request-id $(openssl rand -hex 16)
 ```
 
-`--request-id` 可以不传（命令行自动生成）。应用没有声明任何云资源（没有 `cloud.*` 权限、后台能力和集合）时，
-`prepare` 直接返回 `status: "not_required"`：装上就能用，不需要准备。
+`--request-id` 可以不传（命令行自动生成，32 位小写十六进制）。旧应用没有声明任何云资源（没有 `cloud.*` 权限、后台能力和集合）时，
+`prepare` 直接返回 `status: "not_required"`：装上就能用，不需要准备。`appid` 应用只声明数据时，在开发权限阶段后返回 `status: "ready"`。
+
+下表是**旧 `app_key` 应用**的阶段（`completed_stages`）；`appid` 应用只走到开发环境、数据库、开发权限，以及（声明了 headless 时）签名并激活到开发：
 
-| 阶段（`completed_stages`） | 做了什么                                                   |
-| -------------------------- | ---------------------------------------------------------- |
-| `dev_environment`          | 创建开发环境                                               |
-| `database_allocation`      | 开通数据库（有数据声明时）                                 |
-| `prod_environment`         | 创建生产环境——**部署未开放生产时在这里失败**               |
-| `declared_permissions`     | 按声明授予生产数据域权限，并**启用全部 headless 后台能力** |
-| `release_candidate`        | 为该应用包创建发布候选                                     |
-| `release_sign`             | 服务端签名                                                 |
-| `release_activate`         | **激活到生产**                                             |
-| `prod_collections`         | 在生产环境按声明创建集合（有数据声明时）                   |
+| 阶段（`completed_stages`） | 做了什么                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `dev_environment`          | 创建开发环境                                                                                             |
+| `database_allocation`      | 开通数据库（有数据声明时）                                                                               |
+| `prod_environment`         | 创建生产环境——**部署未开放生产时在这里失败**                                                             |
+| `declared_permissions`     | 按声明授予生产数据域权限，并启用全部 headless 后台能力。**条件执行**：只有声明了云数据能力或数据库时才走 |
+| `release_candidate`        | 为该应用包创建发布候选                                                                                   |
+| `release_sign`             | 服务端签名                                                                                               |
+| `release_activate`         | **激活到生产**                                                                                           |
+| `prod_collections`         | 在生产环境按声明创建集合（有数据声明时）                                                                 |
+
+纯前台、或只有云函数而没有云数据能力的旧应用会跳过 `declared_permissions`；完全没有云资源的旧应用直接返回 `not_required`。
 
 失败时返回卡住的 `stage` 和已完成的阶段，**不会自动重试**；先 `zleap-app diagnose` 核对，再用**同一个** `--request-id` 继续。
 成功同样只是 `runtime_test=not_checked`。
 
 > **生产激活影响全体使用者**（危险）
 >
-> 激活前请先在开发环境用**同一个版本**完整验证。`prepare` 会直接激活到生产并启用全部后台能力，
-> 确认这正是你想要的再执行。
+> 激活前请先在开发环境用**同一个版本**完整验证。旧应用的 `prepare` 会直接激活到生产并启用全部后台能力，
+> 确认这正是你想要的再执行。`appid` 应用的 `prepare` 只到开发环境，不会改变线上版本。
 
 参考：[版本与激活（旧应用）· 激活到生产](console-legacy-release.md#激活到生产)。
 
-## ⑨ 分享给同事
-
-> **appid 应用**（提示）
->
-> 在控制台「版本管理」里把版本「发布为线上版本」即全企业可见，不需要下面的「发布到企业目录」，见上文 [用 appid 的应用](#用-appid-的应用-上传后在版本管理里发布)。
+### ⑨ 分享给同事
 
-上传的包默认只有你自己能看到。让同事用上（想让同事**一起开发**，是在控制台「成员」里把他加为开发者，见 [成员管理](console-members.md)）：
+让同事用上（想让同事**一起开发**，是在控制台「成员」里把他加为开发者，见 [成员管理](console-members.md)）。
+旧应用上传的包默认只有你自己能看到：
 
 1. **发布到企业目录**：应用中心「我的发布」展开「管理版本」，在版本行点「**发布到企业目录**」
    （确认框「企业用户将能在应用中心看到这个固定版本。发布不会授予 Agent 或生产后台权限。」）；
-   命令行等价操作 `zleap-app market-publish <package_id> --app-key <appid>`（注意是 `package_id`，不是 `app_id`）。目前**没有审核步骤**。
+   命令行等价操作 `zleap-app market-publish <package_id> --app-key <app_key>`（注意是 `package_id`，不是 `app_id`）。目前**没有审核步骤**。
 2. **同事安装**：同事在应用中心「发现」里找到并安装，安装时同样授予该版本声明的权限；
    后台能力仍需同事本人在应用窗口「权限」里允许。安装带已就绪发布的版本时，会自动绑定该发布。
 
@@ -292,48 +499,58 @@ zleap-app prepare <app_id> --version-id <version_id> --request-id $(openssl rand
 
 参考：[上传与发布应用](app-center-publish.md)、[安装与卸载](app-center-install.md)。
 
-## ⑩ 迭代新版本
+### ⑩ 迭代新版本
 
 每次迭代都是「改代码 → 提高 `version` → 打包上传 → （有后台部分）签名 → 激活/升级」：
 
 | 场景                         | 做法                                                                                                                                 |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 自己先换到新版本             | 控制台概览「升级到 v{x} 并激活」（需新版本已签名）；或 `zleap-app update <app_id> --expected-version-id <当前> --version-id <新>`    |
-| 同事升级                     | 新版本发布到企业目录后，同事在应用中心「更新」里升级。**新版本必须先签成「已就绪」**，否则更新会被拦下                               |
+| 同事升级                     | 新版本先「发布到企业目录」，同事在应用中心「更新」里升级。**新版本必须先签成「已就绪」**，否则更新会被拦下                           |
 | 回退                         | `zleap-app rollback <app_id> --expected-version-id <当前> --version-id <旧>`。只切换本人安装，**不回退业务数据**                     |
 | 改了 `data` / `storage` 声明 | 命令行 `update` / `rollback` 返回 `DATA_MIGRATION_REQUIRED` 并保持原版本；应用中心更新会在预检里给出警告或阻断。平台不替你做数据迁移 |
 | 想改已有集合的结构           | 新版本改 Schema **不会**更新已有集合；需要新建集合并自行迁移数据                                                                     |
 | 下架某个版本                 | 「撤回企业目录」/ `market-unpublish`。**撤回后其他人已有的安装将无法再打开该版本**                                                   |
 
+> **先上新版本，再撤旧版本**（危险）
+>
+> 已安装旧版本的同事不会自动升级。直接撤回旧版本，他们下次打开会失败。正确顺序是：
+> 新版本「发布到企业目录」→ 等同事在应用中心「更新」→ 再撤回旧版本。
+
 权限在版本切换时的处理：应用中心更新时，如果新版本没有扩大 `requires`，原有授权自动延续；扩大了则需要重新同意。
 命令行 `update` 会撤销旧授权、停用后台能力，再按目标版本重新授予声明的权限。
 
 ## 上线前检查清单
 
-| 检查项                                                           | 在哪里看            |
-| ---------------------------------------------------------------- | ------------------- |
-| Manifest 的集合结构已定稿（之后不能改）                          | `manifest.json`     |
-| `check --target` 在目标部署上通过                                | 命令行              |
-| 开通清单前 3 步完成，运行体检全部通过                            | 控制台概览          |
-| （有后台）已签名、已激活开发、后台能力已允许，函数状态「可调用」 | 版本与激活 / 云函数 |
-| 用同一版本完成了真实读写验证（手动或 `zleap-app test`）          | 应用窗口 / 验收报告 |
-| （生产已开放）生产环境已创建、门禁 7 项通过、已激活生产          | 版本与激活          |
-| 已发布到企业目录，同事侧安装后能打开并读写                       | 应用中心            |
+| 检查项                                                           | `appid` 应用                                               | 旧 `app_key` 应用                                    |
+| ---------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
+| Manifest 的集合结构已定稿（之后不能改）                          | 检查 `manifest.json`                                       | 同左                                                 |
+| `check --target` 在目标部署上通过                                | 命令行（需先登录）                                         | 同左                                                 |
+| （声明了集合时）开通清单前 3 步完成，运行体检全部通过            | 控制台概览（安装后通常自动 3/5）                           | 控制台概览（必要时手动创建 / 同步）                  |
+| （有后台）已签名、已激活开发、后台能力已允许，函数状态「可调用」 | 「版本管理」下方「开发环境：云函数激活」+ 应用窗口「权限」 | 「版本与激活」+ 应用窗口「权限」                     |
+| 用同一版本完成了真实读写验证（手动或 `zleap-app test`）          | 应用窗口 / 验收报告                                        | 同左                                                 |
+| （生产已开放时）生产环境与集合已准备好                           | 首次「发布为线上版本」自动完成                             | 生产门禁 7 项 +「激活到生产」或 `prepare`            |
+| 已发布给同事，同事安装后能打开并读写                             | 「版本管理」→「发布为线上版本」（应用中心「发现」安装）    | 「发布到企业目录」/ `market-publish`（应用中心安装） |
 
 ## 常见卡点
 
-| 现象                                               | 原因                                                             | 处理                                                               |
-| -------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 上传报 40400「appid 不存在」                       | `appid` 还没在控制台创建，或抄错了                               | 先在云开发控制台「创建应用」，复制它的 `appid`                     |
-| 上传报 40300「你不是这个应用的开发者」             | 你不是这个应用的成员                                             | 请应用管理员在控制台「成员」里把你加为开发者                       |
-| 应用中心显示「暂不可用」                           | 申请了白名单外的能力、`host_api.profile` 不是 `app-runtime/2` 等 | 应用中心 · 暂不可用（文档站 /app-center/overview#「暂不可用」是什么意思） |
-| 应用打开报「连接需要处理」/ `RESOURCE_NOT_READY`   | 当前数据域没有环境或数据库未就绪                                 | 完成 ⑤（生产已开放时还要完成 ⑧）                                   |
-| `SCOPE_FORBIDDEN`（服务端原因 `CONSENT_REQUIRED`） | 「权限」里的应用权限一项都没勾                                   | 勾选后「保存并重新加载」                                           |
-| `PUBLISHER_REQUIRED`                               | 非发布者访问开发数据域                                           | 见 ⑨ 的说明                                                        |
-| `FUNCTION_RELEASE_REQUIRED`                        | 云函数所在版本没有绑定已就绪发布                                 | 完成 ⑥                                                             |
-| `ENV_FORBIDDEN`（同事打不开）                      | 生产已开放，但应用还没有生产环境                                 | 完成 ⑧                                                             |
-| `COLLECTION_NOT_FOUND`（激活到生产之后）           | 生产环境建好了，但生产数据域里还没有集合                         | 控制台生产环境「数据库」开通，或跑 `prepare`                       |
-| `prepare` 在 `prod_environment` 失败               | 部署未开放生产                                                   | 改走控制台的开发环境流程                                           |
-| `COMMIT_UNKNOWN` / 「结果待确认」                  | 网络中断，服务端可能已处理                                       | 用原操作号查询结果，**不要换个编号重新提交**                       |
+| 现象                                               | 原因                                                                    | 处理                                                                                    | 适用    |
+| -------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------- |
+| 上传报 40400「appid 不存在」                       | `appid` 还没在控制台创建，或抄错了                                      | 先在云开发控制台「创建应用」，复制它的 `appid`                                          | `appid` |
+| 上传报 40300「你不是这个应用的开发者」             | 你不是这个应用的成员                                                    | 请应用管理员在控制台「成员」里把你加为开发者                                            | 两者    |
+| `prepare` 报 403「只能准备本人private应用」        | 旧应用的包不是本人上传的 private 包                                      | 用本人上传且已安装的 private 包再准备                                                   | 旧应用  |
+| `prepare` 报 403「只能准备本人上传的版本」        | `appid` 应用传了别人上传的 `version_id`                                 | 只准备本人上传的版本（可见性 `private` 或 `members`）                                   | `appid` |
+| 发布报 `UPLOADER_NOT_ON_VERSION`                   | 带云资源的版本第一次发布，上传者没在用这个版本                          | 让上传者先 `npm run deploy` / 点「我也用这个」，再发布                                  | `appid` |
+| 同事在应用中心看不到某个开发版本                   | `appid` 应用的开发版本可见性为 `members`，只有应用成员能看到            | 把同事加为开发者；要给全企业用，在控制台「版本管理」发布为线上版本                     | `appid` |
+| 应用中心显示「暂不可用」                           | 申请了白名单外的能力、`host_api.profile` 不是 `app-runtime/2` 等        | 应用中心 · 暂不可用（文档站 /app-center/overview#「暂不可用」是什么意思）                      | 两者    |
+| 应用打开报「连接需要处理」/ `RESOURCE_NOT_READY`   | 当前数据域没有环境或数据库未就绪                                        | 完成第 3 步 / ⑤（生产已开放时还要完成 ⑧）                                               | 两者    |
+| `SCOPE_FORBIDDEN`（服务端原因 `CONSENT_REQUIRED`） | 「权限」里的应用权限一项都没勾                                          | 勾选后「保存并重新加载」                                                                | 两者    |
+| `PUBLISHER_REQUIRED`                               | 非发布者访问开发数据域                                                  | 用发布者账号调试，或完成 ⑧ / 发布线上版本后走生产数据域                                 | 两者    |
+| `FUNCTION_RELEASE_REQUIRED`                        | 云函数所在版本没有绑定已就绪发布                                        | 完成 ⑥（`appid` 应用在「版本管理」下方做）                                              | 两者    |
+| `ENV_FORBIDDEN`（同事打不开）                      | 生产已开放，但应用还没有生产环境                                        | `appid` 应用先发布线上版本；旧应用完成 ⑧                                                | 两者    |
+| `COLLECTION_NOT_FOUND`（激活到生产之后）           | 生产数据域里还没有集合                                                  | 旧应用在控制台生产环境「数据库」开通或跑 `prepare`；`appid` 应用检查 `data.collections` | 两者    |
+| `prepare` 在 `prod_environment` 失败               | 部署未开放生产                                                          | 改走控制台的开发环境流程；`appid` 应用等「发布为线上版本」自动准备                      | 旧应用  |
+| 首次「发布为线上版本」卡在准备生产                 | 部署未开放生产，带云资源的版本建不出生产环境                            | 联系运维开放生产；只用宿主能力的应用不受影响                                            | `appid` |
+| `COMMIT_UNKNOWN` / 「结果待确认」                  | 网络中断，服务端可能已处理                                              | 用原操作号查询结果，**不要换个编号重新提交**                                            | 两者    |
 
 完整错误码见 [状态与错误码](status-codes.md)，平台未开放的能力见 平台边界与限制（文档站 /reference/limits）。