cloudcc-cli 2.3.1 → 2.3.2

package/src/role/docs/devguide.md

@@ -0,0 +1,387 @@
+# CloudCC 角色使用总结
+
+角色（Role）是 CloudCC 系统中用于定义职能分工和业务角色的重要概念。通过角色可以对用户进行分组管理，实现权限的精细化控制。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的角色操作
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新角色 |
+| `get` | 查询角色列表 |
+| `delete` | 删除角色 |
+
+---
+
+## CLI 命令详解
+
+### 创建角色
+
+创建一个新的 CloudCC 角色。
+
+```bash
+cc create role <path> <roleName> [parentRoleName] [description]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `roleName` | 是 | 角色名称 |
+| `parentRoleName` | 否 | 直属上司角色名称（不传则交互式选择） |
+| `description` | 否 | 角色描述（暂不支持保存到后端） |
+
+**示例：**
+
+```bash
+# 交互式选择直属上司
+cc create role . "销售经理"
+
+# 指定直属上司为 CEO（非交互式）
+cc create role . "销售经理" "CEO"
+
+# 指定直属上司并添加描述
+cc create role . "市场专员" "销售总监" "负责市场推广工作"
+```
+
+**创建流程说明：**
+1. 调用 `role/addRole` 获取可用直属上司列表
+2. 如果指定了 `parentRoleName`，自动匹配对应角色；否则进入交互式选择
+3. 调用 `role/saveRole` 创建新角色
+
+---
+
+### 查询角色列表
+
+获取当前环境中的所有角色列表。
+
+```bash
+cc get role <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**示例：**
+
+```bash
+# 获取所有角色
+cc get role .
+
+# 带查询条件
+cc get role . '%7B%22name%22%3A%22%E9%94%80%E5%94%AE%22%7D'
+```
+
+---
+
+### 删除角色
+
+删除指定的角色。
+
+```bash
+cc delete role <projectPath> <roleId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `roleId` | 是 | 角色 ID |
+
+**示例：**
+
+```bash
+# 删除指定角色
+cc delete role . a0I9D000000XXXXUAI
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为新部门创建 CloudCC 角色
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询现有角色
+cc get role .
+
+# 3. 创建新角色（交互式选择直属上司）
+cc create role . "销售经理"
+cc create role . "销售代表" "初级销售人员"
+
+# 4. 验证角色创建成功
+cc get role .
+
+# 5. 如需删除
+# cc delete role . <roleId>
+```
+
+### 创建角色流程说明
+
+创建角色的完整流程包含以下步骤：
+
+1. **获取直属上司列表** - 调用 `role/addRole` 接口获取可选的上级角色
+2. **选择直属上司** - 通过交互式选择确定新角色的上级
+3. **保存角色** - 调用 `role/saveRole` 接口创建角色
+
+---
+
+## API 接口详情
+
+### 什么是角色？
+
+**角色（Role）** 是 CloudCC 系统中用于定义职能分工的概念。角色与简档（Profile）结合使用，共同控制用户的系统访问权限。
+
+### 核心属性
+
+| 属性 | 说明 | 示例 |
+|------|------|------|
+| **名称（rolename）** | 角色显示名称 | "销售经理" |
+| **描述（description）** | 角色描述 | "负责销售团队管理" |
+| **父角色（parentroleId）** | 上级角色 ID | "2025238BCF0D98D52xUF" |
+| **角色ID（roleid）** | 角色唯一标识 | "202608C20F87C90KRqZr" |
+| **创建时间** | 角色创建时间戳 | 1757993089000 |
+
+---
+
+## 一、查询角色
+
+### 1.1 查询角色列表
+
+**接口**: `POST /api/role/queryRole`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| display | string | 否 | 显示模式，传 `"list"` 返回列表数据 |
+
+**请求示例**：
+
+```json
+{
+  "display": "list"
+}
+```
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "data": {
+    "list": [
+      {
+        "id": "202608C20F87C90KRqZr",
+        "rolename": "销售经理",
+        "parentroleId": "2025238BCF0D98D52xUF"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 二、创建角色
+
+### 2.1 获取直属上司列表
+
+**接口**: `POST /api/role/addRole`
+
+**说明**：创建角色前需要调用此接口获取可选的直属上司（上级角色）列表。
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | string | 是 | 固定值 `"bab2025F8B20EE4d4005"` |
+
+**请求示例**：
+
+```json
+{
+  "id": "bab2025F8B20EE4d4005"
+}
+```
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "data": {
+    "flist": [
+      {
+        "id": "2025238BCF0D98D52xUF",
+        "name": "总经理"
+      },
+      {
+        "id": "2025238BCF0D98D52xUG",
+        "name": "销售总监"
+      }
+    ]
+  }
+}
+```
+
+### 2.2 保存新角色
+
+**接口**: `POST /api/role/saveRole`
+
+**说明**：选择直属上司后，调用此接口创建新角色。
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| dataJson | string | 是 | JSON 字符串，包含 rolename 和 parentroleId |
+
+**dataJson 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| rolename | string | 是 | 新角色名称 |
+| parentroleId | string | 是 | 直属上司角色 ID |
+
+**请求示例**：
+
+```json
+{
+  "dataJson": "{\"rolename\":\"新角色\",\"parentroleId\":\"2025238BCF0D98D52xUF\"}"
+}
+```
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "data": "202608C20F87C90KRqZr"  // 新创建的角色 ID
+}
+```
+
+### 2.3 创建流程总结
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1. 调用 addRole │────▶│ 2. 选择直属上司 │────▶│ 3. 调用 saveRole│
+│   获取上司列表   │     │  (交互式选择)   │     │   创建新角色    │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+---
+
+## 三、删除角色
+
+### 3.1 删除前检查
+
+- [ ] 是否有用户关联此角色
+- [ ] 是否有下级角色依赖此角色
+- [ ] 级联影响确认
+
+### 3.2 删除流程
+
+**接口**: `POST /api/role/deleteRole`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| roleid | string | 是 | 角色 ID（注意是小写） |
+
+**请求示例**：
+
+```json
+{
+  "roleid": "202608C20F87C90KRqZr"
+}
+```
+
+---
+
+## 四、角色数据结构
+
+### 4.1 查询接口返回的角色数据
+
+```javascript
+{
+  id: "202608C20F87C90KRqZr",
+  rolename: "销售经理",
+  parentroleId: "2025238BCF0D98D52xUF"
+}
+```
+
+### 4.2 addRole 接口返回的上司数据
+
+```javascript
+{
+  id: "2025238BCF0D98D52xUF",
+  name: "总经理"
+}
+```
+
+---
+
+## 五、最佳实践
+
+### 命名规范
+
+| 项目 | 规范 | 示例 |
+|------|------|------|
+| 角色名 | 使用职能名称 | `销售经理`、`市场专员` |
+| 描述 | 简洁说明职责 | `负责华东区销售管理` |
+
+### 角色层级设计
+
+- **合理分层**：根据组织架构设计角色层级
+- **避免循环**：确保角色层级无循环依赖
+- **权限继承**：上级角色自动继承下级角色的权限
+
+### 创建角色注意事项
+
+- 创建角色时必须选择一个直属上司
+- 直属上司决定了角色在组织架构中的位置
+- 建议先规划好组织架构再批量创建角色
+
+---
+
+## 六、常见问题
+
+**Q: 角色和简档的区别？**
+
+A:
+- **简档（Profile）**：控制用户的系统功能访问权限，决定用户能做什么
+- **角色（Role）**：定义用户的组织架构位置，用于数据共享和审批流程
+
+**Q: 创建角色时如何选择直属上司？**
+
+A: 当前实现会自动调用 `addRole` 接口获取可用的直属上司列表，并通过交互式命令行让用户选择。如需特定来源，建议先调用 `cc get role .` 查看现有角色。
+
+**Q: 删除角色会影响用户吗？**
+
+A: 如果角色已被用户关联，删除前需要先解除关联或转移用户到其他角色。
+
+**Q: 可以修改角色的父级吗？**
+
+A: 可以，调用角色更新接口修改 `parentroleId` 字段，注意检查循环依赖。
+
+**Q: addRole 接口中的 id 参数是什么？**
+
+A: 这是固定值 `"bab2025F8B20EE4d4005"`，用于获取直属上司列表的上下文标识。
+
+---
+
+*文档版本：1.1 | 最后更新：2026-03-26*

package/src/role/docs/introduction.md

@@ -0,0 +1,124 @@
+# CloudCC 角色使用总结
+
+角色（Role）用于定义 CloudCC 系统中的职能分工，可以对用户进行分组管理并分配不同的权限。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的角色操作
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新角色 |
+| `get` | 查询角色列表 |
+| `delete` | 删除角色 |
+
+---
+
+## CLI 命令详解
+
+### 创建角色
+
+创建一个新的 CloudCC 角色。
+
+```bash
+cc create role <path> <roleName> [description]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `roleName` | 是 | 角色名称 |
+| `description` | 否 | 角色描述 |
+
+**示例：**
+
+```bash
+# 创建角色
+cc create role . "销售经理"
+
+# 创建带描述的角色
+cc create role . "市场专员" "负责市场推广工作"
+```
+
+---
+
+### 查询角色列表
+
+获取当前环境中的所有角色列表。
+
+```bash
+cc get role <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**示例：**
+
+```bash
+# 获取所有角色
+cc get role .
+
+# 带查询条件
+cc get role . '%7B%22name%22%3A%22%E9%94%80%E5%94%AE%22%7D'
+```
+
+---
+
+### 删除角色
+
+删除指定的角色。
+
+```bash
+cc delete role <projectPath> <roleId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `roleId` | 是 | 角色 ID |
+
+**示例：**
+
+```bash
+# 删除指定角色
+cc delete role . a0I9D000000XXXXUAI
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为新部门创建 CloudCC 角色
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询现有角色
+cc get role .
+
+# 3. 创建新角色
+cc create role . "销售经理"
+cc create role . "销售代表"
+
+# 4. 验证角色创建成功
+cc get role .
+
+# 5. 如需删除
+# cc delete role . <roleId>
+```
+
+---
+
+*文档版本：1.0 | 最后更新：2026-03-26*

package/src/role/get.js

@@ -0,0 +1,57 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+
+/**
+ * 查询角色列表
+ * 用法：cc get role <projectPath> [encodedCondJson]
+ * 接口：POST /api/role/queryRole
+ * 默认参数：{ display: "list" }
+ */
+async function get(argvs, isMcp = false) {
+    const projectPath = argvs[2] || process.cwd();
+    const condArg = argvs[3];
+
+    let body = { display: "list" };
+    if (condArg) {
+        try {
+            body = JSON.parse(decodeURI(condArg));
+        } catch (e) {
+            throw new Error("Get Role Failed: encodedCondJson 解析失败，请传 encodeURI(JSON.stringify(...))");
+        }
+    }
+
+    const config = await getPackageJson(projectPath);
+    const res = await postClass(
+        config.setupSvc + "/api/role/queryRole",
+        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 Role Failed: " + msg);
+}
+
+module.exports = get;

package/src/role/index.js

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

package/src/scheduleJob/doc.js

@@ -0,0 +1,49 @@
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+const INTRODUCTION = path.join(DOCS_DIR, "introduction.md");
+const DEVGUIDE = path.join(DOCS_DIR, "devguide.md");
+
+function readDocOrFallback(filePath, fallback) {
+    try {
+        return fs.readFileSync(filePath, "utf8").trim();
+    } catch (e) {
+        return fallback;
+    }
+}
+
+function getIntroductionDoc() {
+    return readDocOrFallback(
+        INTRODUCTION,
+        `# CloudCC 定时作业（scheduleJob）介绍\n\n（未找到文件：${INTRODUCTION}）\n`
+    );
+}
+
+function getDevGuideDoc() {
+    return readDocOrFallback(
+        DEVGUIDE,
+        `# CloudCC 定时作业（scheduleJob）开发指南\n\n（未找到文件：${DEVGUIDE}）\n`
+    );
+}
+
+/**
+ * cc doc scheduleJob <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+function doc(argvs = []) {
+    const subType = String(argvs[2] || "").trim().toLowerCase();
+    if (!subType || subType === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    if (subType === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${argvs[2]}，请使用 introduction 或 devguide`);
+}
+
+module.exports = doc;

package/src/scheduleJob/docs/devguide.md

@@ -0,0 +1,79 @@
+# CloudCC 定时作业（scheduleJob）开发指南
+
+本指南说明 `scheduleJob` 模块在 cloudcc-cli
+中的能力边界、命令参数、接口映射与二次开发注意事项。
+
+---
+
+## 一、模块定位
+
+`scheduleJob` 只负责“作业管理”相关能力：
+
+- 查询作业列表：`get`
+- 查询作业详情：`detail`
+- 删除作业：`delete`
+- 文档查看：`doc`
+
+---
+
+## 二、CLI 命令说明
+
+### 1) 查询作业列表
+
+```bash
+cc get scheduleJob <projectPath> [encodedCondJson]
+```
+
+参数说明：
+
+| 参数              | 必填 | 说明                      |
+| ----------------- | ---- | ------------------------- |
+| `projectPath`     | 否   | 项目路径，默认当前目录    |
+| `encodedCondJson` | 否   | URI 编码后的查询条件 JSON |
+
+---
+
+### 2) 查询作业详情
+
+```bash
+cc detail scheduleJob <jobId> [projectPath]
+```
+
+参数说明：
+
+| 参数          | 必填 | 说明                   |
+| ------------- | ---- | ---------------------- |
+| `jobId`       | 是   | 定时作业 ID            |
+| `projectPath` | 否   | 项目路径，默认当前目录 |
+
+---
+
+### 3) 删除作业
+
+```bash
+cc delete scheduleJob <jobId> [projectPath]
+```
+
+参数说明：
+
+| 参数          | 必填 | 说明                   |
+| ------------- | ---- | ---------------------- |
+| `jobId`       | 是   | 待删除作业 ID          |
+| `projectPath` | 否   | 项目路径，默认当前目录 |
+
+---
+
+### 4) 查看文档
+
+```bash
+cc doc scheduleJob <introduction|devguide>
+```
+
+---
+
+## 三、关联文档
+
+- `cc doc timer introduction`
+- `cc doc timer devguide`
+
+---