cloudcc-cli 2.4.0 → 2.4.2

package/src/timer/docs/devguide.md

@@ -18,38 +18,16 @@
 - `2-timer-classes-analysis.md` 提供当前项目定时器使用场景和共性模式
 - `timer devguide` 提供本地目录、CLI、发布和 SOURCE 区域约束
 
-## 3. 先判断：是不是应该写成定时器类
+## 3. 与 introduction 的分工（避免重复）
 
-AI 在动手写代码前，必须先判断需求是否真的适合用定时器类。
+为避免与 `timer introduction` 内容重复，本 `devguide` 只保留“开发落地规范”：
 
-### 3.1 适合定时器类的情况
+- 命令与入参（可直接执行）
+- 目录与文件约束（可直接检查）
+- SDK 用法与边界（可直接编码）
+- 代码模板与禁止事项（可直接评审）
 
-- 任务按时间触发，而不是按单条记录实时触发
-- 需要每天、每周、每月、月初、月末执行
-- 需要批量扫描一批记录并统一处理
-- 需要失败补偿、周期重试或后台巡检
-- 需要构建底表、看板、台账、报表支撑数据
-- 需要在满足条件后自动提醒、自动推进、自动同步
-
-### 3.2 不适合定时器类的情况
-
-- 记录保存时必须立刻校验或立刻拦截
-- 单笔数据变化后必须在同一事务里马上联动
-- 高度依赖前端交互、人工确认、页面反馈
-- 只是一次性临时数据处理，不需要长期调度
-
-### 3.3 当前项目中定时器的六大主类型
-
-根据现有项目总结，AI 应优先将需求归入以下类型之一：
-
-- 提醒通知类
-- 同步推送集成类
-- 刷新更新修正类
-- 报表底表支撑类
-- 自动生成派生类
-- 权限共享治理类
-
-如果需求明显不属于上述类型，AI 应重新评估是否真的应该落到定时器类。
+“定时器是什么、能解决什么、与触发器差异、适用/不适用场景”等概念说明，统一以 `cloudcc doc timer introduction` 为准。
 
 ## 4. 文件与交付规范
 
@@ -75,6 +53,217 @@ AI 在动手写代码前，必须先判断需求是否真的适合用定时器
 - 让类继承 `CCSchedule`
 - 构造方法名与类名一致
 
+### 4.4 timer 模块支持的 CLI 命令总览（重点：入参）
+
+说明：
+
+- 下文命令中的资源名使用 `timer`，也可使用别名 `schedule`（两者路由到同一模块）。
+- `projectPath` 未传时，默认使用当前工作目录。
+
+#### 1) 创建定时类
+
+命令：
+
+```bash
+cloudcc create timer <name>
+```
+
+参数：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `name` | 是 | `string` | 定时类名称（同时作为目录名、Java 类名） |
+
+示例：
+
+```bash
+cloudcc create timer DailySyncJob
+```
+
+---
+
+#### 2) 发布定时类
+
+命令：
+
+```bash
+cloudcc publish timer <name>
+```
+
+参数：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `name` | 是 | `string` | 本地 `schedule/<name>/` 目录名 |
+
+示例：
+
+```bash
+cloudcc publish timer DailySyncJob
+```
+
+---
+
+#### 3) 拉取定时类（按本地名称）
+
+命令：
+
+```bash
+cloudcc pull timer <name>
+```
+
+参数：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `name` | 是 | `string` | 本地 `schedule/<name>/` 目录名；会读取该目录 `config.json` 中的 `id` 到线上拉取 |
+
+示例：
+
+```bash
+cloudcc pull timer DailySyncJob
+```
+
+---
+
+#### 4) 查询定时类列表（支持条件查询）
+
+命令：
+
+```bash
+cloudcc get timer [listQueryJson] [projectPath]
+```
+
+`listQueryJson` 推荐结构：
+
+```json
+{
+    "shownum": 2000,
+    "showpage": 1,
+    "sname": "",
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `shownum` | `number|string` | 否 | 每页条数，默认 `2000` |
+| `showpage` | `number|string` | 否 | 页码，默认 `1` |
+| `sname` | `string` | 否 | 名称筛选关键字，模糊查询 |
+
+示例：
+
+```bash
+cloudcc get timer "$(node -e 'console.log(encodeURI(JSON.stringify({shownum:2000,showpage:1,fid:\"\",sname:\"Daily\",rptcond:\"\",rptorder:\"\"})))')"
+```
+
+---
+
+#### 5) 查看定时类详情
+
+命令：
+
+```bash
+cloudcc detail timer <name> <id>
+```
+
+参数规则（实现口径）：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `name` | 条件必填 | `string` | 传 `name` 时优先查本地；本地不完整时再走线上 |
+| `id` | 条件必填 | `string` | 当 `name` 为空时，必须传 `id` 走线上查询 |
+
+等价理解：`name` 与 `id` 至少传一个，优先使用 `name` 路径。
+
+示例（按本地名）：
+
+```bash
+cloudcc detail timer DailySyncJob
+```
+
+示例（按线上 id）：
+
+```bash
+cloudcc detail timer "" a0Bxxxxxxxxxxxx
+```
+
+---
+
+#### 6) 按 ID 拉取并落地到本地目录
+
+命令：
+
+```bash
+cloudcc pullList timer <id> <projectPath>
+```
+
+参数：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `id` | 是 | `string` | 线上定时类 ID |
+| `projectPath` | 是 | `string` | 项目根目录；会写入到 `<projectPath>/schedule/<name>/` |
+
+示例：
+
+```bash
+cloudcc pullList timer a0Bxxxxxxxxxxxx /path/to/project
+```
+
+---
+
+#### 7) 删除定时类
+
+命令：
+
+```bash
+cloudcc delete timer <nameOrId> [projectPath]
+```
+
+参数规则：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `nameOrId` | 是 | `string` | 可传本地目录名或线上 ID；若本地 `schedule/<nameOrId>/config.json` 存在且带 `id`，优先使用其中 `id` 删除 |
+| `projectPath` | 否 | `string` | 项目根目录，默认当前目录 |
+
+示例（按名称）：
+
+```bash
+cloudcc delete timer DailySyncJob
+```
+
+示例（按 id）：
+
+```bash
+cloudcc delete timer a0Bxxxxxxxxxxxx
+```
+
+---
+
+#### 8) 文档命令
+
+命令：
+
+```bash
+cloudcc doc timer <introduction|devguide>
+```
+
+参数：
+
+| 参数 | 必填 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `introduction|devguide` | 是 | `string` | `introduction` 返回概念文档；`devguide` 返回开发规范（并附 SDK 速查） |
+
+示例：
+
+```bash
+cloudcc doc timer introduction
+cloudcc doc timer devguide
+```
+
 ## 5. AI 编写定时器类的核心原则
 
 ### 5.1 先分析，再编码