create-zleap-app 0.10.3 → 0.10.5
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 +1 -1
- package/skills/zleap-cloud-app/SKILL.md +7 -7
- package/skills/zleap-cloud-app/references/app-runtime.md +3 -3
- package/skills/zleap-cloud-app/references/cloud-functions.md +28 -24
- package/skills/zleap-cloud-app/references/console-members.md +7 -17
- package/skills/zleap-cloud-app/references/limits.md +27 -36
- package/skills/zleap-cloud-app/references/manifest.md +24 -58
- package/skills/zleap-cloud-app/references/permissions.md +21 -21
- package/skills/zleap-cloud-app/references/sdk-database-files.md +9 -9
- package/skills/zleap-cloud-app/references/status-codes.md +123 -138
- package/skills/zleap-cloud-app/references/triggers.md +5 -5
- package/skills/zleap-cloud-app-release/SKILL.md +46 -80
- package/skills/zleap-cloud-app-release/references/app-center-install.md +24 -23
- package/skills/zleap-cloud-app-release/references/app-center-publish.md +66 -146
- package/skills/zleap-cloud-app-release/references/console-functions.md +18 -22
- package/skills/zleap-cloud-app-release/references/console-members.md +7 -17
- package/skills/zleap-cloud-app-release/references/console-release.md +37 -33
- package/skills/zleap-cloud-app-release/references/console-workspace.md +28 -83
- package/skills/zleap-cloud-app-release/references/dev-to-production.md +104 -361
- package/skills/zleap-cloud-app-release/references/permissions.md +21 -21
- package/skills/zleap-cloud-app-release/references/status-codes.md +123 -138
- package/templates/react-ts/scripts/zleap.mjs +16 -2
- package/templates/react-ts/src/cloud/client.ts +3 -3
- package/skills/zleap-cloud-app-release/references/console-legacy-release.md +0 -411
package/package.json
CHANGED
|
@@ -29,9 +29,9 @@ npm create zleap-app@latest <目录> -- --appid <appid> --name "<应用名>" -y
|
|
|
29
29
|
|
|
30
30
|
`appid` 由平台生成，**不能自己编**：请用户先在云开发控制台侧栏顶部的应用切换下拉里点「创建应用」（填名称），复制生成的 `appid`
|
|
31
31
|
（`zl` + 16 位小写十六进制，如 `zl3f9a2c7e1b0d4a68`），创建者自动成为管理员。没有 `appid` 时非交互脚手架会报错并提示先创建应用——问用户要，不要猜。
|
|
32
|
-
manifest 里写 `"appid": "<appid>"
|
|
32
|
+
manifest 里写 `"appid": "<appid>"`，不要写 `app_key` 和 `publisher`。CLI 登录参数名是 `--app-key`，填的就是 appid；CLI 输出里的 `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` | 部署已开放生产、应用还没有生产环境，非成员打不开 → 任一成员「发布为线上版本」（平台自动准备生产） |
|
|
101
|
+
| `COLLECTION_NOT_FOUND`（上生产后） | 生产环境建了但没开通集合 → 重新「发布为线上版本」（生产库未就绪时发布会报 `PROD_DATABASE_NOT_READY`，稍后重试） |
|
|
102
102
|
| `PUBLISHER_REQUIRED` | 非发布者访问开发数据域（默认只给发布者） |
|
|
103
103
|
| `SCHEMA_INVALID` | 写入字段与集合结构不符（缺必填、类型错、多了字段） |
|
|
104
104
|
| `VERSION_CONFLICT` | 别处先改过，重读后再改 |
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
> **适用范围**（提示）
|
|
11
11
|
>
|
|
12
12
|
>
|
|
13
|
-
> -
|
|
14
|
-
>
|
|
13
|
+
> - 「线上版本」由应用成员在控制台「版本管理」里「发布为线上版本」产生，见 版本管理（文档站 /console/release#版本管理）。
|
|
14
|
+
> 每次上传都是开发版本，还没发布时只有应用成员能用。
|
|
15
15
|
> - **不需要开通任何云资源**：没有数据库、云函数的纯前端应用也能用，也不需要在 Manifest 里声明权限。
|
|
16
16
|
> - 和 Cloud SDK 一样，只能在 zleapOS 窗口里用；浏览器直接打开页面时以 `OPEN_IN_ZLEAP_OS` 失败。
|
|
17
17
|
>
|
|
@@ -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
|
|
|
@@ -351,7 +351,7 @@ await zl.cloud.os.database.mutate({
|
|
|
351
351
|
> - 私有集合里读到的文档自带 `_openid`（写入者标识），可以直接用（`examples/moments` 的 `stats` 就是这么做的）。
|
|
352
352
|
>
|
|
353
353
|
> 由页面传入的 `openid` 只是业务参数，函数无法再向平台核验；手机号 / 邮箱同理，函数拿不到授权登录的信息。
|
|
354
|
-
> `getContext().userId` 是平台内部用户 ID
|
|
354
|
+
> `getContext().userId` 是平台内部用户 ID，不要用它区分业务用户，也不要存它、返回给前端。
|
|
355
355
|
|
|
356
356
|
### 读写失败时拿到什么
|
|
357
357
|
|
|
@@ -560,50 +560,51 @@ 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
|
+
带后台能力的版本在上传时由平台自动签名；安装、切换版本、在「权限」里允许后台运行时会自动绑定，没有单独的签名或绑定步骤。
|
|
580
|
+
|
|
580
581
|
详细界面见 版本管理（文档站 /console/release）、云函数与后台能力（文档站 /console/functions）、安装与卸载（文档站 /app-center/install），
|
|
581
582
|
端到端顺序见 从开发到上线（文档站 /guide/dev-to-production）。
|
|
582
583
|
|
|
583
|
-
| 少了哪一步
|
|
584
|
-
|
|
|
585
|
-
| 没有任何已启用的后台能力
|
|
586
|
-
| 这项能力没被授权
|
|
587
|
-
|
|
|
588
|
-
| 部署没接入函数计算节点 / 调度服务
|
|
584
|
+
| 少了哪一步 | 现象 |
|
|
585
|
+
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
586
|
+
| 没有任何已启用的后台能力 | 会话里没有 `app-execution/1`，前端 `callFunction` / `capabilities.invoke` **在发请求前**就抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 为 `UNSUPPORTED_OPERATION`） |
|
|
587
|
+
| 这项能力没被授权 | 403「此能力尚未由用户授权」 |
|
|
588
|
+
| `managed_function` 没绑定就绪发布（正常不会出现） | `FUNCTION_RELEASE_REQUIRED`；「权限」对话框里该项下方提示「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签。」。到「权限」里重新保存一次，或在「版本管理」切换一次版本，平台会自动补签并绑定 |
|
|
589
|
+
| 部署没接入函数计算节点 / 调度服务 | `FUNCTION_RUNTIME_UNAVAILABLE`（平台未开放，不是你写错了） |
|
|
589
590
|
|
|
590
|
-
###
|
|
591
|
+
### 开发环境 ≠ 生产发布
|
|
591
592
|
|
|
592
|
-
|
|
593
|
+
上面这条链只让云函数在**开发环境**运行。要让其他使用者在生产环境用上它：
|
|
593
594
|
|
|
594
|
-
|
|
595
|
-
- **旧 `app_key` 应用**：继续在「版本与激活」里走发布候选 / 签名 / 激活。
|
|
595
|
+
把版本「发布为线上版本」（控制台「版本管理」，或 `zleap-app release`）。任一成员都可以发布任一版本，不要求上传者正在使用这个版本。带云资源的版本**第一次**发布时，平台自动完成**应用级**生产准备：生产环境 → 签发生产发布（归属上传者）→ 生产门禁（签名、审批窗口、信任策略核对）→ 生产库与生产集合，不依赖任何人的安装。生产库还没就绪时返回 40900（`PROD_DATABASE_NOT_READY`），通常 1 分钟内就绪，稍后重新发布即可；上传者账号已停用时返回 40900（`UPLOADER_INACTIVE`），请其他成员重新上传这个版本后再发布。已经发布过的版本再次发布（包括回退）直接复用当时的就绪发布。只用宿主能力的应用直接发布，没有额外的签名步骤。
|
|
596
596
|
|
|
597
|
-
`zleap-app prepare`
|
|
598
|
-
|
|
597
|
+
`zleap-app prepare` 只准备开发环境，不会碰生产；因为上传、安装 / 切换版本时平台会自动签名并绑定，通常不需要，
|
|
598
|
+
只在 `zleap-app diagnose` 提示 `next_action: app_prepare` 时兜底使用。准备完成后用
|
|
599
|
+
`zleap-app invoke <app_id> --capability <id> --environment dev` 测试。
|
|
599
600
|
|
|
600
601
|
`logic_unit` 和 `builtin` provider 不进函数沙箱，**不需要**签名发布，授权后台能力即可执行。
|
|
601
602
|
|
|
602
603
|
> **授权后要重新加载**（提示）
|
|
603
604
|
>
|
|
604
605
|
> 后台能力的启用状态在打开 Cloud 会话时就算好了。「保存并重新加载」会自动重开；
|
|
605
|
-
>
|
|
606
|
-
>
|
|
606
|
+
> 在控制台里改了授权或切换了新版本后，请点应用窗口的「重新加载应用」。
|
|
607
|
+
> 切换版本并绑定新发布后旧会话会失效（`RELEASE_UNAVAILABLE`），宿主桥会重开会话并重试一次。
|
|
607
608
|
|
|
608
609
|
## 调用后台能力（前端 SDK）
|
|
609
610
|
|
|
@@ -830,8 +831,11 @@ 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
|
+
- 正常不会出现：带后台能力的版本上传时由平台自动签名，安装 / 切换版本 / 保存权限时自动绑定，缺签随用随签。如果出现，在应用窗口「权限」里允许后台运行（重新保存一次），或在控制台「版本管理」切换一次版本，平台会自动补签并绑定；仍然出现，说明部署的发布签名不可用（联系平台管理员检查签名密钥 / 信任配置），或重新上传。
|
|
837
|
+
|
|
838
|
+
处理后重新打开应用窗口「权限」确认该能力下没有「还没有可用的签名发布」的提示，再重新加载应用。
|
|
835
839
|
|
|
836
840
|
### `RUNTIME_GATEWAY_UNAVAILABLE` / 其他 `RUNTIME_GATEWAY_*`
|
|
837
841
|
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
> **一句话流程**（提示）
|
|
9
9
|
>
|
|
10
10
|
> 控制台「创建应用」→ 复制 `appid` → 脚手架带上 `appid` 或写进 `manifest.json` → `npm run deploy` 上传 →
|
|
11
|
-
> （需要协作时）「团队」→「成员」里添加开发者
|
|
11
|
+
> （需要协作时）「团队」→「成员」里添加开发者 →（给全企业用时）「版本管理」里发布为线上版本。
|
|
12
12
|
|
|
13
13
|
## 创建应用
|
|
14
14
|
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
npm create zleap-app@latest my-app -- --appid zl3f9a2c7e1b0d4a68
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
2. **已有项目：把 appid 写进 manifest.json
|
|
49
|
+
2. **已有项目：把 appid 写进 manifest.json**
|
|
50
50
|
|
|
51
51
|
```json
|
|
52
52
|
{
|
|
@@ -96,22 +96,16 @@
|
|
|
96
96
|
|
|
97
97
|
- **修改角色**（管理员）：在成员行的角色下拉里切换「管理员 / 开发者」；
|
|
98
98
|
- **移除**（管理员）：点成员行的「**移除**」，确认「移除 {名字}？——移除后对方不能再上传或管理这个应用，已上传的版本保留。」；
|
|
99
|
-
-
|
|
99
|
+
- **退出**（自己）：在自己那一行点「**退出**」，确认「退出「{应用}」？——退出后你不能再上传或管理这个应用，需要管理员重新添加。」
|
|
100
100
|
|
|
101
101
|
应用**至少要保留一位管理员**。移除、退出或降级会让应用没有管理员时，操作被拒绝：
|
|
102
102
|
40900「应用至少要保留一位管理员」，处理方式是先把另一位成员设为管理员，再做这个操作。
|
|
103
103
|
|
|
104
104
|
非管理员调用成员管理会得到 40300「只有应用管理员可以管理成员」。
|
|
105
105
|
|
|
106
|
-
###
|
|
106
|
+
### 上传时的成员校验
|
|
107
107
|
|
|
108
|
-
|
|
109
|
-
但那一行只有角色标签：没有角色下拉，也没有「移除」/「退出」按钮，不能在这里修改角色或退出。
|
|
110
|
-
（其他通过邀请加入的成员仍按上面的规则管理。）
|
|
111
|
-
|
|
112
|
-
## 上传时的成员校验
|
|
113
|
-
|
|
114
|
-
用 `appid` 的应用，谁能上传由成员决定，Manifest 里的 `publisher` 不再起作用：
|
|
108
|
+
谁能上传由成员决定：
|
|
115
109
|
|
|
116
110
|
| 情况 | 结果 |
|
|
117
111
|
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -123,8 +117,8 @@
|
|
|
123
117
|
|
|
124
118
|
用 `appid` 的应用里，每个成员上传的都是一个**开发版本**，全部列在侧栏「发布」组的「版本管理（文档站 /console/release#版本管理）」里，标出上传者和上传时间：
|
|
125
119
|
|
|
126
|
-
-
|
|
127
|
-
-
|
|
120
|
+
- 任何成员（管理员或开发者）都可以把任一成员上传的版本「发布为线上版本」，或「回退到此版本」，不要求上传者正在使用这个版本；
|
|
121
|
+
- 「切换到此版本」只把你本人桌面上的应用切到任一成员上传的版本，包括同事还没发布的版本（方便联调），不影响其他人，也不改变线上版本；成员从不被自动切换；
|
|
128
122
|
- 开发版本只对成员可见，不是成员的人看不到、也切不到。
|
|
129
123
|
|
|
130
124
|
## 用户授权
|
|
@@ -146,10 +140,6 @@
|
|
|
146
140
|
|
|
147
141
|
用户授权页：只展示人数统计，不展示具体用户（图为还没有人授权时的空状态）。
|
|
148
142
|
|
|
149
|
-
## 目前的限制
|
|
150
|
-
|
|
151
|
-
- 旧 `app_key` 应用仍走「版本与激活」，那里看不到其他成员的发布。
|
|
152
|
-
|
|
153
143
|
## 相关
|
|
154
144
|
|
|
155
145
|
- 快速开始（文档站 /guide/quickstart） — 从创建应用到第一次上传
|
|
@@ -14,25 +14,22 @@
|
|
|
14
14
|
|
|
15
15
|
## 能力开放状态
|
|
16
16
|
|
|
17
|
-
| 能力
|
|
18
|
-
|
|
|
19
|
-
| 云数据库
|
|
20
|
-
| 文件存储
|
|
21
|
-
| 日志
|
|
22
|
-
| 云函数 / 后台能力
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
| 纯后台（`headless`）应用 | ❌ 基本不可用 | 声明云函数等即「运行环境未开放」，请用 `both` |
|
|
34
|
-
| `agent.interaction` | ❌ 未开放 | 声明会导致应用无法安装 |
|
|
35
|
-
| 集合分区 `app` | ❌ 未开放 | Manifest 写 `partition: "app"` 会被拒绝 |
|
|
17
|
+
| 能力 | 状态 | 说明 |
|
|
18
|
+
| ---------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| 云数据库 | ✅ 开放 | 集合按 Manifest 自动创建；文档、索引、备份恢复 |
|
|
20
|
+
| 文件存储 | ✅ 开放 | 分块上传、下载、条件覆盖、软删除 |
|
|
21
|
+
| 日志 | ✅ 开放 | 查询 + 追尾；生产环境只读，发布者可见全部调用日志 |
|
|
22
|
+
| 云函数 / 后台能力 | ⚠️ 视部署而定 | 需要部署了函数运行环境；还需就绪的签名发布（带后台能力的版本上传时由平台自动签名，安装 / 切换版本 / 授权时自动绑定）并授权 |
|
|
23
|
+
| 发布候选与签名 | ✅ 自动 | 平台在上传时自动签发开发版本、首次发布时自动签发生产发布，没有手动步骤。签名需部署配置发布信任策略，未配置时发布报「发布信任策略尚未配置…」 |
|
|
24
|
+
| 生产环境数据 / 文件管理（控制台） | ⚠️ 视部署而定 | 生产开放后可在控制台查看和修改（页面有影响范围提示） |
|
|
25
|
+
| 应用中心 · 更新 / 回滚 | ✅ 开放 | 有升级预检；只切换当前用户自己的安装 |
|
|
26
|
+
| 控制台 · 发布为线上版本 | ✅ 开放 | 控制台「发布 → 版本管理」；发布后全企业可见，无审核步骤；回退 = 把旧版本再发布一次 |
|
|
27
|
+
| 生产准备（首次发布带云资源的版本） | ⚠️ 视部署而定 | 平台自动完成生产环境、生产发布、生产门禁、生产库与集合；发布信任配置未就绪时没有生产入口 |
|
|
28
|
+
| 应用成员（管理员 / 开发者） | ✅ 开放 | 控制台「团队」→「成员」，见 [成员管理](console-members.md) |
|
|
29
|
+
| 使用其他成员上传的开发版本 | ✅ 开放 | 版本可见性为 `members`；成员在「版本管理」里用「切换到此版本」切换（只影响自己） |
|
|
30
|
+
| 纯后台（`headless`）应用 | ❌ 基本不可用 | 声明云函数等即「运行环境未开放」，请用 `both` |
|
|
31
|
+
| `agent.interaction` | ❌ 未开放 | 声明会导致应用无法安装 |
|
|
32
|
+
| 集合分区 `app` | ❌ 未开放 | Manifest 写 `partition: "app"` 会被拒绝 |
|
|
36
33
|
|
|
37
34
|
## 未实现的 SDK 功能
|
|
38
35
|
|
|
@@ -67,15 +64,15 @@
|
|
|
67
64
|
|
|
68
65
|
### Manifest
|
|
69
66
|
|
|
70
|
-
| 项 | 限制
|
|
71
|
-
| ------------- |
|
|
72
|
-
| 嵌套深度 | ≤ **24**
|
|
73
|
-
| 节点总数 | ≤ **16384**
|
|
74
|
-
| `appid` | `zl` + 16
|
|
75
|
-
| `name` | 1–128 位
|
|
76
|
-
| `description` | ≤ 2000 位
|
|
77
|
-
| `icon` | ≤ 512 位
|
|
78
|
-
| `version` | ≤ 32 位（语义化版本）
|
|
67
|
+
| 项 | 限制 |
|
|
68
|
+
| ------------- | ------------------------------------ |
|
|
69
|
+
| 嵌套深度 | ≤ **24** |
|
|
70
|
+
| 节点总数 | ≤ **16384** |
|
|
71
|
+
| `appid` | `zl` + 16 位小写十六进制，由平台生成 |
|
|
72
|
+
| `name` | 1–128 位 |
|
|
73
|
+
| `description` | ≤ 2000 位 |
|
|
74
|
+
| `icon` | ≤ 512 位 |
|
|
75
|
+
| `version` | ≤ 32 位（语义化版本） |
|
|
79
76
|
|
|
80
77
|
### 云函数与 Provider
|
|
81
78
|
|
|
@@ -190,12 +187,6 @@
|
|
|
190
187
|
输入长度以你在能力 `input_schema` 里声明的为准；`copilot-studio` 示例用的是 `input` ≤ 16000、`system` ≤ 4000，
|
|
191
188
|
平台侧的输入上限**未验证**。
|
|
192
189
|
|
|
193
|
-
### 发布
|
|
194
|
-
|
|
195
|
-
| 项 | 限制 |
|
|
196
|
-
| ------------ | ----------- |
|
|
197
|
-
| 签名证明文件 | ≤ **2 MiB** |
|
|
198
|
-
|
|
199
190
|
### 日志
|
|
200
191
|
|
|
201
192
|
| 项 | 限制 |
|
|
@@ -265,8 +256,8 @@
|
|
|
265
256
|
| 项目 | 未配置时的表现 |
|
|
266
257
|
| ------------ | ------------------------------------------------------------------------------------- |
|
|
267
258
|
| 函数运行环境 | 控制台云函数显示 `RUNTIME_UNAVAILABLE · 函数执行 Provider 尚未开放。` |
|
|
268
|
-
| 发布信任策略 |
|
|
269
|
-
|
|
|
259
|
+
| 发布信任策略 | 发布签名失败，报「发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期。」 |
|
|
260
|
+
| 生产发布 | 发布信任配置未就绪时控制台不出现生产入口；发布接口报 `PRODUCTION_RELEASE_UNAVAILABLE` |
|
|
270
261
|
| 数据服务 | `RESOURCE_NOT_READY` / `DATA_SERVICE_UNAVAILABLE` |
|
|
271
262
|
|
|
272
263
|
> **关于「能跑」的判断标准**（注意）
|
|
@@ -64,28 +64,26 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
|
|
|
64
64
|
|
|
65
65
|
## 顶层字段
|
|
66
66
|
|
|
67
|
-
| 字段 | 必填 | 类型 | 说明
|
|
68
|
-
| --------------- | ---- | ------ |
|
|
69
|
-
| `schema` | ✅ | 字符串 | 固定为 `"zleap.app/2"`，其他值会直接被拒绝
|
|
70
|
-
| `appid` | ✅ | 字符串 | 应用唯一标识，在云开发控制台「创建应用」后由平台生成，见下方说明
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `notifications` | | 对象 | 通知频道声明（见下） |
|
|
88
|
-
| `storage` | | 对象 | 宿主 KV / 数据空间声明（见下） |
|
|
67
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
68
|
+
| --------------- | ---- | ------ | ------------------------------------------------------------------- |
|
|
69
|
+
| `schema` | ✅ | 字符串 | 固定为 `"zleap.app/2"`，其他值会直接被拒绝 |
|
|
70
|
+
| `appid` | ✅ | 字符串 | 应用唯一标识，在云开发控制台「创建应用」后由平台生成，见下方说明 |
|
|
71
|
+
| `name` | ✅ | 字符串 | 显示名，1–128 位，**必须有可见字符** |
|
|
72
|
+
| `version` | ✅ | 字符串 | 语义化版本（SemVer），≤32 位，如 `1.0.0`、`1.2.0-beta.1` |
|
|
73
|
+
| `description` | | 字符串 | ≤2000 位 |
|
|
74
|
+
| `icon` | | 字符串 | ≤512 位 |
|
|
75
|
+
| `execution` | ✅ | 枚举 | `foreground` / `headless` / `both`，必须与 `runtime` 一致 |
|
|
76
|
+
| `runtime` | ✅ | 对象 | 运行环境声明（见下） |
|
|
77
|
+
| `background` | | 对象 | 后台运行模式，默认 `{ "on_install": "disabled", "modes": [] }` |
|
|
78
|
+
| `triggers` | | 对象 | 触发器声明，默认 `{ "scheduled": [], "events": [] }` |
|
|
79
|
+
| `events` | | 对象 | 事件发布与订阅，默认 `{ "publishes": [], "subscribes": [] }` |
|
|
80
|
+
| `data` | | 对象 | 数据集合、集合 Schema 与访问规则（见下） |
|
|
81
|
+
| `resources` | | 对象 | 资源限制，默认 `{ "max_concurrency": 1 }` |
|
|
82
|
+
| `host_api` | | 对象 | 宿主能力声明，默认 `{ "profile": "app-runtime/2", "requires": [] }` |
|
|
83
|
+
| `agent` | | 对象 | Agent 交互声明 |
|
|
84
|
+
| `capabilities` | | 数组 | 只能是 `["notify.send"]`（应用通知，见下） |
|
|
85
|
+
| `notifications` | | 对象 | 通知频道声明（见下） |
|
|
86
|
+
| `storage` | | 对象 | 宿主 KV / 数据空间声明（见下） |
|
|
89
87
|
|
|
90
88
|
### `appid`
|
|
91
89
|
|
|
@@ -102,37 +100,12 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
|
|
|
102
100
|
- `appid` 必须已在控制台创建，否则 40400「appid 不存在」（`detail.reason` 为 `APP_NOT_FOUND`，处理：先在云开发控制台「创建应用」）；
|
|
103
101
|
- 上传者必须是应用成员（管理员或开发者），否则 40300「你不是这个应用的开发者」（`detail.reason` 为 `NOT_APP_MEMBER`，
|
|
104
102
|
处理：请联系应用管理员在云开发控制台「成员」里把你加为开发者），见 [成员管理](console-members.md)；
|
|
105
|
-
-
|
|
106
|
-
- 用 `zleap-app` 登录时，开发会话只限定一个 `appid`（`auth login --app-key <appid>`），包里的 `appid` 必须与登录时的一致；
|
|
103
|
+
- 用 `zleap-app` 登录时，开发会话只限定一个 `appid`（`auth login --app-key <appid>`，参数名是 `--app-key`，填的是 `appid`），包里的 `appid` 必须与登录时的一致；
|
|
107
104
|
- 应用被删除后，原 `appid` **不能**再用于上传。
|
|
108
105
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
> **已弃用**（注意）
|
|
106
|
+
> **CLI / 接口回执里的 `app_key`**（提示）
|
|
112
107
|
>
|
|
113
|
-
> `
|
|
114
|
-
|
|
115
|
-
校验器本身接受 `^[a-z][a-z0-9_.-]*$`，但**上传和运行**还要求它是「发布者命名空间」形式：
|
|
116
|
-
|
|
117
|
-
- 至少两段，用 `.` 分隔；
|
|
118
|
-
- 每段以小写字母开头，只含小写字母和数字，`-`、`_` 只能夹在字母数字之间；
|
|
119
|
-
- 总长 ≤64。
|
|
120
|
-
|
|
121
|
-
| 正例 | 反例 |
|
|
122
|
-
| -------------------- | ------------------------------------ |
|
|
123
|
-
| `com.example.todo` | `mytodo`（没有点） |
|
|
124
|
-
| `com.example.my-app` | `Com.Example.Todo`（大写） |
|
|
125
|
-
| `com.example.my_app` | `com.example.-app`（`-` 不能打头） |
|
|
126
|
-
| `org.acme.notes2` | `com.example.2notes`（段以数字开头） |
|
|
127
|
-
|
|
128
|
-
不满足时报「manifest app_key 必须使用包含发布者前缀的小写命名空间」或
|
|
129
|
-
「第三方应用 app_key 必须包含发布者命名空间」。
|
|
130
|
-
|
|
131
|
-
旧 `app_key` 应用一经上传就归属第一个上传者（上传过包的人视为该应用的管理员）：
|
|
132
|
-
|
|
133
|
-
- 其他用户再用同一个 `app_key` 上传会被拒绝（「不能覆盖其他发布者的应用标识」）；
|
|
134
|
-
- 应用被删除后，原 `app_key` **不能**再用于上传；
|
|
135
|
-
- 用 `zleap-app` 登录时，开发会话只限定一个 `app_key`，包里的 `app_key` 必须与登录时的一致。
|
|
108
|
+
> `zleap-app check`、`publish` 等命令与接口回执 JSON 里的 `app_key` 字段就是这里的 `appid`，只是沿用了旧字段名。
|
|
136
109
|
|
|
137
110
|
### `version` 与重复上传
|
|
138
111
|
|
|
@@ -143,13 +116,6 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
|
|
|
143
116
|
|
|
144
117
|
改了任何文件都要升版本号再上传。
|
|
145
118
|
|
|
146
|
-
### `publisher` 发布者
|
|
147
|
-
|
|
148
|
-
用 `appid` 的应用**不需要** `publisher`，写了也会被忽略——谁能上传由应用成员决定。
|
|
149
|
-
|
|
150
|
-
只有旧 `app_key` 应用还会核对它：写了就必须等于上传者本人的用户 ID（字符串），
|
|
151
|
-
否则上传被拒：「发布者声明不属于当前登录用户」。
|
|
152
|
-
|
|
153
119
|
### `execution` 必须与运行形态一致
|
|
154
120
|
|
|
155
121
|
`execution` 不是自由填写的标签，而是由 `runtime` 里**实际声明了哪些部分**决定的：
|
|
@@ -541,7 +507,7 @@ Manifest 校验器接受 `^[a-zA-Z][a-zA-Z0-9_.-]*$`（≤128），但**数据
|
|
|
541
507
|
| `on_install` | 只能是 `"disabled"`（默认） |
|
|
542
508
|
| `modes` | 从 `on_demand` / `scheduled` / `events` 中选，最多 3 个 |
|
|
543
509
|
|
|
544
|
-
|
|
510
|
+
安装应用**不会**自动启动后台任务。后台能力要在安装后由用户在应用窗口「权限」或控制台里单独允许。
|
|
545
511
|
**要用定时触发器，`modes` 必须含 `"scheduled"`；事件触发器要含 `"events"`**，否则启用时报 `TRIGGER_MODE_NOT_DECLARED`。
|
|
546
512
|
|
|
547
513
|
## `triggers` — 触发器
|
|
@@ -138,17 +138,17 @@
|
|
|
138
138
|
|
|
139
139
|
对话框里**没有环境选择**。数据域（dev「调试」/ prod「生产」）由宿主根据部署决定，对话框只显示当前是哪个：
|
|
140
140
|
|
|
141
|
-
| 部署状态 | 数据域 | 谁能用
|
|
142
|
-
| ---------- | ------ |
|
|
143
|
-
| 未开放生产 | dev |
|
|
144
|
-
| 已开放生产 | prod | 其他安装者一律走生产（应用没有生产环境时报 `ENV_FORBIDDEN`）；发布者本人在应用有生产环境后走生产，否则仍走 dev
|
|
141
|
+
| 部署状态 | 数据域 | 谁能用 |
|
|
142
|
+
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
143
|
+
| 未开放生产 | dev | 默认只有开发团队：这个应用的全部成员（其他人报 `PUBLISHER_REQUIRED`，对话框显示「当前安装未申请此能力，或你无权访问应用云空间。」） |
|
|
144
|
+
| 已开放生产 | prod | 其他安装者一律走生产（应用没有生产环境时报 `ENV_FORBIDDEN`）；发布者本人在应用有生产环境后走生产，否则仍走 dev |
|
|
145
145
|
|
|
146
146
|
生产是否开放取决于部署：发布信任配置就绪即开放（由运维自动配置），不由应用决定。
|
|
147
147
|
应用代码里只写 `zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV })`，**不要写死 `'dev'` / `'prod'`**。
|
|
148
148
|
|
|
149
149
|
> **生产未开放时，同事用不了 Cloud 数据**（注意）
|
|
150
150
|
>
|
|
151
|
-
> 此时所有人都走 dev，而 dev
|
|
151
|
+
> 此时所有人都走 dev，而 dev 默认只对开发团队（这个应用的全部成员）开放（部署可另行放开）。你把应用发布为线上版本后，
|
|
152
152
|
> 同事能安装、能打开，但云数据读写会被拒绝。这属于「平台未开放」，不是代码写错了。
|
|
153
153
|
|
|
154
154
|
### 授权与会话的关系
|
|
@@ -196,7 +196,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
|
|
|
196
196
|
> 授权后，本应用可在关窗后按你勾选的能力运行（如定时巡检），只作用于你本人的数据，其他使用者看不到。
|
|
197
197
|
|
|
198
198
|
- 授权限定在**这个安装 + 这个版本 + 这个环境**；每一步执行前都会重新检查；
|
|
199
|
-
- `managed_function
|
|
199
|
+
- `managed_function`（云函数）还要求绑定**就绪**的签名发布，否则该项下方提示「该版本还没有可用的签名发布，暂时无法执行。重新保存一次权限会自动补签。」，调用返回 `FUNCTION_RELEASE_REQUIRED`。带后台能力的版本上传时由平台自动签名；在这里保存（或允许 / 撤销后台运行）时自动绑定，缺签时当场补签，正常不会看到这条提示；
|
|
200
200
|
- `logic_unit` / `builtin` provider 不需要发布；
|
|
201
201
|
- `os.agent.complete` 等内置动作同样是一项后台能力，要在这里启用后才能调用。
|
|
202
202
|
|
|
@@ -328,21 +328,21 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
|
|
|
328
328
|
|
|
329
329
|
## 排查「没权限」
|
|
330
330
|
|
|
331
|
-
| 症状 | 检查项
|
|
332
|
-
| ---------------------------------------------------- |
|
|
333
|
-
| 应用显示「暂不可用」，装不上 | `requires` 里有白名单外的非可选能力？声明了 `agent.interaction`、前台 provider / 前台 provides？`host_api` 写错？
|
|
334
|
-
| 上传就失败 | `appid` 是否已在控制台创建、你是否是应用成员、provider `permissions` 是否 ⊆ `requires`、集合是否已声明
|
|
335
|
-
| 打开应用报 `CONSENT_REQUIRED` | 「权限」里的四项全被取消且没有已启用的后台能力——勾选后保存
|
|
336
|
-
| `PUBLISHER_REQUIRED` | 当前数据域是 dev，而你不是该版本的发布者。等部署开放生产，或用发布者账号验证
|
|
337
|
-
| `ENV_FORBIDDEN` | 当前数据域的环境未创建 / 不可用，或部署未开放生产
|
|
338
|
-
| 数据库调用 `UNSUPPORTED_OPERATION` | 环境、数据库是否就绪？是否授权了数据库读写？改完后重新加载应用了吗？
|
|
339
|
-
| `SCOPE_FORBIDDEN` / `RULE_DENIED` | 授权是否被取消？集合是否在 `data.collections` 里？记录规则是否允许？详见 [状态与错误码](status-codes.md)
|
|
340
|
-
| 云函数访问不到字段 | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？
|
|
341
|
-
| 用户之间看不到彼此数据 | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"`
|
|
342
|
-
| 前端调用后台能力 `BACKGROUND_CAPABILITY_UNAVAILABLE` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载（旧 SDK 报 `UNSUPPORTED_OPERATION`）
|
|
343
|
-
| 云函数 `FUNCTION_RELEASE_REQUIRED` |
|
|
344
|
-
| 更新版本后后台任务不跑了 | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力
|
|
345
|
-
| 跨应用调用失败 | 普通 SDK 不支持跨应用调用
|
|
331
|
+
| 症状 | 检查项 |
|
|
332
|
+
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
333
|
+
| 应用显示「暂不可用」，装不上 | `requires` 里有白名单外的非可选能力？声明了 `agent.interaction`、前台 provider / 前台 provides？`host_api` 写错？ |
|
|
334
|
+
| 上传就失败 | `appid` 是否已在控制台创建、你是否是应用成员、provider `permissions` 是否 ⊆ `requires`、集合是否已声明 |
|
|
335
|
+
| 打开应用报 `CONSENT_REQUIRED` | 「权限」里的四项全被取消且没有已启用的后台能力——勾选后保存 |
|
|
336
|
+
| `PUBLISHER_REQUIRED` | 当前数据域是 dev，而你不是该版本的发布者。等部署开放生产，或用发布者账号验证 |
|
|
337
|
+
| `ENV_FORBIDDEN` | 当前数据域的环境未创建 / 不可用，或部署未开放生产 |
|
|
338
|
+
| 数据库调用 `UNSUPPORTED_OPERATION` | 环境、数据库是否就绪？是否授权了数据库读写？改完后重新加载应用了吗？ |
|
|
339
|
+
| `SCOPE_FORBIDDEN` / `RULE_DENIED` | 授权是否被取消？集合是否在 `data.collections` 里？记录规则是否允许？详见 [状态与错误码](status-codes.md) |
|
|
340
|
+
| 云函数访问不到字段 | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？ |
|
|
341
|
+
| 用户之间看不到彼此数据 | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"` |
|
|
342
|
+
| 前端调用后台能力 `BACKGROUND_CAPABILITY_UNAVAILABLE` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载（旧 SDK 报 `UNSUPPORTED_OPERATION`） |
|
|
343
|
+
| 云函数 `FUNCTION_RELEASE_REQUIRED` | 在应用窗口「权限」里允许后台运行（重新保存一次），或在「版本管理」切换一次版本，平台自动补签并绑定；仍出现请联系平台管理员检查签名密钥 / 信任配置，或重新上传 |
|
|
344
|
+
| 更新版本后后台任务不跑了 | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力 |
|
|
345
|
+
| 跨应用调用失败 | 普通 SDK 不支持跨应用调用 |
|
|
346
346
|
|
|
347
347
|
## 相关
|
|
348
348
|
|
|
@@ -79,7 +79,7 @@ const db = zl.cloud.database();
|
|
|
79
79
|
|
|
80
80
|
> **为什么用 `DYNAMIC_CURRENT_ENV`**（提示）
|
|
81
81
|
>
|
|
82
|
-
> 数据域（dev / prod）是「部署 + 当前用户 +
|
|
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` |
|
|
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();
|
|
@@ -612,9 +612,9 @@ async function saveTodo(data) {
|
|
|
612
612
|
}
|
|
613
613
|
```
|
|
614
614
|
|
|
615
|
-
>
|
|
615
|
+
> **绑定新发布后的会话失效**（提示）
|
|
616
616
|
>
|
|
617
|
-
>
|
|
617
|
+
> 安装切换到另一个版本并绑定新的发布后，旧会话会收到 `RELEASE_UNAVAILABLE`。宿主会自动重开会话并**重试一次**，
|
|
618
618
|
> 多数情况下应用无感。若仍失败，请用户重新打开应用。
|
|
619
619
|
|
|
620
620
|
## 后台执行与能力调用
|