cloudcc-cli 2.3.2 → 2.3.3

package/src/pagelayout/docs/devguide.md

@@ -1,30 +1,19 @@
-# CloudCC 页面布局使用总结
+# CloudCC 页面布局 CLI 命令说明
 
-页面布局（Page Layout）用于定义对象在详情页的字段展示方式，包括字段排列、分区、按钮位置等。
-
-**前置条件**：页面布局操作需要先选中自定义对象或标准对象。
-
----
-
-## 快速开始（CLI 命令）
-
-### 支持的页面布局操作
+## 支持的命令
 
 | 操作 | 说明 |
 |------|------|
 | `get` | 查询页面布局列表 |
 | `create` | 创建/复制页面布局 |
-
----
+| `delete` | 删除页面布局 |
 
 ## CLI 命令详解
 
 ### 查询页面布局列表
 
-获取指定对象的页面布局列表。
-
 ```bash
-cc get pagelayout <projectPath> <objApiName>
+cc get pagelayout <projectPath> <prefix>
 ```
 
 **参数说明：**
@@ -32,7 +21,7 @@ cc get pagelayout <projectPath> <objApiName>
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `projectPath` | 否 | 项目路径，`.` 表示当前目录 |
-| `objApiName` | 是 | 对象 API 名称（前缀） |
+| `prefix` | 是 | 对象前缀（如 001, b25） |
 
 **示例：**
 
@@ -40,16 +29,12 @@ cc get pagelayout <projectPath> <objApiName>
 # 查询对象 b25 的页面布局列表
 cc get pagelayout . b25
 
-# 使用完整 API 名称
-cc get pagelayout . Account
+# 查询客户对象（001）的页面布局列表
+cc get pagelayout . 001
 ```
 
----
-
 ### 创建页面布局
 
-基于现有布局创建新的页面布局。
-
 ```bash
 cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]
 ```
@@ -77,219 +62,22 @@ cc create pagelayout . 20267D1465464C5OB6m5 "课程表2" add20261DA7347CZPAUz
 cc create pagelayout . 20267D1465464C5OB6m5 "课程表2" add20261DA7347CZPAUz false
 ```
 
----
-
-## 完整工作流示例
-
-### 场景：为自定义对象创建新的页面布局
+### 删除页面布局
 
 ```bash
-# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
-cat cloudcc-cli.config.js
-
-# 2. 查询对象的页面布局列表
-cc get pagelayout . b25
-
-# 3. 根据对象 ID 创建新布局
-cc create pagelayout . 20267D1465464C5OB6m5 "新的布局名称"
-
-# 4. 验证创建成功，再次查询列表
-cc get pagelayout . b25
+cc delete pagelayout <projectPath> <layoutId>
 ```
 
----
-
-## API 接口详情
-
-### 什么是页面布局？
-
-**页面布局（Page Layout）** 定义了对象在详情页的展示方式，包括：
-- 字段的排列和分组
-- 相关列表的显示
-- 操作按钮的位置
-- 动态布局规则
-
-### 核心属性
-
-| 属性 | 说明 | 示例 |
-|------|------|------|
-| **ID（id）** | 页面布局唯一标识 | `add20261DA7347CZPAUz` |
-| **名称（layoutName）** | 页面布局显示名称 | `课程表布局` |
-| **对象 ID（objid）** | 关联的对象 ID | `20267D1465464C5OB6m5` |
-
----
-
-## 一、查询页面布局列表
-
-### 1.1 接口说明
-
-**接口**: `POST /api/layout/queryPageLayout`
-
-**请求参数**：
-
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| `prefix` | string | 是 | 对象 API 名称前缀 |
-
-**返回数据**：
-
-```javascript
-{
-  "result": true,
-  "returnInfo": "操作成功",
-  "layouts": [
-    {
-      "id": "add20261DA7347CZPAUz",
-      "layoutName": "默认布局",
-      "objid": "20267D1465464C5OB6m5",
-      // ... 其他字段
-    }
-  ]
-}
-```
-
-**返回字段说明**：
+**参数说明：**
 
-| 字段 | 类型 | 说明 |
+| 参数 | 必填 | 说明 |
 |------|------|------|
-| `layouts` | array | 页面布局数组 |
-| `layouts[].id` | string | 布局 ID |
-| `layouts[].layoutName` | string | 布局名称 |
-| `layouts[].objid` | string | 关联对象 ID |
-
----
-
-## 二、创建页面布局
-
-创建页面布局是一个两步流程：
-
-1. **获取现有布局列表**：调用 `layout/newpage` 接口获取可用于复制的布局
-2. **复制创建新布局**：调用 `layout/cloneLayout` 接口基于选定布局创建新布局
-
-### 2.1 获取现有布局列表
-
-**接口**: `POST /api/layout/newpage`
-
-**请求参数**：
-
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| `objid` | string | 是 | 对象 ID |
-
-**返回数据**：
-
-```javascript
-{
-  "result": true,
-  "returnInfo": "操作成功",
-  "layouts": [
-    {
-      "id": "add20261DA7347CZPAUz",
-      "layoutName": "默认布局",
-      "objid": "20267D1465464C5OB6m5"
-    }
-  ]
-}
-```
-
-**默认布局选择逻辑**：
-
-- 返回列表中的第一个布局作为默认复制源
-
-### 2.2 复制创建新布局
-
-**接口**: `POST /api/layout/cloneLayout`
-
-**请求参数**：
-
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| `layoutId` | string | 是 | 要复制的源布局 ID |
-| `layoutName` | string | 是 | 新布局名称 |
-| `objid` | string | 是 | 对象 ID |
-| `isCloneDynamic` | string | 否 | 是否复制动态布局规则，默认 `"true"` |
-
-**请求示例**：
-
-```javascript
-{
-  "layoutId": "add20261DA7347CZPAUz",
-  "layoutName": "课程表2",
-  "objid": "20267D1465464C5OB6m5",
-  "isCloneDynamic": "true"
-}
-```
-
-**返回数据**：
-
-```javascript
-{
-  "result": true,
-  "returnInfo": "操作成功",
-  "data": {
-    "id": "add2026XXXXXXXXXXXXX",
-    "layoutName": "课程表2"
-  }
-}
-```
-
----
-
-## 三、页面布局数据结构
+| `projectPath` | 否 | 项目路径，`.` 表示当前目录 |
+| `layoutId` | 是 | 要删除的页面布局 ID |
 
-### 3.1 列表数据格式
+**示例：**
 
-```javascript
-{
-  id: "add20261DA7347CZPAUz",
-  layoutName: "默认布局",
-  objid: "20267D1465464C5OB6m5"
-}
+```bash
+# 删除指定页面布局
+cc delete pagelayout . add202610BD89F09XyGT
 ```
-
----
-
-## 四、最佳实践
-
-### 命名规范
-
-| 项目 | 规范 | 示例 |
-|------|------|------|
-| 布局名称 | 使用描述性名称 | `标准详情页布局`、`移动端布局` |
-| 复制源选择 | 选择结构最相近的布局作为复制源 | - |
-
-### 布局设计建议
-
-- **按需复制动态布局规则**：如果源布局有复杂的动态规则，确认是否需要复制到新布局
-- **避免重复创建**：创建前先查询现有布局，避免重复
-
-### 推荐操作流程
-
-1. 查看对象现有布局：`cc get pagelayout . <apiName>`
-2. 确定复制源布局 ID
-3. 创建新布局：`cc create pagelayout . <objId> <layoutName> [sourceLayoutId]`
-4. 验证创建结果
-
----
-
-## 五、常见问题
-
-**Q: 为什么查询页面布局需要先选中对象？**
-
-A: 页面布局是绑定到具体对象的，不同对象有不同的字段和关联关系，因此必须先确定对象才能操作其页面布局。
-
-**Q: 如何获取对象 ID？**
-
-A: 可以通过对象 API 名称查询对象信息获取 ID，或从管理后台的对象管理页面获取。
-
-**Q: isCloneDynamic 参数的作用是什么？**
-
-A: 该参数控制是否复制源布局的动态布局规则。设置为 `"true"` 时会复制动态规则，设置为 `"false"` 则只复制静态布局。
-
-**Q: 创建页面布局时报错 "对象不存在"？**
-
-A: 请确认传入的 `objId` 是正确的对象 ID，且该对象在当前环境中存在。
-
----
-
-*文档版本：1.0 | 最后更新：2026-03-26*

package/src/pagelayout/get.js

@@ -4,21 +4,21 @@ const chalk = require("chalk");
 
 /**
  * 查询页面布局列表
- * 用法：cc get pagelayout <projectPath> <objApiName>
+ * 用法：cc get pagelayout <projectPath> <prefix>
  */
 async function get(argvs, isMcp = false) {
     const projectPath = argvs[2] || process.cwd();
-    const objApiName = argvs[3];
+    const prefix = argvs[3];
 
-    if (!objApiName) {
+    if (!prefix) {
         console.error();
-        console.error(chalk.red("Error: 缺少对象 API 名称"));
-        console.error("用法: cc get pagelayout <projectPath> <objApiName>");
+        console.error(chalk.red("Error: 缺少对象前缀"));
+        console.error("用法: cc get pagelayout <projectPath> <prefix>");
         console.error("示例:");
+        console.error("  cc get pagelayout . 001");
         console.error("  cc get pagelayout . b25");
-        console.error("  cc get pagelayout . Account");
         console.error();
-        throw new Error("缺少必需参数: objApiName");
+        throw new Error("缺少必需参数: prefix");
     }
 
     const config = await getPackageJson(projectPath);
@@ -26,13 +26,13 @@ async function get(argvs, isMcp = false) {
     const res = await postClass(
         config.setupSvc + "/api/layout/queryPageLayout",
         {
-            prefix: objApiName
+            prefix: prefix
         },
         config.accessToken
     );
 
     if (res && res.result) {
-        const layouts = res.layouts || [];
+        const layouts = res.data?.layouts || [];
         if (!isMcp) {
             console.log(JSON.stringify(layouts));
         }

package/src/pagelayout/index.js

@@ -1,6 +1,7 @@
 const cc = {}
 cc.create = require("./create")
 cc.get = require("./get")
+cc.delete = require("./delete")
 cc.doc = require("./doc")
 async function main(action, argvs) {
   await cc[action](argvs)

package/src/plugin/docs/devguide.md

@@ -5,6 +5,68 @@
 
 ---
 
+## CLI 与本地文件（必读）
+
+`plugins/<插件名>/` 目录、`config.json` 以及首次发布写回的 `id` 均与 **cloudcc-cli** 的创建、发布、拉取逻辑绑定。**必须通过下列命令** 完成新建插件目录、与云端同步、发布与删除；不要手工整包复制其他项目的 `plugins/`、不要私自篡改 `config.json` 中的 `id` 或破坏元数据，否则容易导致编译入口错误、发布失败或与云端不一致。
+
+**允许的做法**：在 CLI 已生成的目录内用 IDE 编辑 `.vue`、子组件与 `utils/` 等源码；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+
+执行命令前请确认：已完成 `cc doc project devguide` 中的环境初始化，项目根目录配置可用且具备 `accessToken`（发布流程还会使用 `pluginToken` / 账号密钥等，以你项目配置为准）。
+
+### 命令总览（以代码实现为准）
+
+```bash
+cc create plugin <name>
+cc publish plugin <name>
+cc get plugin [projectPath]
+cc detail plugin <pluginName> [pluginId] [projectPath]
+cc detail plugin "" <pluginId> [projectPath]
+cc pull plugin <pluginNameOrId> [projectPath]
+cc delete plugin <pluginNameOrId> [projectPath]
+cc doc plugin <introduction|devguide>
+```
+
+参数约定：
+
+- `name` / `pluginName`：插件目录名，与 `plugins/<name>/` 一致。
+- `projectPath`：项目根路径；不传则使用当前工作目录。`get` 的第一个可选参数即为 `projectPath`。
+- `pluginNameOrId`：本地目录名，或云端组件 ID；若本地存在 `config.json` 且含 `id`，`pull` / `delete` 会优先使用该 `id`。
+- `pluginId`：`detail` 仅查云端时，将 `pluginName` 置空：`cc detail plugin "" <pluginId>`。
+
+### 命令作用摘要
+
+| 命令 | 作用 |
+|------|------|
+| `create` | 在 `plugins/<name>/` 生成入口 `.vue`、`components/`、`config.json` 等模板 |
+| `publish` | 使用 `vue-cli-service` 编译并上传；首次成功且接口返回 `id` 时可写回 `config.json` |
+| `get` | 拉取云端组件列表，标准输出为 JSON |
+| `detail` | 按目录名读本地；或按 `pluginId` 读云端（不传 `pluginName` 时） |
+| `pull` | 按本地 `id` 或按传入的 ID 从云端还原文件到本地 `plugins/` 等路径 |
+| `delete` | 调用接口删除云端组件 |
+| `doc` | 输出 `introduction` 或 `devguide`（`devguide` 含附录 CCDK SDK 速查） |
+
+### 推荐操作顺序
+
+```bash
+# 1) 查看云端已有组件（可选）
+cc get plugin .
+
+# 2) 仅通过 create 生成目录与模板
+cc create plugin my_plugin
+
+# 3) 本地调试后发布（勿跳过 CLI 发布流程）
+cc publish plugin my_plugin
+
+# 4) 与云端对齐或迁移机器时拉取
+cc pull plugin my_plugin
+# 或已知云端 ID：cc pull plugin <id> .
+
+# 5) 不再使用时删除云端组件
+cc delete plugin my_plugin
+```
+
+---
+
 ## 0. 自定义组件概述（能力与场景）
 
 本文节整合了仓库内实践用法，帮助你在开始编码前先判断：什么是自定义组件、能解决什么问题、何时该用。
@@ -100,7 +162,8 @@ npm run serve
 
 ### 1.2 创建组件
 
-- 新建一个组件文件，**组件名称必须满足 DOM 命名规则**，例如：`cc-com-demo.vue`
+- **使用本 CLI 时**：在项目根执行 `cc create plugin <name>`，会在 `plugins/<name>/` 生成标准模板（推荐）。
+- 或在模板工程中手动新建入口文件，**组件名称必须满足 DOM 命名规则**，例如：`cc-com-demo.vue`
   - 推荐遵循：以 `cc-` 开头，后续使用小写单词和 `-` 连接。
 
 ### 1.3 在 `App` 中引入组件
@@ -115,12 +178,15 @@ npm run serve
 
 ### 1.5 发布组件
 
-在 VS Code 中：
+**推荐（与仓库、CI 一致）**：在项目根目录执行：
+
+```bash
+cc publish plugin <与目录名一致的 name>
+```
 
-- 右键点击组件的入口文件（你的自定义组件文件）
-- 选择「发布组件」（CloudCC 插件菜单）
-- 控制台提示发布成功信息，表示组件已经上传至 CloudCC
-  平台，可在页面编辑器中使用。
+CLI 会编译 `plugins/<name>/<name>.vue` 并上传；首次成功且接口返回 `id` 时可能写回 `plugins/<name>/config.json`。
+
+也可在 VS Code 中右键组件入口文件，选择「发布组件」（CloudCC 扩展），控制台提示成功即表示已上传至平台，可在页面编辑器中使用。
 
 ---
 
@@ -847,6 +913,7 @@ componentInfo: {
 
 ## 13. 自定义组件开发 Checklist
 
+- [ ] 插件目录与云端同步仅通过 `cc create` / `cc publish` / `cc pull` / `cc delete` 等命令操作，不整包复制他人 `plugins/` 或手改 `config.json` 的 `id`
 - [ ] 组件文件名与 `componentInfo.component` 命名符合规范（小写 + `-`
       分隔，全局唯一）
 - [ ] 样式默认使用 `lang="scss" scoped`，避免样式污染
@@ -860,7 +927,9 @@ componentInfo: {
 
 ---
 
-## 14. 命令使用说明（补充）
+## 14. 命令使用说明（与实现一致）
+
+文首「CLI 与本地文件（必读）」为总览；本节按子命令列出行为细节。
 
 ### 14.1 create
 
@@ -868,7 +937,7 @@ componentInfo: {
 cc create plugin <name>
 ```
 
-- 创建 `plugins/<name>/` 目录及基础模板文件。
+- 创建 `plugins/<name>/` 目录、入口 `<name>.vue`、`components/` 与 `config.json` 模板。
 
 ### 14.2 publish
 
@@ -876,8 +945,8 @@ cc create plugin <name>
 cc publish plugin <name>
 ```
 
-- 编译并发布 `plugins/<name>/` 到云端。
-- 首次发布成功且返回 `id` 时，会写回 `plugins/<name>/config.json`。
+- 以 `plugins/<name>/<name>.vue` 为入口编译（`vue-cli-service build --target lib`），再上传到云端。
+- 首次发布成功且响应包含 `id` 时，会写回 `plugins/<name>/config.json`（若此前无 `id`）。
 
 ### 14.3 get
 
@@ -885,17 +954,19 @@ cc publish plugin <name>
 cc get plugin [projectPath]
 ```
 
-- 获取云端插件列表，输出 JSON。
+- 分页请求云端组件列表，标准输出为 JSON 数组。
+- `projectPath` 可选，用于解析项目根下的 `cloudcc-cli` 配置。
 
 ### 14.4 detail
 
 ```bash
-cc detail plugin <pluginName> [projectPath]
+cc detail plugin <pluginName> [pluginId] [projectPath]
 cc detail plugin "" <pluginId> [projectPath]
 ```
 
-- 传 `pluginName`：查本地 `plugins/<pluginName>/`。
-- 传 `pluginId`：查云端详情。
+- 提供 `pluginName`（且非空）：读取本地 `plugins/<pluginName>/` 的 `config.json` 与入口 `.vue`。
+- 将 `pluginName` 置为空并传 `pluginId`：仅从云端查询详情（`projectPath` 仍用于配置）。
+- 需要指定项目根且保留「仅本地名」时，可用占位：`cc detail plugin <pluginName> "" <projectPath>`（中间空串表示无 `pluginId`）。
 
 ### 14.5 pull
 
@@ -903,7 +974,8 @@ cc detail plugin "" <pluginId> [projectPath]
 cc pull plugin <pluginNameOrId> [projectPath]
 ```
 
-- 若本地 `config.json` 有 `id`，优先按该 `id` 拉取；否则按输入值当 `id` 拉取。
+- 若 `plugins/<输入>/config.json` 存在且含 `id`，按该 `id` 拉取。
+- 否则将输入视为云端组件 ID，拉取后在 `plugins/<归一化名称>/` 等处落盘并更新 `config.json`。
 
 ### 14.6 delete
 
@@ -911,7 +983,8 @@ cc pull plugin <pluginNameOrId> [projectPath]
 cc delete plugin <pluginNameOrId> [projectPath]
 ```
 
-- 若本地 `config.json` 有 `id`，优先按该 `id` 删除；否则按输入值当 `id` 删除。
+- 若本地 `plugins/<name>/config.json` 存在且含 `id`，优先按该 `id` 调删除接口。
+- 否则将参数视为云端 ID 直接删除。
 
 ### 14.7 doc
 
@@ -920,4 +993,4 @@ cc doc plugin introduction
 cc doc plugin devguide
 ```
 
-- 输出 plugin 模块文档内容。
+- 仅支持 `introduction` 与 `devguide`；`devguide` 会在正文后拼接附录「CCDK SDK 速查」。