create-zleap-app 0.10.4 → 0.10.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/index.js +3 -0
  2. package/package.json +3 -3
  3. package/skills/zleap-cloud-app/SKILL.md +3 -3
  4. package/skills/zleap-cloud-app/references/app-runtime.md +3 -3
  5. package/skills/zleap-cloud-app/references/cloud-functions.md +25 -18
  6. package/skills/zleap-cloud-app/references/console-members.md +8 -16
  7. package/skills/zleap-cloud-app/references/limits.md +27 -36
  8. package/skills/zleap-cloud-app/references/manifest.md +26 -58
  9. package/skills/zleap-cloud-app/references/permissions.md +21 -21
  10. package/skills/zleap-cloud-app/references/sdk-database-files.md +12 -10
  11. package/skills/zleap-cloud-app/references/status-codes.md +117 -136
  12. package/skills/zleap-cloud-app/references/triggers.md +4 -4
  13. package/skills/zleap-cloud-app-release/SKILL.md +39 -82
  14. package/skills/zleap-cloud-app-release/references/app-center-install.md +22 -23
  15. package/skills/zleap-cloud-app-release/references/app-center-publish.md +56 -142
  16. package/skills/zleap-cloud-app-release/references/console-functions.md +12 -28
  17. package/skills/zleap-cloud-app-release/references/console-members.md +8 -16
  18. package/skills/zleap-cloud-app-release/references/console-release.md +18 -24
  19. package/skills/zleap-cloud-app-release/references/console-workspace.md +23 -90
  20. package/skills/zleap-cloud-app-release/references/dev-to-production.md +79 -349
  21. package/skills/zleap-cloud-app-release/references/permissions.md +21 -21
  22. package/skills/zleap-cloud-app-release/references/status-codes.md +117 -136
  23. package/templates/react-ts/scripts/zleap.mjs +14 -0
  24. package/templates/react-ts/src/cloud/client.ts +3 -3
  25. package/skills/zleap-cloud-app-release/references/console-legacy-release.md +0 -411
@@ -4,30 +4,19 @@
4
4
 
5
5
  这一篇讲左侧导航「**我的发布**」里与应用包有关的全部操作,以及与之等价的 `zleap-app` 命令行操作。
6
6
 
7
- 先分清两条上线路径——**用哪种应用,就走哪条路**:
8
-
9
- | 应用类型 | 上传后是什么 | 怎么让同事用上 |
10
- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
11
- | **平台 `appid` 应用**(在云开发控制台创建,形如 `zl3f9a2c7e1b0d4a68`) | **开发版本**,可见性 `members`:只有应用成员(管理员 / 开发者)能看到和安装 | 在云开发控制台「**发布 → 版本管理**」里点「**发布为线上版本**」;应用中心的「发布到企业目录」对它不适用 |
12
- | **旧 `app_key` 应用**(形如 `com.example.my-app`) | 默认「仅自己可见」(`private`);从应用中心上传时,如果已有企业可见版本则会继承 | 在应用中心点「**发布到企业目录**」;撤回也用应用中心 |
7
+ 整个链路只有一条:
13
8
 
14
9
  ```
15
- appid 应用:
16
- 上传(应用中心 / CLI)──▶ 开发版本(members,仅应用成员可见)──▶ 控制台「版本管理」发布为线上版本 ──▶ 全企业可见
17
-
18
- 旧 app_key 应用:
19
- 上传 ──▶ 仅自己可见(private)──▶ 发布到企业目录(enterprise)──▶ 同事在「发现」安装
20
- │ │
21
- └─ 你自己可以直接安装调试 └─ 可随时「撤回企业目录」
10
+ 上传(应用中心 / CLI)──▶ 开发版本(仅应用成员可见,members)──▶ 控制台「版本管理」发布为线上版本 ──▶ 全企业可见(enterprise)
22
11
  ```
23
12
 
24
13
  > **几个容易混淆的「发布」**(提示)
25
14
  >
26
15
  >
27
- > - **上传**:把 ZIP 变成一个固定版本。`appid` 应用得到的是「开发版本」,只有应用成员看得到、装得上;旧 `app_key` 应用默认只有你自己看得到。
28
- > - **发布为线上版本**(仅 `appid` 应用,CLI 叫 `release`):在云开发控制台「版本管理」里把**某一个开发版本**设为线上版本,全企业可见。**没有审核步骤**。
29
- > - **发布到企业目录**(仅旧 `app_key` 应用,CLI 叫 `market-publish`、「上架」):把**某一个版本**改成企业可见。**没有审核步骤**。
30
- > - **签名与绑定**(让云函数 / 后台任务能跑):`appid` 应用不需要手动操作——声明了后台能力的版本上传时平台自动签名,安装、切换版本时自动绑定;旧 `app_key` 应用在控制台「版本与激活」里手动新建发布候选、签名、激活。和目录可见性是两回事。
16
+ > - **上传**:把 ZIP 变成一个固定版本。每次上传得到的都是**开发版本**,只有应用成员看得到、装得上。
17
+ > - **发布为线上版本**(CLI 叫 `release`):在云开发控制台「版本管理」里把**某一个开发版本**设为线上版本,全企业可见。**没有审核步骤**。在「我的发布」里点成员版本的「**去版本管理发布**」也能直接打开对应入口。
18
+ > - **回退**:把旧版本再发布一次,控制台里的按钮是「**回退到此版本**」。
19
+ > - **签名与绑定**(让云函数 / 后台任务能跑):带后台(headless)能力的版本上传时平台自动签名;安装、切换版本、允许后台运行时如果缺签,平台会自动补签并绑定,不需要手动操作。
31
20
  >
32
21
 
33
22
  ## 面板结构
@@ -38,11 +27,10 @@ appid 应用:
38
27
  「应用包」标签页里依次是:
39
28
 
40
29
  - 标题「**应用包**」和统计「`N 个应用 · M 个版本`」;
41
- - 提示「上传新版本,在应用卡片内管理目录可见性与云开发发布候选。」;
42
30
  - 主按钮「**上传应用包**」和「**刷新**」;
43
31
  - 应用卡片列表:**按应用分组**,同一个 `appid` 的多个版本收在一张卡片里。
44
32
 
45
- (截图:「我的发布 → 自建应用 → 应用包」:应用卡片、目录状态与「管理版本」「⋯」按钮,见文档站)
33
+ (截图:「我的发布 → 自建应用 → 应用包」:应用卡片、版本统计与「管理版本」「⋯」按钮,见文档站)
46
34
 
47
35
  「我的发布」按应用分组;卡片右侧的「管理版本」展开版本列表,「⋯」里是云开发控制台、编辑资料和删除。
48
36
 
@@ -50,19 +38,18 @@ appid 应用:
50
38
 
51
39
  ## 上传应用包
52
40
 
53
- > **平台 appid 应用:先在控制台创建应用**(提示)
41
+ > **先在控制台创建应用**(提示)
54
42
  >
55
- > 使用平台 `appid` 时,上传前应用必须已在 [云开发控制台「创建应用」](console-members.md#创建应用),并把生成的 `appid` 写进 `manifest.json`;
56
- > 上传者必须是这个应用的成员(管理员或开发者)。旧 `app_key` 应用不需要这一步,按原有命名空间上传即可。
43
+ > 上传前应用必须已在 [云开发控制台「创建应用」](console-members.md#创建应用) 创建,并把生成的 `appid` 写进 `manifest.json`;
44
+ > 上传者必须是这个应用的成员(管理员或开发者)。
57
45
 
58
46
  ### 操作步骤
59
47
 
60
48
  1. 点「**上传应用包**」。
61
49
  2. 选择 `.zip` 文件。
62
- 3. 等待上传完成,成功提示:「**应用包已上传,可继续发布到企业目录。**」
50
+ 3. 等待上传完成。列表刷新后,新版本出现在应用卡片里,初始是「**仅成员可见**」的开发版本。
63
51
 
64
- `appid` 应用请忽略提示里的「发布到企业目录」——这只对旧 `app_key` 应用成立;`appid` 应用请去控制台「版本管理」发布线上版本,
65
- 也可以点版本行上的「**去版本管理发布**」直接打开。
52
+ 要让同事用上,点这个版本行上的「**去版本管理发布**」,或在云开发控制台「版本管理」里点「**发布为线上版本**」。
66
53
 
67
54
  前端预检不通过(不是 `.zip`、空文件、超过 20 MiB)时提示:
68
55
 
@@ -80,21 +67,18 @@ appid 应用:
80
67
 
81
68
  以下限制来自 `zleap-service/internal/services/apparchive`:
82
69
 
83
- | 要求 | 不满足时的服务端提示 |
84
- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
85
- | ZIP 本身 ≤ 20 MiB、非空 | 应用包必须是非空 ZIP,且不能超过 20 MiB |
86
- | 根目录有 `manifest.json`,且 ≤ 1 MiB | 应用包根目录必须包含 manifest.json / manifest.json 超过 1 MiB 上限 |
87
- | JSON 合法、**不含重复键** | manifest.json 必须是有效 UTF-8 JSON,且不能包含重复键 |
88
- | 根目录有**非空** `LICENSE` | 应用包根目录必须包含非空 LICENSE 文件 |
89
- | `appid` 是控制台生成的应用标识(旧应用为 `app_key` 命名空间,≤ 64 字符) | manifest app_key 必须使用包含发布者前缀的小写命名空间 |
90
- | `appid` 与 `app_key` 同时写时必须一致 | manifest 的 appid 与 app_key 不一致 |
91
- | `runtime.ui.type` 是 `iframe` | 上传UI只支持iframe |
92
- | `runtime.ui.entry` 指向包内存在的 `.html` / `.htm` | manifest entry 必须指向存在的包内 HTML 文件 |
93
- | 仅旧 `app_key` 应用:如写了 `publisher.publisher_id`,必须是你当前的用户 ID(`appid` 应用忽略 `publisher`) | 发布者声明不属于当前登录用户 |
94
- | 条目数 1–2000 | 应用包条目数量必须在 1 至 2000 之间 |
95
- | 单文件 ≤ 20 MiB;解压总大小 ≤ 80 MiB | 应用包单文件大小超过上限 / 应用包解压总大小超过上限 |
96
- | 单文件压缩比 ≤ 100 | 应用包压缩比超过上限 |
97
- | 不含符号链接、加密条目、`..` 等越界路径 | 应用包不允许符号链接或特殊文件 等 |
70
+ | 要求 | 不满足时的服务端提示 |
71
+ | -------------------------------------------------- | ------------------------------------------------------------------ |
72
+ | ZIP 本身 ≤ 20 MiB、非空 | 应用包必须是非空 ZIP,且不能超过 20 MiB |
73
+ | 根目录有 `manifest.json`,且 ≤ 1 MiB | 应用包根目录必须包含 manifest.json / manifest.json 超过 1 MiB 上限 |
74
+ | JSON 合法、**不含重复键** | manifest.json 必须是有效 UTF-8 JSON,且不能包含重复键 |
75
+ | 根目录有**非空** `LICENSE` | 应用包根目录必须包含非空 LICENSE 文件 |
76
+ | `runtime.ui.type` 是 `iframe` | 上传UI只支持iframe |
77
+ | `runtime.ui.entry` 指向包内存在的 `.html` / `.htm` | manifest entry 必须指向存在的包内 HTML 文件 |
78
+ | 条目数 1–2000 | 应用包条目数量必须在 1 至 2000 之间 |
79
+ | 单文件 ≤ 20 MiB;解压总大小 ≤ 80 MiB | 应用包单文件大小超过上限 / 应用包解压总大小超过上限 |
80
+ | 单文件压缩比 ≤ 100 | 应用包压缩比超过上限 |
81
+ | 不含符号链接、加密条目、`..` 等越界路径 | 应用包不允许符号链接或特殊文件 等 |
98
82
 
99
83
  > **两个最常见的失败原因**(危险)
100
84
  >
@@ -115,35 +99,25 @@ appid 应用:
115
99
 
116
100
  ### 版本号规则
117
101
 
118
- | 情况 | 结果 |
119
- | --------------------------------------- | ------------------------------------------------------------------------------- |
120
- | `appid` 还没在控制台创建 | 拒绝:40400「appid 不存在」——先在云开发控制台「创建应用」 |
121
- | 你不是这个应用的成员 | 拒绝:40300「你不是这个应用的开发者」——请管理员在控制台「成员」里把你加为开发者 |
122
- | 旧 `app_key` 已被**其他人**的应用包占用 | 拒绝:「不能覆盖其他发布者的应用标识」(仅旧 `app_key` 应用) |
123
- | 应用已被删除 | 拒绝:「该应用已删除,不能使用原应用标识重新上传」 |
124
- | 同一版本号、**内容完全相同**的 ZIP | 视为重复上传,直接返回已有的那个包 |
125
- | 同一版本号、内容不同 | 拒绝:「该版本已经存在,请更换版本号」——**改代码就要升版本号** |
102
+ | 情况 | 结果 |
103
+ | ---------------------------------- | ------------------------------------------------------------------------------- |
104
+ | `appid` 还没在控制台创建 | 拒绝:40400「appid 不存在」——先在云开发控制台「创建应用」 |
105
+ | 你不是这个应用的成员 | 拒绝:40300「你不是这个应用的开发者」——请管理员在控制台「成员」里把你加为开发者 |
106
+ | 应用已被删除 | 拒绝:「该应用已删除,不能使用原应用标识重新上传」 |
107
+ | 同一版本号、**内容完全相同**的 ZIP | 视为重复上传,直接返回已有的那个包 |
108
+ | 同一版本号、内容不同 | 拒绝:「该版本已经存在,请更换版本号」——**改代码就要升版本号** |
126
109
 
127
110
  ### 上传后会自动发生什么
128
111
 
129
- - 新版本的**可见性**由应用类型决定:
130
- - **平台 `appid` 应用**:无论从应用中心「上传应用包」还是用 CLI `zleap-app publish` 上传,得到都是**开发版本**,可见性固定为 `members`——只有应用成员能看到和安装。它**不会**继承企业可见,也**不会**自动变成线上版本。
131
- - **旧 `app_key` 应用**:应用中心「上传应用包」时,如果这个应用**已经有企业可见的版本**,新版本会**直接继承为企业可见**;否则为「仅自己可见」。CLI `zleap-app publish` **总是**「仅自己可见」,不继承(同版本号已公开时返回「该版本已公开,请使用新版本号上传private候选」)。
132
- - 平台 `appid` 应用声明了后台(headless)能力的版本,平台在上传时**自动签名**,得到就绪发布,不需要再到控制台签名、激活。
133
- - 旧 `app_key` 应用:如果部署配置了发布信任策略,会为这个版本自动建一个**发布候选(草稿)**,在控制台「版本与激活」里继续签名。详见 [版本与激活](console-legacy-release.md)。
112
+ - 新版本固定为**开发版本**,可见性为 `members`——只有应用成员能看到和安装。它**不会**自动变成线上版本,上线要在控制台「版本管理」里发布为线上版本。
113
+ - 声明了后台(headless)能力的版本,平台在上传时**自动签名**,得到就绪发布;安装、切换版本时自动绑定,不需要再到控制台手动签名或激活。
134
114
  - 上传**不会**替你安装,也**不会**授予任何权限。
135
115
 
136
- > **旧 app_key 应用:从应用中心上传新版本,可能立即对同事可见**(注意)
137
- >
138
- > 如果你已经把旧版本发布到了企业目录,再从应用中心上传新版本时,它默认就是「企业可见」,同事可以在「更新」里升级到它。
139
- > 想先自己验证再放出去,请用 `zleap-app publish`(固定 private),验证后再发布。
140
-
141
116
  ## 应用卡片
142
117
 
143
- 卡片头部:应用名、`appid`(旧应用为 `app_key`)、「最近上传 x.y.z · 大小 · 上传于 日期时间」。
118
+ 卡片头部:应用名、`appid`、「最近上传 x.y.z · 大小 · 上传于 日期时间」。
144
119
 
145
- 右侧「**目录状态**」统计:`appid` 应用是「**企业 n**」「**开发版本 n**」,旧 `app_key` 应用是「**企业 N**」「**私有 N**」;
146
- 有停用版本时再加「**停用 N**」,以及「**N 个版本**」。
120
+ 右侧统计:「**企业 n**」「**开发版本 n**」;有停用版本时再加「**停用 N**」,以及「**N 个版本**」。
147
121
 
148
122
  右侧按钮:
149
123
 
@@ -152,31 +126,27 @@ appid 应用:
152
126
 
153
127
  ### 版本列表
154
128
 
155
- 展开后标题「**版本列表**」,说明:「目录上下架作用于单个版本;云开发负责运行环境、发布候选与生产门禁。」
156
- `appid` 应用的说明是:「这是 appid 应用:每次上传都是只有应用成员可见的开发版本,在云开发控制台「版本管理」里发布为线上版本后全企业可见。」
129
+ 展开后标题「**版本列表**」,说明:「这是 appid 应用:每次上传都是只有应用成员可见的开发版本,在云开发控制台「版本管理」里发布为线上版本后全企业可见。」
157
130
 
158
131
  每一行:
159
132
 
160
- | 位置 | 内容 |
161
- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
162
- | 左 | 版本号;最新上传的那一行带「**最近上传**」标记 |
163
- | 中 | 上传时间、包大小 |
164
- | 状态 | 「**仅自己可见**」「**仅成员可见**」或「**企业可见**」;已停用的版本另有「**已停用**」 |
165
- | 按钮 | 「**云开发**」→ 打开控制台的版本页并定位到这个版本(旧应用,以及 `appid` 应用已发布的版本) |
166
- | 按钮 | 「**发布到企业目录**」(旧应用当前私有)或「**撤回企业目录**」(旧应用当前企业可见);`appid` 应用的成员版本是「**去版本管理发布**」 |
133
+ | 位置 | 内容 |
134
+ | ---- | ---------------------------------------------------------------------------------------------------- |
135
+ | 左 | 版本号;最新上传的那一行带「**最近上传**」标记 |
136
+ | 中 | 上传时间、包大小 |
137
+ | 状态 | 「**仅成员可见**」或「**企业可见**」;已停用的版本另有「**已停用**」 |
138
+ | 按钮 | 成员版本:「**去版本管理发布**」;已发布为线上版本的:「**云开发**」→ 打开控制台版本页并定位到该版本 |
167
139
 
168
- 已停用的版本没有发布 / 撤回 / 去版本管理发布按钮,「云开发」按钮也不可点。
140
+ 已停用的版本没有「去版本管理发布」按钮,「云开发」按钮也不可点。
169
141
 
170
- > **平台 appid 应用在「我的发布」里看到什么**(提示)
142
+ > **版本行的两种状态**(提示)
171
143
  >
172
- > `members` 版本显示「**仅成员可见**」,卡片统计为「**企业 n / 开发版本 n**」。版本列表上方会有提示:
173
- > 「这是 appid 应用:每次上传都是只有应用成员可见的开发版本,在云开发控制台「版本管理」里发布为线上版本后全企业可见。」
174
- > 成员版本没有「发布到企业目录」,只有「**去版本管理发布**」(打开控制台「版本管理」);
175
- > 发布为线上版本后,版本可见性变为 **enterprise(企业可见)**,显示「**企业可见**」并保留「**云开发**」按钮。
144
+ > 开发版本显示「**仅成员可见**」和「**去版本管理发布**」;发布为线上版本后,这一行变为「**企业可见**」并保留「**云开发**」按钮。
145
+ > 卡片统计始终是「**企业 n / 开发版本 n**」。
176
146
 
177
- ## appid 应用:发布为线上版本
147
+ ## 发布为线上版本
178
148
 
179
- 平台 `appid` 应用的上线**只在云开发控制台里完成**,不走应用中心的「发布到企业目录」。
149
+ 上线**只在云开发控制台里完成**。
180
150
 
181
151
  1. 打开云开发控制台(系统内置应用,启动台「更多工具」里,或搜索「云开发」直接打开),在顶部应用切换器选中你的应用。
182
152
  2. 侧栏点「**发布 → 版本管理**」。
@@ -184,6 +154,8 @@ appid 应用:
184
154
  4. 在下方版本列表里找到要上线的开发版本(每个版本都标出上传者和上传时间),点「**发布为线上版本**」。可以填写「发布说明(可选)」。
185
155
  5. 确认「把 v{版本} 发布为线上版本?」。
186
156
 
157
+ 也可以从「我的发布」直接进入:在应用卡片的版本行上点「**去版本管理发布**」。
158
+
187
159
  (截图:云开发控制台「版本管理」:线上版本、发布说明、版本列表与「发布为线上版本」,见文档站)
188
160
 
189
161
  「版本管理」上方是线上版本和发布说明,下方列出全部成员上传的开发版本,每个版本都可以「切换到此版本」(只切你自己桌面上的应用)、「发布为线上版本」或「回退到此版本」。
@@ -202,7 +174,7 @@ appid 应用:
202
174
  >
203
175
  > 已经发布过的版本再次发布(包括回退)直接复用当时的就绪发布。只用宿主能力、没有云资源的应用发布即可用,不需要签名。
204
176
 
205
- ### CLI 等价操作(appid 应用)
177
+ ### CLI 等价操作
206
178
 
207
179
  ```bash
208
180
  zleap-app releases APP_ID # 列出全部成员上传的开发版本、当前线上版本和发布记录
@@ -214,64 +186,6 @@ zleap-app release APP_ID --version-id VERSION_ID --notes "这次更新了什么"
214
186
  - 脚手架项目里是 `npm run versions` / `npm run release`;
215
187
  - 上传(`zleap-app publish`)只生成开发版本,发布线上版本要再执行 `release`。
216
188
 
217
- ## 发布到企业目录(仅旧 app_key 应用)
218
-
219
- > **appid 应用不适用**(注意)
220
- >
221
- > 这一节只适用于旧 `app_key` 应用。平台 `appid` 应用调用「发布到企业目录」(或 CLI `market-publish`)会被服务端拒绝:
222
- > 409 `USE_VERSION_MANAGEMENT`「这个应用请在云开发控制台「版本管理」里发布或回退」。请用上一节的「发布为线上版本」。
223
-
224
- 点某个版本行的「**发布到企业目录**」,确认框:
225
-
226
- > **发布"应用名 版本号"到企业目录?**
227
- >
228
- > 企业用户将能在应用中心看到这个固定版本。发布不会授予 Agent 或生产后台权限。
229
-
230
- 确认后提示「**应用包已发布到企业目录。**」;失败提示「发布范围更新失败,请刷新后重试。」
231
-
232
- 服务端会做的事:
233
-
234
- 1. 只有**版本的上传者**(或平台管理员)能改可见性;
235
- 2. 发布前**重新校验**这个版本的 Manifest;
236
- 3. 把这个应用在目录里的「当前版本」更新为**最新的企业可见版本**——别人在「发现」里看到、点「安装」装上的就是它。
237
-
238
- > **「固定版本」是什么意思**(提示)
239
- >
240
- > 发布的是**这一个版本**,不是整个应用。别人安装后,他们的安装就固定在这个版本,直到他们自己在「更新」里升级。
241
- > 你之后发布更新的版本,已安装的同事会在「更新」里看到「已安装 旧 → 最新 新」。
242
-
243
- ### CLI 等价操作(旧 app_key 应用)
244
-
245
- ```bash
246
- zleap-app publish ./out/my-app.zip --target https://os.example.com
247
- # 回执顶层有 app_id / version_id / package_id
248
- zleap-app market-publish <package_id> --app-key zl3f9a2c7e1b0d4a68 # 设为企业可见(--app-key 填 appid)
249
- zleap-app market-unpublish <package_id> --app-key zl3f9a2c7e1b0d4a68 # 撤回为仅自己可见
250
- ```
251
-
252
- - `market-publish` 只适用于**旧 `app_key` 应用**;`appid` 应用请用 `zleap-app release`(见上一节);
253
- - `market-publish` 的参数是 **package_id**(固定版本),不是 app_id;
254
- - 只能操作**本人**、**当前登录限域的 appid** 下的应用包;与应用中心按钮走同一个可见性服务,同样没有审核;
255
- - 需要带 `package.own.market` 权限的开发会话;旧会话请重新 `zleap-app auth login`;
256
- - 网络超时返回 unknown 时,先 `zleap-app status` 查该 package_id 的实际 visibility,不要盲目重试。
257
-
258
- ## 撤回企业目录(仅旧 app_key 应用)
259
-
260
- `appid` 应用没有「撤回企业目录」这一步:让线上版本回到旧版本,是在控制台「版本管理」里对旧版本点「回退到此版本」。下面只适用于旧 `app_key` 应用。
261
-
262
- 点「**撤回企业目录**」,确认框:
263
-
264
- > **从企业目录撤回"应用名 版本号"?**
265
- >
266
- > 撤回后新用户将无法发现此版本;其他人已安装的这个版本将无法再打开(你自己的安装不受影响)。安装记录和应用数据不会被删除,重新发布到企业目录后可恢复使用。
267
-
268
- 确认后提示「**应用包已从企业目录撤回。**」
269
-
270
- > **撤回会让同事的已有安装打不开**(危险)
271
- >
272
- > 服务端在打开应用时会检查:**不是上传者本人、且该版本不再企业可见** → 拒绝运行(「应用运行授权已失效」/「应用包版本不存在或无权访问」)。
273
- > 装着这个版本的其他用户**会立刻无法打开应用**,直到你重新发布这个版本,或他们升级到另一个企业可见版本。
274
-
275
189
  ## 编辑应用资料
276
190
 
277
191
  「⋯」→「**编辑应用资料**」打开「**应用资料**」抽屉:「完善应用介绍和预览,让大家更容易了解你的应用。资料修改不需要重新上传应用包。」
@@ -295,17 +209,17 @@ zleap-app market-unpublish <package_id> --app-key zl3f9a2c7e1b0d4a68 # 撤回
295
209
  >
296
210
  > > **删除"应用名"?**
297
211
  > >
298
- > > 将删除该应用的 N 个发布版本并撤销企业目录、安装、运行会话、Cloud 授权和发布候选。企业可见版本:N。已打开的沙箱会被宿主卸载,运行中的 Cloud sandbox 会失去授权并由 worker/reaper 回收。用户数据、Cloud 数据和归档文件会保留在清理保留期内,不会在此操作中直接清空。
212
+ > > 将删除该应用的 N 个发布版本并撤销安装、运行会话、Cloud 授权和发布候选。企业可见版本:N。已打开的沙箱会被宿主卸载,运行中的 Cloud sandbox 会失去授权并由 worker/reaper 回收。用户数据、Cloud 数据和归档文件会保留在清理保留期内,不会在此操作中直接清空。
299
213
  >
300
214
  > 成功提示二选一:「应用已删除,运行权限已撤销。」或「应用已删除,运行权限已撤销;归档和 Cloud 资源已标记待清理。」
301
215
  >
302
- > 删除影响**所有用户**的安装。删除后这个 `appid`(或旧 `app_key`)**不能再上传**(「该应用已删除,不能使用原应用标识重新上传」)。
303
- > 只想让新用户看不到,请用「撤回企业目录」。
216
+ > 删除影响**所有用户**的安装。删除后这个 `appid` **不能再上传**(「该应用已删除,不能使用原应用标识重新上传」)。
217
+ > 只想让使用者暂时看不到新版本,请在控制台「版本管理」里回退到上一个线上版本,或由管理员在「应用管控」里下架。
304
218
 
305
219
  ## 管理员下架
306
220
 
307
221
  平台管理员可以在「应用管控」里把整个应用**下架**:对所有非管理员隐藏,已安装用户也看不到。
308
- 下架与你的发布互相独立——你重新发布到企业目录(旧应用)或重新发布线上版本(`appid` 应用)**不会**解除管理员下架。
222
+ 下架与你的发布互相独立——你重新发布线上版本**不会**解除管理员下架,需要管理员重新上架。
309
223
 
310
224
  ## 操作结果不确定时
311
225
 
@@ -327,6 +241,6 @@ zleap-app market-unpublish <package_id> --app-key zl3f9a2c7e1b0d4a68 # 撤回
327
241
 
328
242
  - 应用中心界面总览(文档站 ./overview)
329
243
  - [安装与卸载](app-center-install.md) — 安装即授权、更新 / 回滚、应用窗口的授权入口
330
- - [云开发控制台 · 版本管理 / 版本与激活](console-release.md) — 发布候选、签名、激活与生产门禁
244
+ - [云开发控制台 · 版本管理](console-release.md) — 发布为线上版本、回退与发布记录
331
245
  - Manifest v2 配置(文档站 /reference/manifest)
332
246
  - [从开发到上线](dev-to-production.md)
@@ -19,12 +19,11 @@
19
19
 
20
20
  (截图:云函数页,见文档站)
21
21
 
22
- 云函数页:安装还没绑定签名发布时提示「云函数还不能运行」(appid 应用正常情况下不会出现,见[还没激活时](#还没激活时));函数列表只读展示 Manifest 声明。
22
+ 云函数页:安装还没绑定签名发布时提示「云函数还不能运行」,见[还没激活时](#还没激活时);函数列表只读展示 Manifest 声明。
23
23
 
24
24
  两个标签页只在**开发环境**下完整出现。切到**生产环境**时只剩只读的「后台能力」视图,顶部提示
25
25
  「生产环境只读:可以查看本人后台能力的调用记录与结果;函数调试、授权和触发器请在开发环境操作。」
26
- 这里只显示**你本人**在生产环境的激活与调用记录(没有时显示「生产环境还没有你的调用记录。」);
27
- 能力还没激活到生产时会提示该能力尚未在生产环境激活。
26
+ 这里只显示**你本人**在生产环境的调用记录(没有时显示「生产环境还没有你的调用记录。」)。应用还没发布为线上版本时,生产环境里没有可调用的后台能力。
28
27
 
29
28
  > **用命令行试调**(提示)
30
29
  >
@@ -43,11 +42,9 @@
43
42
 
44
43
  > **云函数还不能运行**
45
44
 
46
- appid 应用上传时自动签名,安装、切换版本、保存权限时自动绑定(还没有就绪发布的版本会当场补签),正常情况下不会看到这条提示。
47
- 如果看到了,提示正文是「当前安装还没有绑定签名版本。带云函数的版本上传时由平台自动签名;到「后台能力」里允许后台运行(或在版本管理切换一次版本),平台会自动补签并绑定。」,
48
- 右侧按钮「**去允许后台运行**」切到本页「后台能力」,在那里允许后台运行即会补签并绑定,见[带云资源的应用自动签名与绑定](console-release.md#带云资源的应用自动签名与绑定)。
49
-
50
- 旧 `app_key` 应用的提示正文是「需要把签名版本激活到开发环境。」,右侧按钮「**去激活**」跳到[版本与激活](console-legacy-release.md)页完成激活开发。
45
+ 提示正文是「当前安装还没有绑定签名版本。带云函数的版本上传时由平台自动签名;到「后台能力」里允许后台运行(或在版本管理切换一次版本),平台会自动补签并绑定。」,
46
+ 右侧按钮「**去允许后台运行**」切到本页「后台能力」,在那里允许后台运行即会补签并绑定。
47
+ 平台会自动补签并绑定,不需要手动操作。
51
48
 
52
49
  ### 函数表格
53
50
 
@@ -160,23 +157,13 @@ Provider 有三种类型,写在 `manifest.json` 的 `backend.providers` 里:
160
157
 
161
158
  > **授权与发布绑定**(提示)
162
159
  >
163
- > appid 应用:在这里点「允许后台运行」「撤销授权」「重新授权」,平台会同时把安装绑定到该版本的就绪发布
164
- > (还没有就绪发布时当场补签),**不会解除发布绑定**,也不需要再去「激活开发」。
160
+ > 在这里点「允许后台运行」「撤销授权」「重新授权」,平台会同时把安装绑定到该版本的就绪发布
161
+ > (还没有就绪发布时当场补签),**不会解除发布绑定**,也不需要再单独处理发布绑定。
165
162
  >
166
163
  > 另一条路径是应用窗口顶部的「**权限**」:在其中勾选后台能力并「保存并重新加载」,
167
164
  > 同样会把安装绑定到该版本的就绪发布(见[权限与授权](permissions.md))。
168
165
  > `logic_unit`、`builtin` 类型的能力在开发环境不需要绑定发布。
169
166
 
170
- > **旧 app_key 应用:授权操作会解除发布绑定**(注意)
171
- >
172
- > 旧应用在这里点「允许后台运行」「撤销授权」「重新授权」,都会**解除安装上的已签名发布绑定**。
173
- > 以 Node 云函数(`managed_function`)为执行方的能力随后会报 `FUNCTION_RELEASE_REQUIRED`,
174
- > 需要到[版本与激活](console-legacy-release.md#激活开发)页再点一次「**激活开发**」。
175
- > 安装已绑定发布时,确认框里会提前提示这一点;保存后面板顶部出现「**发布绑定已解除**」提示,侧栏「云函数」旁同步显示「未激活」。
176
- >
177
- > 「激活开发」**不要求**先允许后台运行,两者可以任意顺序完成;但只有两者都做了,后台能力才会真正执行。
178
- > 因为允许 / 撤销会解除发布绑定,推荐顺序仍是:**先允许后台运行,再激活开发**,最后重新加载应用。
179
-
180
167
  > **「关窗不取消后台授权」**(注意)
181
168
  >
182
169
  > 你关掉应用窗口,**不会**停止已批准的后台任务。这是设计如此——
@@ -511,19 +498,16 @@ Cron 用**五个字段**描述执行时间,依次为**分钟、小时、日期
511
498
 
512
499
  安装还没有绑定已签名发布。
513
500
 
514
- - appid 应用:上传时自动签名、安装和切换版本时自动绑定,正常情况下不会停在这里。在应用窗口「权限」里重新保存一次,
515
- 或在「版本管理」里切换一次版本,平台会自动补签并绑定。只有 `zleap-app diagnose` 提示 `next_action: app_prepare` 时,
516
- 才需要兜底运行 `zleap-app prepare`(只准备开发环境,不碰生产)。线上用户由「发布为线上版本」自动准备。
517
- - 旧 `app_key` 应用:到[版本与激活](console-legacy-release.md)完成「验证并签发」和「激活开发」。
501
+ 上传时自动签名、安装和切换版本时自动绑定,正常情况下不会停在这里。在应用窗口「权限」里重新保存一次,
502
+ 或在「版本管理」里切换一次版本,平台会自动补签并绑定。只有 `zleap-app diagnose` 提示 `next_action: app_prepare` 时,
503
+ 才需要兜底运行 `zleap-app prepare`(只准备开发环境,不碰生产)。线上用户由「发布为线上版本」自动准备。
518
504
 
519
505
  ### 试运行或 `callFunction` 报 `FUNCTION_RELEASE_REQUIRED`
520
506
 
521
507
  Node 云函数只运行绑定了就绪签名发布的版本。
522
508
 
523
- - appid 应用:正常情况下不会出现(上传自动签名 + 随用随签)。如果出现,在应用窗口「权限」里重新保存一次,
524
- 或在「版本管理」切换一次版本,平台会自动补签并绑定;仍然出现,说明部署的发布签名不可用(联系平台管理员检查签名密钥 / 信任配置),或重新上传。
525
- - 旧 `app_key` 应用:常见原因是还没激活,或激活后又在这里改过后台授权(会解除绑定)。
526
- 到[版本与激活](console-legacy-release.md#激活开发)页完成「验证并签发」和「激活开发」,然后重新加载应用。
509
+ 正常情况下不会出现(上传自动签名 + 随用随签)。如果出现,在应用窗口「权限」里重新保存一次,
510
+ 或在「版本管理」切换一次版本,平台会自动补签并绑定;仍然出现,说明部署的发布签名不可用(联系平台管理员检查签名密钥 / 信任配置),或重新上传。
527
511
 
528
512
  ### 「后台能力」里看不到我的能力
529
513
 
@@ -8,7 +8,7 @@
8
8
  > **一句话流程**(提示)
9
9
  >
10
10
  > 控制台「创建应用」→ 复制 `appid` → 脚手架带上 `appid` 或写进 `manifest.json` → `npm run deploy` 上传 →
11
- > (需要协作时)「团队」→「成员」里添加开发者 →(给全企业用时)「版本管理」里发布为线上版本(这一步只适用于 `appid` 应用)。
11
+ > (需要协作时)「团队」→「成员」里添加开发者 →(给全企业用时)「版本管理」里发布为线上版本。
12
12
 
13
13
  ## 创建应用
14
14
 
@@ -43,10 +43,12 @@
43
43
  1. **新项目:用脚手架创建,自动带上 appid**
44
44
 
45
45
  ```bash
46
- npm create zleap-app@latest my-app -- --appid zl3f9a2c7e1b0d4a68
46
+ npm create zleap-app@latest my-app -- --appid zl3f9a2c7e1b0d4a68 --name "客户拜访"
47
47
  ```
48
48
 
49
- 2. **已有项目:把 appid 写进 manifest.json(不再需要 app_key 和 publisher)**
49
+ `--name` 填控制台里的应用名:发布时应用名以 `manifest.json` 的 `name` 为准,不填会用目录名(这里是 `my-app`)。
50
+
51
+ 2. **已有项目:把 appid 写进 manifest.json**
50
52
 
51
53
  ```json
52
54
  {
@@ -96,22 +98,16 @@
96
98
 
97
99
  - **修改角色**(管理员):在成员行的角色下拉里切换「管理员 / 开发者」;
98
100
  - **移除**(管理员):点成员行的「**移除**」,确认「移除 {名字}?——移除后对方不能再上传或管理这个应用,已上传的版本保留。」;
99
- - **退出**(自己,且不是旧应用的上传者成员):在自己那一行点「**退出**」,确认「退出「{应用}」?——退出后你不能再上传或管理这个应用,需要管理员重新添加。」
101
+ - **退出**(自己):在自己那一行点「**退出**」,确认「退出「{应用}」?——退出后你不能再上传或管理这个应用,需要管理员重新添加。」
100
102
 
101
103
  应用**至少要保留一位管理员**。移除、退出或降级会让应用没有管理员时,操作被拒绝:
102
104
  40900「应用至少要保留一位管理员」,处理方式是先把另一位成员设为管理员,再做这个操作。
103
105
 
104
106
  非管理员调用成员管理会得到 40300「只有应用管理员可以管理成员」。
105
107
 
106
- ### 旧应用(`app_key`)
107
-
108
- 用旧 `app_key` 命名空间上传的已有应用,**上传过应用包的人视为管理员**,在成员列表里显示为管理员,
109
- 但那一行只有角色标签:没有角色下拉,也没有「移除」/「退出」按钮,不能在这里修改角色或退出。
110
- (其他通过邀请加入的成员仍按上面的规则管理。)
111
-
112
- ## 上传时的成员校验
108
+ ### 上传时的成员校验
113
109
 
114
- 用 `appid` 的应用,谁能上传由成员决定,Manifest 里的 `publisher` 不再起作用:
110
+ 谁能上传由成员决定:
115
111
 
116
112
  | 情况 | 结果 |
117
113
  | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
@@ -146,10 +142,6 @@
146
142
 
147
143
  用户授权页:只展示人数统计,不展示具体用户(图为还没有人授权时的空状态)。
148
144
 
149
- ## 目前的限制
150
-
151
- - 旧 `app_key` 应用仍走「版本与激活」,那里看不到其他成员的发布。
152
-
153
145
  ## 相关
154
146
 
155
147
  - 快速开始(文档站 /guide/quickstart) — 从创建应用到第一次上传
@@ -2,12 +2,8 @@
2
2
 
3
3
  # 版本管理
4
4
 
5
- 控制台侧栏「发布」组下的这个入口,按应用类型显示为两个不同的页面:
6
-
7
- | 应用 | 入口名称 | 做什么 |
8
- | --------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
9
- | 在控制台「创建应用」得到平台 `appid`(`zl…`)的应用 | **版本管理** | 选一个开发版本「发布为线上版本」,全企业可见;回退、发布记录 |
10
- | 旧的 `app_key` 命名空间应用 | **版本与激活** | 发布候选、签名、激活开发 / 生产(见[版本与激活(旧 app_key 应用)](console-legacy-release.md)) |
5
+ 控制台侧栏「发布」组下的这个入口负责应用版本的发布与回退:选一个开发版本「发布为线上版本」,全企业可见;
6
+ 回退就是把旧版本再发布一次。
11
7
 
12
8
  > **应用中心「我的发布」与这里的关系**(提示)
13
9
  >
@@ -50,10 +46,10 @@
50
46
 
51
47
  ### 每个版本的按钮
52
48
 
53
- | 按钮 | 出现在 | 作用 |
54
- | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------ |
55
- | **发布为线上版本** | 比线上版本新的版本,或还没发布过线上版本时 | 把这个版本设为线上版本 |
56
- | **回退到此版本** | 比线上版本旧的版本 | 同样是「发布」,只是目标是旧版本 |
49
+ | 按钮 | 出现在 | 作用 |
50
+ | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
51
+ | **发布为线上版本** | 比线上版本新的版本,或还没发布过线上版本时 | 把这个版本设为线上版本 |
52
+ | **回退到此版本** | 比线上版本旧的版本 | 同样是「发布」,只是目标是旧版本 |
57
53
  | **切换到此版本** | 你已安装该应用,且不是你正在用的版本 | 把**你本人**的安装切到这个版本,提示「你桌面上的应用已切换到 v{版本}(只影响你自己),重新打开应用即可使用」 |
58
54
 
59
55
  悬停「切换到此版本」会提示:「只把你自己桌面上的这个应用切到这个版本,方便试用同事的改动;不影响其他人,也不改变线上版本」。
@@ -89,18 +85,18 @@
89
85
 
90
86
  版本声明了 `data.collections`、任何 `cloud.*` 能力、`runtime.backend` 或 headless 的 `provides` 时,就是带云资源的版本。
91
87
  这样的版本**第一次**「发布为线上版本」时,平台会自动完成**应用级**的生产准备:
92
- 生产环境 → 签发生产发布(归属上传者)→ 生产门禁(签名、审批窗口、信任策略核对)→ 生产库与生产集合。
93
- 这些步骤不依赖任何人的安装,**任一成员都可以发布任一版本**,不要求上传者正在使用这个版本;
94
- 也**不需要你点「激活到生产」**(那个按钮只属于旧 `app_key` 应用)。
88
+ 生产环境 → 签发生产候选(归属上传者)→ 生产门禁 → 生产库与生产集合。
89
+ 这些步骤不依赖任何人的安装,**任一成员都可以发布任一版本**,不要求上传者正在使用这个版本,
90
+ 也不需要手工签名或激活。
95
91
 
96
92
  以下情况发布会被拒绝(业务码都是 40900,原因在 `detail.reason`):
97
93
 
98
- | 业务码 | message | `reason` | next_action |
99
- | ------ | ------------------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------- |
100
- | 40900 | 生产数据库还没就绪,暂时不能发布 | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪,稍后在版本管理里重新发布;持续失败请在控制台「数据库」查看状态 |
101
- | 40900 | 这个版本的上传者账号已停用,无法发布 | `UPLOADER_INACTIVE` | 请其他成员重新上传这个版本(npm run deploy)后再发布 |
94
+ | 业务码 | message | `reason` | next_action |
95
+ | ------ | ------------------------------------ | ------------------------- | --------------------------------------------------------------------------------- |
96
+ | 40900 | 生产数据库还没就绪,暂时不能发布 | `PROD_DATABASE_NOT_READY` | 通常 1 分钟内就绪,稍后在版本管理里重新发布;持续失败请在控制台「数据库」查看状态 |
97
+ | 40900 | 这个版本的上传者账号已停用,无法发布 | `UPLOADER_INACTIVE` | 请其他成员重新上传这个版本(npm run deploy)后再发布 |
102
98
 
103
- 生产门禁不通过时,返回与激活相同的 `reason`(如 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、`RELEASE_POLICY_STALE`、`PRODUCTION_RELEASE_UNAVAILABLE`),重新发布即会重新签发。
99
+ 生产准备失败时会返回对应原因(例如生产门禁未通过 `RELEASE_APPROVAL_EXPIRED_OR_MISSING`、部署未开放生产),重新发布即会重新签发。
104
100
 
105
101
  **再次发布 / 回退到以前发布过的版本**:当时的生产准备已经做完,直接复用当时就绪的发布。
106
102
 
@@ -108,8 +104,8 @@
108
104
 
109
105
  ### 带云资源的应用自动签名与绑定
110
106
 
111
- 带云函数 / 后台能力的版本,**上传时由平台自动签名**,得到就绪发布;没有「新建候选」「验证并签发」「激活开发」这些步骤,
112
- 「版本管理」页也没有单独的云函数激活区块。
107
+ 带云函数 / 后台能力的版本,**上传时由平台自动签名**,得到就绪发布;安装、切换版本、保存权限或允许后台运行时自动绑定,
108
+ 不需要额外步骤。「版本管理」页只有版本列表与发布记录。
113
109
 
114
110
  之后在这些时机,平台会把安装自动绑定到该版本的就绪发布:安装应用;切换版本(本页「切换到此版本」、CLI `update` / `rollback`、`npm run deploy`);
115
111
  在应用窗口「权限」里保存;在控制台「云函数」页允许 / 撤销后台运行。
@@ -143,8 +139,7 @@ zleap-app releases <app_id>
143
139
  zleap-app release <app_id> --version-id <version_id> [--notes 说明]
144
140
  ```
145
141
 
146
- AI 开发工具(`zleap-app mcp serve`)里对应 `app_releases` / `app_release` 两个工具。只支持 `appid` 应用;
147
- 旧 `app_key` 应用调用返回 40900(`reason` 为 `LEGACY_APP`)。
142
+ AI 开发工具(`zleap-app mcp serve`)里对应 `app_releases` / `app_release` 两个工具。
148
143
 
149
144
  ### 接口
150
145
 
@@ -157,13 +152,12 @@ AI 开发工具(`zleap-app mcp serve`)里对应 `app_releases` / `app_releas
157
152
  | `GET /api/v1/app-dev/apps/{app_id}/releases` / `POST /api/v1/app-dev/apps/{app_id}/release` | 同上两条,用开发凭据(CLI)调用 |
158
153
 
159
154
  `unchanged` 为 `true` 表示发布的就是当前线上版本;`prepared` 是带云资源的版本的生产准备结果,不需要准备时为 `null`。
160
- `notes` 超过 500 字返回 42200「发布说明最多 500 字」。对旧 `app_key` 应用调用返回 40900「该应用使用旧的命名空间标识,请在「版本与激活」里管理版本」(`reason` 为 `LEGACY_APP`)。
155
+ `notes` 超过 500 字返回 42200「发布说明最多 500 字」。
161
156
 
162
157
  使用者一侧的更新检查接口见 版本更新与授权登录 · 平台接口(文档站 /reference/app-runtime#平台接口-供参考)。
163
158
 
164
159
  ## 相关
165
160
 
166
- - [版本与激活(旧 app_key 应用)](console-legacy-release.md)
167
161
  - 版本更新与授权登录(文档站 /reference/app-runtime) — 应用里提示更新、`applyUpdate()`
168
162
  - [创建应用与成员管理](console-members.md)
169
163
  - [从开发到上线](dev-to-production.md) — 端到端流程