create-zleap-app 0.10.2 → 0.10.4
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.
- package/package.json +3 -3
- package/skills/zleap-cloud-app/SKILL.md +6 -6
- package/skills/zleap-cloud-app/references/app-runtime.md +1 -1
- package/skills/zleap-cloud-app/references/cloud-functions.md +19 -14
- package/skills/zleap-cloud-app/references/console-members.md +2 -2
- package/skills/zleap-cloud-app/references/limits.md +4 -4
- package/skills/zleap-cloud-app/references/permissions.md +2 -2
- package/skills/zleap-cloud-app/references/sdk-database-files.md +1 -1
- package/skills/zleap-cloud-app/references/status-codes.md +13 -8
- package/skills/zleap-cloud-app/references/triggers.md +4 -4
- package/skills/zleap-cloud-app-release/SKILL.md +21 -12
- package/skills/zleap-cloud-app-release/references/app-center-install.md +7 -5
- package/skills/zleap-cloud-app-release/references/app-center-publish.md +19 -13
- package/skills/zleap-cloud-app-release/references/console-functions.md +30 -18
- package/skills/zleap-cloud-app-release/references/console-legacy-release.md +2 -2
- package/skills/zleap-cloud-app-release/references/console-members.md +2 -2
- package/skills/zleap-cloud-app-release/references/console-release.md +29 -19
- package/skills/zleap-cloud-app-release/references/console-workspace.md +31 -19
- package/skills/zleap-cloud-app-release/references/dev-to-production.md +74 -61
- package/skills/zleap-cloud-app-release/references/permissions.md +2 -2
- package/skills/zleap-cloud-app-release/references/status-codes.md +13 -8
- package/templates/react-ts/scripts/zleap.mjs +11 -3
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-zleap-app",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.4",
|
|
4
4
|
"description": "一条命令创建 zleapOS 云开发应用（React + TypeScript + Vite），并为 Codex / Claude Code / Pi / OpenCode / Cursor 等 AI 编程工具配好 skills",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/
|
|
8
|
+
"url": "git+https://github.com/RuoFeng2015/zleap-app-kit.git",
|
|
9
9
|
"directory": "packages/create-zleap-app"
|
|
10
10
|
},
|
|
11
11
|
"type": "module",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"cliVersion": "0.10.0",
|
|
27
27
|
"sdkPackage": "@zleap-ai/app-sdk",
|
|
28
28
|
"sdkVersion": "0.10.0",
|
|
29
|
-
"skillsRepo": "
|
|
29
|
+
"skillsRepo": "RuoFeng2015/zleap-app-kit"
|
|
30
30
|
},
|
|
31
31
|
"keywords": [
|
|
32
32
|
"zleap",
|
|
@@ -31,7 +31,7 @@ npm create zleap-app@latest <目录> -- --appid <appid> --name "<应用名>" -y
|
|
|
31
31
|
（`zl` + 16 位小写十六进制，如 `zl3f9a2c7e1b0d4a68`），创建者自动成为管理员。没有 `appid` 时非交互脚手架会报错并提示先创建应用——问用户要，不要猜。
|
|
32
32
|
manifest 里写 `"appid": "<appid>"`，**不需要** `app_key` 和 `publisher`。旧项目的 `app_key`（如 `com.example.todo`）只为已有应用保留；`--app-key` 是 `--appid` 的旧别名。
|
|
33
33
|
同事要一起开发，请管理员在控制台「团队」→「成员」里把他加为开发者。每个成员的每次上传都是一个开发版本，在控制台「版本管理」里可见；
|
|
34
|
-
|
|
34
|
+
成员可以在「版本管理」用「切换到此版本」运行同事上传、未发布的版本（只切自己的安装；非成员看不到开发版本）。带云函数的版本上传时平台自动签名、安装 / 切换 / 允许后台运行时自动绑定，appid 应用不需要签名激活操作。给全企业用 = 在「版本管理」里「发布为线上版本」，见 skill `zleap-cloud-app-release`。
|
|
35
35
|
|
|
36
36
|
## 2. 硬性约束（违反就会在运行时失败）
|
|
37
37
|
|
|
@@ -51,7 +51,7 @@ manifest 里写 `"appid": "<appid>"`，**不需要** `app_key` 和 `publisher`
|
|
|
51
51
|
2. **权限**：需要的能力加进 `requires`（`cloud.database.read/write`、`cloud.storage.read/write`、`os.agent.complete` 等，白名单外的非可选能力会让应用「暂不可用」）。`reason` 会展示给用户，写具体用途。
|
|
52
52
|
3. **数据层**：React 模板在 `src/cloud/` 下按集合写一个模块（参照 `src/cloud/todos.ts`），组件只调用这些函数；错误用 `describeError()` 展示。
|
|
53
53
|
4. **本地验证**：`npm run typecheck && npm run check`（`check` 通过只代表静态契约，`runtime_test=not_checked`）。
|
|
54
|
-
5. **部署到自己桌面**：`npm run deploy`（构建 → 检查 →
|
|
54
|
+
5. **部署到自己桌面**：`npm run deploy`（构建 → 检查 → 上传开发版本（appid 应用仅成员可见）→ 安装/切换本人安装；内容变化时自动递增补丁号）。
|
|
55
55
|
- 报未登录/会话过期 → 请用户运行 `npm run login -- --target <OS 地址>` 并在浏览器核对确认码。
|
|
56
56
|
- 报 `DATA_MIGRATION_REQUIRED` → 新版本改了 data/storage 声明，见第 5 节。
|
|
57
57
|
6. **请用户验收**：安装时平台会自动创建开发环境、开通数据库并按声明建集合，`npm run deploy` 结束时会打印状态；显示未就绪时，请用户在「云开发控制台」选中应用 →「概览」按提示处理。然后从启动台打开应用（已打开的点「重新加载应用」）。
|
|
@@ -67,8 +67,8 @@ manifest 里写 `"appid": "<appid>"`，**不需要** `app_key` 和 `publisher`
|
|
|
67
67
|
再在**按钮点击事件里**调用 `zl.auth.authorize({ scopes: ['profile' | 'phone' | 'email'], reason: '用途说明' })`（不在点击里调用 `AUTH_GESTURE_REQUIRED`），
|
|
68
68
|
返回 `{ openid, scopes, profile?, phone?, email? }`——用户可以只勾选一部分、没绑定的不返回，**以 `scopes` 判断拿到了什么**；
|
|
69
69
|
拒绝时 `AUTH_DENIED`（拒绝过的项 24 小时内不再弹框，直接 `AUTH_DENIED`）。`zl.auth.getIdentity()` 静默拿 `openid`（每个应用不同、开发与线上一致）。
|
|
70
|
-
|
|
71
|
-
|
|
70
|
+
云函数里**没有** `zl.cloud.auth`（`getOpenId()` / `getUserInfo()` 都不可用）：需要 openid 时由页面 `getIdentity()` 取到后作为输入传给函数，或用文档自带的 `_openid`；不要用 `getContext().userId`（平台内部 ID，已废弃）。
|
|
71
|
+
不要自己做登录页或索要账号；云函数里读不到授权信息。
|
|
72
72
|
- 都从 `@zleap-ai/app-sdk` 导入（`import { zl, AppError } from '@zleap-ai/app-sdk'`），完整说明见 references/app-runtime.md。
|
|
73
73
|
|
|
74
74
|
## 4. 只有用户能做的事（明确告诉用户，不要假装已完成）
|
|
@@ -97,8 +97,8 @@ manifest 里写 `"appid": "<appid>"`，**不需要** `app_key` 和 `publisher`
|
|
|
97
97
|
| 连接超时 `CALL_TIMEOUT`、独立预览 | 不在 zleapOS 窗口里运行；部署后从启动台打开 |
|
|
98
98
|
| `RESOURCE_NOT_READY` / SDK 没协商到 `document-core/1` | 当前数据域没有环境或数据库未就绪 → 等 1 分钟后重开应用；仍不行请用户在控制台概览检查开发环境与数据库 |
|
|
99
99
|
| `SCOPE_FORBIDDEN` | 没授权（服务端原因 `CONSENT_REQUIRED` 等）→ 请用户点窗口顶部「权限」勾选保存；或 `requires` 没声明 |
|
|
100
|
-
| `ENV_FORBIDDEN` |
|
|
101
|
-
| `COLLECTION_NOT_FOUND`（上生产后） | 生产环境建了但没开通集合 →
|
|
100
|
+
| `ENV_FORBIDDEN` | 部署已开放生产、应用还没有生产环境，非成员打不开 → appid 应用：任一成员「发布为线上版本」（平台自动准备生产）；旧应用：发布者激活到生产（见 release skill） |
|
|
101
|
+
| `COLLECTION_NOT_FOUND`（上生产后） | 生产环境建了但没开通集合 → appid 应用重新「发布为线上版本」（生产库未就绪时发布会报 `PROD_DATABASE_NOT_READY`，稍后重试）；旧应用控制台生产环境「数据库」开通，或 `npx zleap-app prepare` |
|
|
102
102
|
| `PUBLISHER_REQUIRED` | 非发布者访问开发数据域（默认只给发布者） |
|
|
103
103
|
| `SCHEMA_INVALID` | 写入字段与集合结构不符（缺必填、类型错、多了字段） |
|
|
104
104
|
| `VERSION_CONFLICT` | 别处先改过，重读后再改 |
|
|
@@ -37,7 +37,7 @@ import { zl, AppError } from '@zleap-ai/app-sdk';
|
|
|
37
37
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
38
38
|
| 普通使用者（不是应用成员） | **下次打开应用时自动跟随**：宿主先把安装切到线上版本，显示「**正在更新到最新版本…**」，再加载应用。回退同样会跟随 |
|
|
39
39
|
| 已经开着应用的**非成员** | **不会立刻被打断**，继续用当前版本；应用可以用下面的更新管理器提示用户，调用 `applyUpdate()` 立即切换。新版本发布 **24 小时**后，宿主会把还开着旧版本的窗口强制切到线上版本并重新加载（显示「这个版本已超过 24 小时的使用期限，正在更新到最新版本…」） |
|
|
40
|
-
| 应用成员（管理员 / 开发者） |
|
|
40
|
+
| 应用成员（管理员 / 开发者） | **从不自动切换**，在控制台版本管理里用「切换到此版本」自己选（只影响自己，包括同事还没发布的版本） |
|
|
41
41
|
|
|
42
42
|
所以不写任何代码，使用者也会在下次打开时用上新版本。更新管理器只是让「正开着的窗口」也能及时换到新版本。
|
|
43
43
|
|
|
@@ -560,23 +560,24 @@ npx zleap-app publish dist
|
|
|
560
560
|
|
|
561
561
|
示例项目已经把这些串成脚本：`npm run deploy`（构建 → 检查 → 上传开发版本 → 装到自己桌面）、`npm run release -- --notes "…"`（发布为线上版本）。
|
|
562
562
|
|
|
563
|
-
|
|
563
|
+
上传时平台已自动签名，装到桌面时自动绑定，包上传后只差使用者本人一步：在应用窗口「权限」里勾选「统计我的互动」这项后台能力。定时触发器 `stats_refresh` 还要在控制台「触发器」里启用，否则只会手动调用时运行。
|
|
564
564
|
|
|
565
|
-
##
|
|
565
|
+
## 第三步：上传、安装、授权
|
|
566
566
|
|
|
567
567
|
函数代码写好后，要走完下面这条链才会真正执行。缺任何一步，调用都不会进入函数沙箱：
|
|
568
568
|
|
|
569
569
|
```
|
|
570
|
-
① 上传：zleap-app publish 或应用中心「上传应用包」
|
|
570
|
+
① 上传：npm run deploy / zleap-app publish 或应用中心「上传应用包」
|
|
571
|
+
声明了后台能力的版本，平台在上传时自动签名，得到就绪发布
|
|
571
572
|
② 安装（安装即授予声明的 cloud.* 权限；后台能力为「停用」）
|
|
573
|
+
安装、切换版本时平台自动把安装绑定到该版本的就绪发布；还没有就绪发布的版本会当场补签再绑定
|
|
572
574
|
③ 开发环境与数据库：声明了集合的应用安装时自动创建并开通（集合按声明自动创建）；否则在控制台「创建开发环境」
|
|
573
|
-
④
|
|
574
|
-
或在项目里运行 `npx zleap-app prepare <app_id> --version-id <id>`（只准备开发环境）
|
|
575
|
-
概览开通清单里对应「去签名」/「升级安装并激活」；这里只列出你本人上传的版本
|
|
576
|
-
⑤ 应用窗口「权限」→「后台能力（定时任务 / 云函数）」勾选该能力 →「保存并重新加载」
|
|
575
|
+
④ 应用窗口「权限」→「后台能力（定时任务 / 云函数）」勾选该能力 →「保存并重新加载」
|
|
577
576
|
（或在控制台「后台能力」里点「允许后台运行」）
|
|
578
577
|
```
|
|
579
578
|
|
|
579
|
+
appid 应用没有单独的签名、激活步骤。旧 `app_key` 应用在 ② 之后还要到控制台「版本与激活」完成「验证并签发」和「激活开发」，见 版本与激活（文档站 /console/legacy-release#激活开发）。
|
|
580
|
+
|
|
580
581
|
详细界面见 版本管理（文档站 /console/release）、云函数与后台能力（文档站 /console/functions）、安装与卸载（文档站 /app-center/install），
|
|
581
582
|
端到端顺序见 从开发到上线（文档站 /guide/dev-to-production）。
|
|
582
583
|
|
|
@@ -584,17 +585,17 @@ npx zleap-app publish dist
|
|
|
584
585
|
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
585
586
|
| 没有任何已启用的后台能力 | 会话里没有 `app-execution/1`，前端 `callFunction` / `capabilities.invoke` **在发请求前**就抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 为 `UNSUPPORTED_OPERATION`） |
|
|
586
587
|
| 这项能力没被授权 | 403「此能力尚未由用户授权」 |
|
|
587
|
-
|
|
|
588
|
+
| `managed_function` 没绑定就绪发布（appid 应用正常不会出现） | `FUNCTION_RELEASE_REQUIRED`；「权限」对话框里该项下方提示「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签；旧应用请到云开发控制台「版本与激活」完成「激活开发」。」 |
|
|
588
589
|
| 部署没接入函数计算节点 / 调度服务 | `FUNCTION_RUNTIME_UNAVAILABLE`（平台未开放，不是你写错了） |
|
|
589
590
|
|
|
590
|
-
###
|
|
591
|
+
### 开发环境 ≠ 生产发布
|
|
591
592
|
|
|
592
|
-
|
|
593
|
+
上面这条链只让云函数在**开发环境**运行。要让其他使用者在生产环境用上它：
|
|
593
594
|
|
|
594
|
-
- **appid 应用**：把版本「发布为线上版本」（控制台「版本管理」，或 `zleap-app release
|
|
595
|
+
- **appid 应用**：把版本「发布为线上版本」（控制台「版本管理」，或 `zleap-app release`）。任一成员都可以发布任一版本，不要求上传者正在使用这个版本。带云资源的版本**第一次**发布时，平台自动完成**应用级**生产准备：生产环境 → 签发生产发布（归属上传者）→ 生产门禁（签名、审批窗口、信任策略核对）→ 生产库与生产集合，不依赖任何人的安装。生产库还没就绪时返回 40900（`PROD_DATABASE_NOT_READY`），通常 1 分钟内就绪，稍后重新发布即可；上传者账号已停用时返回 40900（`UPLOADER_INACTIVE`），请其他成员重新上传这个版本后再发布。已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。只用宿主能力的应用直接发布，不需要签名激活。
|
|
595
596
|
- **旧 `app_key` 应用**：继续在「版本与激活」里走发布候选 / 签名 / 激活。
|
|
596
597
|
|
|
597
|
-
`zleap-app prepare` 对两类应用都可用：**appid
|
|
598
|
+
`zleap-app prepare` 对两类应用都可用：**appid 应用**通常不需要，只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用（只准备开发环境，不会碰生产），
|
|
598
599
|
准备完成后用 `zleap-app invoke <app_id> --capability <id> --environment dev` 测试；**旧 `app_key` 应用**只接受本人 private 包，一路准备到生产。
|
|
599
600
|
|
|
600
601
|
`logic_unit` 和 `builtin` provider 不进函数沙箱，**不需要**签名发布，授权后台能力即可执行。
|
|
@@ -830,8 +831,12 @@ const job = await zl.cloud.os.capabilities.invoke({
|
|
|
830
831
|
|
|
831
832
|
### `FUNCTION_RELEASE_REQUIRED`
|
|
832
833
|
|
|
833
|
-
`managed_function`
|
|
834
|
-
|
|
834
|
+
`managed_function` 必须绑定**就绪**的发布。
|
|
835
|
+
|
|
836
|
+
- **appid 应用**：正常情况下不会出现（上传自动签名，安装 / 切换版本 / 保存权限时自动绑定，缺签随用随签）。如果出现，在应用窗口「权限」里重新保存一次，或在控制台「版本管理」切换一次版本，平台会自动补签并绑定；仍然出现，说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传。
|
|
837
|
+
- **旧 `app_key` 应用**：到控制台「版本与激活」完成「验证并签发」和「激活开发」，见 版本与激活（文档站 /console/legacy-release#激活开发）。
|
|
838
|
+
|
|
839
|
+
处理后重新打开应用窗口「权限」确认该能力下没有「还没有可用的签名发布」的提示，再重新加载应用。
|
|
835
840
|
|
|
836
841
|
### `RUNTIME_GATEWAY_UNAVAILABLE` / 其他 `RUNTIME_GATEWAY_*`
|
|
837
842
|
|
|
@@ -123,8 +123,8 @@
|
|
|
123
123
|
|
|
124
124
|
用 `appid` 的应用里，每个成员上传的都是一个**开发版本**，全部列在侧栏「发布」组的「版本管理（文档站 /console/release#版本管理）」里，标出上传者和上传时间：
|
|
125
125
|
|
|
126
|
-
-
|
|
127
|
-
-
|
|
126
|
+
- 任何成员（管理员或开发者）都可以把任一成员上传的版本「发布为线上版本」，或「回退到此版本」，不要求上传者正在使用这个版本；
|
|
127
|
+
- 「切换到此版本」只把你本人桌面上的应用切到任一成员上传的版本，包括同事还没发布的版本（方便联调），不影响其他人，也不改变线上版本；成员从不被自动切换；
|
|
128
128
|
- 开发版本只对成员可见，不是成员的人看不到、也切不到。
|
|
129
129
|
|
|
130
130
|
## 用户授权
|
|
@@ -19,16 +19,16 @@
|
|
|
19
19
|
| 云数据库 | ✅ 开放 | 集合按 Manifest 自动创建；文档、索引、备份恢复 |
|
|
20
20
|
| 文件存储 | ✅ 开放 | 分块上传、下载、条件覆盖、软删除 |
|
|
21
21
|
| 日志 | ✅ 开放 | 查询 + 追尾；生产环境只读，发布者可见全部调用日志 |
|
|
22
|
-
| 云函数 / 后台能力 | ⚠️ 视部署而定 |
|
|
23
|
-
| 控制台版本页 · 发布候选、签名验证 | ✅ 开放 |
|
|
24
|
-
| 控制台版本页 · 激活开发 | ✅ 开放 |
|
|
22
|
+
| 云函数 / 后台能力 | ⚠️ 视部署而定 | 需要部署了函数运行环境；还需就绪的签名发布（`appid` 应用上传时自动签名、自动绑定；旧应用需签发并激活）并授权 |
|
|
23
|
+
| 控制台版本页 · 发布候选、签名验证 | ✅ 开放 | 仅旧 `app_key` 应用（「版本与激活」）；`appid` 应用上传时自动签名，没有手动步骤。签名需部署配置发布信任策略，否则报「发布信任策略尚未配置…」 |
|
|
24
|
+
| 控制台版本页 · 激活开发 | ✅ 开放 | 仅旧 `app_key` 应用：把已就绪候选绑定到当前安装的开发环境；`appid` 应用在安装、切换版本、授权时自动绑定 |
|
|
25
25
|
| 控制台版本页 · 激活到生产 | ⚠️ 视部署而定 | `appid` 应用首次「发布为线上版本」会自动准备生产；发布信任配置未就绪时控制台没有生产入口，开放后需通过生产门禁 |
|
|
26
26
|
| 生产环境数据 / 文件管理（控制台） | ⚠️ 视部署而定 | 生产开放后可在控制台查看和修改（页面有影响范围提示） |
|
|
27
27
|
| 应用中心 · 更新 / 回滚 | ✅ 开放 | 有升级预检；只切换当前用户自己的安装 |
|
|
28
28
|
| 应用中心 · 企业目录上架（旧应用） | ✅ 开放 | 仅旧 `app_key` 应用；无审核步骤，见 上传与发布（文档站 /app-center/publish） |
|
|
29
29
|
| 控制台 · 发布为线上版本（`appid`） | ✅ 开放 | 控制台「发布 → 版本管理」；发布后全企业可见，无审核步骤 |
|
|
30
30
|
| 应用成员（管理员 / 开发者） | ✅ 开放 | 控制台「团队」→「成员」，见 [成员管理](console-members.md) |
|
|
31
|
-
| 使用其他成员上传的开发版本（`appid`） | ✅ 开放 | 版本可见性为 `members
|
|
31
|
+
| 使用其他成员上传的开发版本（`appid`） | ✅ 开放 | 版本可见性为 `members`；成员在「版本管理」里用「切换到此版本」切换（只影响自己） |
|
|
32
32
|
| 旧 `app_key` 应用使用别人上传的 private 版本 | ❌ 未开放 | private 版本只有上传者本人能安装；其他人只能安装企业可见版本 |
|
|
33
33
|
| 纯后台（`headless`）应用 | ❌ 基本不可用 | 声明云函数等即「运行环境未开放」，请用 `both` |
|
|
34
34
|
| `agent.interaction` | ❌ 未开放 | 声明会导致应用无法安装 |
|
|
@@ -196,7 +196,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
|
|
|
196
196
|
> 授权后，本应用可在关窗后按你勾选的能力运行（如定时巡检），只作用于你本人的数据，其他使用者看不到。
|
|
197
197
|
|
|
198
198
|
- 授权限定在**这个安装 + 这个版本 + 这个环境**；每一步执行前都会重新检查；
|
|
199
|
-
- `managed_function
|
|
199
|
+
- `managed_function`（云函数）还要求绑定**就绪**的签名发布，否则该项下方提示「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签；旧应用请到云开发控制台「版本与激活」完成「激活开发」。」，调用返回 `FUNCTION_RELEASE_REQUIRED`。appid 应用由平台在上传时自动签名、在这里保存（或允许 / 撤销后台运行）时自动绑定，缺签时当场补签，正常不会看到这条提示；旧 `app_key` 应用到控制台「版本与激活」完成「验证并签发」和「激活开发」；
|
|
200
200
|
- `logic_unit` / `builtin` provider 不需要发布；
|
|
201
201
|
- `os.agent.complete` 等内置动作同样是一项后台能力，要在这里启用后才能调用。
|
|
202
202
|
|
|
@@ -340,7 +340,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
|
|
|
340
340
|
| 云函数访问不到字段 | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？ |
|
|
341
341
|
| 用户之间看不到彼此数据 | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"` |
|
|
342
342
|
| 前端调用后台能力 `BACKGROUND_CAPABILITY_UNAVAILABLE` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载（旧 SDK 报 `UNSUPPORTED_OPERATION`） |
|
|
343
|
-
| 云函数 `FUNCTION_RELEASE_REQUIRED` |
|
|
343
|
+
| 云函数 `FUNCTION_RELEASE_REQUIRED` | appid 应用：在应用窗口「权限」里重新保存一次，或在「版本管理」切换一次版本，平台自动补签并绑定；仍出现请联系平台管理员检查签名密钥 / 信任配置，或重新上传。旧应用：到「版本与激活」完成「验证并签发」与「激活开发」 |
|
|
344
344
|
| 更新版本后后台任务不跑了 | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力 |
|
|
345
345
|
| 跨应用调用失败 | 普通 SDK 不支持跨应用调用 |
|
|
346
346
|
|
|
@@ -118,7 +118,7 @@ const caps = await zl.cloud.os.ready();
|
|
|
118
118
|
| `document-core/1` | `get` / `count` / `add` / `set` / `update` / `remove` / `operations.get` | 数据库已就绪、Manifest 的 `data.collections` 非空、已授予 `cloud.database.read` 或 `write`（`data.schemas` 可选，不写就是灵活集合） |
|
|
119
119
|
| `watch-snapshot/1` | `watch()` | 在上一条基础上，声明并授予了 `cloud.database.read` |
|
|
120
120
|
| `storage-object/1` | `uploadFile` / `downloadFile` / `deleteFile` / `os.files.*` | 部署启用了对象存储、授予了 `cloud.storage.read` 或 `write`；生产数据域还要求当前安装绑定了已就绪的签名发布 |
|
|
121
|
-
| `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` |
|
|
121
|
+
| `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` | 当前安装有已启用的后台能力授权（在应用窗口「权限」里勾选了后台能力；`appid` 应用的发布绑定由平台自动完成，旧 `app_key` 应用还需「激活开发」）；缺失时抛 `BACKGROUND_CAPABILITY_UNAVAILABLE` |
|
|
122
122
|
|
|
123
123
|
```js
|
|
124
124
|
const { profiles } = await zl.cloud.os.ready();
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
| **权限类** | `SCOPE_FORBIDDEN`、`RULE_DENIED`、`ENV_FORBIDDEN` | 去授权或改规则，不要盲目重试 |
|
|
13
13
|
| **数据类** | `SCHEMA_INVALID`、`VERSION_CONFLICT`、`INDEX_REQUIRED` | 改代码、改数据或建索引 |
|
|
14
14
|
| **结果未知** | `COMMIT_UNKNOWN`、`NODE_LOST` | **用原操作编号查询**，不要换编号重试 |
|
|
15
|
-
| **未就绪** | `RESOURCE_NOT_READY`、`FUNCTION_RELEASE_REQUIRED` | 等开通完成 /
|
|
15
|
+
| **未就绪** | `RESOURCE_NOT_READY`、`FUNCTION_RELEASE_REQUIRED` | 等开通完成 / 发布就绪并绑定后再试 |
|
|
16
16
|
| **繁忙或超限** | `APP_RATE_LIMITED`、`RESOURCE_EXHAUSTED` | 稍后重试，或按提示清理数据、调整用法 |
|
|
17
17
|
| **临时故障** | `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE` | 可以重试 |
|
|
18
18
|
| **平台未开放** | `UNSUPPORTED_OPERATION`、`FEATURE_UNAVAILABLE` | 改实现，重试无用 |
|
|
@@ -166,7 +166,7 @@
|
|
|
166
166
|
|
|
167
167
|
| 错误码 | 含义 | 处理 |
|
|
168
168
|
| ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
169
|
-
| `FUNCTION_RELEASE_REQUIRED` |
|
|
169
|
+
| `FUNCTION_RELEASE_REQUIRED` | 当前安装还没有绑定就绪的签名发布 | `appid` 应用：正常不会出现；在应用窗口「权限」里重新保存一次，或在控制台「版本管理」切换一次版本，平台自动补签并绑定；仍出现说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传。旧 `app_key` 应用：到「版本与激活」完成「验证并签发」和「激活开发」 |
|
|
170
170
|
| `RELEASE_UNAVAILABLE` | 发布代数已变化（激活了新版本），旧会话作废 | 宿主会自动重开会话并重试一次；仍失败时重新打开应用 |
|
|
171
171
|
| `RELEASE_NOT_READY` | 发布候选尚未就绪 | 先完成签发 |
|
|
172
172
|
| `RELEASE_DISABLED` | 发布候选已撤回 | 使用其他就绪候选 |
|
|
@@ -331,7 +331,7 @@
|
|
|
331
331
|
| ------------------------------------ | --------------------------------------- | ---------------------------------------- |
|
|
332
332
|
| 50390 | 应用执行worker尚未启用 | 部署未开放后台执行，联系管理员 |
|
|
333
333
|
| 50390 `FUNCTION_RUNTIME_UNAVAILABLE` | 应用执行需要共享调度服务 | 同上 |
|
|
334
|
-
| 40300 `FUNCTION_RELEASE_REQUIRED` | 云函数必须绑定已验证发布 |
|
|
334
|
+
| 40300 `FUNCTION_RELEASE_REQUIRED` | 云函数必须绑定已验证发布 | 见 [发布与后台调用](#发布与后台调用) |
|
|
335
335
|
| 40900（无原因码） | 同一操作编号的输入不同 | 新调用用新的操作编号 |
|
|
336
336
|
| 40900（无原因码） | 首次受理操作已过期 | 用新的操作编号重新提交 |
|
|
337
337
|
| 42900 | 调用历史容量已满 / 本人后台调用队列已满 | 等在途作业结束后再提交（每人最多 16 个） |
|
|
@@ -406,7 +406,8 @@
|
|
|
406
406
|
|
|
407
407
|
`zleap-app prepare` 的特殊结果：
|
|
408
408
|
|
|
409
|
-
- **平台 `appid`
|
|
409
|
+
- **平台 `appid` 应用**通常不需要 `prepare`（上传自动签名、安装 / 切换版本时自动绑定），只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用。
|
|
410
|
+
它只准备开发环境：只声明数据的应用在开发权限阶段后结束，`status` 为 **`ready`**，响应里 `"environment": "dev"`；
|
|
410
411
|
Manifest 声明了 headless 后台能力时，还会创建发布候选、签名并激活到开发。
|
|
411
412
|
- **旧 `app_key` 应用**没有声明云资源（无 `cloud.*` 权限、无后台能力、无集合）时直接返回 `status` 为 **`not_required`**，
|
|
412
413
|
`next` 提示「应用未声明云资源或后台执行，安装后即可运行」。
|
|
@@ -422,7 +423,7 @@
|
|
|
422
423
|
>
|
|
423
424
|
> - **平台 `appid` 应用**：接受**本人上传**的版本（可见性 `private` 或 `members`），只准备开发环境
|
|
424
425
|
> （开发环境 → 数据库 → 开发数据域权限，声明了 headless 时再加签名并激活到开发），不会碰生产；
|
|
425
|
-
> 生产由**首次 `release
|
|
426
|
+
> 生产由**首次 `release`（发布为线上版本）**自动准备。appid 应用通常不需要它，只在 `diagnose` 提示 `next_action: app_prepare` 时兜底使用。
|
|
426
427
|
> - **旧 `app_key` 应用**：只接受**本人 private、且已安装**的包，一路准备到生产。
|
|
427
428
|
|
|
428
429
|
`zleap-app publish` 等写操作网络结果不明时返回 `COMMIT_UNKNOWN`，**不会自动重传**：
|
|
@@ -474,7 +475,8 @@
|
|
|
474
475
|
|
|
475
476
|
| 业务码 | message | `detail.reason` | 处理（`next_action`） |
|
|
476
477
|
| ------ | -------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
477
|
-
| 40900 |
|
|
478
|
+
| 40900 | 生产数据库还没就绪，暂时不能发布 | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪，稍后在版本管理里重新发布；持续失败请在控制台「数据库」查看状态 |
|
|
479
|
+
| 40900 | 这个版本的上传者账号已停用，无法发布 | `UPLOADER_INACTIVE` | 请其他成员重新上传这个版本（npm run deploy）后再发布 |
|
|
478
480
|
| 40900 | 这个应用请在云开发控制台「版本管理」里发布或回退 | `USE_VERSION_MANAGEMENT` | 应用中心不能改平台 `appid` 应用的线上版本；到控制台「发布 → 版本管理」点「发布为线上版本」或「回退到此版本」 |
|
|
479
481
|
| 40900 | 该应用使用旧的命名空间标识，请在「版本与激活」里管理版本 | `LEGACY_APP` | 旧 `app_key` 应用走「版本与激活」 |
|
|
480
482
|
| 40400 | 版本不存在或已删除 / 该版本没有可用制品 | — | 刷新版本列表后重试 |
|
|
@@ -484,11 +486,14 @@
|
|
|
484
486
|
`USE_VERSION_MANAGEMENT` 来自应用中心的「发布到企业目录 / 撤回企业目录」接口，不是版本管理接口本身的错误；
|
|
485
487
|
它表示**这个应用不该在应用中心改线上状态**。平台 `appid` 应用请改用控制台「版本管理」。
|
|
486
488
|
|
|
487
|
-
|
|
489
|
+
任一成员都可以发布任一版本，不要求上传者正在使用这个版本。带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本**第一次**发布时，
|
|
490
|
+
平台自动完成应用级生产准备（生产环境 → 签发生产发布 → 生产门禁 → 生产库与生产集合），`PROD_DATABASE_NOT_READY`、`UPLOADER_INACTIVE` 只在这一步出现；
|
|
491
|
+
生产门禁不通过时返回与激活相同的原因码（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`，见 [发布与激活](#发布与激活)），重新发布即会重新签发。
|
|
492
|
+
已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。见 版本管理 · 带云资源的版本（文档站 /console/release#带云资源的版本）。
|
|
488
493
|
|
|
489
494
|
## 版本更新与回滚
|
|
490
495
|
|
|
491
|
-
###
|
|
496
|
+
### 版本切换（控制台「切换到此版本」/ CLI `update`、`rollback`）
|
|
492
497
|
|
|
493
498
|
这些码来自安装版本切换接口（`appversion/read.go`、`official.go`、`apply.go`）：
|
|
494
499
|
|
|
@@ -115,8 +115,8 @@
|
|
|
115
115
|
|
|
116
116
|
1. 触发器指向的**后台能力已启用**：在应用窗口「权限」的「后台能力（定时任务 / 云函数）」里勾选，
|
|
117
117
|
或在 后台能力面板（文档站 /console/functions#后台能力） 点「允许后台运行」（安装时后台能力一律是停用）；
|
|
118
|
-
2. 如果该能力的 provider 是云函数（`managed_function
|
|
119
|
-
|
|
118
|
+
2. 如果该能力的 provider 是云函数（`managed_function`），当前安装还要绑定**就绪**的签名发布，否则执行时报 `FUNCTION_RELEASE_REQUIRED`。
|
|
119
|
+
appid 应用由平台在上传时自动签名、安装 / 切换版本 / 授权时自动绑定，不需要手动操作；旧 `app_key` 应用要在版本与激活（文档站 /console/legacy-release#激活开发）完成「激活开发」；
|
|
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"
|
|
381
|
+
`background.modes` 里没有 `"scheduled"`（或 `"events"`）。补上后上传新版本、把安装更新到该版本（appid 应用切换时平台自动绑定新版本的就绪发布；旧 `app_key` 应用云函数类能力还要重新「激活开发」）。
|
|
382
382
|
|
|
383
383
|
### 报 `TRIGGER_NOT_DECLARED`
|
|
384
384
|
|
|
@@ -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`
|
|
403
|
+
2. 云函数类能力：当前安装绑定了就绪发布吗？运行记录里出现 `FUNCTION_RELEASE_REQUIRED` 时，appid 应用在应用窗口「权限」里重新保存一次或在「版本管理」切换一次版本（平台自动补签并绑定），旧 `app_key` 应用到「版本与激活」完成「激活开发」；
|
|
404
404
|
3. 「接下来」的时间是不是还没到？
|
|
405
405
|
4. 数据库是否正在冻结（备份/恢复中）？
|
|
406
406
|
5. 看卡片的「最近投递」，再到 日志（文档站 /console/logs） 按调用编号查有没有执行记录。
|
|
@@ -20,17 +20,19 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
20
20
|
|
|
21
21
|
要点：
|
|
22
22
|
- 只用宿主能力（无 `data.collections`、无 `cloud.*`、无 `runtime.backend`、无 headless provides）的版本：发布即可用，不需要签名、激活和环境。
|
|
23
|
-
-
|
|
24
|
-
|
|
23
|
+
- 带云资源的版本：**第一次**发布时平台自动完成**应用级**生产准备（生产环境 → 签发生产发布（归属上传者）→ 生产门禁 → 生产库与集合），
|
|
24
|
+
不依赖任何人的安装：**任一成员可以发布任一成员上传的版本**，不要求上传者正在用它。再次发布 / 回退直接复用当时的就绪发布。
|
|
25
|
+
可能的 40900（看 `detail.reason`）：`PROD_DATABASE_NOT_READY`（生产库还没就绪，稍后重新发布）、`UPLOADER_INACTIVE`（上传者账号已停用，请其他成员重新上传后再发布）；
|
|
26
|
+
生产门禁不通过时 reason 与激活相同（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`），重新发布会重新签发。
|
|
25
27
|
- 已开着应用的人不被打断；非成员下次打开时自动跟随到线上版本（「正在更新到最新版本…」）；成员从不被自动切换。
|
|
26
28
|
想让开着的窗口及时更新，在应用里用 `zl.app.getUpdateManager()`（见 skill `zleap-cloud-app` 的 references/app-runtime.md）。
|
|
27
|
-
-
|
|
29
|
+
- 成员可在「版本管理」用「**切换到此版本**」把**自己的**安装切到任一成员上传的版本（含同事未发布的版本），不影响别人、不改线上版本；开发版本只对成员可见。
|
|
28
30
|
- 接口（成员）：`GET /api/v1/app-cloud/apps/{app_id}/versions`、`POST /api/v1/app-cloud/apps/{app_id}/publish` `{version_id, notes?}`。
|
|
29
31
|
**发布影响全企业使用者：只有用户明确说「发布 / 上线 / 回退到 x」时才执行，执行前复述要发布的版本号。**
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
- 带云函数的版本在开发环境调试**不需要签名 / 激活操作**：上传时平台自动签名，安装 / 切换版本 / 在应用窗口「权限」里允许后台运行时自动绑定
|
|
33
|
+
（版本还没签名时当场补签）。用户在应用窗口「权限」里允许后台运行后，`npx zleap-app invoke <app_id> --capability <id> --environment dev` 调试。
|
|
34
|
+
控制台没有「开发环境：云函数激活」区块，也没有「我也用这个」（已改名「切换到此版本」）。
|
|
35
|
+
- `npx zleap-app prepare` 对 appid 应用只是兜底：仅当 `npx zleap-app diagnose` 返回 `next_action: app_prepare` 时用，只准备开发环境、不碰生产，只能准备本人上传的版本。
|
|
34
36
|
|
|
35
37
|
旧 `app_key` 命名空间应用（`com.example.xxx`）继续按下文走「版本与激活」（references/console-legacy-release.md）。
|
|
36
38
|
|
|
@@ -61,7 +63,14 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
61
63
|
|
|
62
64
|
## 3. 有后台能力 / 云函数的应用（开发环境）
|
|
63
65
|
|
|
64
|
-
|
|
66
|
+
**appid 应用**（AI 能做的是命令与代码，界面操作要请用户完成）：
|
|
67
|
+
|
|
68
|
+
1. **上传**：`npm run deploy`。带 headless 能力的版本上传时平台自动签名，deploy 把本人安装切到新版本时自动绑定。
|
|
69
|
+
2. **允许后台运行**（用户）：应用窗口顶部「权限」→ 勾选「后台能力（定时任务 / 云函数）」下的能力 →「保存并重新加载」。版本还没签名时保存这一步会自动补签并绑定。
|
|
70
|
+
3. **试调**：同下文第 5 步（`invoke` / `invocation` / `runtime-logs`）。报 `FUNCTION_RELEASE_REQUIRED`：请用户在「权限」里重新保存一次或在「版本管理」切换一次版本（会自动补签）；仍失败说明部署的签名服务不可用，交给平台管理员。
|
|
71
|
+
4. **触发器**：同下文第 6 步。控制台「云函数」页允许 / 撤销授权**不会**解除 appid 应用的发布绑定。
|
|
72
|
+
|
|
73
|
+
**旧 `app_key` 应用**，顺序很重要，按此执行：
|
|
65
74
|
|
|
66
75
|
1. **上传**：`npm run deploy`（含 `cloudfunctions/` 的包也可以，校验规则与应用中心上传一致）；也可由用户在应用中心「我的发布」→「上传应用包」上传，再在应用详情「安装」。
|
|
67
76
|
2. **签名**（用户）：云开发控制台 →「版本与激活」，在该版本的草稿候选上点「验证并签发」→ 状态变「已就绪」。没有草稿就「新建发布候选」。
|
|
@@ -75,7 +84,7 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
75
84
|
|
|
76
85
|
坑：
|
|
77
86
|
- 激活和允许后台运行**没有先后要求**，但两者都做了后台能力才会执行。激活到还没有的环境时平台会自动创建该环境。
|
|
78
|
-
-
|
|
87
|
+
- 旧 `app_key` 应用：在控制台「云函数」页点「允许后台运行 / 撤销授权 / 重新授权」会**解除发布绑定**，之后要重新「激活开发」（appid 应用不会解除）。
|
|
79
88
|
- `managed_function` 必须绑定就绪发布，否则 `FUNCTION_RELEASE_REQUIRED`；`builtin`、`logic_unit` 在开发环境不需要。
|
|
80
89
|
- 激活新发布后旧会话失效（`RELEASE_UNAVAILABLE`），宿主会自动重开。
|
|
81
90
|
- 云函数里 `zl.cloud.os.database.query` / `mutate` **都必须带 `request_id`**（非空、≤128，用 `` `${context.invocationId}:用途` ``），否则网关拒绝、未捕获时整次调用 `USER_EXCEPTION`。
|
|
@@ -102,7 +111,7 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
102
111
|
- 命令行：`npx zleap-app market-publish <package_id> --app-key <appid>`（是 **package_id**，在 `.zleap/state.json` 或 publish 回执里，不是 app_id）。撤回：`market-unpublish`。无审核步骤。
|
|
103
112
|
- 应用中心：「我的发布」→「管理版本」→ 版本行「发布到企业目录」。
|
|
104
113
|
- 同事在「发现」里安装；后台能力仍需同事自己在应用窗口「权限」里允许。
|
|
105
|
-
-
|
|
114
|
+
- 让同事**一起开发**（上传、在控制台管理）是另一回事：管理员在控制台「团队」→「成员」里把他加为开发者。所有成员的上传都在「版本管理」里，成员之间可以用「切换到此版本」互相使用（含未发布的版本）。
|
|
106
115
|
- **撤回企业目录会让其他人已安装的该版本无法打开**——执行前告诉用户。
|
|
107
116
|
- 应用中心上传的新版本，若该应用已有企业可见版本会自动继承企业可见；`zleap-app publish` 永远是 private。
|
|
108
117
|
- 同事用「更新」升级到新版本，**新版本必须先签成「已就绪」**，否则更新被拦下。
|
|
@@ -123,7 +132,7 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
123
132
|
- [ ] 集合结构已定稿（上线后不能改）
|
|
124
133
|
- [ ] `npx zleap-app check <dist 或项目> --target <OS>` 在目标部署上通过
|
|
125
134
|
- [ ] 控制台开通清单前 3 步完成，「运行体检」通过
|
|
126
|
-
- [ ]
|
|
135
|
+
- [ ] （有后台）后台能力已允许、函数「可调用」（旧应用另需已签名、已激活开发）
|
|
127
136
|
- [ ] 同一版本完成真实读写验证（用户手动，或 `zleap-app test` 浏览器验收）
|
|
128
137
|
- [ ] （生产开放）生产环境已建、门禁 7 项通过、已激活生产
|
|
129
138
|
- [ ] 已发布到企业目录，同事侧安装后能打开并读写
|
|
@@ -132,7 +141,7 @@ manifest 里是 `"appid": "zl…"`（控制台「创建应用」得到的平台
|
|
|
132
141
|
|
|
133
142
|
- references/dev-to-production.md — 端到端流程（十个阶段、四种路线、常见卡点）
|
|
134
143
|
- references/console-release.md — 「版本管理」（appid 应用：发布线上版本、回退、命令行发布）
|
|
135
|
-
- references/console-legacy-release.md —
|
|
144
|
+
- references/console-legacy-release.md — 「版本与激活」页（旧应用：候选、签名、激活、生产门禁、使用情况）
|
|
136
145
|
- references/console-functions.md — 后台能力授权、试运行、触发器
|
|
137
146
|
- references/console-workspace.md — 概览开通清单与运行体检
|
|
138
147
|
- references/app-center-publish.md / app-center-install.md — 上传、企业目录、安装授权、更新回退
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
>
|
|
22
22
|
> 创建了但还没上传过任何版本的应用是草稿，不会出现在应用中心。
|
|
23
23
|
>
|
|
24
|
-
> 想装其他版本，先装上，再用「更新」或 CLI `update`
|
|
24
|
+
> 想装其他版本，先装上，再用「更新」或 CLI `update` 切换；应用成员也可以在控制台「版本管理」里用「**切换到此版本**」直接切换到某个开发版本（只影响自己桌面上的应用）。
|
|
25
25
|
|
|
26
26
|
### 安装确认框
|
|
27
27
|
|
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
| 安装之后 | 还需要什么 |
|
|
67
67
|
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
68
68
|
| 云数据库 / 存储能读写 | 云环境、数据库、集合已就绪（声明了集合的应用安装时会自动创建开发环境并开通，通常一分钟内），且仍要过数据面的 ACL 检查 |
|
|
69
|
-
| 后台任务 / 云函数会运行 |
|
|
69
|
+
| 后台任务 / 云函数会运行 | **不会自动启动**：安装时后台能力被预置为「停用」，需要在应用窗口「权限」里勾选；安装还要绑定就绪发布（`appid` 应用由平台自动签名、自动绑定，旧应用要手动签发并激活） |
|
|
70
70
|
| 定时任务 | 开发者开放了的定时任务，在「权限」里对应后台能力下面有开关，自己决定开不开；时间和内容由开发者定 |
|
|
71
71
|
| Agent 能调用你的应用 | 安装不授予 Agent 调用权限 |
|
|
72
72
|
|
|
@@ -138,7 +138,7 @@
|
|
|
138
138
|
宿主发现线上版本和自己装的不一样，会先把安装切到线上版本，显示「**正在更新到最新版本…**」，再加载应用；
|
|
139
139
|
- **已经开着的窗口不会立刻被打断**：宿主每 20 秒检查一次更新，先通过 `zl.app.getUpdateManager()` 通知应用，应用可以用 `onUpdateReady` 提示用户、调用 `applyUpdate()` 立即切换，见 版本更新与授权登录（文档站 /reference/app-runtime#版本更新）；
|
|
140
140
|
- 但宽限期只有 **24 小时**：新线上版本发布 24 小时后，**非成员**的旧窗口会被强制切换并重新加载，提示「**这个版本已超过 24 小时的使用期限，正在更新到最新版本…**」；
|
|
141
|
-
- 应用成员（管理员 /
|
|
141
|
+
- 应用成员（管理员 / 开发者）**从不被自动切换**，他们在控制台「版本管理」里用「**切换到此版本**」自己选版本（只影响自己，含同事未发布的开发版本）。
|
|
142
142
|
|
|
143
143
|
下面的「更新」页、回滚和 CLI 切换照常可用。
|
|
144
144
|
|
|
@@ -179,7 +179,8 @@
|
|
|
179
179
|
> **目标版本必须有「就绪」的发布**（注意）
|
|
180
180
|
>
|
|
181
181
|
> 应用中心前端还会检查目标版本的 `release_id`：为空时显示「该版本尚未发布（release）。切过去后云函数等后台能力无法激活，请先由发布者签发该版本。」并阻止升级——包括没有云函数的纯前端应用（服务端预检对纯前端应用其实不拦，这是前后端判定不一致）。
|
|
182
|
-
>
|
|
182
|
+
> 所以旧 `app_key` 应用发布新版本给同事前，先在控制台「版本与激活」里把它签发到「就绪」。
|
|
183
|
+
> 平台 `appid` 应用不需要手动签发：声明了后台能力的版本上传时平台已自动签名，使用者也会自动跟随线上版本（见上文）。
|
|
183
184
|
|
|
184
185
|
**更新时授权怎么处理**（`appversion/apply.go`）：
|
|
185
186
|
|
|
@@ -276,7 +277,8 @@ CLI 走的是开发会话接口（`appinstallation/version.go` 的 `SwitchVersio
|
|
|
276
277
|
|
|
277
278
|
> 授权后，本应用可在关窗后按你勾选的能力运行（如定时巡检），以你的身份读写你在本应用中的数据。
|
|
278
279
|
|
|
279
|
-
|
|
280
|
+
勾选了但该版本还没有可用的签名发布时，会提示：「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签；旧应用请到云开发控制台「版本与激活」完成「激活开发」。」
|
|
281
|
+
`appid` 应用正常不会看到这条提示：上传时平台已自动签名，保存权限时会自动绑定（必要时当场补签）。
|
|
280
282
|
|
|
281
283
|
**主按钮**：**保存并重新加载**。二次确认：
|
|
282
284
|
|
|
@@ -27,7 +27,7 @@ appid 应用：
|
|
|
27
27
|
> - **上传**：把 ZIP 变成一个固定版本。`appid` 应用得到的是「开发版本」，只有应用成员看得到、装得上；旧 `app_key` 应用默认只有你自己看得到。
|
|
28
28
|
> - **发布为线上版本**（仅 `appid` 应用，CLI 叫 `release`）：在云开发控制台「版本管理」里把**某一个开发版本**设为线上版本，全企业可见。**没有审核步骤**。
|
|
29
29
|
> - **发布到企业目录**（仅旧 `app_key` 应用，CLI 叫 `market-publish`、「上架」）：把**某一个版本**改成企业可见。**没有审核步骤**。
|
|
30
|
-
> -
|
|
30
|
+
> - **签名与绑定**（让云函数 / 后台任务能跑）：`appid` 应用不需要手动操作——声明了后台能力的版本上传时平台自动签名，安装、切换版本时自动绑定；旧 `app_key` 应用在控制台「版本与激活」里手动新建发布候选、签名、激活。和目录可见性是两回事。
|
|
31
31
|
>
|
|
32
32
|
|
|
33
33
|
## 面板结构
|
|
@@ -129,7 +129,8 @@ appid 应用：
|
|
|
129
129
|
- 新版本的**可见性**由应用类型决定：
|
|
130
130
|
- **平台 `appid` 应用**：无论从应用中心「上传应用包」还是用 CLI `zleap-app publish` 上传，得到都是**开发版本**，可见性固定为 `members`——只有应用成员能看到和安装。它**不会**继承企业可见，也**不会**自动变成线上版本。
|
|
131
131
|
- **旧 `app_key` 应用**：应用中心「上传应用包」时，如果这个应用**已经有企业可见的版本**，新版本会**直接继承为企业可见**；否则为「仅自己可见」。CLI `zleap-app publish` **总是**「仅自己可见」，不继承（同版本号已公开时返回「该版本已公开，请使用新版本号上传private候选」）。
|
|
132
|
-
-
|
|
132
|
+
- 平台 `appid` 应用声明了后台（headless）能力的版本，平台在上传时**自动签名**，得到就绪发布，不需要再到控制台签名、激活。
|
|
133
|
+
- 旧 `app_key` 应用：如果部署配置了发布信任策略，会为这个版本自动建一个**发布候选（草稿）**，在控制台「版本与激活」里继续签名。详见 [版本与激活](console-legacy-release.md)。
|
|
133
134
|
- 上传**不会**替你安装，也**不会**授予任何权限。
|
|
134
135
|
|
|
135
136
|
> **旧 app_key 应用：从应用中心上传新版本，可能立即对同事可见**（注意）
|
|
@@ -156,12 +157,12 @@ appid 应用：
|
|
|
156
157
|
|
|
157
158
|
每一行：
|
|
158
159
|
|
|
159
|
-
| 位置 | 内容
|
|
160
|
-
| ---- |
|
|
161
|
-
| 左 | 版本号；最新上传的那一行带「**最近上传**」标记
|
|
162
|
-
| 中 | 上传时间、包大小
|
|
163
|
-
| 状态 | 「**仅自己可见**」「**仅成员可见**」或「**企业可见**」；已停用的版本另有「**已停用**」
|
|
164
|
-
| 按钮 | 「**云开发**」→ 打开控制台的版本页并定位到这个版本（旧应用，以及 `appid` 应用已发布的版本）
|
|
160
|
+
| 位置 | 内容 |
|
|
161
|
+
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
162
|
+
| 左 | 版本号；最新上传的那一行带「**最近上传**」标记 |
|
|
163
|
+
| 中 | 上传时间、包大小 |
|
|
164
|
+
| 状态 | 「**仅自己可见**」「**仅成员可见**」或「**企业可见**」；已停用的版本另有「**已停用**」 |
|
|
165
|
+
| 按钮 | 「**云开发**」→ 打开控制台的版本页并定位到这个版本（旧应用，以及 `appid` 应用已发布的版本） |
|
|
165
166
|
| 按钮 | 「**发布到企业目录**」（旧应用当前私有）或「**撤回企业目录**」（旧应用当前企业可见）；`appid` 应用的成员版本是「**去版本管理发布**」 |
|
|
166
167
|
|
|
167
168
|
已停用的版本没有发布 / 撤回 / 去版本管理发布按钮，「云开发」按钮也不可点。
|
|
@@ -185,16 +186,21 @@ appid 应用：
|
|
|
185
186
|
|
|
186
187
|
（截图：云开发控制台「版本管理」：线上版本、发布说明、版本列表与「发布为线上版本」，见文档站）
|
|
187
188
|
|
|
188
|
-
|
|
189
|
+
「版本管理」上方是线上版本和发布说明，下方列出全部成员上传的开发版本，每个版本都可以「切换到此版本」（只切你自己桌面上的应用）、「发布为线上版本」或「回退到此版本」。
|
|
190
|
+
**任一成员都可以发布任一版本**，包括同事上传的版本。
|
|
189
191
|
|
|
190
192
|
发布后**全企业可见**：新安装装的就是它，不是应用成员的使用者下次打开应用时自动更新。**回退**就是把一个旧版本再「发布为线上版本」，按钮文案是「回退到此版本」。
|
|
191
193
|
|
|
192
194
|
> **带云资源的版本第一次发布**（注意）
|
|
193
195
|
>
|
|
194
|
-
> 带数据库集合、`cloud.*`
|
|
195
|
-
>
|
|
196
|
-
>
|
|
197
|
-
>
|
|
196
|
+
> 带数据库集合、`cloud.*` 能力或云函数的版本**第一次**发布时，平台自动完成**应用级**生产准备：生产环境 → 签发生产发布（归属上传者）→
|
|
197
|
+
> 生产门禁（签名、审批窗口、信任策略核对）→ 生产库与生产集合。不依赖任何人的安装。可能返回 40900（看 `detail.reason`）：
|
|
198
|
+
>
|
|
199
|
+
> - `PROD_DATABASE_NOT_READY`「生产数据库还没就绪，暂时不能发布」：通常 1 分钟内就绪，稍后在版本管理里重新发布；持续失败请在控制台「数据库」查看状态。
|
|
200
|
+
> - `UPLOADER_INACTIVE`「这个版本的上传者账号已停用，无法发布」：请其他成员重新上传这个版本（`npm run deploy`）后再发布。
|
|
201
|
+
> - 生产门禁不通过（如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`）：重新发布即会重新签发。
|
|
202
|
+
>
|
|
203
|
+
> 已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。只用宿主能力、没有云资源的应用发布即可用，不需要签名。
|
|
198
204
|
|
|
199
205
|
### CLI 等价操作（appid 应用）
|
|
200
206
|
|