cloudcc-cli 2.3.1 → 2.3.3

package/src/user/docs/devguide.md

@@ -0,0 +1,122 @@
+# CloudCC 用户 CLI 命令说明
+
+## 支持的命令
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新用户 |
+| `get` | 查询用户列表 |
+| `view` | 查看单个用户详情 |
+| `update` | 编辑/禁用用户 |
+| `delete` | 删除用户 |
+
+## CLI 命令详解
+
+### 创建用户
+
+```bash
+cc create user <path> <userName> <profileId> [email]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `userName` | 是 | 用户名称 |
+| `profileId` | 是 | 关联简档 ID |
+| `email` | 否 | 用户邮箱 |
+
+**示例：**
+
+```bash
+# 创建用户
+cc create user . "张三" a0I9D000000XXXXUAI
+
+# 创建带邮箱的用户
+cc create user . "李四" a0I9D000000XXXXUAI "lisi@example.com"
+```
+
+### 查询用户列表
+
+```bash
+cc get user <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**查询条件参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `start` | number | 起始位置，默认 0 |
+| `limit` | number | 每页条数，默认 30 |
+| `keyword` | string | 搜索关键词 |
+
+**示例：**
+
+```bash
+# 获取所有用户
+cc get user .
+
+# 带查询条件（搜索关键词）
+cc get user . '%7B%22keyword%22%3A%22张三%22%2C%22limit%22%3A50%7D'
+```
+
+### 查看单个用户详情
+
+```bash
+cc view user <projectPath> <userId>
+```
+
+**示例：**
+
+```bash
+cc view user . 00520260C00C6FEfsMnT
+```
+
+### 编辑/禁用用户
+
+```bash
+cc update user <projectPath> <userDataJson>
+```
+
+**userDataJson 关键字段：**
+
+| 字段名 | 说明 |
+|--------|------|
+| `id` | 用户 ID（必填）|
+| `loginName` | 登录名（必填）|
+| `isusing` | 是否启用：`true`/`false` |
+| `lastName` | 姓 |
+| `email` | 邮箱 |
+| `mobile` | 手机 |
+| `profileId` | 简档 ID |
+| `role` | 角色 ID |
+
+**示例：**
+
+```bash
+# 禁用用户
+cc update user . '%7B%22id%22%3A%22xxx%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22false%22%7D'
+
+# 启用用户
+cc update user . '%7B%22id%22%3A%22xxx%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22true%22%7D'
+```
+
+### 删除用户
+
+```bash
+cc delete user <projectPath> <userId>
+```
+
+**示例：**
+
+```bash
+cc delete user . 00520260C00C6FEfsMnT
+```

package/src/user/docs/introduction.md

@@ -0,0 +1,124 @@
+# CloudCC 用户使用总结
+
+用户（User）用于定义 CloudCC 系统中的登录账号，每个用户都关联一个简档以确定其权限。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的用户操作
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新用户 |
+| `get` | 查询用户列表 |
+| `delete` | 删除用户 |
+
+---
+
+## CLI 命令详解
+
+### 创建用户
+
+创建一个新的 CloudCC 用户。
+
+```bash
+cc create user <path> <userName> <profileId> [email]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `userName` | 是 | 用户名称 |
+| `profileId` | 是 | 关联简档 ID |
+| `email` | 否 | 用户邮箱 |
+
+**示例：**
+
+```bash
+# 创建用户
+cc create user . "张三" a0I9D000000XXXXUAI
+
+# 创建带邮箱的用户
+cc create user . "李四" a0I9D000000XXXXUAI "lisi@example.com"
+```
+
+---
+
+### 查询用户列表
+
+获取当前环境中的所有用户列表。
+
+```bash
+cc get user <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**示例：**
+
+```bash
+# 获取所有用户
+cc get user .
+
+# 带查询条件
+cc get user . '%7B%22status%22%3A%22active%22%7D'
+```
+
+---
+
+### 删除用户
+
+删除指定的用户。
+
+```bash
+cc delete user <projectPath> <userId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `userId` | 是 | 用户 ID |
+
+**示例：**
+
+```bash
+# 删除指定用户
+cc delete user . a0I9D000000XXXXUAI
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为新员工创建 CloudCC 账号
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询可用简档，确定要分配的权限
+cc get profile .
+
+# 3. 创建新用户
+cc create user . "王五" a0I9D000000XXXXUAI "wangwu@example.com"
+
+# 4. 验证用户创建成功
+cc get user .
+
+# 5. 如需删除
+# cc delete user . <userId>
+```
+
+---
+
+*文档版本：1.0 | 最后更新：2026-03-26*

package/src/user/get.js

@@ -0,0 +1,112 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+const chalk = require("chalk");
+
+/**
+ * 获取用户视图列表
+ * @param {Object} config - 项目配置
+ * @returns {Promise<string>} 视图 ID
+ */
+async function getUserViewId(config) {
+    try {
+        const res = await postClass(
+            config.setupSvc + "/api/view/list/getViewList",
+            { objId: "user" },
+            config.accessToken
+        );
+
+        if (res && res.result && res.data && Array.isArray(res.data) && res.data.length > 0) {
+            // 查找"全部"视图
+            const allView = res.data.find(item =>
+                item.name === "全部" ||
+                item.label === "全部" ||
+                item.viewName === "全部" ||
+                item.name === "All" ||
+                item.label === "All"
+            );
+
+            if (allView) {
+                return allView.id || allView.viewId;
+            }
+
+            // 没有找到"全部"视图，使用第一条数据
+            return res.data[0].id || res.data[0].viewId;
+        }
+
+        throw new Error("未找到用户视图列表");
+    } catch (error) {
+        throw new Error("获取用户视图列表失败: " + error.message);
+    }
+}
+
+/**
+ * 查询用户列表
+ * 用法：cc get user <projectPath> [encodedCondJson]
+ */
+async function get(argvs, isMcp = false) {
+    const projectPath = argvs[2] || process.cwd();
+    const condArg = argvs[3];
+
+    let body = {};
+    if (condArg) {
+        try {
+            body = JSON.parse(decodeURI(condArg));
+        } catch (e) {
+            try {
+                body = JSON.parse(condArg);
+            } catch (e2) {
+                throw new Error("Get User Failed: encodedCondJson 解析失败，请传 encodeURI(JSON.stringify(...))");
+            }
+        }
+    }
+
+    const config = await getPackageJson(projectPath);
+
+    // 如果没有指定 viewId，先查询视图列表获取
+    if (!body.viewId) {
+        try {
+            body.viewId = await getUserViewId(config);
+        } catch (error) {
+            console.error(chalk.yellow("Warning: " + error.message));
+        }
+    }
+
+    const res = await postClass(
+        config.setupSvc + "/api/usermange/queryUserList",
+        {
+            start: 0,
+            limit: 30,
+            keyword: "",
+            ...body
+        },
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        const data = res.data;
+        let rawList = [];
+        if (Array.isArray(data)) {
+            rawList = data;
+        } else if (data && Array.isArray(data.list)) {
+            rawList = data.list;
+        } else if (data && typeof data === "object") {
+            rawList = Object.keys(data)
+                .filter((key) => /list$/i.test(key) && Array.isArray(data[key]))
+                .flatMap((key) =>
+                    data[key].map((item) => ({
+                        ...item,
+                        __group: key
+                    }))
+                );
+        }
+        if (!isMcp) {
+            console.log(JSON.stringify(rawList));
+        }
+        return rawList;
+    }
+
+    const msg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+    throw new Error("Get User Failed: " + msg);
+}
+
+module.exports = get;

package/src/user/index.js

@@ -0,0 +1,12 @@
+const cc = {}
+cc.create = require("./create")
+cc.delete = require("./delete")
+cc.get = require("./get")
+cc.view = require("./view")
+cc.update = require("./update")
+cc.doc = require("./doc")
+function main(action, argvs) {
+  cc[action](argvs)
+}
+
+module.exports = main;

package/src/user/update.js

@@ -0,0 +1,96 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+const chalk = require("chalk");
+
+/**
+ * 编辑/禁用用户
+ * 用法：cc update user <projectPath> <userDataJson>
+ * @param {Array} argvs - 命令行参数数组
+ * @returns {Promise<Object>} 更新结果
+ */
+async function update(argvs) {
+    try {
+        const projectPath = argvs[2] || process.cwd();
+        const userDataArg = argvs[3];
+
+        if (!userDataArg) {
+            console.error();
+            console.error(chalk.red("Error: 缺少用户数据"));
+            console.error(chalk.yellow("用法: cc update user <projectPath> <userDataJson>"));
+            console.error(chalk.yellow("示例: cc update user . '{\"id\":\"xxx\",\"loginName\":\"test@example.com\",\"isusing\":\"false\"}'"));
+            console.error();
+            throw new Error("缺少必需参数: userDataJson");
+        }
+
+        // 解析用户数据
+        let userData;
+        try {
+            userData = JSON.parse(decodeURI(userDataArg));
+        } catch (e) {
+            try {
+                userData = JSON.parse(userDataArg);
+            } catch (e2) {
+                console.error();
+                console.error(chalk.red("Error: 用户数据 JSON 解析失败"));
+                console.error(chalk.yellow("请确保传入的是有效的 JSON 字符串或 URI 编码后的 JSON"));
+                console.error();
+                throw new Error("userDataJson 解析失败");
+            }
+        }
+
+        // 验证必填字段
+        if (!userData.id) {
+            console.error();
+            console.error(chalk.red("Error: 缺少用户 ID"));
+            console.error();
+            throw new Error("用户数据中必须包含 id 字段");
+        }
+
+        if (!userData.loginName) {
+            console.error();
+            console.error(chalk.red("Error: 缺少登录名"));
+            console.error();
+            throw new Error("用户数据中必须包含 loginName 字段");
+        }
+
+        const config = await getPackageJson(projectPath);
+        if (!config || !config.accessToken) {
+            console.error();
+            console.error(chalk.red("Error: 配置未找到或 accessToken 缺失"));
+            console.error();
+            throw new Error("配置未找到或 accessToken 缺失");
+        }
+
+        console.error();
+        console.error(chalk.green(`Updating user (${userData.id}), please wait...`));
+        console.error();
+
+        // 构造 dataJson 字符串
+        const dataJson = JSON.stringify(userData);
+
+        const result = await postClass(
+            config.setupSvc + "/api/usermange/editandsave",
+            { dataJson: dataJson },
+            config.accessToken
+        );
+
+        if (result && result.result) {
+            console.error();
+            console.error(chalk.green("Success! User updated."));
+            console.error();
+            return result;
+        }
+
+        const msg = result && (result.returnInfo || result.message) ? (result.returnInfo || result.message) : "Unknown error";
+        console.error();
+        console.error(chalk.red("Error: " + msg));
+        console.error();
+        throw new Error("Update User Failed: " + msg);
+    } catch (error) {
+        console.error();
+        console.error(chalk.red("用户更新失败:"), error);
+        throw error;
+    }
+}
+
+module.exports = update;

package/src/user/view.js

@@ -0,0 +1,60 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+const chalk = require("chalk");
+
+/**
+ * 查看单个用户详情
+ * 用法：cc view user <projectPath> <userId>
+ */
+async function view(argvs, isMcp = false) {
+    try {
+        const projectPath = argvs[2] || process.cwd();
+        const userId = argvs[3];
+
+        if (!userId) {
+            console.error();
+            console.error(chalk.red("Error: 缺少用户 ID"));
+            console.error(chalk.yellow("用法: cc view user <projectPath> <userId>"));
+            console.error();
+            throw new Error("缺少必需参数: userId");
+        }
+
+        const config = await getPackageJson(projectPath);
+        if (!config || !config.accessToken) {
+            console.error();
+            console.error(chalk.red("Error: 配置未找到或 accessToken 缺失"));
+            console.error();
+            throw new Error("配置未找到或 accessToken 缺失");
+        }
+
+        console.error();
+        console.error(chalk.green(`Fetching user details (${userId}), please wait...`));
+        console.error();
+
+        const res = await postClass(
+            config.setupSvc + "/api/usermange/viewUser",
+            { userId: userId },
+            config.accessToken
+        );
+
+        if (res && res.result) {
+            const data = res.data || res;
+            if (!isMcp) {
+                console.log(JSON.stringify(data, null, 2));
+            }
+            return data;
+        }
+
+        const msg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+        console.error();
+        console.error(chalk.red("Error: " + msg));
+        console.error();
+        throw new Error("View User Failed: " + msg);
+    } catch (error) {
+        console.error();
+        console.error(chalk.red("查看用户详情失败:"), error);
+        throw error;
+    }
+}
+
+module.exports = view;

package/test/classes.cli.test.js

@@ -17,7 +17,7 @@ async function runCc(args) {
   return execAsync(cmd, { cwd: repoRoot });
 }
 
-test("类管理流程：创建→doc→发布→拉取→线上详情→列表→批量拉取→delete→清空classes文件夹", async (t) => {
+test("自定义类", async (t) => {
   const className = `CCbbbbbbFlow${Date.now()}`;
   const classDir = path.join(repoRoot, "classes", className);
   const configPath = path.join(classDir, "config.json");
@@ -40,9 +40,12 @@ test("类管理流程：创建→doc→发布→拉取→线上详情→列表
     assert.equal(config.name, className);
   });
 
-  t.test("2) 获取 doc（classes overview）", async () => {
-    const { stdout } = await runCc(["doc", "classes", "overview"]);
-    assert.match(stdout, /CloudCC 自定义类开发指南|CloudCC 类编辑知识库/);
+  t.test("2) 获取 doc（classes introduction / devguide）", async () => {
+    const intro = await runCc(["doc", "classes", "introduction"]);
+    assert.match(intro.stdout, /CloudCC 自定义类能力与适用场景说明/);
+
+    const devguide = await runCc(["doc", "classes", "devguide"]);
+    assert.match(devguide.stdout, /CloudCC 自定义类开发指南/);
   });
 
   t.test("3) 发布类（publish，写回 config.id）", async () => {

package/test/customPage.cli.test.js

@@ -0,0 +1,96 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..");
+
+const createCustomPage = require("../src/customPage/create");
+const listCustomPage = require("../src/customPage/get");
+const deleteCustomPage = require("../src/customPage/delete");
+const doc = require("../src/customPage/doc");
+
+/** CloudCC 业务接口常见结构：成功为 result === true 或 returnCode 为 "200" */
+function isApiSuccess(res) {
+  if (res == null) return false;
+  if (res.result === true) return true;
+  return String(res.returnCode) === "200";
+}
+
+function listRecords(res) {
+  const data = res && res.data ? res.data : {};
+  if (Array.isArray(data.records)) return data.records;
+  if (Array.isArray(data.list)) return data.list;
+  if (Array.isArray(data)) return data;
+  return [];
+}
+
+function pickCreatedPageId(res) {
+  const raw = res && res.data != null ? res.data : null;
+  if (raw == null) return null;
+  if (typeof raw === "string" && raw.trim()) return raw.trim();
+  if (typeof raw === "object" && raw.id) return String(raw.id);
+  return null;
+}
+
+/** doc() 会 console.log 全文，单测里静默避免刷屏 */
+function docQuiet(argvs) {
+  const prev = console.log;
+  console.log = () => {};
+  try {
+    return doc(argvs);
+  } finally {
+    console.log = prev;
+  }
+}
+
+test("customPage：doc → 创建 → 列表含新建 → 删除 → 列表无该条（result / returnCode 校验）", async (t) => {
+  let createdPageId = null;
+
+  await t.test("1) doc：introduction / devguide", async () => {
+    const intro = docQuiet(["doc", "customPage", "introduction"]);
+    assert.match(intro, /自定义页面/);
+    const dev = docQuiet(["doc", "customPage", "devguide"]);
+    assert.match(dev, /自定义页面/);
+  });
+
+  await t.test("2) create：无参，insertCustomPage 成功（result / returnCode）", async () => {
+    const res = await createCustomPage(["create", "customPage"]);
+    assert.ok(
+      isApiSuccess(res),
+      `create 接口应 result=true 或 returnCode=200，实际: ${JSON.stringify({ result: res?.result, returnCode: res?.returnCode })}`
+    );
+    createdPageId = pickCreatedPageId(res);
+    assert.ok(createdPageId, `应从 res.data 解析页面 id，实际 data: ${JSON.stringify(res?.data)}`);
+  });
+
+  await t.test("3) pageCustomPage 列表包含刚创建的 id", async () => {
+    assert.ok(createdPageId);
+    const res = await listCustomPage(["get", "customPage", "1", "50", repoRoot]);
+    assert.ok(
+      isApiSuccess(res),
+      `get 列表接口应 result=true 或 returnCode=200，实际: ${JSON.stringify({ result: res?.result, returnCode: res?.returnCode })}`
+    );
+    const hit = listRecords(res).some((row) => row && String(row.id) === String(createdPageId));
+    assert.ok(hit, "列表 records 中应包含刚创建页面的 id");
+  });
+
+  await t.test("4) deleteCustomPage 成功（result / returnCode）", async () => {
+    assert.ok(createdPageId);
+    const res = await deleteCustomPage(["delete", "customPage", createdPageId, repoRoot]);
+    assert.ok(
+      isApiSuccess(res),
+      `delete 接口应 result=true 或 returnCode=200，实际: ${JSON.stringify({ result: res?.result, returnCode: res?.returnCode })}`
+    );
+  });
+
+  await t.test("5) 再次列表，不应包含已删除 id", async () => {
+    assert.ok(createdPageId);
+    const res = await listCustomPage(["get", "customPage", "1", "50", repoRoot]);
+    assert.ok(
+      isApiSuccess(res),
+      `get 列表接口应 result=true 或 returnCode=200，实际: ${JSON.stringify({ result: res?.result, returnCode: res?.returnCode })}`
+    );
+    const stillThere = listRecords(res).some((row) => row && String(row.id) === String(createdPageId));
+    assert.equal(stillThere, false, "删除后列表不应再包含该页面 id");
+  });
+});