cloudcc-cli 2.3.2 → 2.3.4

package/src/role/docs/devguide.md

@@ -1,12 +1,6 @@
-# CloudCC 角色使用总结
+# CloudCC 角色 CLI 命令说明
 
-角色（Role）是 CloudCC 系统中用于定义职能分工和业务角色的重要概念。通过角色可以对用户进行分组管理，实现权限的精细化控制。
-
----
-
-## 快速开始（CLI 命令）
-
-### 支持的角色操作
+## 支持的命令
 
 | 操作 | 说明 |
 |------|------|
@@ -14,14 +8,10 @@
 | `get` | 查询角色列表 |
 | `delete` | 删除角色 |
 
----
-
 ## CLI 命令详解
 
 ### 创建角色
 
-创建一个新的 CloudCC 角色。
-
 ```bash
 cc create role <path> <roleName> [parentRoleName] [description]
 ```
@@ -32,8 +22,8 @@ cc create role <path> <roleName> [parentRoleName] [description]
 |------|------|------|
 | `path` | 是 | 项目路径，`.` 表示当前目录 |
 | `roleName` | 是 | 角色名称 |
-| `parentRoleName` | 否 | 直属上司角色名称（不传则交互式选择） |
-| `description` | 否 | 角色描述（暂不支持保存到后端） |
+| `parentRoleName` | 否 | 直属上司角色名称（不传则交互式选择）|
+| `description` | 否 | 角色描述 |
 
 **示例：**
 
@@ -41,24 +31,15 @@ cc create role <path> <roleName> [parentRoleName] [description]
 # 交互式选择直属上司
 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]
 ```
@@ -80,12 +61,8 @@ 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>
 ```
@@ -100,288 +77,5 @@ cc delete role <projectPath> <roleId>
 **示例：**
 
 ```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/timer/docs/devguide.md

@@ -4,6 +4,82 @@
 
 ---
 
+## CLI 与本地文件（必读）
+
+本仓库中的**定时类**（与定时作业绑定的 Java 类）通过 **cloudcc-cli** 与平台同步，本地目录为 **`schedule/<类名>/`**（内含 `*.java` 与 `config.json`），源码中的 `// @SOURCE_CONTENT_START` … `// @SOURCE_CONTENT_END` 与发布、拉取逻辑一致。**必须通过下列命令** 完成新建目录、发布、拉取与删除；不要手工新建 `schedule/` 子目录、不要整包复制其他项目的定时类、不要私自篡改 `config.json` 中的 `id` 或版本字段。
+
+**允许的做法**：在 CLI 已生成的主类中，仅在上述 SOURCE 标记之间编写业务逻辑；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+
+执行命令前请确认：已完成 `cc doc project devguide` 中的环境初始化，项目根目录配置可用且包含 `accessToken`。
+
+### 命令总览（以代码实现为准）
+
+```bash
+cc create timer <name>
+cc publish timer <name>
+cc pull timer <name>
+cc get timer [listQueryJson] [projectPath]
+cc detail timer <name>
+cc detail timer "" <id>
+cc pullList timer <id> <projectPath>
+cc delete timer <nameOrId> [projectPath]
+cc doc timer <introduction|devguide>
+```
+
+参数约定：
+
+- `name`：定时类名，与 `schedule/<name>/` 目录名一致。
+- `listQueryJson`：可选；列表查询 JSON 经 `encodeURI(JSON.stringify(...))` 编码后传入；不传则使用默认分页参数。
+- `projectPath`：项目根路径，可选。
+- `id`：线上定时类 ID。`detail` 仅查服务器时：`cc detail timer "" <id>`。`pullList` 必填。
+- `nameOrId`：本地目录名或类 ID；若本地 `config.json` 含 `id`，删除时优先使用该 ID。
+
+### 命令作用摘要
+
+| 命令 | 作用 |
+|------|------|
+| `create` | 在 `schedule/<name>/` 生成继承 `CCSchedule` 的 Java 模板与 `config.json` |
+| `publish` | 将 SOURCE 区域提交到服务器；首次成功后可写回 `config.json` 的 `id` |
+| `pull` | 按本地 `id` 拉取远端源码，覆盖主类中 SOURCE 区域（需已发布） |
+| `get` | 查询线上定时类列表（JSON 输出） |
+| `detail` | 按类名优先读本地；或仅按 `id` 读服务器 |
+| `pullList` | 按类 `id` 将线上定时类落到指定项目的 `schedule/<类名>/` |
+| `delete` | 删除服务器上的定时类 |
+| `doc` | 输出模块文档；`devguide` 含附录后端 Java SDK 速查 |
+
+### 推荐操作顺序
+
+```bash
+# 1) 查看线上已有定时类（可选）
+cc get timer
+
+# 2) 新建定时类（仅通过 create 生成目录与模板）
+cc create timer MySchedule
+
+# 3) 编辑 schedule/MySchedule/MySchedule.java 中 SOURCE 区域后发布
+cc publish timer MySchedule
+
+# 4) 与服务器对齐时拉取
+cc pull timer MySchedule
+
+# 5) 按已知线上 ID 拉到指定项目
+cc pullList timer <线上类ID> <projectPath>
+
+# 6) 删除
+cc delete timer MySchedule
+```
+
+### 文档子命令
+
+```bash
+cc doc timer introduction
+cc doc timer devguide
+```
+
+仅支持 `introduction` 与 `devguide`。
+
+---
+
 ## 📌 什么是定时作业？
 
 定时作业是一种**自动化任务调度系统**，允许你：
@@ -416,7 +492,13 @@ function main($CCDK, obj) {
 
 ## 📋 管理操作
 
-### 查询定时作业
+### 定时类：使用 CLI 管理本地 `schedule/`（推荐）
+
+与**定时类源码**的创建、同步、删除，请优先使用上文「CLI 与本地文件（必读）」中的命令，避免绕过 CLI 直接改目录或 `config.json`。
+
+以下接口面向**定时作业配置**（调度时间、启用状态等在设置中的作业），与 `schedule/` 下定时类源码管理是不同层面；具体以你环境的管理后台与 OpenAPI 为准。
+
+### 查询定时作业（平台接口示例）
 
 ```bash
 # 获取列表

package/src/triggers/docs/devguide.md

@@ -6,6 +6,113 @@
 
 ---
 
+## CLI 与本地文件（必读）
+
+本仓库中的触发器源码通过 **cloudcc-cli** 与平台同步，本地目录为 **`triggers/<对象 API 名小写>/<触发器名>/`**（内含 `*.java`、`config.json`），源码中的 `// @SOURCE_CONTENT_START` … `// @SOURCE_CONTENT_END` 与发布、拉取逻辑一致。**必须通过下列命令** 完成新建、发布、拉取与删除；不要手工拼目录、不要整包复制其他项目的触发器、不要私自篡改 `config.json` 中的 `id`、`apiname` 等字段。
+
+**允许的做法**：在 CLI 已生成的主类中，仅在上述 SOURCE 标记之间编写业务逻辑；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+
+执行命令前请确认：已完成 `cc doc project devguide` 中的环境初始化，项目根目录配置可用且包含 `accessToken`。创建触发器前通常需要先通过 `cc get object ...` 等拿到目标对象的 `schemetableName`、`targetObjectId`（见下文物「创建」示例）。
+
+### 命令总览（以代码实现为准）
+
+```bash
+cc create triggers <encodedCreateJson>
+cc publish triggers <namePath>
+cc pull triggers <namePath>
+cc get triggers <listQueryJson> [projectPath]
+cc detail triggers <namePath>
+cc detail triggers "" <id>
+cc pullList triggers <id> <projectPath>
+cc delete triggers <namePathOrId> [projectPath]
+cc doc triggers <introduction|devguide>
+```
+
+参数约定：
+
+- `encodedCreateJson`：`encodeURI(JSON.stringify({ ... }))`，其中至少包含：
+  - `schemetableName`：目标对象 API 名（如 `Account`）
+  - `targetObjectId`：目标对象 ID
+  - `triggerTime`：触发时机（如 `beforeInsert`、`beforeUpsert` 等，以平台为准）
+  - `name`：触发器类名（目录名）
+  - `apiname`：触发器 API 名（全局唯一）
+- `namePath`：**对象目录/触发器名**，与本地路径一致，例如 `account/MyTrigger`（`schemetableName` 小写 + `/` + `name`）。`publish`、`pull`、`delete`（按路径删除时）均使用该形式。
+- `listQueryJson`：列表查询 JSON，经 `encodeURI(JSON.stringify(...))` 编码后传入（**必填**，实现上无默认空查询）。
+- `projectPath`：项目根路径，可选。
+- `id`：线上触发器 ID。`detail` 仅查服务器：`cc detail triggers "" <id>`。
+- `namePathOrId`：可为 `对象小写/触发器名` 形式的路径；若本地 `config.json` 含 `id`，删除时优先用该 ID。
+
+### 命令作用摘要
+
+| 命令 | 作用 |
+|------|------|
+| `create` | 在 `triggers/<对象小写>/<name>/` 生成继承 `CCTrigger` 的 Java 与 `config.json` |
+| `publish` | 提交 SOURCE 区域等到服务器；首次成功后可写回 `config.json` 的 `id`、`apiname` 等 |
+| `pull` | 按本地已发布 `id` 拉取远端源码，覆盖 SOURCE 区域 |
+| `get` | 按条件查询线上触发器列表（JSON 输出） |
+| `detail` | 按 `namePath` 优先读本地；或仅按 `id` 读服务器 |
+| `pullList` | 按触发器 `id` 还原到指定项目的 `triggers/...` |
+| `delete` | 删除服务器上的触发器 |
+| `doc` | 输出模块文档；`devguide` 含附录后端 Java SDK 速查 |
+
+### 创建示例（需先准备对象信息）
+
+先构造对象（字段与平台约定一致），再整段做 `encodeURI(JSON.stringify(...))`，作为 `cc create triggers` 的**唯一参数**：
+
+```json
+{
+  "schemetableName": "Account",
+  "targetObjectId": "<目标对象 ID>",
+  "triggerTime": "beforeInsert",
+  "name": "MyTrigger",
+  "apiname": "NTrigger_unique_api_name"
+}
+```
+
+在 Node 中生成编码后参数示例：
+
+```bash
+node -p "encodeURI(JSON.stringify({schemetableName:'Account',targetObjectId:'<对象ID>',triggerTime:'beforeInsert',name:'MyTrigger',apiname:'NTrigger_xxx'}))"
+```
+
+将命令输出的**一整行**传给：`cc create triggers '<粘贴>'`。
+
+### 推荐操作顺序
+
+```bash
+# 1) 查询自定义对象，取得 schemetableName、targetObjectId（示例）
+cc get object . custom
+
+# 2) 创建本地触发器目录与模板（encodedCreateJson 见上文）
+cc create triggers '<encodedCreateJson>'
+
+# 3) 编辑 triggers/<对象小写>/<name>/<name>.java 中 SOURCE 后发布
+cc publish triggers account/MyTrigger
+
+# 4) 与服务器对齐
+cc pull triggers account/MyTrigger
+
+# 5) 列表（查询 JSON 需 encodeURI）
+cc get triggers '<listQueryJson>' .
+
+# 6) 按线上 ID 拉到指定项目
+cc pullList triggers <线上触发器ID> <projectPath>
+
+# 7) 删除
+cc delete triggers account/MyTrigger
+```
+
+### 文档子命令
+
+```bash
+cc doc triggers introduction
+cc doc triggers devguide
+```
+
+仅支持 `introduction` 与 `devguide`。
+
+---
+
 ## 一、什么是触发器
 
 CloudCC 触发器是完全符合 Java 语法规范的代码，在特定业务事件发生时自动执行，实现业务逻辑自动化处理。
@@ -292,6 +399,7 @@ System.out.println("记录 ID：" + record.get("id"));
 
 ### 8.3 触发器开发 Checklist
 
+- [ ] 本地 `triggers/` 目录仅通过 `cc create` / `cc pull` / `cc pullList` / `cc publish` / `cc delete` 等命令维护，不手造路径、不手改 `config.json` 的 `id`
 - [ ] 明确触发时机（before/after/approval）
 - [ ] 评估并规避递归触发风险
 - [ ] 添加异常处理与关键日志