cloudcc-cli 2.3.2 → 2.3.3

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）
 - [ ] 评估并规避递归触发风险
 - [ ] 添加异常处理与关键日志