cloudcc-cli 2.2.8 → 2.2.9

package/docs/cloudcc/345/256/232/346/227/266/344/275/234/344/270/232.md

@@ -0,0 +1,472 @@
+# CloudCC 定时作业完全指南
+
+> 定时作业（Scheduled Jobs）是 CloudCC CRM 系统中的后台任务调度机制，用于在指定时间自动执行业务逻辑。
+
+---
+
+## 📌 什么是定时作业？
+
+定时作业是一种**自动化任务调度系统**，允许你：
+
+- 设定任务的执行时间（如每天上午 8 点、每周一、每月 1 号）
+- 关联自定义的业务逻辑代码（定时类）
+- 系统自动在指定时间触发执行，无需人工干预
+
+**类比理解：** 就像手机的闹钟功能，但触发的是业务代码而不是铃声。
+
+---
+
+## 🎯 定时作业的主要作用
+
+### 1. 自动化重复性任务
+
+将人工需要定期执行的操作自动化，例如：
+
+- 每天发送收款提醒邮件
+- 每周生成销售报表
+- 每月清理过期数据
+
+### 2. 时间敏感的业务逻辑
+
+在特定时间点必须执行的操作：
+
+- 合同到期前 30 天提醒续约
+- 客户生日当天发送祝福
+- 季度末自动生成业绩报告
+
+### 3. 后台批处理
+
+处理大量数据的离线任务：
+
+- 夜间同步外部系统数据
+- 批量更新客户状态
+- 计算佣金和业绩
+
+### 4. 监控与预警
+
+持续监控系统状态并触发告警：
+
+- 客户超过 15 天未联系 → 提醒销售跟进
+- 收款计划逾期 → 通知财务人员
+- 资产即将失效 → 自动生成业务机会
+
+---
+
+## 💡 为什么要用定时作业？
+
+### 对比人工操作
+
+| 维度 | 人工操作 | 定时作业 |
+|------|----------|----------|
+| **准确性** | 可能遗忘、出错 | 100% 准时执行 |
+| **效率** | 耗时耗力 | 自动执行，零人力成本 |
+| **一致性** | 不同人操作可能有差异 | 每次执行逻辑一致 |
+| **可扩展性** | 任务多了忙不过来 | 可同时运行多个任务 |
+| **可追溯** | 难以追踪谁什么时候做的 | 完整执行日志 |
+
+### 核心价值
+
+```
+定时作业 = 自动化 + 准时性 + 可追溯
+```
+
+---
+
+## 🔧 定时作业能解决哪些问题？
+
+### 问题 1：遗忘和延误
+
+**场景：** 销售忘记跟进客户，导致商机流失
+
+**解决：** 设置定时作业检测客户最后联系时间，超过 15 天自动提醒
+
+```
+┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
+│ 客户最后联系时间 │ →  │ 定时作业检测  │ →  │ 创建跟进活动     │
+│ > 15 天          │    │ (每天 8:00)   │    │ 并通知销售       │
+└─────────────────┘    └──────────────┘    └─────────────────┘
+```
+
+### 问题 2：重复劳动效率低
+
+**场景：** 财务人员每天手动发送收款提醒，耗时 2 小时
+
+**解决：** 定时作业自动扫描逾期收款计划，批量发送邮件
+
+```
+人工方式：每天 2 小时 × 250 工作日 = 500 小时/年
+定时作业：配置 1 次，自动执行，0 小时/年
+节省：500 小时/年 ≈ 62 个工作日
+```
+
+### 问题 3：跨系统数据同步
+
+**场景：** CRM 和 ERP 系统数据需要保持一致
+
+**解决：** 定时作业每晚同步两个系统的数据
+
+```
+┌──────────┐         ┌──────────────┐         ┌──────────┐
+│   CRM    │ ←─────→ │  定时作业同步  │ ←─────→ │   ERP    │
+│  客户数据 │  2:00   │  (每日凌晨)   │  2:30   │  客户数据 │
+└──────────┘         └──────────────┘         └──────────┘
+```
+
+### 问题 4：报表生成和分发
+
+**场景：** 管理层需要定期查看各类报表
+
+**解决：** 定时作业自动生成报表并邮件发送给相关人员
+
+```
+定时触发 → 查询数据 → 生成报表 → 发送邮件 → 完成
+   ↓
+ 每周一 9:00
+```
+
+---
+
+## 📚 典型业务场景
+
+### 场景 1：销售管理
+
+| 场景 | 触发条件 | 执行动作 |
+|------|----------|----------|
+| 线索分配 | 新线索创建后 24 小时未分配 | 自动分配给销售主管 |
+| 客户跟进提醒 | 客户最后联系时间 > 15 天 | 创建跟进活动并通知销售 |
+| 商机推进提醒 | 商机停留当前阶段 > 30 天 | 提醒销售经理介入 |
+| 业绩统计 | 每日 23:00 | 计算当日业绩并更新报表 |
+
+### 场景 2：客户服务
+
+| 场景 | 触发条件 | 执行动作 |
+|------|----------|----------|
+| 服务到期提醒 | 服务合同到期前 30 天 | 发送续约提醒邮件 |
+| 客户满意度调查 | 服务完成后 7 天 | 发送满意度调查问卷 |
+| 生日祝福 | 客户生日当天 | 发送祝福短信/邮件 |
+| 投诉升级 | 投诉 48 小时未处理 | 自动升级至上级主管 |
+
+### 场景 3：财务管理
+
+| 场景 | 触发条件 | 执行动作 |
+|------|----------|----------|
+| 收款提醒 | 收款计划日期前 7 天 | 邮件通知客户和财务 |
+| 逾期通知 | 收款计划逾期 1 天 | 发送逾期通知并标记 |
+| 发票生成 | 确认收款后 | 自动生成并发送发票 |
+| 佣金计算 | 每月 1 日 | 计算销售佣金并生成报表 |
+
+### 场景 4：数据维护
+
+| 场景 | 触发条件 | 执行动作 |
+|------|----------|----------|
+| 数据清理 | 每周日 3:00 | 清理临时表和过期日志 |
+| 数据备份 | 每日 1:00 | 备份关键数据到指定位置 |
+| 数据同步 | 每日 2:00 | 同步 CRM 与外部系统数据 |
+| 索引优化 | 每月 1 日 4:00 | 重建数据库索引提升性能 |
+
+### 场景 5：营销自动化
+
+| 场景 | 触发条件 | 执行动作 |
+|------|----------|----------|
+| 营销活动提醒 | 活动开始前 3 天 | 通知参与人员准备 |
+| 线索培育 | 线索创建后第 3/7/14 天 | 发送培育邮件 |
+| 活动效果分析 | 活动结束后 1 天 | 生成效果分析报告 |
+| 客户分群更新 | 每日 5:00 | 根据行为更新客户分群 |
+
+---
+
+## ⚙️ 技术实现
+
+### 定时作业结构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    定时作业 (Schedule Job)               │
+├─────────────────────────────────────────────────────────┤
+│  基本信息                                                │
+│  ├── 名称 (name)                                        │
+│  ├── ID (id)                                            │
+│  └── 描述 (description)                                 │
+├─────────────────────────────────────────────────────────┤
+│  调度配置                                                │
+│  ├── 频率类型 (frequency): daily/weekly/monthly         │
+│  ├── 执行时间 (executetime): 08:00                      │
+│  ├── 星期 (weeks): Mon,Tues,Wed,Thur,Fri                │
+│  ├── 开始日期 (startdate): 2024-01-01                   │
+│  └── 结束日期 (enddate): 2024-12-31                     │
+├─────────────────────────────────────────────────────────┤
+│  关联程序                                                │
+│  ├── 程序 ID (prgid)                                    │
+│  └── 定时类 (className): com.xxx.scheduler.MyJob        │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 执行流程
+
+```
+┌─────────────┐
+│  系统时钟   │
+└──────┬──────┘
+       │ 到达触发时间
+       ▼
+┌─────────────┐
+│ 调度器检查   │ ──→ 是否在有效期内？
+└──────┬──────┘     ──→ 状态是否激活？
+       │ 是
+       ▼
+┌─────────────┐
+│ 加载定时类   │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│ 执行 main() │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│ 记录执行日志 │
+└─────────────┘
+```
+
+### 定时类示例
+
+```javascript
+/**
+ * 定时类：客户长时间未联系自动新建活动
+ * 程序 ID: ccp20213DC20298RebnS
+ */
+function main($CCDK, obj) {
+  // 1. 查询超过 15 天未联系的客户
+  const fifteenDaysAgo = new Date();
+  fifteenDaysAgo.setDate(fifteenDaysAgo.getDate() - 15);
+  
+  const customers = $CCDK.query(`
+    SELECT Id, Name, OwnerId 
+    FROM Account 
+    WHERE LastActivityDate < '${fifteenDaysAgo.toISOString()}'
+  `);
+  
+  // 2. 为每个客户创建跟进活动
+  customers.forEach(customer => {
+    $CCDK.create('Activity', {
+      Subject: `跟进客户：${customer.Name}`,
+      Type: 'Call',
+      Status: 'Not Started',
+      OwnerId: customer.OwnerId,
+      RelatedToId: customer.Id
+    });
+  });
+  
+  return `已为 ${customers.length} 个客户创建跟进活动`;
+}
+```
+
+---
+
+## 📊 实际案例（来自你的系统）
+
+### 案例 1：客户长时间未联系新建活动
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 作业名称：客户长时间未联系新建活动                    │
+├─────────────────────────────────────────────────────┤
+│ 执行时间：每天 上午 8:00                             │
+│ 有效期：2021-12-04 ~ 2033-12-21                     │
+│ 状态：✅ 运行中                                      │
+│                                                     │
+│ 业务逻辑：                                          │
+│ 1. 扫描所有客户，找出最后联系时间 > 15 天的          │
+│ 2. 为每个客户自动创建"跟进"活动                      │
+│ 3. 活动分配给对应的销售负责人                        │
+│                                                     │
+│ 价值：防止销售遗忘客户跟进，提升客户满意度            │
+└─────────────────────────────────────────────────────┘
+```
+
+### 案例 2：计划收款日期 7 天后发送邮件
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 作业名称：计划收款日期 7 天后发送邮件                  │
+├─────────────────────────────────────────────────────┤
+│ 执行时间：每天 上午 8:00                             │
+│ 有效期：2021-12-10 ~ 2034-12-31                     │
+│ 状态：✅ 运行中                                      │
+│                                                     │
+│ 业务逻辑：                                          │
+│ 1. 查询收款计划日期 = 今天 + 7 天的记录              │
+│ 2. 发送邮件给客户提醒付款                            │
+│ 3. 抄送财务人员和对应销售                            │
+│                                                     │
+│ 价值：提前提醒客户付款，降低逾期率，改善现金流        │
+└─────────────────────────────────────────────────────┘
+```
+
+### 案例 3：资产失效三个月自动生成业务机会
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 作业名称：资产失效三个月自动生成业务机会              │
+├─────────────────────────────────────────────────────┤
+│ 执行时间：每天 凌晨 1:00                             │
+│ 有效期：2021-12-10 ~ 2033-12-31                     │
+│ 状态：✅ 运行中                                      │
+│                                                     │
+│ 业务逻辑：                                          │
+│ 1. 查询资产失效时间 = 今天 - 3 个月的记录            │
+│ 2. 自动创建新的业务机会（续费/升级）                 │
+│ 3. 分配给原销售或客户经理                            │
+│                                                     │
+│ 价值：抓住续费时机，提升客户生命周期价值              │
+└─────────────────────────────────────────────────────┘
+```
+
+### 案例 4：报表订阅（已过期）
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 作业名称：报表订阅 - 销售部收款统计报表               │
+├─────────────────────────────────────────────────────┤
+│ 执行时间：每月 10 日 下午 4:00                        │
+│ 有效期：2025-01-01 ~ 2025-02-28 ⚠️ 已过期           │
+│ 状态：⚠️ 需要续期或停用                              │
+│                                                     │
+│ 业务逻辑：                                          │
+│ 1. 生成销售部收款统计报表                            │
+│ 2. 发送邮件给销售总监和财务经理                      │
+│                                                     │
+│ 建议：如仍需此报表，需更新有效期                      │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🎓 最佳实践
+
+### 1. 合理设置执行时间
+
+```
+✅ 推荐：
+- 报表生成：非工作时间（如 23:00 或凌晨）
+- 邮件通知：工作时间开始前（如 8:00）
+- 数据同步：系统负载低时（如 2:00-4:00）
+
+❌ 避免：
+- 业务高峰期执行大量数据处理
+- 多个重任务同时执行
+```
+
+### 2. 设置合理的有效期
+
+```
+✅ 推荐：
+- 长期任务：设置 5-10 年有效期
+- 临时任务：设置明确结束日期
+- 定期审查：每季度检查过期任务
+
+❌ 避免：
+- 不设置结束日期（永久运行）
+- 过期任务不处理（占用系统资源）
+```
+
+### 3. 错误处理和日志
+
+```javascript
+function main($CCDK, obj) {
+  try {
+    // 业务逻辑
+    const result = doSomething();
+    return `成功：${result}`;
+  } catch (error) {
+    // 记录错误日志
+    $CCDK.log(`定时作业执行失败：${error.message}`);
+    // 发送告警通知
+    sendAlertToAdmin(error);
+    throw error; // 让系统记录失败状态
+  }
+}
+```
+
+### 4. 性能优化
+
+```
+✅ 推荐：
+- 批量操作代替循环单条处理
+- 使用分页查询避免内存溢出
+- 异步处理非关键逻辑
+
+❌ 避免：
+- 单次查询大量数据（>10000 条）
+- 在定时作业中调用外部 API（无超时控制）
+- 长时间运行的任务（>30 分钟）
+```
+
+### 5. 监控和告警
+
+```
+建议配置：
+- 执行失败时发送邮件/短信告警
+- 定期检查执行日志
+- 监控任务执行时长变化
+```
+
+---
+
+## 📋 管理操作
+
+### 查询定时作业
+
+```bash
+# 获取列表
+POST /ccsetup/api/schedulAbleprg/list
+
+# 获取详细信息
+POST /ccsetup/api/schedulAbleprg/edit
+Body: { "id": "作业 ID" }
+```
+
+### 常见管理需求
+
+| 需求 | 操作 |
+|------|------|
+| 查看有哪些定时作业 | 调用 list 接口 |
+| 查看作业详细配置 | 调用 edit 接口 |
+| 启用/禁用作业 | 修改作业状态（需管理权限） |
+| 修改执行时间 | 编辑作业的 executetime 和 frequency |
+| 延长有效期 | 更新 enddate 字段 |
+| 创建新作业 | 使用 cloudcc-cli 创建定时类并配置调度 |
+
+---
+
+## 🚨 常见问题
+
+### Q1: 定时作业不执行怎么办？
+
+**检查清单：**
+1. 当前日期是否在有效期内？
+2. 作业状态是否为激活？
+3. 定时类代码是否有错误？
+4. 系统日志是否有报错？
+
+### Q2: 如何调试定时作业？
+
+**方法：**
+1. 在代码中添加日志输出
+2. 手动执行定时类测试逻辑
+3. 查看系统执行日志
+4. 设置测试环境验证
+
+### Q3: 定时作业可以传递参数吗？
+
+**答案：** 可以。在配置定时作业时设置参数，在定时类中通过 `obj` 参数接收。
+
+### Q4: 定时作业执行失败会重试吗？
+
+**答案：** 默认不自动重试。建议在代码中实现重试逻辑或配置告警通知人工处理。
+
+---
+
+
+*最后更新：2026-03-25*